@openwop/openwop-conformance 2.35.0 → 2.36.0

package/src/scenarios/v2-webhook-secret-rotation.test.ts

@@ -0,0 +1,132 @@
+/**
+ * RFC 0201 §E — multi-signature secret rotation (suite 2.36.0, target major 2;
+ * gated on `webhooks.signatureAlgorithms` listing `standard-webhooks-1` AND the
+ * `webhooks.secretRotation` facet).
+ *
+ * After `POST /webhooks/{webhookId}/rotate-secret`, for `overlapSeconds`, every
+ * delivery's `webhook-signature` MUST carry exactly one entry under the new
+ * secret and one under the previous secret, and `OpenWOP-Signature` stays on the
+ * previous secret; afterwards only the new secret signs. The route is tenant-
+ * checked before lookup (`403 id_tenant_mismatch`), refuses a subscription that
+ * did not opt in (`400 validation_error`), and returns no secret.
+ *
+ * The post-overlap leg waits for `previousSecretExpiresAt` only when
+ * `overlapSeconds` fits inside the suite's retry-wait cap
+ * (`OPENWOP_WEBHOOK_RETRY_WAIT_MS`, operator-raisable). Past the cap it is not
+ * observed, and the row says so with a `partial-witness:` detail — which the
+ * acceptance predicate refuses to cite as `executed-pass` (RFC 0201 §Falsifiability).
+ *
+ * How it FAILS: signing only with the new secret (one entry); moving
+ * `OpenWOP-Signature` to the new secret at rotation; a foreign-tenant id that
+ * reaches the lookup (`404` instead of `403`); a response that echoes the secret.
+ *
+ * @see spec/v2/core/webhooks.md §Standard Webhooks
+ * @see RFCS/0201-standard-webhooks-signature-scheme.md §E
+ */
+
+import { afterEach, describe, it, expect } from 'vitest';
+import { createHmac } from 'node:crypto';
+import { driver } from '../lib/driver.js';
+import { req } from '../lib/requirement-ids.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { projectBoundId } from '../lib/bound-id.js';
+import { retryWaitCapMs } from '../lib/webhook-retry-window.js';
+import { hitHeader, mintWhsec, startModalReceiver, verifyStandardWebhooks, type ModalHit } from '../lib/webhook-receiver.js';
+import {
+  STANDARD_WEBHOOKS_ALG,
+  deliveriesFor,
+  driveRun,
+  loopbackRefusal,
+  registerSw,
+  swGate,
+  unregisterAllSw,
+  waitFor,
+} from '../lib/standard-webhooks.js';
+
+const CAP_MS = retryWaitCapMs();
+
+let closeReceiver: (() => Promise<void>) | null = null;
+afterEach(async () => {
+  await unregisterAllSw();
+  if (closeReceiver) { const c = closeReceiver; closeReceiver = null; await c(); }
+});
+
+function v1SignedBy(secret: string, h: ModalHit): boolean {
+  const ts = hitHeader(h, 'openwop-timestamp');
+  return ts !== undefined && hitHeader(h, 'openwop-signature') === `sha256=${createHmac('sha256', secret).update(`${ts}.${h.body}`, 'utf8').digest('hex')}`;
+}
+
+async function oneDelivery(rx: { hits: ModalHit[] }, webhookId: string): Promise<{ runStatus: number; delivery: ModalHit | undefined }> {
+  const run = await driveRun();
+  await waitFor(() => deliveriesFor(rx.hits, webhookId, run.runId).length > 0, 15_000);
+  return { runStatus: run.status, delivery: deliveriesFor(rx.hits, webhookId, run.runId)[0] };
+}
+
+describe('RFC 0201 §E — secret rotation overlaps, then retires (gated on webhooks.secretRotation)', () => {
+  it('a rotation dual-signs for overlapSeconds, keeps OpenWOP-Signature on the previous secret, and is tenant-checked', async () => {
+    const g = await swGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const rot = g.facet['secretRotation'] as { overlapSeconds?: unknown } | undefined;
+    if (!rot || typeof rot.overlapSeconds !== 'number') return softSkip('inapplicable', 'webhooks.secretRotation not advertised (RFC 0201 §E.18) — rotateWebhookSecret is not offered');
+    const overlapSeconds = rot.overlapSeconds;
+    const rx = await startModalReceiver();
+    closeReceiver = rx.close;
+    const target = rx.urlFor('echo');
+    const s1 = mintWhsec();
+    const s2 = mintWhsec();
+    const reg = await registerSw({ url: target.url, events: ['run.completed'], signatureAlgorithms: ['v1', STANDARD_WEBHOOKS_ALG], secret: s1 });
+    const blocked = loopbackRefusal(reg, target.tunnelled);
+    if (blocked) return softSkip('blocked', blocked);
+    if (reg.status !== 201) return softSkip('blocked', `the opt-in registration answered ${reg.status} ${readErrorCode(reg.json) ?? ''} — nothing to rotate`);
+    const webhookId = (reg.json as { webhookId: string }).webhookId;
+    const plain = await registerSw({ url: rx.urlFor('no-echo').url, events: ['run.completed'] });
+
+    const ID = 'openwop.requirement.0201.secret-rotation';
+    // Tenant check BEFORE lookup: a well-formed id in a tenant that is not the
+    // caller's, which therefore cannot exist for this caller.
+    const ownTenant = webhookId.slice(0, webhookId.indexOf('/'));
+    const foreign = `${ownTenant === 'openwop-conformance-foreign' ? 'openwop-conformance-other' : 'openwop-conformance-foreign'}/${'a'.repeat(22)}`;
+    const cross = await driver.post(`/webhooks/${projectBoundId(foreign)}/rotate-secret`, { secret: s2 });
+    expect(cross.status, req(ID, 'RFC 0201 §E.18 / identity.md §5', `a foreign-tenant webhookId MUST be refused 403 before the lookup (got ${cross.status})`)).toBe(403);
+    expect(readErrorCode(cross.json), req(ID, 'RFC 0201 §E.18', 'the foreign-tenant refusal MUST carry id_tenant_mismatch')).toBe('id_tenant_mismatch');
+    if (plain.status === 201) {
+      const plainId = (plain.json as { webhookId: string }).webhookId;
+      const notOpted = await driver.post(`/webhooks/${projectBoundId(plainId)}/rotate-secret`, { secret: s2 });
+      expect(notOpted.status, req(ID, 'RFC 0201 §E.18', `rotating a subscription that did not opt in MUST be refused 400 validation_error (got ${notOpted.status})`)).toBe(400);
+    }
+
+    const rotated = await driver.post(`/webhooks/${projectBoundId(webhookId)}/rotate-secret`, { secret: s2 });
+    expect(rotated.status, req(ID, 'RFC 0201 §E.18', `rotateWebhookSecret MUST answer 200 on an opted-in subscription (got ${rotated.status} ${readErrorCode(rotated.json) ?? ''})`)).toBe(200);
+    const body = rotated.json as { rotatedAt?: string; previousSecretExpiresAt?: string };
+    const span = Date.parse(body.previousSecretExpiresAt ?? '') - Date.parse(body.rotatedAt ?? '');
+    expect(Math.abs(span - overlapSeconds * 1000) <= 1000, req(ID, 'RFC 0201 §E.19', `previousSecretExpiresAt MUST be rotatedAt + overlapSeconds (${overlapSeconds}s; got ${span}ms)`)).toBe(true);
+    expect(rotated.text.includes(s2) || rotated.text.includes(s2.slice(6)), req(ID, 'RFC 0201 §E.19', 'the rotation response MUST carry no secret')).toBe(false);
+
+    const during = await oneDelivery(rx, webhookId);
+    expect(during.runStatus, req(ID, 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    expect(during.delivery, req(ID, 'webhooks.md §Durability', 'the rotated subscription MUST keep receiving deliveries')).toBeDefined();
+    const d = during.delivery!;
+    const underNew = verifyStandardWebhooks(d.body, d.headers, s2);
+    const underOld = verifyStandardWebhooks(d.body, d.headers, s1);
+    expect(underNew.entries.length, req(ID, 'RFC 0201 §E.20', `during the overlap webhook-signature MUST carry exactly two entries (got ${underNew.entries.length})`)).toBe(2);
+    expect(underNew.matched, req(ID, 'RFC 0201 §E.20', 'one entry MUST verify under the new secret')).toBe(1);
+    expect(underOld.matched, req(ID, 'RFC 0201 §E.20', 'one entry MUST verify under the previous secret')).toBe(1);
+    expect(v1SignedBy(s1, d), req(ID, 'RFC 0201 §E.20', 'OpenWOP-Signature MUST stay on the previous secret during the overlap')).toBe(true);
+
+    // After the overlap: only when it fits the operator's wait cap.
+    const expiresAt = Date.parse(body.previousSecretExpiresAt ?? '');
+    if (expiresAt - Date.now() > CAP_MS) {
+      return softSkip('inapplicable', `the post-overlap leg is not observed: overlapSeconds (${overlapSeconds}) exceeds the suite wait cap (${CAP_MS}ms; raise OPENWOP_WEBHOOK_RETRY_WAIT_MS to witness it)`);
+    }
+    await new Promise((r) => setTimeout(r, Math.max(0, expiresAt - Date.now()) + 1_500));
+    const after = await oneDelivery(rx, webhookId);
+    expect(after.delivery, req(ID, 'webhooks.md §Durability', 'the subscription MUST keep receiving deliveries after the overlap')).toBeDefined();
+    const a = after.delivery!;
+    const aNew = verifyStandardWebhooks(a.body, a.headers, s2);
+    expect(aNew.entries.length, req(ID, 'RFC 0201 §E.20', `after previousSecretExpiresAt webhook-signature MUST carry one entry (got ${aNew.entries.length})`)).toBe(1);
+    expect(aNew.matched, req(ID, 'RFC 0201 §E.20', 'the one entry MUST verify under the new secret')).toBe(1);
+    expect(verifyStandardWebhooks(a.body, a.headers, s1).matched, req(ID, 'RFC 0201 §E.20', 'the previous secret MUST NOT sign anything after previousSecretExpiresAt')).toBe(0);
+    expect(v1SignedBy(s2, a), req(ID, 'RFC 0201 §E.20', 'OpenWOP-Signature MUST move to the new secret at previousSecretExpiresAt')).toBe(true);
+  }, CAP_MS + 90_000);
+});

package/src/scenarios/v2-webhook-standard-webhooks-delivery.test.ts

@@ -0,0 +1,195 @@
+/**
+ * RFC 0201 §A–§C — the Standard Webhooks companion scheme on the wire
+ * (suite 2.36.0, target major 2; gated on `webhooks.signatureAlgorithms`
+ * listing `standard-webhooks-1`).
+ *
+ * Three legs, one requirement id each:
+ *
+ *   1. `opt-in-only` — a registration WITHOUT `signatureAlgorithms`, aimed at a
+ *      receiver that never echoes a challenge, still gets `201`; the receiver
+ *      sees no verification request; its deliveries carry no `webhook-*`
+ *      header. A host that verifies, or adds the headers for, everyone fails.
+ *   2. `registration-validated` — the opt-in is checked (no `v1`, a repeated
+ *      value, an unadvertised id, a missing / non-`whsec_` / 8-byte secret are
+ *      each `400 validation_error`), a valid opt-in's `201` echoes the applied
+ *      list, and no response body carries the secret or its key bytes.
+ *   3. `delivery-signed` — an opted-in delivery carries the five `OpenWOP-*`
+ *      headers verifying under scheme `v1` with `OpenWOP-Signature-Algorithm:
+ *      v1`, AND a `webhook-signature` entry verifying over
+ *      `{webhook-id}.{webhook-timestamp}.{rawBody}` with the decoded secret, a
+ *      `webhook-timestamp` equal to `OpenWOP-Timestamp`, and a `webhook-id`
+ *      that is not the subscription id. The verifier is the suite's own
+ *      (`webhook-receiver.ts`), pinned to the upstream library's test vector.
+ *
+ * How each FAILS (the sabotage run before citing a row):
+ *   (a) webhook-* added to every subscription            → leg 1
+ *   (b) verification run for a non-opted registration     → leg 1 (no-echo ⇒ 400)
+ *   (c) `webhook-signature` computed over `ts.body`        → leg 3
+ *   (d) `standard-webhooks-1` in OpenWOP-Signature-Algorithm → leg 3
+ *   (e) webhook-timestamp ≠ OpenWOP-Timestamp              → leg 3
+ *   (f) `["standard-webhooks-1"]` accepted without `v1`    → leg 2
+ *
+ * @see spec/v2/core/webhooks.md §Standard Webhooks
+ * @see RFCS/0201-standard-webhooks-signature-scheme.md §B, §C
+ */
+
+import { afterEach, describe, it, expect } from 'vitest';
+import { createHmac } from 'node:crypto';
+import { req } from '../lib/requirement-ids.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import {
+  decodeWhsec,
+  hitHeader,
+  mintWhsec,
+  startModalReceiver,
+  STANDARD_WEBHOOKS_ID,
+  verifyStandardWebhooks,
+} from '../lib/webhook-receiver.js';
+import {
+  STANDARD_WEBHOOKS_ALG,
+  deliveriesFor,
+  driveRun,
+  loopbackRefusal,
+  registerSw,
+  standardWebhooksHeaderNames,
+  swGate,
+  unregisterAllSw,
+  waitFor,
+} from '../lib/standard-webhooks.js';
+
+const DELIVERY_WAIT_MS = 15_000;
+
+let closeReceiver: (() => Promise<void>) | null = null;
+afterEach(async () => {
+  await unregisterAllSw();
+  if (closeReceiver) { const c = closeReceiver; closeReceiver = null; await c(); }
+});
+
+function v1Verifies(secret: string, h: { headers: Record<string, string | string[] | undefined>; body: string }): boolean {
+  const ts = hitHeader(h, 'openwop-timestamp');
+  const sig = hitHeader(h, 'openwop-signature');
+  if (ts === undefined || sig === undefined) return false;
+  return sig === `sha256=${createHmac('sha256', secret).update(`${ts}.${h.body}`, 'utf8').digest('hex')}`;
+}
+
+describe('RFC 0201 — Standard Webhooks companion scheme (gated on standard-webhooks-1)', () => {
+  it('a subscription that did not opt in is neither verified nor given webhook-* headers', async () => {
+    const g = await swGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const rx = await startModalReceiver();
+    closeReceiver = rx.close;
+    const target = rx.urlFor('no-echo');
+    const reg = await registerSw({ url: target.url, events: ['run.completed'] });
+    const blockedReg = loopbackRefusal(reg, target.tunnelled);
+    if (blockedReg) return softSkip('blocked', blockedReg);
+    const ID = 'openwop.requirement.0201.opt-in-only';
+    expect(
+      reg.status,
+      req(ID, 'RFC 0201 §B.8 / §D.15', `a registration without signatureAlgorithms MUST NOT be verified — against an endpoint that never echoes a challenge it MUST still answer 201 (got ${reg.status} ${readErrorCode(reg.json) ?? ''})`),
+    ).toBe(201);
+    const webhookId = (reg.json as { webhookId: string }).webhookId;
+    const run = await driveRun();
+    expect(run.status, req(ID, 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    await waitFor(() => deliveriesFor(rx.hits, webhookId, run.runId).length > 0, DELIVERY_WAIT_MS);
+    expect(
+      rx.hits.filter((h) => h.mode === 'no-echo' && h.verification).length,
+      req(ID, 'RFC 0201 §D.15', 'the receiver MUST see no verification request for a subscription that did not opt in'),
+    ).toBe(0);
+    const ours = deliveriesFor(rx.hits, webhookId, run.runId);
+    expect(ours.length, req(ID, 'webhooks.md §Durability', 'the host MUST deliver run.completed for this run to the registered subscriber (a leg with no delivery would witness nothing)')).toBeGreaterThan(0);
+    for (const d of ours) {
+      expect(
+        standardWebhooksHeaderNames(d),
+        req(ID, 'RFC 0201 §B.8', 'a delivery to a subscription that did not opt in MUST NOT carry any webhook-* header'),
+      ).toEqual([]);
+      expect(hitHeader(d, 'openwop-signature-algorithm'), req(ID, 'webhooks.md §Headers', 'OpenWOP-Signature-Algorithm stays v1')).toBe('v1');
+    }
+  }, 45_000);
+
+  it('the opt-in is validated, its 201 echoes the applied list, and no response carries the secret', async () => {
+    const g = await swGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const rx = await startModalReceiver();
+    closeReceiver = rx.close;
+    const target = rx.urlFor('echo');
+    const secret = mintWhsec();
+    const base = { url: target.url, events: ['run.completed'] };
+    const ID = 'openwop.requirement.0201.registration-validated';
+    const refusals: Array<[string, Record<string, unknown>]> = [
+      ['standard-webhooks-1 without v1', { ...base, signatureAlgorithms: [STANDARD_WEBHOOKS_ALG], secret }],
+      ['a repeated value', { ...base, signatureAlgorithms: ['v1', 'v1', STANDARD_WEBHOOKS_ALG], secret }],
+      ['an id the host does not list', { ...base, signatureAlgorithms: ['v1', 'openwop-conformance-unlisted-9'], secret }],
+      ['an opt-in with no secret', { ...base, signatureAlgorithms: ['v1', STANDARD_WEBHOOKS_ALG] }],
+      ['a secret not in whsec_ form', { ...base, signatureAlgorithms: ['v1', STANDARD_WEBHOOKS_ALG], secret: 'plain-shared-secret-of-sufficient-length' }],
+      ['a whsec_ secret of 8 bytes', { ...base, signatureAlgorithms: ['v1', STANDARD_WEBHOOKS_ALG], secret: `whsec_${Buffer.alloc(8, 7).toString('base64')}` }],
+    ];
+    const bodies: string[] = [];
+    for (const [label, body] of refusals) {
+      const res = await registerSw(body);
+      const blockedRes = loopbackRefusal(res, target.tunnelled);
+      if (blockedRes) return softSkip('blocked', blockedRes);
+      bodies.push(res.text);
+      expect(res.status, req(ID, 'RFC 0201 §B.5–§B.6', `${label} MUST be refused 400 validation_error (got ${res.status})`)).toBe(400);
+      expect(readErrorCode(res.json), req(ID, 'RFC 0201 §B.5–§B.6', `${label} MUST carry the code validation_error`)).toBe('validation_error');
+    }
+    const ok = await registerSw({ ...base, signatureAlgorithms: ['v1', STANDARD_WEBHOOKS_ALG], secret });
+    const blockedOk = loopbackRefusal(ok, target.tunnelled);
+    if (blockedOk) return softSkip('blocked', blockedOk);
+    bodies.push(ok.text);
+    expect(ok.status, req(ID, 'RFC 0201 §B / §D.14', `a valid opt-in against an echoing endpoint MUST answer 201 (got ${ok.status} ${readErrorCode(ok.json) ?? ''})`)).toBe(201);
+    const applied = (ok.json as { signatureAlgorithms?: unknown } | null)?.signatureAlgorithms;
+    expect(
+      Array.isArray(applied) ? [...(applied as string[])].sort() : applied,
+      req(ID, 'RFC 0201 §B.7', 'the 201 MUST carry signatureAlgorithms — the list the dispatcher will apply'),
+    ).toEqual(['standard-webhooks-1', 'v1']);
+    const key = decodeWhsec(secret)!;
+    const leaks = [secret, secret.slice('whsec_'.length), key.toString('hex'), key.toString('base64url')];
+    for (const b of bodies) {
+      for (const l of leaks) {
+        expect(b.includes(l), req(ID, 'RFC 0201 §B.6', 'the host MUST NOT return the supplied secret (or its key bytes) in any response')).toBe(false);
+      }
+    }
+  }, 45_000);
+
+  it('an opted-in delivery is dual-signed and its Standard Webhooks signature covers the id', async () => {
+    const g = await swGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const rx = await startModalReceiver();
+    closeReceiver = rx.close;
+    const target = rx.urlFor('echo');
+    const secret = mintWhsec();
+    const reg = await registerSw({ url: target.url, events: ['run.completed'], signatureAlgorithms: ['v1', STANDARD_WEBHOOKS_ALG], secret });
+    const blockedReg = loopbackRefusal(reg, target.tunnelled);
+    if (blockedReg) return softSkip('blocked', blockedReg);
+    const ID = 'openwop.requirement.0201.delivery-signed';
+    expect(reg.status, req(ID, 'RFC 0201 §B', `the opt-in registration MUST answer 201 (got ${reg.status} ${readErrorCode(reg.json) ?? ''})`)).toBe(201);
+    const webhookId = (reg.json as { webhookId: string }).webhookId;
+    const run = await driveRun();
+    expect(run.status, req(ID, 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
+    await waitFor(() => deliveriesFor(rx.hits, webhookId, run.runId).length > 0, DELIVERY_WAIT_MS);
+    const ours = deliveriesFor(rx.hits, webhookId, run.runId);
+    expect(ours.length, req(ID, 'webhooks.md §Durability', 'the host MUST deliver run.completed for this run to the opted-in subscriber')).toBeGreaterThan(0);
+    const d = ours[0]!;
+    expect(hitHeader(d, 'openwop-signature-algorithm'), req(ID, 'RFC 0201 §A.2', 'OpenWOP-Signature-Algorithm MUST stay v1 on an opted-in delivery (never standard-webhooks-1)')).toBe('v1');
+    for (const h of ['openwop-webhook-id', 'openwop-event-type', 'openwop-timestamp', 'openwop-signature']) {
+      expect(hitHeader(d, h), req(ID, 'RFC 0201 §C.9', `every header the host sends today MUST still be sent — ${h}`)).toBeDefined();
+    }
+    expect(v1Verifies(secret, d), req(ID, 'RFC 0201 §C.9', 'OpenWOP-Signature MUST verify under scheme v1 keyed by the secret string as issued')).toBe(true);
+    const wid = hitHeader(d, 'webhook-id');
+    expect(wid !== undefined && STANDARD_WEBHOOKS_ID.test(wid), req(ID, 'RFC 0201 §C.10', `webhook-id MUST match ^[A-Za-z0-9_-]{16,128}$ (got ${String(wid)})`)).toBe(true);
+    expect(wid, req(ID, 'RFC 0201 §C.11', 'webhook-id MUST NOT be the subscription id carried in OpenWOP-Webhook-Id')).not.toBe(hitHeader(d, 'openwop-webhook-id'));
+    expect(hitHeader(d, 'webhook-timestamp'), req(ID, 'RFC 0201 §C.9', 'webhook-timestamp MUST equal OpenWOP-Timestamp')).toBe(hitHeader(d, 'openwop-timestamp'));
+    const verdict = verifyStandardWebhooks(d.body, d.headers, secret);
+    expect(
+      verdict.matched,
+      req(ID, 'RFC 0201 §C.9', `at least one webhook-signature entry MUST verify over {webhook-id}.{webhook-timestamp}.{rawBody} with the decoded secret (verifier: ${verdict.reason ?? 'ok'}; ${verdict.entries.length} entr${verdict.entries.length === 1 ? 'y' : 'ies'})`),
+    ).toBeGreaterThan(0);
+    // The control that separates "signs the id" from "signs ts.body": the
+    // verifier recomputes over the id, so a host that left the id out of the
+    // signed bytes already failed above. Recompute with a different id and
+    // confirm it does NOT match, so the pass above is attributable to the id.
+    const forged = verifyStandardWebhooks(d.body, { ...d.headers, 'webhook-id': `${wid ?? ''}X` }, secret);
+    expect(forged.matched, req(ID, 'RFC 0201 §C.9', 'the signature MUST cover webhook-id — recomputing with a different id MUST NOT match')).toBe(0);
+  }, 45_000);
+});