Initial release

.eslintrc.json

@@ -0,0 +1,13 @@
+{
+  "root": true,
+  "env": {
+    "node": true,
+    "es2021": true
+  },
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "extends": ["eslint:recommended", "plugin:node/recommended", "prettier"],
+  "ignorePatterns": ["docs"]
+}

.gitattributes

@@ -0,0 +1 @@
+* text=auto

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on: push
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: ['18.x', '20.x']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js v${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+          cache-dependency-path: 'package.json'
+      - name: Install npm dependencies
+        run: npm install
+      - name: Run lint
+        run: npm run lint
+      - name: Run tests
+        run: npm test

.gitignore

@@ -0,0 +1,6 @@
+# npm
+/node_modules
+/package-lock.json
+
+# JSDoc
+/docs

.prettierrc.json

@@ -0,0 +1,5 @@
+{
+  "proseWrap": "always",
+  "semi": false,
+  "singleQuote": true
+}

.release-it.json

@@ -0,0 +1,11 @@
+{
+  "git": {
+    "commitMessage": "v${version}",
+    "tagName": "v${version}",
+    "tagAnnotation": "v${version}"
+  },
+  "github": {
+    "release": true,
+    "releaseName": "v${version}"
+  }
+}

LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2023 Truepic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,218 @@
+<h1 align="center" width="100%">
+  Truepic Webhook Verifier for Node.js
+</h1>
+
+<h3 align="center" width="100%">
+  <i>Verify webhooks from Truepic Vision or Lens in your Node.js app</i>
+</h3>
+
+This module verifies
+
+- the integrity of the data being received,
+- the authenticity of the sender (Truepic),
+- the authenticity of the receiver (you), and
+- the time between the request being sent and received to prevent replay
+  attacks.
+
+If you're not using Node.js, this also serves as a reference implementation with
+thorough documentation to make the translation into another language as painless
+as possible.
+
+## Installation
+
+```bash
+npm install @truepic/webhook-verifier
+```
+
+## Usage
+
+The `@truepic/webhook-verifier` module exports a default function that should be
+imported to begin:
+
+```js
+import verifyTruepicWebhook from '@truepic/webhook-verifier'
+```
+
+This `verifyTruepicWebhook` function (or whatever you imported it as) is then
+called with the following arguments:
+
+```js
+verifyTruepicWebhook({
+  url: 'The full URL that received the request and is registered with Truepic.',
+  secret: "The shared secret that's registered with Truepic.",
+  header: 'The value of the `truepic-signature` header from the request.',
+  body: 'The raw body (unparsed JSON) from the request.',
+  leewayMinutes:
+    'The number of minutes allowed between the request being sent and received. Defaults to `5`.',
+})
+```
+
+A boolean `true` is returned if the webhook is verified in all of the ways
+described above. Otherwise, if anything fails to check out, a
+`TruepicWebhookVerifierError` is thrown with a message describing why (as much
+as possible).
+
+You should place this function call at the beginning of your webhook route
+handler. Exactly how this is done depends on the web framework that you're
+using. Below are a few examples for popular web frameworks that should be easy
+to adapt if you're using a different one.
+
+### Example: Express.js
+
+```js
+import verifyTruepicWebhook from '@truepic/webhook-verifier'
+import express from 'express'
+import { env } from 'node:process'
+
+const app = express()
+
+app.post(
+  '/truepic/webhook',
+  // This is important! We need the raw request body for `verifyTruepicWebhook`.
+  express.raw({
+    type: 'application/json',
+  }),
+  (req, res, next) => {
+    try {
+      verifyTruepicWebhook({
+        url: env.TRUEPIC_WEBHOOK_URL,
+        secret: env.TRUEPIC_WEBHOOK_SECRET,
+        header: req.header('truepic-signature'),
+        body: req.body.toString(),
+      })
+    } catch (error) {
+      // The request cannot be verified. We're simply logging a warning here,
+      // but you can handle however makes sense.
+      console.warn(error)
+
+      // Return OK so a (potential) bad actor doesn't gain any insight.
+      return res.sendStatus(200)
+    }
+
+    // Process the webhook now that it's verified...
+
+    res.sendStatus(200)
+  },
+)
+
+// The rest of your app...
+```
+
+### Example: Fastify
+
+```bash
+npm install fastify-raw-body
+```
+
+```js
+import verifyTruepicWebhook from '@truepic/webhook-verifier'
+import Fastify from 'fastify'
+import { env } from 'node:process'
+
+const app = Fastify({
+  logger: true,
+})
+
+// This is important! We need the raw request body for `verifyTruepicWebhook`.
+await app.register(import('fastify-raw-body'))
+
+app.post('/truepic/webhook', async (request) => {
+  try {
+    verifyTruepicWebhook({
+      url: env.TRUEPIC_WEBHOOK_URL,
+      secret: env.TRUEPIC_WEBHOOK_SECRET,
+      header: request.headers['truepic-signature'],
+      body: request.rawBody,
+    })
+  } catch (error) {
+    // The request cannot be verified. We're simply logging a warning here,
+    // but you can handle however makes sense.
+    request.log.warn(error)
+
+    // Return OK so a (potential) bad actor doesn't gain any insight.
+    return {}
+  }
+
+  // Process the webhook now that it's verified...
+
+  return {}
+})
+
+// The rest of your app...
+```
+
+## Development
+
+### Prerequisites
+
+The only prerequisite is a compatible version of Node.js (see `engines.node` in
+[`package.json`](package.json)).
+
+### Dependencies
+
+Install dependencies with npm:
+
+```bash
+npm install
+```
+
+### Tests
+
+The built-in Node.js [test runner](https://nodejs.org/docs/latest/api/test.html)
+and [assertions module](https://nodejs.org/docs/latest/api/assert.html) is used
+for testing.
+
+To run the tests:
+
+```bash
+npm test
+```
+
+During development, it's recommended to run the tests automatically on file
+change:
+
+```bash
+npm test -- --watch
+```
+
+### Docs
+
+[JSDoc](https://jsdoc.app/) is used to document the code.
+
+To generate the docs as HTML to the (git-ignored) `docs` directory:
+
+```bash
+npm run docs
+```
+
+### Code Style & Linting
+
+[Prettier](https://prettier.io/) is setup to enforce a consistent code style.
+It's highly recommended to
+[add an integration to your editor](https://prettier.io/docs/en/editors.html)
+that automatically formats on save.
+
+[ESLint](https://eslint.org/) is setup with the
+["recommended" rules](https://eslint.org/docs/latest/rules/) to enforce a level
+of code quality. It's also highly recommended to
+[add an integration to your editor](https://eslint.org/docs/latest/use/integrations#editors)
+that automatically formats on save.
+
+To run via the command line:
+
+```bash
+npm run lint
+```
+
+### Releasing
+
+When the `development` branch is ready for release,
+[Release It!](https://github.com/release-it/release-it) is used to orchestrate
+the release process:
+
+```bash
+npm run release
+```
+
+Once the release process is complete, merge the `development` branch into the
+`main` branch, which should always reflect the latest release.

package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@truepic/webhook-verifier",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Verify webhooks from Truepic Vision or Lens in your Node.js app",
+  "homepage": "https://github.com/TRUEPIC/webhook-verifier-nodejs#readme",
+  "bugs": "https://github.com/TRUEPIC/webhook-verifier-nodejs/issues",
+  "license": "MIT",
+  "main": "./src/main.js",
+  "repository": "TRUEPIC/webhook-verifier-nodejs",
+  "scripts": {
+    "docs": "jsdoc src --recurse --destination docs",
+    "lint": "npm run lint:format && npm run lint:quality",
+    "lint:format": "prettier --check .",
+    "lint:format:fix": "prettier --write .",
+    "lint:quality": "eslint .",
+    "lint:quality:fix": "eslint --fix .",
+    "release": "release-it --only-version",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "eslint": "^8.55.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-node": "^11.1.0",
+    "jsdoc": "^4.0.2",
+    "prettier": "3.1.0",
+    "release-it": "^17.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

src/error.js

@@ -0,0 +1,22 @@
+/**
+ * The custom error thrown when verification fails.
+ *
+ * @memberof module:@truepic/webhook-verifier
+ * @extends Error
+ */
+class TruepicWebhookVerifierError extends Error {
+  /**
+   * Create an error for a failed verification.
+   *
+   * @param {string} message The description of what failed.
+   */
+  constructor(message) {
+    super(message)
+
+    Error.captureStackTrace(this, this.constructor)
+
+    this.name = this.constructor.name
+  }
+}
+
+export default TruepicWebhookVerifierError