@crowdsource.you/core 1.2.0

package/src/express/middleware.ts

@@ -0,0 +1,387 @@
+/**
+ * The webhook receiver.
+ *
+ * ```ts
+ * app.post('/webhooks/crowdsource', crowdsourceWebhooks({
+ *   on: {
+ *     'case.decided': async (event) => { await moderationQueue.add(event.id, event.data); },
+ *   },
+ * }));
+ * ```
+ *
+ * No `express.raw`, no body-parser ordering to get right, no secret to plumb
+ * through — the secret comes from the environment and the handler reads the
+ * request stream itself. That is not convenience for its own sake. The single
+ * most likely way to ship a broken CrowdSource integration is to verify a
+ * signature over `JSON.stringify(req.body)`, which succeeds on every test
+ * payload a developer writes by hand and fails on the first real delivery whose
+ * key order or unicode escaping differs — or, far worse, succeeds on a forged
+ * body that happens to re-serialise identically. This middleware makes that
+ * unreachable: it verifies the bytes it read, and if something upstream already
+ * consumed them it REFUSES rather than reconstructing them.
+ *
+ * What it guarantees, in order:
+ *
+ *   1. The signature is checked over the bytes that arrived (§10.8).
+ *   2. A timestamp outside the five-minute window is rejected before anything
+ *      is dispatched, in both directions.
+ *   3. An event id already claimed is acknowledged without running the handler
+ *      again (§10.8), and a handler that throws releases the claim so the
+ *      retry in §10.9 still works.
+ *   4. An event type this integration does not handle — including one that did
+ *      not exist when it was written — is acknowledged and ignored (§10.11). A
+ *      new event type never breaks an existing integration.
+ *   5. Nothing sensitive is logged. The `onRejected` hook is given the reason
+ *      and never the body (§10.8's last line).
+ */
+
+import type { RequestHandler, Request, Response, NextFunction } from 'express';
+
+import {
+  KnownWebhookEventSchema,
+  WEBHOOK_EVENT_ID_HEADER,
+  WEBHOOK_SIGNATURE_HEADER,
+  WEBHOOK_TIMESTAMP_HEADER,
+  WebhookEventEnvelopeSchema,
+  type KnownWebhookEvent,
+  type WebhookEventEnvelope,
+  type WebhookEventType,
+} from '@crowdsource.you/contracts';
+
+import { memoryProcessedEventStore, type ProcessedEventStore } from './store.js';
+import { verifyWebhookDelivery, type WebhookRejection } from './verify.js';
+
+/** The active signing secret. */
+export const WEBHOOK_SECRET_ENV_VAR = 'CROWDSOURCE_WEBHOOK_SECRET';
+
+/** The secret being retired, during the overlap §10.8 requires for rotation. */
+export const WEBHOOK_PREVIOUS_SECRET_ENV_VAR = 'CROWDSOURCE_WEBHOOK_SECRET_PREVIOUS';
+
+/** Matches the backend's own `express.json` limit. */
+const DEFAULT_MAX_BODY_BYTES = 1_048_576;
+
+/**
+ * A handler per event type, each receiving the event with its payload narrowed.
+ *
+ * Every entry is optional and an absent one is not an error: an integration that
+ * only cares about `case.decided` registers only that.
+ */
+export type WebhookEventHandlers = {
+  readonly [T in WebhookEventType]?: (
+    event: Extract<KnownWebhookEvent, { type: T }>,
+  ) => void | Promise<void>;
+};
+
+export interface CrowdSourceWebhooksOptions {
+  /**
+   * The active secret. Defaults to `process.env.CROWDSOURCE_WEBHOOK_SECRET`.
+   */
+  readonly secret?: string;
+  /**
+   * The secret being retired. Defaults to
+   * `process.env.CROWDSOURCE_WEBHOOK_SECRET_PREVIOUS`. Both are accepted while
+   * it is set, which is what makes a rotation lossless (§10.8).
+   */
+  readonly previousSecret?: string;
+  readonly on?: WebhookEventHandlers;
+  /**
+   * Called for a verified event no handler in `on` covers, including a type this
+   * version of the contracts package does not know. Optional: without it, an
+   * unhandled event is acknowledged and dropped, which is what §10.11 requires.
+   */
+  readonly onUnhandled?: (event: WebhookEventEnvelope) => void | Promise<void>;
+  /** Defaults to an in-process store. See `store.ts` for when that is not enough. */
+  readonly store?: ProcessedEventStore;
+  /** §10.8's five minutes. Lower it in tests, never raise it in production. */
+  readonly toleranceSeconds?: number;
+  readonly maxBodyBytes?: number;
+  /**
+   * Observability for a refused delivery. Receives the reason and nothing else
+   * — never the body, never the signature, never a header.
+   */
+  readonly onRejected?: (rejection: WebhookRejection) => void;
+}
+
+/**
+ * Thrown when the request cannot be verified because of how the application is
+ * assembled, not because of anything the sender did.
+ *
+ * Passed to `next()` so it reaches the application's error handler and is
+ * impossible to miss. The alternative — falling back to `req.body` — is the bug
+ * this whole package exists to prevent.
+ */
+export class CrowdSourceWebhookConfigurationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'CrowdSourceWebhookConfigurationError';
+  }
+}
+
+export function crowdsourceWebhooks(options: CrowdSourceWebhooksOptions = {}): RequestHandler {
+  const store = options.store ?? memoryProcessedEventStore();
+  const handlers = options.on ?? {};
+  const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+
+  return (request: Request, response: Response, next: NextFunction): void => {
+    void handleDelivery({
+      request,
+      response,
+      next,
+      store,
+      handlers,
+      maxBodyBytes,
+      options,
+    });
+  };
+}
+
+interface DeliveryContext {
+  readonly request: Request;
+  readonly response: Response;
+  readonly next: NextFunction;
+  readonly store: ProcessedEventStore;
+  readonly handlers: WebhookEventHandlers;
+  readonly maxBodyBytes: number;
+  readonly options: CrowdSourceWebhooksOptions;
+}
+
+async function handleDelivery(context: DeliveryContext): Promise<void> {
+  const { request, response, next, options } = context;
+
+  let rawBody: Buffer;
+  try {
+    rawBody = await readRawBody(request, context.maxBodyBytes);
+  } catch (error: unknown) {
+    if (error instanceof BodyTooLargeError) {
+      options.onRejected?.('payload_too_large');
+      response.status(413).json({ received: false, rejection: 'payload_too_large' });
+      return;
+    }
+    next(error);
+    return;
+  }
+
+  const verification = verifyWebhookDelivery({
+    eventIdHeader: request.get(WEBHOOK_EVENT_ID_HEADER),
+    timestampHeader: request.get(WEBHOOK_TIMESTAMP_HEADER),
+    signatureHeader: request.get(WEBHOOK_SIGNATURE_HEADER),
+    rawBody,
+    secrets: configuredSecrets(options),
+    nowMs: Date.now(),
+    ...(options.toleranceSeconds === undefined
+      ? {}
+      : { toleranceSeconds: options.toleranceSeconds }),
+  });
+
+  if (!verification.ok) {
+    options.onRejected?.(verification.rejection);
+    /**
+     * 401, not 400. A refused delivery is an authentication failure from the
+     * sender's point of view, and §10.9 keeps retrying 4xx a bounded number of
+     * times either way — what matters is that it is never a 2xx, because a 2xx
+     * would retire the delivery as successfully processed.
+     *
+     * `no_secret_configured` is the one case that is OUR fault, and it still
+     * answers 401 rather than 500: a receiver with no secret must not tell the
+     * world it is running unconfigured, and answering non-2xx keeps the event on
+     * the sender's retry schedule until somebody fixes it.
+     */
+    response.status(401).json({ received: false, rejection: verification.rejection });
+    return;
+  }
+
+  const parsed = WebhookEventEnvelopeSchema.safeParse(parseJson(rawBody));
+  if (!parsed.success) {
+    options.onRejected?.('malformed_event');
+    response.status(400).json({ received: false, rejection: 'malformed_event' });
+    return;
+  }
+  const envelope = parsed.data;
+
+  /**
+   * The signed header and the signed body must name the same event. They are
+   * both inside the signature, so a disagreement is not an attack — it is a
+   * sender defect — but a receiver that deduped on the header while handling the
+   * body would process one event under another's id.
+   */
+  if (envelope.id !== verification.eventId) {
+    options.onRejected?.('event_id_mismatch');
+    response.status(400).json({ received: false, rejection: 'event_id_mismatch' });
+    return;
+  }
+
+  const claimed = await context.store.claim(envelope.id);
+  if (!claimed) {
+    response.status(200).json({ received: true, eventId: envelope.id, duplicate: true });
+    return;
+  }
+
+  try {
+    const handled = await dispatch(context.handlers, envelope, options.onUnhandled);
+    response.status(200).json({ received: true, eventId: envelope.id, duplicate: false, handled });
+  } catch (error: unknown) {
+    // The claim goes back so §10.9's retry schedule can deliver it again. Losing
+    // a decision because a queue was briefly down is not an acceptable outcome.
+    await context.store.release(envelope.id);
+    next(error);
+  }
+}
+
+/**
+ * Dispatches a verified event, and returns whether anything handled it.
+ *
+ * The switch is exhaustive over the contract's event types on purpose: adding an
+ * event to `WEBHOOK_EVENT_TYPES` stops this file compiling until it is handled
+ * here, which is the right failure for the SDK. For an INTEGRATION it is the
+ * opposite — the `default` branch means an unrecognised type is acknowledged and
+ * ignored, so a newer CrowdSource never breaks an older receiver (§10.11).
+ *
+ * The payload is only parsed against the known-event schema when a handler is
+ * actually registered for that type. An integration handling `case.decided` is
+ * therefore unaffected by a later change to what `appeal.created` carries.
+ */
+async function dispatch(
+  handlers: WebhookEventHandlers,
+  envelope: WebhookEventEnvelope,
+  onUnhandled: CrowdSourceWebhooksOptions['onUnhandled'],
+): Promise<boolean> {
+  const known = KnownWebhookEventSchema.safeParse(envelope);
+  if (known.success && (await invoke(handlers, known.data))) return true;
+
+  if (onUnhandled) {
+    await onUnhandled(envelope);
+    return true;
+  }
+  return false;
+}
+
+/** Calls `handler` with `event` if there is one, and says whether there was. */
+async function call<T>(
+  handler: ((event: T) => void | Promise<void>) | undefined,
+  event: T,
+): Promise<boolean> {
+  if (handler === undefined) return false;
+  await handler(event);
+  return true;
+}
+
+/**
+ * The exhaustive half of `dispatch`, written out rather than looked up.
+ *
+ * Indexing the handler map with `event.type` while `event.type` is still a union
+ * would need a cast to call the result, and a cast is exactly what must not sit
+ * between a signed event and the code that acts on it. Narrowing per case is
+ * what makes each call provably well-typed, and it means adding an event to the
+ * contract stops this file compiling until it is handled.
+ */
+async function invoke(
+  handlers: WebhookEventHandlers,
+  event: KnownWebhookEvent,
+): Promise<boolean> {
+  switch (event.type) {
+    case 'report.received':
+      return await call(handlers['report.received'], event);
+    case 'case.created':
+      return await call(handlers['case.created'], event);
+    case 'case.escalated':
+      return await call(handlers['case.escalated'], event);
+    case 'case.decided':
+      return await call(handlers['case.decided'], event);
+    case 'decision.corrected':
+      return await call(handlers['decision.corrected'], event);
+    case 'appeal.created':
+      return await call(handlers['appeal.created'], event);
+    case 'appeal.decided':
+      return await call(handlers['appeal.decided'], event);
+    case 'case.closed':
+      return await call(handlers['case.closed'], event);
+    case 'community_note.status_changed':
+      return await call(handlers['community_note.status_changed'], event);
+    default:
+      return false;
+  }
+}
+
+function configuredSecrets(options: CrowdSourceWebhooksOptions): readonly string[] {
+  const active = options.secret ?? process.env[WEBHOOK_SECRET_ENV_VAR];
+  const previous = options.previousSecret ?? process.env[WEBHOOK_PREVIOUS_SECRET_ENV_VAR];
+  return [active, previous].filter((secret): secret is string => typeof secret === 'string' && secret.length > 0);
+}
+
+function parseJson(rawBody: Buffer): unknown {
+  try {
+    return JSON.parse(rawBody.toString('utf8')) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+class BodyTooLargeError extends Error {}
+
+/**
+ * The bytes as they arrived.
+ *
+ * Three sources, in the order that keeps the guarantee:
+ *
+ *   1. `req.body` is already a Buffer — `express.raw()` is mounted ahead of this
+ *      handler, which is correct and supported.
+ *   2. `req.rawBody` is a Buffer — the `express.json({ verify })` idiom, also
+ *      correct.
+ *   3. Nothing has touched the request — read the stream.
+ *
+ * Anything else REFUSES. A parsed `req.body` means a JSON parser ran first and
+ * the original bytes are gone; re-serialising them would produce a different
+ * value from the one that was signed, and the only way to make that "work"
+ * would be to verify a signature over bytes CrowdSource never sent.
+ */
+async function readRawBody(request: Request, maxBodyBytes: number): Promise<Buffer> {
+  const carried: unknown = Reflect.get(request, 'rawBody');
+  if (Buffer.isBuffer(carried)) return carried;
+
+  const parsedBody: unknown = request.body;
+  if (Buffer.isBuffer(parsedBody)) return parsedBody;
+
+  if (parsedBody !== undefined && parsedBody !== null) {
+    throw new CrowdSourceWebhookConfigurationError(
+      'A body parser ran before the CrowdSource webhook handler, so the signed bytes no longer exist. Mount this handler before express.json(), scope express.json() away from the webhook route, or use express.json({ verify }) to keep the raw body.',
+    );
+  }
+
+  if (request.readableEnded) {
+    throw new CrowdSourceWebhookConfigurationError(
+      'The request body was already consumed before the CrowdSource webhook handler ran, so the signed bytes no longer exist.',
+    );
+  }
+
+  return await new Promise<Buffer>((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    let received = 0;
+    let settled = false;
+
+    request.on('data', (chunk: Buffer) => {
+      if (settled) return;
+      received += chunk.length;
+      if (received > maxBodyBytes) {
+        settled = true;
+        // Paused rather than destroyed: destroying the request takes the socket
+        // with it, and the 413 the caller is about to write would never reach
+        // the sender — which would turn a clear refusal into a connection reset
+        // that a delivery worker can only report as "unknown".
+        request.pause();
+        reject(new BodyTooLargeError());
+        return;
+      }
+      chunks.push(chunk);
+    });
+    request.on('end', () => {
+      if (settled) return;
+      settled = true;
+      resolve(Buffer.concat(chunks));
+    });
+    request.on('error', (error: Error) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    });
+  });
+}

package/src/express/store.ts

@@ -0,0 +1,85 @@
+/**
+ * Idempotency by event id (§10.8: "store the processed event id").
+ *
+ * A delivery is retried on the schedule in §10.9 — six times over 24 hours —
+ * and a retry can also happen because the receiver's 2xx was lost rather than
+ * because it failed. So the same event WILL arrive twice at a healthy receiver,
+ * and "did I already do this?" is the only thing standing between that and a
+ * piece of content being removed twice or a user being suspended twice.
+ *
+ * The interface is claim/release rather than a "seen?" check, because the
+ * obvious design is wrong in a way that is hard to see. Recording the id BEFORE
+ * the handler runs makes a handler failure permanent: every retry is deduped
+ * away and the work is lost silently, which is the worst possible outcome for a
+ * moderation decision. Recording it AFTER lets two concurrent deliveries of the
+ * same event both run. Claiming before and releasing on failure gets both: one
+ * in flight, and a failure still retryable.
+ */
+
+/** The retry schedule of §10.9 ends at 24 hours; a claim outlives it. */
+const DEFAULT_TTL_MS = 25 * 60 * 60 * 1_000;
+
+const DEFAULT_MAX_ENTRIES = 10_000;
+
+export interface ProcessedEventStore {
+  /** True when this call took the claim; false when the event is already held. */
+  claim(eventId: string): boolean | Promise<boolean>;
+  /** Gives the claim back so a redelivery can be processed. */
+  release(eventId: string): void | Promise<void>;
+}
+
+export interface MemoryProcessedEventStoreOptions {
+  readonly ttlMs?: number;
+  readonly maxEntries?: number;
+}
+
+/**
+ * The default store: an in-process map with a TTL.
+ *
+ * **Per process.** Two instances behind a load balancer each keep their own,
+ * so a redelivery that lands on the other instance is NOT deduped. That is
+ * usually fine — the handlers a receiver should be writing are idempotent
+ * anyway, because §7.6 makes the application responsible for recording what it
+ * did about a decision — but an application whose enforcement is not idempotent
+ * must pass a shared store (Redis, its own database) instead. Saying so here is
+ * the point: a dedupe that silently only works on one instance is exactly the
+ * kind of thing that looks correct in staging.
+ *
+ * There is no timer. Expiry is evaluated on read and the map is pruned on
+ * insert, so nothing here keeps a Node event loop alive — a module-level
+ * `setInterval` in a library is how a consumer's test run stops exiting.
+ */
+export function memoryProcessedEventStore(
+  options: MemoryProcessedEventStoreOptions = {},
+): ProcessedEventStore {
+  const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+  const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+  const claims = new Map<string, number>();
+
+  const prune = (now: number): void => {
+    for (const [eventId, expiresAt] of claims) {
+      if (expiresAt <= now) claims.delete(eventId);
+    }
+    // Insertion-ordered, so the oldest claims go first once the cap is hit.
+    while (claims.size >= maxEntries) {
+      const oldest = claims.keys().next();
+      if (oldest.done === true) break;
+      claims.delete(oldest.value);
+    }
+  };
+
+  return {
+    claim(eventId: string): boolean {
+      const now = Date.now();
+      const held = claims.get(eventId);
+      if (held !== undefined && held > now) return false;
+
+      prune(now);
+      claims.set(eventId, now + ttlMs);
+      return true;
+    },
+    release(eventId: string): void {
+      claims.delete(eventId);
+    },
+  };
+}

package/src/express/verify.ts

@@ -0,0 +1,166 @@
+/**
+ * Webhook signature verification (§10.8), as a pure function.
+ *
+ * Kept free of Express, of I/O and of the clock so that the security-critical
+ * decision — do these bytes carry a valid, fresh signature from a secret we
+ * hold? — can be attacked directly by a test rather than through a request. A
+ * signature check that cannot be made to fail is worse than no check at all, so
+ * the corpus in `__tests__/verify.test.ts` is mutation-tested: each deliberately
+ * weakened verifier must be CAUGHT by at least one case, and a case that no
+ * mutant fails is a case that proves nothing.
+ *
+ * §10.8 in full, and where each line lands:
+ *
+ *   * `signedPayload = timestamp + "." + rawBody` — `buildWebhookSignedPayload`
+ *     in the contracts package, so the signer and the verifier cannot disagree
+ *     about what gets signed. This module works on the BYTES of that value (see
+ *     `signedPayloadBytes`).
+ *   * "reject timestamps more than five minutes away" — `TOLERANCE`, applied in
+ *     BOTH directions. A future timestamp is as much a replay signal as an old
+ *     one, and only checking the past accepts a signature minted for a clock
+ *     nobody controls.
+ *   * "compare signatures in constant time" — `timingSafeEqual` over the decoded
+ *     digests. Never `===`: it returns on the first differing byte, which is a
+ *     forgery oracle with enough attempts.
+ *   * "store the processed event id" — `store.ts`, not here. Freshness and
+ *     authenticity are decidable from the request; whether it was already
+ *     handled is not.
+ *   * "allow two secrets during rotation" — `secrets` is a list, every entry is
+ *     tried, and the result names WHICH one matched so an operator can see the
+ *     old secret going quiet before they retire it.
+ */
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+import {
+  WEBHOOK_SIGNATURE_VERSION,
+  WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS,
+  WebhookSignatureHeaderSchema,
+  WebhookTimestampHeaderSchema,
+  buildWebhookSignedPayload,
+} from '@crowdsource.you/contracts';
+
+/**
+ * Why a delivery was refused. Terse on purpose: it goes back on the wire, into
+ * the sender's delivery log, and into `onRejected`.
+ *
+ * The first eight are what verification itself decides; the last three are the
+ * middleware's. They share one vocabulary so the reason a receiver reports and
+ * the reason it answers with are always the same string — two lists would drift
+ * the first time one of them grew.
+ */
+export const WEBHOOK_REJECTIONS = [
+  'missing_event_id',
+  'missing_timestamp',
+  'missing_signature',
+  'malformed_timestamp',
+  'malformed_signature',
+  'timestamp_out_of_window',
+  'signature_mismatch',
+  'no_secret_configured',
+  'malformed_event',
+  'event_id_mismatch',
+  'payload_too_large',
+] as const;
+
+export type WebhookRejection = (typeof WEBHOOK_REJECTIONS)[number];
+
+export interface WebhookVerificationInput {
+  readonly eventIdHeader: string | undefined;
+  readonly timestampHeader: string | undefined;
+  readonly signatureHeader: string | undefined;
+  /** The bytes as they arrived. Never a re-serialisation of a parsed body. */
+  readonly rawBody: Buffer;
+  /** Active secret first; the previous one during rotation (§10.8). */
+  readonly secrets: readonly string[];
+  readonly nowMs: number;
+  readonly toleranceSeconds?: number;
+}
+
+export type WebhookVerification =
+  | {
+      readonly ok: true;
+      readonly eventId: string;
+      /** Which configured secret matched. `0` is the active one. */
+      readonly secretIndex: number;
+    }
+  | { readonly ok: false; readonly rejection: WebhookRejection };
+
+/**
+ * The exact bytes signed, without a UTF-8 round trip.
+ *
+ * §10.8 defines the signed payload as a STRING, and
+ * `buildWebhookSignedPayload` is that definition. Decoding the body to a string
+ * to rebuild it would map any invalid UTF-8 byte to U+FFFD — which is lossy, so
+ * two different bodies could produce the same signed payload. Concatenating the
+ * prefix bytes with the body bytes is the same value for every well-formed
+ * (UTF-8) JSON body and is not lossy for anything else. `verify.test.ts` asserts
+ * the two agree.
+ */
+export function signedPayloadBytes(timestamp: string, rawBody: Buffer): Buffer {
+  // The prefix is taken FROM the contract's own function rather than restated
+  // as `${timestamp}.`, so a change to the separator follows automatically
+  // instead of leaving two definitions to drift.
+  const prefix = buildWebhookSignedPayload(timestamp, '');
+  return Buffer.concat([Buffer.from(prefix, 'utf8'), rawBody]);
+}
+
+function digestsMatch(expectedHex: string, presentedHex: string): boolean {
+  const expected = Buffer.from(expectedHex, 'hex');
+  const presented = Buffer.from(presentedHex, 'hex');
+  // The header schema fixes the length at 64 hex characters, so this is never
+  // the branch that rejects a real delivery — it is what stops `timingSafeEqual`
+  // from throwing if that ever stops being true.
+  if (expected.length !== presented.length) return false;
+  return timingSafeEqual(expected, presented);
+}
+
+/**
+ * Verifies one delivery.
+ *
+ * Order matters: everything cheap and decidable from the headers is checked
+ * BEFORE any HMAC is computed, so a flood of malformed deliveries cannot be
+ * turned into a CPU cost. The one thing that must not be reordered is the
+ * timestamp window, which §10.8 puts before the comparison — a signature that
+ * was valid last week is still cryptographically valid, and freshness is the
+ * only thing that makes it a replay.
+ */
+export function verifyWebhookDelivery(input: WebhookVerificationInput): WebhookVerification {
+  if (input.secrets.length === 0) return { ok: false, rejection: 'no_secret_configured' };
+
+  const eventId = input.eventIdHeader?.trim();
+  if (!eventId) return { ok: false, rejection: 'missing_event_id' };
+  if (input.timestampHeader === undefined) return { ok: false, rejection: 'missing_timestamp' };
+  if (input.signatureHeader === undefined) return { ok: false, rejection: 'missing_signature' };
+
+  if (!WebhookTimestampHeaderSchema.safeParse(input.timestampHeader).success) {
+    return { ok: false, rejection: 'malformed_timestamp' };
+  }
+  if (!WebhookSignatureHeaderSchema.safeParse(input.signatureHeader).success) {
+    return { ok: false, rejection: 'malformed_signature' };
+  }
+
+  const tolerance = input.toleranceSeconds ?? WEBHOOK_TIMESTAMP_TOLERANCE_SECONDS;
+  const skewSeconds = Math.abs(input.nowMs / 1_000 - Number(input.timestampHeader));
+  if (skewSeconds > tolerance) return { ok: false, rejection: 'timestamp_out_of_window' };
+
+  const presentedHex = input.signatureHeader.slice(`${WEBHOOK_SIGNATURE_VERSION}=`.length);
+  const payload = signedPayloadBytes(input.timestampHeader, input.rawBody);
+
+  /**
+   * Every secret is tried and the loop does not break early. Breaking would make
+   * "the active secret matched" measurably faster than "the previous one did",
+   * which tells a caller how far through a rotation the receiver is — small, but
+   * free to avoid.
+   */
+  let matchedIndex = -1;
+  input.secrets.forEach((secret, index) => {
+    const expected = createHmac('sha256', secret).update(payload).digest('hex');
+    if (digestsMatch(expected, presentedHex) && matchedIndex === -1) {
+      matchedIndex = index;
+    }
+  });
+
+  if (matchedIndex === -1) return { ok: false, rejection: 'signature_mismatch' };
+  return { ok: true, eventId, secretIndex: matchedIndex };
+}