@baack-software/baack-ts-tasks 0.0.0-stage → 0.0.1

package/src/server/webhooks.ts

@@ -0,0 +1,369 @@
+import { isBaackApiError, type Task } from '@baack-software/baack-ts-client';
+import type { TaskClient } from '../task-client.ts';
+import { parseTimestamp } from '../time.ts';
+import type { Ref } from '../types.ts';
+
+/**
+ * Receiving Baack webhooks: verifying a delivery's signature, reading its event, and fetching the task it is about.
+ * Uses Web Crypto and the Fetch API types only, so it runs on Node 20+, Deno, Bun and edge runtimes.
+ *
+ * A delivery is a POST whose body is a webhook event, an envelope naming what changed (`trigger`) and where it is
+ * (`v1`), without the changed representation itself; read it from the API. Its headers:
+ *
+ * - `Signature`: base64 HMAC-SHA256, keyed with the subscription's secret, over the UTF-8 bytes of the parts
+ *   `Signed-Headers` lists, in that order and without separators. Today that is the body, then `Last-Modified`, then
+ *   `Idempotency-Key`.
+ * - `Last-Modified`: when the trigger happened, an ISO local date-time (UTC, without a zone, like other Baack
+ *   timestamps), signed as sent.
+ * - `Idempotency-Key`: the trigger's URN. Retries carry the same key, so handle each key once.
+ * - `X-Attempt-Number` and `X-Attempts-Remaining`: where a delivery is in its retries.
+ */
+
+/** Header names, lower case as the Fetch API's `Headers` and Node's `IncomingMessage` give them. */
+export const WEBHOOK_HEADERS = {
+  signature: 'signature',
+  signedHeaders: 'signed-headers',
+  timestamp: 'last-modified',
+  idempotencyKey: 'idempotency-key',
+  attempt: 'x-attempt-number',
+  attemptsRemaining: 'x-attempts-remaining',
+} as const;
+
+/** What a delivery signs when it doesn't say, the order the API uses. */
+export const DEFAULT_SIGNED_PARTS = ['body', WEBHOOK_HEADERS.timestamp, WEBHOOK_HEADERS.idempotencyKey] as const;
+
+/** The kinds of representation a trigger can be about. */
+export type WebhookSubject =
+  | 'UNKNOWN'
+  | 'ADDRESS'
+  | 'API_CLIENT'
+  | 'BEARER_TOKEN'
+  | 'BOOLEAN_ITEM'
+  | 'CLIENT_IDENTIFIER'
+  | 'COMPANY'
+  | 'DATETIME_ITEM'
+  | 'DOUBLE_ITEM'
+  | 'EMAIL'
+  | 'ENTITY'
+  | 'ENTITY_LIST'
+  | 'GROUP'
+  | 'GROUP_MEMBERSHIP'
+  | 'IDENTITY'
+  | 'JSON_ITEM'
+  | 'LINK_ITEM'
+  | 'REFERENCE_ITEM'
+  | 'IMAGE_ITEM'
+  | 'LATLONG_ITEM'
+  | 'LONG_ITEM'
+  | 'MARKDOWN_ITEM'
+  | 'MESSAGE_THREAD'
+  | 'MESSAGE_THREAD_NOTIFICATION'
+  | 'MONEY_ITEM'
+  | 'OAUTH_TOKEN'
+  | 'PERMISSION'
+  | 'PERSON'
+  | 'PERSON_NAME'
+  | 'PROJECT'
+  | 'ROLE'
+  | 'TASK'
+  | 'TELEPHONE'
+  | 'TEMPLATE_ITEM'
+  | 'TEXT_ITEM'
+  | 'THREAD_POST'
+  | 'WEBHOOK_SUBSCRIPTION'
+  | 'WORKFLOW';
+
+export type WebhookEventKind = 'CREATE' | 'UPDATE' | 'DELETE';
+
+/** What happened: a representation of `subject` was created, updated or deleted. */
+export interface WebhookTrigger {
+  urn: string;
+  owner?: Ref;
+  subject: WebhookSubject;
+  event: WebhookEventKind;
+  /** The URN of the representation that changed. */
+  targetUrn?: string;
+  timestamp?: string;
+}
+
+/** A webhook delivery's body. */
+export interface WebhookEvent {
+  trigger: WebhookTrigger;
+  subscription?: { urn: string; [field: string]: unknown };
+  /** Where the changed representation is. */
+  v1?: { urn: string; url?: string };
+}
+
+/** A delivery that passed verification. */
+export interface WebhookDelivery {
+  event: WebhookEvent;
+  /** The trigger's URN; the same on every retry of this delivery. */
+  idempotencyKey: string;
+  /** `Last-Modified`, as sent. */
+  timestamp: string;
+  attempt?: number;
+  attemptsRemaining?: number;
+}
+
+export type WebhookRejection =
+  | 'missing-signature'
+  | 'missing-header'
+  | 'unsigned-body'
+  | 'bad-signature'
+  | 'stale'
+  | 'malformed-event';
+
+/** Thrown when a delivery can't be trusted or read. Answer 401 (or 400 for `malformed-event`) and don't act on it. */
+export class WebhookVerificationError extends Error {
+  override readonly name = 'WebhookVerificationError';
+
+  constructor(
+    readonly reason: WebhookRejection,
+    message: string,
+  ) {
+    super(message);
+  }
+}
+
+/** Header lookups from the Fetch API's `Headers`, or a plain object such as Node's `req.headers`. */
+export type HeaderSource = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+
+export interface VerifyOptions {
+  /**
+   * Refuse deliveries whose `Last-Modified` is older than this. Off by default: retries keep the trigger's time, so a
+   * late retry is still genuine. Use the idempotency key against replays instead.
+   */
+  maxAgeMs?: number;
+  now?: Date;
+}
+
+/**
+ * Checks a delivery's signature and returns its event. `body` must be the raw bytes or text as received: parsing and
+ * re-serialising the JSON changes the bytes and the signature won't match. Throws `WebhookVerificationError`.
+ */
+export async function verifyWebhook(
+  delivery: { body: string | Uint8Array; headers: HeaderSource },
+  secret: string,
+  options: VerifyOptions = {},
+): Promise<WebhookDelivery> {
+  const header = (name: string) => readHeader(delivery.headers, name);
+  const signature = header(WEBHOOK_HEADERS.signature);
+  if (!signature) throw new WebhookVerificationError('missing-signature', 'The delivery has no Signature header.');
+
+  const listed = header(WEBHOOK_HEADERS.signedHeaders);
+  const parts = listed ? listed.split(',').map((part) => part.trim().toLowerCase()) : [...DEFAULT_SIGNED_PARTS];
+  // A signature that doesn't cover the body proves nothing about the event.
+  if (!parts.includes('body')) throw new WebhookVerificationError('unsigned-body', 'Signed-Headers does not include the body.');
+  const body = typeof delivery.body === 'string' ? encoder.encode(delivery.body) : delivery.body;
+  const signed: Uint8Array[] = [];
+  for (const part of parts) {
+    if (part === 'body') {
+      signed.push(body);
+      continue;
+    }
+    const value = header(part);
+    if (value === undefined) throw new WebhookVerificationError('missing-header', `The signed header ${part} is missing.`);
+    signed.push(encoder.encode(value));
+  }
+
+  const expected = decodeBase64(signature);
+  const key = await hmacKey(secret, ['verify']);
+  // Web Crypto's verify compares in constant time.
+  if (!expected || !(await crypto.subtle.verify('HMAC', key, expected as BufferSource, concat(signed) as BufferSource))) {
+    throw new WebhookVerificationError('bad-signature', 'The signature does not match.');
+  }
+
+  const timestamp = header(WEBHOOK_HEADERS.timestamp) ?? '';
+  if (options.maxAgeMs !== undefined) {
+    // Zoneless, so parseTimestamp (UTC) rather than Date.parse, which would read it as local time.
+    const at = parseTimestamp(timestamp)?.getTime();
+    const now = (options.now ?? new Date()).getTime();
+    if (at === undefined || now - at > options.maxAgeMs) {
+      throw new WebhookVerificationError('stale', `The delivery is from ${timestamp || 'an unknown time'}, too long ago.`);
+    }
+  }
+
+  const event = parseWebhookEvent(typeof delivery.body === 'string' ? delivery.body : decoder.decode(delivery.body));
+  const idempotencyKey = header(WEBHOOK_HEADERS.idempotencyKey) ?? event.trigger.urn;
+  const attempt = toNumber(header(WEBHOOK_HEADERS.attempt));
+  const attemptsRemaining = toNumber(header(WEBHOOK_HEADERS.attemptsRemaining));
+  return {
+    event,
+    idempotencyKey,
+    timestamp,
+    ...(attempt === undefined ? {} : { attempt }),
+    ...(attemptsRemaining === undefined ? {} : { attemptsRemaining }),
+  };
+}
+
+/** `verifyWebhook` for a Fetch API `Request`, reading its body. */
+export async function verifyWebhookRequest(request: Request, secret: string, options?: VerifyOptions): Promise<WebhookDelivery> {
+  const body = new Uint8Array(await request.arrayBuffer());
+  return verifyWebhook({ body, headers: request.headers }, secret, options);
+}
+
+/** Reads a delivery's body as a webhook event, checking the parts handlers rely on. Throws `WebhookVerificationError`. */
+export function parseWebhookEvent(body: string): WebhookEvent {
+  let value: unknown;
+  try {
+    value = JSON.parse(body);
+  } catch {
+    throw new WebhookVerificationError('malformed-event', 'The body is not JSON.');
+  }
+  const trigger = (value as { trigger?: Partial<WebhookTrigger> } | null)?.trigger;
+  if (!trigger || typeof trigger.urn !== 'string' || typeof trigger.subject !== 'string' || typeof trigger.event !== 'string') {
+    throw new WebhookVerificationError('malformed-event', 'The event has no trigger with a urn, subject and event.');
+  }
+  return value as WebhookEvent;
+}
+
+/** The URN of the representation an event is about. */
+export function webhookTarget(event: WebhookEvent): string | undefined {
+  return event.v1?.urn || event.trigger.targetUrn || undefined;
+}
+
+/**
+ * Signs a delivery the way the API does, returning the headers to send with `body`. For tests and for replaying or
+ * simulating deliveries locally.
+ */
+export async function signWebhook(
+  body: string,
+  secret: string,
+  { timestamp, idempotencyKey }: { timestamp: string; idempotencyKey: string },
+): Promise<Record<string, string>> {
+  const key = await hmacKey(secret, ['sign']);
+  const data = concat([encoder.encode(body), encoder.encode(timestamp), encoder.encode(idempotencyKey)]);
+  const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, data as BufferSource));
+  return {
+    Signature: encodeBase64(mac),
+    'Signed-Headers': DEFAULT_SIGNED_PARTS.join(','),
+    'Last-Modified': timestamp,
+    'Idempotency-Key': idempotencyKey,
+  };
+}
+
+/**
+ * The task an event is about, read fresh, since events don't carry it. `null` when the task was deleted, by the event
+ * or since. Throws for events about anything but a task.
+ */
+export async function taskFromWebhook(event: WebhookEvent, tasks: TaskClient): Promise<Task | null> {
+  if (event.trigger.subject !== 'TASK') throw new TypeError(`The event is about a ${event.trigger.subject}, not a task.`);
+  const urn = webhookTarget(event);
+  if (!urn || event.trigger.event === 'DELETE') return null;
+  try {
+    return await tasks.get(urn);
+  } catch (error) {
+    if (isBaackApiError(error) && error.isNotFound) return null;
+    throw error;
+  }
+}
+
+/** Remembers which deliveries were handled, so a retry isn't acted on twice. */
+export interface IdempotencyStore {
+  /** Records the key and returns true the first time it is seen, false after. */
+  claim(key: string): Promise<boolean> | boolean;
+  /** Forgets a key whose handling failed, so a retry runs it. */
+  release?(key: string): Promise<void> | void;
+}
+
+/**
+ * Keys held in memory for `ttlMs` (default a day). Enough for one process; use a shared store (a database row with
+ * a unique key, Redis `SET NX`) when several handle deliveries.
+ */
+export function memoryIdempotencyStore(ttlMs = 24 * 3600_000): IdempotencyStore {
+  const seen = new Map<string, number>();
+  return {
+    claim(key) {
+      const now = Date.now();
+      for (const [old, at] of seen) if (now - at > ttlMs) seen.delete(old);
+      if (seen.has(key)) return false;
+      seen.set(key, now);
+      return true;
+    },
+    release(key) {
+      seen.delete(key);
+    },
+  };
+}
+
+export interface WebhookHandlerOptions {
+  secret: string;
+  /** Acts on a verified delivery seen for the first time. A throw answers 500, so the API retries. */
+  onEvent: (delivery: WebhookDelivery) => Promise<void> | void;
+  /** Default: in memory, per process. */
+  idempotency?: IdempotencyStore;
+  verify?: VerifyOptions;
+}
+
+/**
+ * A Fetch API handler (`(request) => Response`) for a webhook endpoint: verifies, skips repeats, and runs `onEvent`.
+ * Answers 401 to an untrusted delivery, 400 to an unreadable one, 200 once handled or already handled.
+ */
+export function webhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response> {
+  const idempotency = options.idempotency ?? memoryIdempotencyStore();
+  return async (request) => {
+    let delivery: WebhookDelivery;
+    try {
+      delivery = await verifyWebhookRequest(request, options.secret, options.verify);
+    } catch (error) {
+      if (error instanceof WebhookVerificationError) {
+        return new Response(error.message, { status: error.reason === 'malformed-event' ? 400 : 401 });
+      }
+      throw error;
+    }
+    if (!(await idempotency.claim(delivery.idempotencyKey))) return new Response('Already handled', { status: 200 });
+    try {
+      await options.onEvent(delivery);
+    } catch (error) {
+      // Not handled after all: let the retry run it.
+      await idempotency.release?.(delivery.idempotencyKey);
+      throw error;
+    }
+    return new Response('OK', { status: 200 });
+  };
+}
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+function hmacKey(secret: string, usages: KeyUsage[]): Promise<CryptoKey> {
+  return crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, usages);
+}
+
+function readHeader(headers: HeaderSource, name: string): string | undefined {
+  if (typeof (headers as Headers).get === 'function') return (headers as Headers).get(name) ?? undefined;
+  const record = headers as Record<string, string | readonly string[] | undefined>;
+  const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+  const value = key === undefined ? undefined : record[key];
+  return Array.isArray(value) ? value.join(', ') : (value as string | undefined);
+}
+
+function concat(parts: readonly Uint8Array[]): Uint8Array {
+  const result = new Uint8Array(parts.reduce((length, part) => length + part.length, 0));
+  let offset = 0;
+  for (const part of parts) {
+    result.set(part, offset);
+    offset += part.length;
+  }
+  return result;
+}
+
+function encodeBase64(bytes: Uint8Array): string {
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+
+function decodeBase64(text: string): Uint8Array | undefined {
+  try {
+    return Uint8Array.from(atob(text.trim()), (char) => char.charCodeAt(0));
+  } catch {
+    return undefined;
+  }
+}
+
+function toNumber(value: string | undefined): number | undefined {
+  if (value === undefined || value === '') return undefined;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : undefined;
+}