@usehenri/webhooks 0.0.0 → 1.2.0

package/src/module.js

@@ -0,0 +1,368 @@
+const BaseModule = require('@usehenri/core/module');
+
+const debug = require('debug')('henri:webhooks');
+
+const { Webhooks } = require('./webhooks');
+const { definition } = require('./job');
+
+/**
+ * Outbound webhooks: the henri module this package ships.
+ *
+ * `package.json` points at it with `"henri": { "module": "./module.js" }`,
+ * so an application that depends on `@usehenri/webhooks` has it in the boot
+ * as `henri.webhooks`, with nothing else to write. One that does not has no
+ * such module, and core carries none of this.
+ *
+ * ## Why a package, and not part of one that exists
+ *
+ * It could have been part of `@usehenri/jobs`, which it depends on. It is
+ * not, because the queue would then carry an HTTP client, a signing scheme,
+ * an SSRF address check, an endpoints table and a key at rest -- none of
+ * which a queue needs, and all of which an application that only wanted
+ * background work would have to read past in a security review. It could
+ * have been part of core, and core carries neither the queue nor the
+ * uploads for the same reason. So: a package, next to `@usehenri/jobs` and
+ * `@usehenri/uploads`, peer-depending on both core and the queue, following
+ * the precedent those two set.
+ *
+ * ## Where it sits in the boot
+ *
+ * Runlevel 4, after the queue: it registers the delivery job on
+ * `henri.jobs`, so `henri jobs` -- which boots to that level and binds no
+ * port -- has the definition and performs the deliveries. `henri.cache` is
+ * at 3 and is used, without being needed, to keep an endpoint lookup off the
+ * database on every event.
+ *
+ * An application that installed this package and has no running queue boots
+ * anyway: the endpoints can be registered and inspected, and the first
+ * `emit()` is what says the queue is missing. Failing the boot over it would
+ * be a worse trade -- a webhook is not what an application serves.
+ *
+ * @class WebhooksModule
+ * @extends {BaseModule}
+ */
+class WebhooksModule extends BaseModule {
+  /**
+   * Creates an instance of WebhooksModule.
+   *
+   * @param {object} [henri=null] A henri instance
+   * @memberof WebhooksModule
+   */
+  constructor(henri = null) {
+    super();
+
+    this.reloadable = true;
+    this.needs = ['config', 'model'];
+    this.after = ['cache', 'jobs'];
+    this.runlevel = 4;
+    this.name = 'webhooks';
+    this.henri = henri;
+
+    this.webhooks = null;
+    this.enabled = false;
+
+    this.init = this.init.bind(this);
+    this.stop = this.stop.bind(this);
+    this.reload = this.reload.bind(this);
+  }
+
+  /**
+   * Module initialization
+   * Called after being loaded by Modules
+   *
+   * @async
+   * @returns {Promise<string>} The name of the module
+   * @throws when the endpoints table cannot be reached
+   * @memberof WebhooksModule
+   */
+  async init() {
+    const { config, pen } = this.henri;
+    const settings =
+      config && config.has && config.has('webhooks')
+        ? config.get('webhooks')
+        : {};
+
+    this.webhooks = new Webhooks(this.henri, {
+      agent: this.agent(),
+      config: settings || {},
+    });
+
+    try {
+      await this.webhooks.start();
+    } catch (error) {
+      pen.error('webhooks', 'unable to prepare the endpoints', error.message);
+      throw error;
+    }
+
+    this.enabled = true;
+    this.deliver();
+
+    const wanted = this.webhooks.config;
+    const said = [
+      `deliveries on the ${wanted.queue} queue`,
+      `${wanted.maxAttempts} attempts`,
+    ];
+
+    if (wanted.allowPrivate) {
+      said.push('private addresses are ALLOWED');
+    }
+
+    if (wanted.allowHttp) {
+      said.push('plaintext http is ALLOWED');
+    }
+
+    pen.info('webhooks', ...said);
+
+    return this.name;
+  }
+
+  /**
+   * The user agent the deliveries carry
+   *
+   * @returns {string} `henri-webhooks/<version>`
+   * @memberof WebhooksModule
+   */
+  agent() {
+    try {
+      return `henri-webhooks/${require('../package.json').version}`;
+    } catch (error) {
+      return 'henri-webhooks';
+    }
+  }
+
+  /**
+   * Registers the delivery job on the queue
+   *
+   * An application that wants its own delivery job writes
+   * `app/jobs/henri/webhook.js`, and it wins: the queue refuses to replace a
+   * definition that came from a file, the way it does for `henri/mail`.
+   *
+   * @returns {boolean} Whether the job was registered
+   * @memberof WebhooksModule
+   */
+  deliver() {
+    const { jobs, pen } = this.henri;
+
+    if (!jobs || !jobs.enabled) {
+      pen.warn(
+        'webhooks',
+        'no running job queue: the endpoints can be managed, but nothing can be delivered.',
+        'Install @usehenri/jobs, add a "jobs" block to the configuration and run `henri jobs`'
+      );
+
+      return false;
+    }
+
+    if (typeof jobs.define !== 'function') {
+      pen.warn(
+        'webhooks',
+        'this @usehenri/jobs is too old to take a job from a package: upgrade it'
+      );
+
+      return false;
+    }
+
+    const { definition: job, name } = definition(this.webhooks);
+
+    debug('registering the %s job', name);
+
+    return jobs.define(name, job);
+  }
+
+  /**
+   * Stops the module
+   *
+   * @async
+   * @returns {Promise<boolean>} true when there was something to stop
+   * @memberof WebhooksModule
+   */
+  async stop() {
+    if (!this.webhooks) {
+      return false;
+    }
+
+    await this.webhooks.stop();
+    this.enabled = false;
+
+    return true;
+  }
+
+  /**
+   * Reloads the module
+   *
+   * @async
+   * @returns {Promise<string>} Module name
+   * @memberof WebhooksModule
+   */
+  async reload() {
+    await this.stop();
+
+    this.webhooks = null;
+
+    return this.init();
+  }
+
+  /**
+   * The endpoints, or a readable error
+   *
+   * @returns {Webhooks} The endpoints
+   * @throws when the module never started
+   * @memberof WebhooksModule
+   */
+  ready() {
+    if (!this.webhooks) {
+      throw this.henri.pen.fatal(
+        'webhooks',
+        `
+      The webhooks are not ready: the module did not start.`,
+        null,
+        null,
+        'HENRI_WEBHOOK_NOT_STARTED'
+      );
+    }
+
+    return this.webhooks;
+  }
+
+  /**
+   * Registers an endpoint, and hands its secret over once
+   *
+   * @param {object} options `url`, `events`, `owner`, `description`,
+   *   `headers`, `secret`
+   * @returns {Promise<object>} The endpoint, with `secret`
+   * @memberof WebhooksModule
+   */
+  register(options) {
+    return this.ready().register(options);
+  }
+
+  /**
+   * Sends an event to every endpoint subscribed to it
+   *
+   * @param {string} event The event name
+   * @param {*} [data] What the receivers get, under `data`
+   * @param {object} [options] `owner`, `wait`, `at`
+   * @returns {Promise<Array<object>>} The deliveries enqueued
+   * @memberof WebhooksModule
+   */
+  emit(event, data, options) {
+    return this.ready().emit(event, data, options);
+  }
+
+  /**
+   * Enqueues one delivery to one endpoint
+   *
+   * @param {string} id The endpoint id
+   * @param {string} event The event name
+   * @param {*} [data] What the receiver gets, under `data`
+   * @param {object} [options] `wait`, `at`
+   * @returns {Promise<object>} The delivery
+   * @memberof WebhooksModule
+   */
+  deliverTo(id, event, data, options) {
+    return this.ready().enqueue(id, event, data, options);
+  }
+
+  /**
+   * One endpoint
+   *
+   * @param {string} id The endpoint id
+   * @returns {Promise<?object>} The endpoint, or null
+   * @memberof WebhooksModule
+   */
+  endpoint(id) {
+    return this.ready().endpoint(id);
+  }
+
+  /**
+   * The endpoints
+   *
+   * @param {object} [filter] `owner`, `disabled`, `limit`, `offset`
+   * @returns {Promise<Array<object>>} The endpoints
+   * @memberof WebhooksModule
+   */
+  endpoints(filter) {
+    return this.ready().endpoints(filter);
+  }
+
+  /**
+   * The active secrets of an endpoint, in the clear
+   *
+   * @param {string} id The endpoint id
+   * @returns {Promise<Array<string>>} The secrets that still sign
+   * @memberof WebhooksModule
+   */
+  secrets(id) {
+    return this.ready().secrets(id);
+  }
+
+  /**
+   * Changes an endpoint
+   *
+   * @param {string} id The endpoint id
+   * @param {object} [changes] `url`, `events`, `description`, `headers`
+   * @returns {Promise<object>} The endpoint
+   * @memberof WebhooksModule
+   */
+  update(id, changes) {
+    return this.ready().update(id, changes);
+  }
+
+  /**
+   * Gives an endpoint a new secret
+   *
+   * @param {string} id The endpoint id
+   * @param {object} [options] `grace`, `secret`
+   * @returns {Promise<object>} The endpoint, with the new `secret`
+   * @memberof WebhooksModule
+   */
+  rotate(id, options) {
+    return this.ready().rotate(id, options);
+  }
+
+  /**
+   * Stops sending to an endpoint
+   *
+   * @param {string} id The endpoint id
+   * @param {object} [options] `reason`
+   * @returns {Promise<object>} The endpoint
+   * @memberof WebhooksModule
+   */
+  disable(id, options) {
+    return this.ready().disable(id, options);
+  }
+
+  /**
+   * Sends to an endpoint again
+   *
+   * @param {string} id The endpoint id
+   * @returns {Promise<object>} The endpoint
+   * @memberof WebhooksModule
+   */
+  enable(id) {
+    return this.ready().enable(id);
+  }
+
+  /**
+   * Forgets an endpoint for good
+   *
+   * @param {string} id The endpoint id
+   * @returns {Promise<boolean>} Whether there was one to remove
+   * @memberof WebhooksModule
+   */
+  remove(id) {
+    return this.ready().remove(id);
+  }
+
+  /**
+   * The endpoints and what the queue holds for them
+   *
+   * @returns {Promise<object>} `{ endpoints, queue, deliveries }`
+   * @memberof WebhooksModule
+   */
+  stats() {
+    return this.ready().stats();
+  }
+}
+
+module.exports = WebhooksModule;

package/src/secrets.js

@@ -0,0 +1,240 @@
+const {
+  createCipheriv,
+  createDecipheriv,
+  createHash,
+  hkdfSync,
+  randomBytes,
+  randomUUID,
+} = require('crypto');
+
+const { WebhookError } = require('./errors');
+const { SCHEME, generate } = require('./signature');
+
+/**
+ * The signing secrets of an endpoint, and what protects them at rest.
+ *
+ * A signing secret is a bearer credential in both directions: whoever holds
+ * it can forge a delivery the receiver will believe. It has to be readable
+ * -- henri signs with it on every attempt, so it cannot be hashed the way a
+ * password is -- which leaves encryption as the only thing that makes a
+ * stolen database dump less than a forged delivery.
+ *
+ * So a secret is sealed with a key derived from `config.secret` (HKDF-
+ * SHA256, one label, 32 bytes) and stored as AES-256-GCM. The row carries
+ * the first bytes of the key's digest, so a `HENRI_SECRET` that changed is
+ * reported as exactly that instead of failing to decrypt with a wall of
+ * noise. An application without a `secret` -- there is one as soon as it has
+ * users -- stores its secrets as they are, and the boot says so once.
+ *
+ * The consequence is worth writing down, because it is a real operational
+ * trap: **rotating `HENRI_SECRET` makes every stored webhook secret
+ * unreadable**. The fix is not to decrypt them, it is to rotate the
+ * endpoints' own secrets (`henri webhooks:rotate <id>`) and hand the new
+ * ones to the receivers. Rotate one, not the other, or rotate both in that
+ * order.
+ */
+
+/** The label the endpoint key is derived under */
+const LABEL = 'henri.webhooks.secret.v1';
+
+/**
+ * How a sealed value announces itself, and what separates its parts.
+ *
+ * A colon, not a dot: base64 has no colon in it, and the marker itself
+ * carries a version so the format can change without guessing.
+ */
+const SEALED = 'henri-webhooks-v1';
+
+/** The bytes of the derived key */
+const KEY_BYTES = 32;
+
+/** The bytes of a GCM nonce */
+const IV_BYTES = 12;
+
+/** How much of the key's digest names it in a row */
+const KEY_ID = 8;
+
+/**
+ * The key an application seals its endpoint secrets with
+ *
+ * @param {?string} secret `config.secret`
+ * @returns {?object} `{ id, key }`, or null without a secret
+ */
+const keyring = (secret) => {
+  if (!secret) {
+    return null;
+  }
+
+  const key = Buffer.from(
+    hkdfSync('sha256', String(secret), 'henri.webhooks', LABEL, KEY_BYTES)
+  );
+
+  return {
+    id: createHash('sha256').update(key).digest('hex').slice(0, KEY_ID),
+    key,
+  };
+};
+
+/**
+ * Whether a stored value is sealed
+ *
+ * @param {string} value The stored value
+ * @returns {boolean} Whether it was encrypted
+ */
+const isSealed = (value) => String(value || '').startsWith(`${SEALED}:`);
+
+/**
+ * Seals a secret for the database
+ *
+ * @param {string} value The secret
+ * @param {?object} keys The keyring, or null to store it as it is
+ * @returns {string} What goes in the row
+ */
+const seal = (value, keys) => {
+  if (!keys) {
+    return value;
+  }
+
+  const iv = randomBytes(IV_BYTES);
+  const cipher = createCipheriv('aes-256-gcm', keys.key, iv);
+  const sealed = Buffer.concat([
+    cipher.update(String(value), 'utf8'),
+    cipher.final(),
+  ]);
+
+  return [
+    SEALED,
+    keys.id,
+    iv.toString('base64'),
+    cipher.getAuthTag().toString('base64'),
+    sealed.toString('base64'),
+  ].join(':');
+};
+
+/**
+ * Reads a secret back
+ *
+ * @param {string} value What the row holds
+ * @param {?object} keys The keyring
+ * @returns {string} The secret
+ * @throws {WebhookError} SECRET_UNREADABLE when the key no longer opens it
+ */
+const open = (value, keys) => {
+  if (!isSealed(value)) {
+    return value;
+  }
+
+  const [, id, iv, tag, sealed] = String(value).split(':');
+
+  if (!keys) {
+    throw new WebhookError(
+      'HENRI_WEBHOOK_SECRET_UNREADABLE',
+      '@usehenri/webhooks: this endpoint secret is encrypted and the application has no "secret" to open it with',
+      {
+        hint: 'Set HENRI_SECRET back to what it was when the endpoint was registered',
+        retryable: false,
+      }
+    );
+  }
+
+  if (id !== keys.id) {
+    throw new WebhookError(
+      'HENRI_WEBHOOK_SECRET_UNREADABLE',
+      `@usehenri/webhooks: this endpoint secret was sealed with another key (${id}, not ${keys.id})`,
+      {
+        hint: 'HENRI_SECRET changed: put the old one back, or give the endpoint a new secret with `henri webhooks:rotate <id>` and hand it to the receiver',
+        retryable: false,
+      }
+    );
+  }
+
+  try {
+    const decipher = createDecipheriv(
+      'aes-256-gcm',
+      keys.key,
+      Buffer.from(iv, 'base64')
+    );
+
+    decipher.setAuthTag(Buffer.from(tag, 'base64'));
+
+    return Buffer.concat([
+      decipher.update(Buffer.from(sealed, 'base64')),
+      decipher.final(),
+    ]).toString('utf8');
+  } catch (error) {
+    throw new WebhookError(
+      'HENRI_WEBHOOK_SECRET_UNREADABLE',
+      '@usehenri/webhooks: this endpoint secret does not decrypt',
+      {
+        cause: error,
+        hint: 'The row was changed after it was written, or the key it was sealed with is gone: rotate the endpoint secret',
+        retryable: false,
+      }
+    );
+  }
+};
+
+/**
+ * A new secret record, ready to be stored
+ *
+ * @param {object} [options={}] `secret` (one of your own), `now`
+ * @returns {object} `{ id, key, scheme, createdAt, expiresAt }`
+ */
+const fresh = (options = {}) => ({
+  createdAt: options.now || Date.now(),
+  expiresAt: null,
+  id: randomUUID(),
+  key: options.secret || generate(),
+  scheme: SCHEME,
+});
+
+/**
+ * The records that still sign, oldest expiry last
+ *
+ * @param {Array<object>} secrets The stored records
+ * @param {number} [now=Date.now()] The moment
+ * @returns {Array<object>} The records that have not expired
+ */
+const active = (secrets, now = Date.now()) =>
+  (secrets || []).filter(
+    (record) => !record.expiresAt || record.expiresAt > now
+  );
+
+/**
+ * A rotation: a new record first, the old ones expiring after a grace
+ *
+ * Every record that has not expired keeps signing until it does, so a
+ * receiver has the length of the grace to install the new secret without
+ * dropping a delivery. A grace of zero retires the old secrets at once,
+ * which is what a leak calls for.
+ *
+ * @param {Array<object>} secrets The stored records
+ * @param {object} [options={}] `grace` (ms), `secret`, `now`
+ * @returns {Array<object>} The records to store
+ */
+const rotate = (secrets, options = {}) => {
+  const now = options.now || Date.now();
+  const grace = Math.max(0, Number(options.grace) || 0);
+  const next = fresh({ now, secret: options.secret });
+  const kept = active(secrets, now).map((record) => ({
+    ...record,
+    expiresAt: Math.min(record.expiresAt || Infinity, now + grace),
+  }));
+
+  return grace === 0 ? [next] : [next, ...kept];
+};
+
+module.exports = {
+  IV_BYTES,
+  KEY_BYTES,
+  KEY_ID,
+  LABEL,
+  SEALED,
+  active,
+  fresh,
+  isSealed,
+  keyring,
+  open,
+  rotate,
+  seal,
+};