@openwop/openwop-conformance 2.45.10 → 2.45.12

package/src/lib/trigger-delivery-witness.ts

@@ -0,0 +1,340 @@
+/**
+ * The trigger-bridge delivery witness on the normative surface (RFC 0230's
+ * signed ingest, RFC 0232's dead-letter read), shared by every major that
+ * serves it. What differs between majors — the subscription path, how an id
+ * becomes a path segment, event names, the page schema — is the profile row
+ * in `major-profile.ts`.
+ *
+ * Each leg OBSERVES and returns findings; it asserts nothing. The scenario file
+ * maps findings to requirement ids, and `trigger-delivery-witness.test.ts`
+ * proves every leg against a scratch double with one defect turned on.
+ *
+ * There is no seam path here. At major 2 no seam drives a trigger delivery, so
+ * a leg whose only surface is a seam is `inapplicable` (no party can cause the
+ * condition), never `blocked`.
+ *
+ * Today only `v2-trigger-bridge-delivery` and `v2-trigger-dead-letter-read` use
+ * it; the major-1 files keep their own inline legs, which the production hosts
+ * have already witnessed.
+ */
+
+import { driver } from './driver.js';
+import { readErrorCode } from './error-envelope.js';
+import type { MajorProfile } from './major-profile.js';
+import { freshWebhookId, standardWebhooksSignature } from './triggerBridge.js';
+import { freshCanary, judge as judgeDeadLetters, type DeadLetterRead } from './trigger-dead-letter-witness.js';
+
+export interface TriggerFinding {
+  readonly ok: boolean;
+  readonly doc: string;
+  readonly message: string;
+}
+export type LegOutcome =
+  | { readonly kind: 'skip'; readonly disposition: 'inapplicable' | 'blocked'; readonly reason: string }
+  | { readonly kind: 'observed'; readonly findings: readonly TriggerFinding[]; readonly note?: string };
+
+const isRecord = (v: unknown): v is Record<string, unknown> => v !== null && typeof v === 'object' && !Array.isArray(v);
+const f = (ok: boolean, doc: string, message: string): TriggerFinding => ({ ok, doc, message });
+
+/** What the host advertises for the trigger bridge at this major. */
+export interface TriggerAdverts {
+  readonly family: Record<string, unknown> | null;
+  readonly inboundSigning: boolean;
+  readonly deadLetter: { readonly retentionDays: number; readonly maxPageSize: number } | null;
+}
+
+export function adverts(profile: MajorProfile, doc: unknown): TriggerAdverts {
+  const family = profile.family(doc, 'triggerBridge');
+  const ingestion = isRecord(family?.['ingestion']) ? family!['ingestion'] as Record<string, unknown> : undefined;
+  const signing = ingestion?.['inboundSigning'];
+  const dl = isRecord(family?.['deadLetter']) ? family!['deadLetter'] as Record<string, unknown> : undefined;
+  return {
+    family,
+    inboundSigning: Array.isArray(signing) && signing.includes('standard-webhooks-1'),
+    deadLetter: dl !== undefined && typeof dl['retentionDays'] === 'number' && typeof dl['maxPageSize'] === 'number'
+      ? { retentionDays: dl['retentionDays'] as number, maxPageSize: dl['maxPageSize'] as number }
+      : null,
+  };
+}
+
+/** The gate every signed-path leg shares. */
+export function signedGate(a: TriggerAdverts): LegOutcome | null {
+  if (a.family === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host does not advertise triggerBridge' };
+  if (!a.inboundSigning) return { kind: 'skip', disposition: 'inapplicable', reason: 'triggerBridge.ingestion.inboundSigning does not list standard-webhooks-1, and no other wire surface delivers a trigger event at this major' };
+  return null;
+}
+
+export interface Sub { readonly subscriptionId: string; readonly ingestUrl: string; readonly signingSecret: string }
+
+async function register(profile: MajorProfile, mode: 'none' | 'required'): Promise<Sub | string> {
+  const res = await driver.post(profile.triggerSubscriptionsPath, { source: 'webhook', workflowId: 'conformance-noop', verification: { mode } });
+  const body = res.json as { subscription?: { subscriptionId?: unknown }; binding?: { ingestUrl?: unknown; signingSecret?: unknown } } | undefined;
+  const subscriptionId = body?.subscription?.subscriptionId;
+  const ingestUrl = body?.binding?.ingestUrl;
+  const signingSecret = body?.binding?.signingSecret;
+  if (res.status !== 201 || typeof subscriptionId !== 'string' || typeof ingestUrl !== 'string' || typeof signingSecret !== 'string') {
+    return `POST ${profile.triggerSubscriptionsPath} answered ${res.status} without the binding (subscriptionId, ingestUrl, signingSecret)`;
+  }
+  return { subscriptionId, ingestUrl, signingSecret };
+}
+
+async function ingest(sub: Sub, body: string, opts: { webhookId?: string; signature?: string; timestamp?: string } = {}): Promise<{ status: number; json: Record<string, unknown> | undefined }> {
+  const id = opts.webhookId ?? freshWebhookId();
+  const ts = opts.timestamp ?? String(Math.floor(Date.now() / 1000));
+  const sig = opts.signature ?? standardWebhooksSignature(sub.signingSecret, id, ts, body);
+  const res = await driver.post(sub.ingestUrl, body, {
+    authenticated: false,
+    headers: { 'Content-Type': 'application/json', 'webhook-id': id, 'webhook-timestamp': ts, 'webhook-signature': sig },
+  });
+  return { status: res.status, json: isRecord(res.json) ? res.json : undefined };
+}
+
+export const BAD_SIGNATURE = 'v1,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
+const DOC_INGEST = 'webhooks.md §Inbound triggers';
+
+/** A registration that did not yield the binding is a host defect on an advertised surface. */
+function bindingFinding(reason: string): LegOutcome {
+  return { kind: 'observed', findings: [f(false, DOC_INGEST, `a host advertising inboundSigning MUST return the binding on webhook registration: ${reason}`)] };
+}
+
+/** Leg 1: a repeated `webhook-id` is effectively-once. */
+export async function dedupLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  const sub = await register(profile, 'none'); if (typeof sub === 'string') return bindingFinding(sub);
+  const body = JSON.stringify({ conformance: 'dedup' });
+  const webhookId = freshWebhookId();
+  const first = await ingest(sub, body, { webhookId });
+  const runId = first.json?.['runId'];
+  const again = await ingest(sub, body, { webhookId });
+  return { kind: 'observed', findings: [
+    f(first.status === 202, DOC_INGEST, `a signed delivery MUST answer 202 (got ${first.status})`),
+    f(typeof runId === 'string' && runId.length > 0, DOC_INGEST, 'a 202 MUST carry the started runId'),
+    f(again.status === 200, DOC_INGEST, `a repeated webhook-id MUST answer 200, starting no new run (got ${again.status})`),
+    f(again.json?.['outcome'] === 'duplicate', DOC_INGEST, `the dedup no-op MUST say outcome "duplicate" (got ${String(again.json?.['outcome'])})`),
+    f(again.json?.['runId'] === runId, DOC_INGEST, 'a dedup no-op MUST return the prior runId'),
+  ] };
+}
+
+/** Leg 2: a refused post starts no run and does not change the subscription's state. */
+export async function refusedLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  const sub = await register(profile, 'required'); if (typeof sub === 'string') return bindingFinding(sub);
+  const body = JSON.stringify({ conformance: 'dead-letter' });
+  const bad = await ingest(sub, body, { signature: BAD_SIGNATURE });
+  const read = await driver.get(`${profile.triggerSubscriptionsPath}/${profile.idSegment(sub.subscriptionId)}`);
+  const state = (read.json as { subscription?: { state?: unknown } } | undefined)?.subscription?.state;
+  const ok = await ingest(sub, body);
+  return { kind: 'observed', findings: [
+    f(bad.status === 401, DOC_INGEST, `a bad signature under required verification MUST answer 401 (got ${bad.status})`),
+    f(readErrorCode(bad.json) === 'signature_invalid', DOC_INGEST, `the refusal MUST carry signature_invalid (got ${String(readErrorCode(bad.json))})`),
+    f(bad.json?.['runId'] === undefined, DOC_INGEST, 'a failed required check MUST NOT start a run'),
+    f(state === 'active', DOC_INGEST, `a refused event MUST NOT change the subscription's state (read answered ${read.status}, state ${String(state)})`),
+    f(ok.status === 202, DOC_INGEST, `after a refused post the subscription MUST still deliver a correctly signed one (got ${ok.status})`),
+  ] };
+}
+
+/** How far off the skew probes are: twice the 300 s bound, so ordinary clock drift cannot pass or fail them. */
+export const SKEW_PROBE_SECONDS = 600;
+
+/**
+ * Leg 2b (RFC 0230 §C): under `required`, a `webhook-timestamp` more than 300 s
+ * from the host's clock fails the check, in either direction, even when the
+ * signature over that timestamp is correct. The post starts no run and leaves
+ * the subscription `active`.
+ */
+export async function staleTimestampLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  const sub = await register(profile, 'required'); if (typeof sub === 'string') return bindingFinding(sub);
+  const body = JSON.stringify({ conformance: 'stale-timestamp' });
+  const now = Math.floor(Date.now() / 1000);
+  const findings: TriggerFinding[] = [];
+  for (const [label, ts] of [['stale', now - SKEW_PROBE_SECONDS], ['future', now + SKEW_PROBE_SECONDS]] as const) {
+    // Correctly signed over the skewed timestamp: only the skew can refuse it.
+    const res = await ingest(sub, body, { timestamp: String(ts) });
+    findings.push(
+      f(res.status === 401, DOC_INGEST, `a ${label} webhook-timestamp (${SKEW_PROBE_SECONDS} s off) under required verification MUST answer 401 (got ${res.status})`),
+      f(readErrorCode(res.json) === 'signature_invalid', DOC_INGEST, `the ${label}-timestamp refusal MUST carry signature_invalid (got ${String(readErrorCode(res.json))})`),
+      f(res.json?.['runId'] === undefined, DOC_INGEST, `a ${label}-timestamp post MUST NOT start a run`),
+    );
+  }
+  const read = await driver.get(`${profile.triggerSubscriptionsPath}/${profile.idSegment(sub.subscriptionId)}`);
+  const state = (read.json as { subscription?: { state?: unknown } } | undefined)?.subscription?.state;
+  const ok = await ingest(sub, body);
+  findings.push(
+    f(state === 'active', DOC_INGEST, `a skewed post MUST NOT change the subscription's state (read answered ${read.status}, state ${String(state)})`),
+    f(ok.status === 202, DOC_INGEST, `after the skewed posts the subscription MUST still deliver a current, correctly signed one (got ${ok.status})`),
+  );
+  return { kind: 'observed', findings };
+}
+
+/** True when `v` holds a `signingSecret` key at any depth. */
+function hasSecretKey(v: unknown): boolean {
+  if (Array.isArray(v)) return v.some(hasSecretKey);
+  if (!isRecord(v)) return false;
+  return Object.entries(v).some(([k, x]) => k === 'signingSecret' || hasSecretKey(x));
+}
+
+/**
+ * Leg 2c (RFC 0230 §B, SR-1): the `whsec_` secret is returned once, in the
+ * registration's binding, and never on a re-read of the subscription. A host
+ * that serves no re-read cannot return it there, so the leg is `inapplicable`.
+ */
+export async function signingSecretOnceLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  const sub = await register(profile, 'none'); if (typeof sub === 'string') return bindingFinding(sub);
+  const read = await driver.get(`${profile.triggerSubscriptionsPath}/${profile.idSegment(sub.subscriptionId)}`);
+  if (read.status === 404 || read.status === 405) {
+    return { kind: 'skip', disposition: 'inapplicable', reason: `the host serves no re-read of a trigger subscription at this major (GET answered ${read.status}), so no re-read can return the secret` };
+  }
+  const text = read.text;
+  const keyBytes = sub.signingSecret.replace(/^whsec_/, '');
+  return { kind: 'observed', findings: [
+    f(read.status === 200, DOC_INGEST, `the re-read of a subscription just registered MUST answer 200 when the host serves it (got ${read.status})`),
+    f(!hasSecretKey(read.json), DOC_INGEST, 'a re-read MUST NOT carry signingSecret'),
+    f(!text.includes(sub.signingSecret) && (keyBytes.length < 8 || !text.includes(keyBytes)), DOC_INGEST, 'a re-read MUST NOT carry the secret\'s value'),
+    f(!text.includes('whsec_'), DOC_INGEST, 'a re-read MUST NOT carry any whsec_ secret'),
+  ] };
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** Leg 3: the delivered run's `run.started` carries the delivery as `causationId`. */
+export async function causationLeg(profile: MajorProfile, a: TriggerAdverts, opts: { pollMs?: number; pollTries?: number } = {}): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  const sub = await register(profile, 'none'); if (typeof sub === 'string') return bindingFinding(sub);
+  const res = await ingest(sub, JSON.stringify({ conformance: 'causation' }));
+  const runId = res.json?.['runId'];
+  if (res.status !== 202 || typeof runId !== 'string' || runId.length === 0) {
+    return { kind: 'observed', findings: [f(false, DOC_INGEST, `a signed delivery MUST answer 202 with the started runId (got ${res.status} ${JSON.stringify(res.json ?? null).slice(0, 200)})`)] };
+  }
+  const startedType = profile.eventType('run.started');
+  const attemptType = profile.eventType('trigger.delivery.attempted');
+  if (startedType === undefined || attemptType === undefined) return { kind: 'skip', disposition: 'blocked', reason: 'the event codemap is not on disk in this layout, so this major\'s event names are unknown' };
+  let events: Array<Record<string, unknown>> = [];
+  let pollStatus = 0;
+  for (let i = 0; i < (opts.pollTries ?? 10); i++) {
+    const poll = await driver.get(`${profile.runsPath}/${profile.idSegment(runId)}/events/poll`);
+    pollStatus = poll.status;
+    events = ((poll.json as { events?: unknown } | undefined)?.events as Array<Record<string, unknown>> | undefined) ?? [];
+    if (events.some((e) => e['type'] === startedType)) break;
+    await sleep(opts.pollMs ?? 500);
+  }
+  const started = events.find((e) => e['type'] === startedType);
+  const causationId = started?.['causationId'];
+  const delivered = events.find((e) => e['type'] === attemptType && isRecord(e['payload']) && (e['payload'] as Record<string, unknown>)['outcome'] === 'delivered');
+  const findings = [
+    f(started !== undefined, 'webhooks.md §Inbound triggers', `a delivered run MUST emit ${startedType} (poll answered ${pollStatus}; saw ${events.map((e) => String(e['type'])).join(',') || 'none'})`),
+    f(typeof causationId === 'string' && causationId.length > 0, 'webhooks.md §Inbound triggers', `${startedType} MUST carry the delivery id as causationId`),
+  ];
+  if (delivered !== undefined) findings.push(f(causationId === delivered['eventId'], 'webhooks.md §Inbound triggers', `${startedType}.causationId MUST equal the delivered attempt's eventId`));
+  return { kind: 'observed', findings, note: delivered === undefined ? 'the delivered attempt event is not on the run log, so equality was not checked' : 'causationId equals the delivered attempt' };
+}
+
+/** GET one page of a subscription's dead letters at this major. Asserts nothing. */
+export async function readDeadLettersAt(profile: MajorProfile, subscriptionId: string, query: { limit?: number; cursor?: string } = {}, headers?: Record<string, string>): Promise<DeadLetterRead> {
+  const qs = new URLSearchParams();
+  if (query.limit !== undefined) qs.set('limit', String(query.limit));
+  if (query.cursor !== undefined) qs.set('cursor', query.cursor);
+  const suffix = qs.toString() === '' ? '' : `?${qs.toString()}`;
+  const res = await driver.get(`${profile.triggerSubscriptionsPath}/${profile.idSegment(subscriptionId)}/dead-letters${suffix}`, headers ? { headers } : {});
+  return { status: res.status, json: res.json };
+}
+
+/** Leg 4a: a dead-lettered (run-less) attempt is content-free, read through RFC 0232's read. */
+export async function runlessAttemptLeg(profile: MajorProfile, a: TriggerAdverts, validate: (page: unknown) => { ok: boolean; errors: string }): Promise<LegOutcome> {
+  const gate = signedGate(a); if (gate) return gate;
+  if (a.deadLetter === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'a dead-lettered attempt is on no run\'s log, and the host does not advertise triggerBridge.deadLetter, the only surface that reads it at this major' };
+  const sub = await register(profile, 'required'); if (typeof sub === 'string') return bindingFinding(sub);
+  const canary = freshCanary();
+  const bad = await ingest(sub, JSON.stringify({ conformance: 'runless-attempt', canary }), { signature: BAD_SIGNATURE });
+  const read = await readDeadLettersAt(profile, sub.subscriptionId);
+  const findings = [f(bad.status === 401, DOC_INGEST, `a bad signature under required verification MUST answer 401 (got ${bad.status})`)];
+  for (const j of judgeDeadLetters(read, { subscriptionId: sub.subscriptionId, canary, signature: BAD_SIGNATURE, signingSecret: sub.signingSecret, retentionDays: a.deadLetter.retentionDays }, validate)) {
+    findings.push(f(j.ok, DOC_INGEST, j.message));
+  }
+  return { kind: 'observed', findings, note: 'RFC 0232 dead-letter read' };
+}
+
+/** Leg 4b: a run-less state change. No surface causes one without a seam, and no seam exists at this major. */
+export function runlessStateChangeLeg(a: TriggerAdverts): LegOutcome {
+  if (a.family === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host does not advertise triggerBridge' };
+  return { kind: 'skip', disposition: 'inapplicable', reason: 'no wire surface causes a trigger subscription state change, and no seam drives one at this major (RFC 0232 §E, gap G2)' };
+}
+
+// ---------------------------------------------------------------------------
+// The read's own rules (RFC 0232 §B).
+// ---------------------------------------------------------------------------
+
+function readGate(a: TriggerAdverts): LegOutcome | null {
+  if (a.family === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host does not advertise triggerBridge' };
+  if (a.deadLetter === null) return { kind: 'skip', disposition: 'inapplicable', reason: 'the host does not advertise triggerBridge.deadLetter' };
+  if (!a.inboundSigning) return { kind: 'skip', disposition: 'inapplicable', reason: 'triggerBridge.deadLetter is advertised without inboundSigning, so the suite cannot cause a dead letter unaided' };
+  return null;
+}
+
+async function refusedTwice(profile: MajorProfile, n: number): Promise<Sub | string> {
+  const sub = await register(profile, 'required'); if (typeof sub === 'string') return sub;
+  for (let i = 0; i < n; i++) await ingest(sub, JSON.stringify({ conformance: 'dead-letter-read', i }), { signature: BAD_SIGNATURE });
+  return sub;
+}
+const deliveriesOf = (json: unknown): unknown[] => { const d = (json as { deliveries?: unknown } | undefined)?.deliveries; return Array.isArray(d) ? d : []; };
+const cursorOf = (json: unknown): unknown => (json as { nextCursor?: unknown } | undefined)?.nextCursor;
+
+export async function pagingLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = readGate(a); if (gate) return gate;
+  const sub = await refusedTwice(profile, 2); if (typeof sub === 'string') return bindingFinding(sub);
+  const first = await readDeadLettersAt(profile, sub.subscriptionId, { limit: 1 });
+  const cursor = cursorOf(first.json);
+  const second = typeof cursor === 'string' ? await readDeadLettersAt(profile, sub.subscriptionId, { limit: 1, cursor }) : undefined;
+  const big = await readDeadLettersAt(profile, sub.subscriptionId, { limit: a.deadLetter!.maxPageSize + 1 });
+  return { kind: 'observed', findings: [
+    f(first.status === 200, DOC_INGEST, `a host advertising triggerBridge.deadLetter MUST serve the read (got ${first.status})`),
+    f(deliveriesOf(first.json).length === 1, DOC_INGEST, `a page MUST NOT exceed limit (got ${deliveriesOf(first.json).length} for limit 1)`),
+    f(typeof cursor === 'string' && cursor.length > 0, DOC_INGEST, 'with two dead letters and limit 1, the page MUST carry nextCursor'),
+    f(second?.status === 200 && deliveriesOf(second.json).length === 1, DOC_INGEST, `the page's own cursor MUST continue to the second dead letter (got ${String(second?.status)})`),
+    f(big.status === 200, DOC_INGEST, `a limit above maxPageSize MUST be clamped, not refused (got ${big.status})`),
+  ] };
+}
+
+export async function cursorLeg(profile: MajorProfile, a: TriggerAdverts): Promise<LegOutcome> {
+  const gate = readGate(a); if (gate) return gate;
+  const subA = await refusedTwice(profile, 2); if (typeof subA === 'string') return bindingFinding(subA);
+  const page = await readDeadLettersAt(profile, subA.subscriptionId, { limit: 1 });
+  const cursor = cursorOf(page.json);
+  if (typeof cursor !== 'string' || cursor.length === 0) {
+    return { kind: 'observed', findings: [f(false, DOC_INGEST, `with two dead letters and limit 1, the page MUST carry nextCursor (read answered ${page.status})`)] };
+  }
+  const subB = await refusedTwice(profile, 1); if (typeof subB === 'string') return bindingFinding(subB);
+  const cross = await readDeadLettersAt(profile, subB.subscriptionId, { cursor });
+  return { kind: 'observed', findings: [
+    f(cross.status === 400, DOC_INGEST, `a cursor minted for another subscription MUST be refused 400 (got ${cross.status})`),
+    f(readErrorCode(cross.json) === 'validation_error', DOC_INGEST, `the refusal MUST carry validation_error (got ${String(readErrorCode(cross.json))})`),
+  ] };
+}
+
+export async function tenantLeg(profile: MajorProfile, a: TriggerAdverts, otherTenantKey: string | undefined, ownKey: string): Promise<LegOutcome> {
+  const gate = readGate(a); if (gate) return gate;
+  if (!otherTenantKey) return { kind: 'skip', disposition: 'blocked', reason: 'OPENWOP_TEST_TENANT_B_API_KEY (a credential bound to a second tenant) is not set — the cross-tenant read cannot run' };
+  if (otherTenantKey.trim() === ownKey) return { kind: 'skip', disposition: 'blocked', reason: 'OPENWOP_TEST_TENANT_B_API_KEY equals OPENWOP_API_KEY — the second credential must resolve to a DIFFERENT tenant, or the leg measures nothing' };
+  const sub = await refusedTwice(profile, 1); if (typeof sub === 'string') return bindingFinding(sub);
+  const foreign = await readDeadLettersAt(profile, sub.subscriptionId, {}, { Authorization: `Bearer ${otherTenantKey}` });
+  const unknown = await readDeadLettersAt(profile, `${sub.subscriptionId}-never-minted`);
+  const noDisclosure = f(!JSON.stringify(foreign.json ?? null).includes('verification_failed'), DOC_INGEST, 'a foreign read MUST NOT disclose a record');
+  const unknownFinding = f(unknown.status === 404, DOC_INGEST, `an id the host never minted MUST answer 404 (got ${unknown.status})`);
+  if (profile.foreignTenantRead === 'id_tenant_mismatch') {
+    // identity.md §5: a bound id whose tenant segment is not the caller's is
+    // refused 403 id_tenant_mismatch, before any lookup, so it discloses nothing.
+    return { kind: 'observed', findings: [
+      f(foreign.status === 403, 'identity.md §5', `another tenant's bound id MUST be refused 403 (got ${foreign.status})`),
+      f(readErrorCode(foreign.json) === 'id_tenant_mismatch', 'identity.md §5', `the refusal MUST carry id_tenant_mismatch (got ${String(readErrorCode(foreign.json))})`),
+      noDisclosure,
+      unknownFinding,
+    ] };
+  }
+  return { kind: 'observed', findings: [
+    f(foreign.status === 404, DOC_INGEST, `another tenant's read MUST answer 404 (got ${foreign.status})`),
+    noDisclosure,
+    unknownFinding,
+    f(readErrorCode(foreign.json) === readErrorCode(unknown.json), DOC_INGEST, 'a foreign id MUST be answered exactly as an unknown one'),
+  ] };
+}

package/src/lib/trigger-double.ts

@@ -0,0 +1,133 @@
+/**
+ * A scratch double for the trigger bridge's normative surface at major 2: the
+ * signed ingest (RFC 0230) and the dead-letter read (RFC 0232). Each self-test
+ * turns on ONE defect to show `trigger-delivery-witness.ts` convicts it, and a
+ * standalone instance lets the scenario files themselves be run against it.
+ *
+ * A test double, not a host: it executes nothing, and nothing it does is
+ * evidence about any implementation.
+ */
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { unprojectBoundId } from './bound-id.js';
+import { standardWebhooksSignature } from './triggerBridge.js';
+
+/** The credential the double treats as a second tenant. */
+export const OTHER_TENANT_KEY = 'tenant-b-key';
+
+export type TriggerDefect =
+  | 'none' | 'dedup-new-run' | 'refused-starts-run' | 'refused-changes-state' | 'no-causation'
+  | 'record-leaks-canary' | 'refused-not-recorded' | 'refused-records-state-change' | 'wrong-retention'
+  | 'limit-ignored' | 'cursor-not-bound' | 'tenant-leak' | 'tenant-404' | 'skew-accepted' | 'reread-leaks-secret';
+
+interface DoubleSub { id: string; n: number; mode: string; secret: string; state: string; seen: Map<string, string>; dead: Array<Record<string, unknown>> }
+
+export class TriggerDouble {
+  defect: TriggerDefect = 'none';
+  url = '';
+  private server: Server | undefined;
+  private subs = new Map<string, DoubleSub>();
+  private runs = new Map<string, Array<Record<string, unknown>>>();
+  private seq = 0;
+  discovery: Record<string, unknown> = { triggerBridge: { status: 'experimental', since: '2.45', witness: 'self', ingestion: { inboundSigning: ['standard-webhooks-1'] }, deadLetter: { retentionDays: 7, maxPageSize: 100 } } };
+
+  async start(): Promise<string> {
+    this.server = createServer((req, res) => { void this.handle(req, res); });
+    await new Promise<void>((r) => this.server!.listen(0, '127.0.0.1', r));
+    this.url = `http://127.0.0.1:${(this.server.address() as AddressInfo).port}`;
+    return this.url;
+  }
+  async stop(): Promise<void> { const s = this.server; if (s) { s.closeAllConnections(); await new Promise<void>((r) => s.close(() => r())); } }
+  reset(defect: TriggerDefect): void { this.defect = defect; this.subs.clear(); this.runs.clear(); }
+
+  private id(prefix: string): string { return `acme/${prefix}-${String(++this.seq).padStart(16, '0')}`; }
+  private send(res: ServerResponse, status: number, body: unknown): void { res.writeHead(status, { 'content-type': 'application/json' }); res.end(JSON.stringify(body)); }
+  private async raw(req: IncomingMessage): Promise<string> { const c: Buffer[] = []; for await (const x of req) c.push(x as Buffer); return Buffer.concat(c).toString('utf8'); }
+
+  private startRun(sub: DoubleSub): string {
+    const runId = this.id('run');
+    const attemptId = `evt${String(++this.seq).padStart(16, '0')}`;
+    this.runs.set(runId, [
+      { eventId: attemptId, type: 'trigger.delivery-attempted', payload: { subscriptionId: sub.id, dedupKey: 'opaque', attempt: 1, outcome: 'delivered', runId }, sequence: 1 },
+      { eventId: `evt${String(++this.seq).padStart(16, '0')}`, type: 'run.started', ...(this.defect === 'no-causation' ? {} : { causationId: attemptId }), payload: {}, sequence: 2 },
+    ]);
+    return runId;
+  }
+
+  private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const u = new URL(req.url ?? '/', 'http://x');
+    const path = u.pathname;
+    if (req.method === 'GET' && path === '/.well-known/openwop') return this.send(res, 200, this.discovery);
+
+    if (req.method === 'POST' && path === '/trigger-subscriptions') {
+      const body = JSON.parse(await this.raw(req) || '{}') as { verification?: { mode?: string } };
+      const n = this.subs.size + 1;
+      const sub: DoubleSub = { id: this.id('sub'), n, mode: body.verification?.mode ?? 'none', secret: `whsec_${Buffer.from(`secret-${n}-bytes`).toString('base64')}`, state: 'active', seen: new Map(), dead: [] };
+      this.subs.set(sub.id, sub);
+      return this.send(res, 201, { subscription: { subscriptionId: sub.id, source: 'webhook', state: 'active' }, binding: { ingestUrl: `${this.url}/ingest/${n}`, signingSecret: sub.secret } });
+    }
+
+    const ing = /^\/ingest\/(\d+)$/.exec(path);
+    if (req.method === 'POST' && ing) {
+      const sub = [...this.subs.values()].find((s) => s.n === Number(ing[1]));
+      if (!sub) return this.send(res, 404, { error: 'not_found', message: 'no ingest' });
+      const body = await this.raw(req);
+      const id = String(req.headers['webhook-id'] ?? ''); const ts = String(req.headers['webhook-timestamp'] ?? '');
+      // RFC 0230 §C: a timestamp more than 300 s from the clock fails the check, however well signed.
+      const fresh = Math.abs(Date.now() / 1000 - Number(ts)) <= 300 || this.defect === 'skew-accepted';
+      const good = fresh && req.headers['webhook-signature'] === standardWebhooksSignature(sub.secret, id, ts, body);
+      if (!good && sub.mode === 'required') {
+        if (this.defect !== 'refused-not-recorded') {
+          const at = Date.now();
+          sub.dead.unshift({
+            subscriptionId: sub.id, attemptEventId: `evt${String(++this.seq).padStart(16, '0')}`,
+            attempt: { subscriptionId: sub.id, dedupKey: 'opaque', attempt: 1, outcome: 'dead-lettered' },
+            reason: 'verification_failed',
+            deadLetteredAt: new Date(at).toISOString(),
+            expiresAt: new Date(at + (this.defect === 'wrong-retention' ? 1 : 7) * 86_400_000).toISOString(),
+            ...(this.defect === 'record-leaks-canary' ? { body } : {}),
+            ...(this.defect === 'refused-records-state-change' ? { stateChange: { subscriptionId: sub.id, source: 'webhook', fromState: 'active', toState: 'failed', reason: 'signature-invalid' } } : {}),
+          });
+        }
+        if (this.defect === 'refused-changes-state') sub.state = 'failed';
+        return this.send(res, 401, { error: 'signature_invalid', message: 'bad signature', ...(this.defect === 'refused-starts-run' ? { runId: this.startRun(sub) } : {}) });
+      }
+      const prior = sub.seen.get(id);
+      if (prior !== undefined && this.defect !== 'dedup-new-run') return this.send(res, 200, { outcome: 'duplicate', runId: prior });
+      const runId = this.startRun(sub);
+      sub.seen.set(id, runId);
+      return this.send(res, 202, { outcome: 'delivered', runId });
+    }
+
+    const poll = /^\/runs\/([^/]+)\/events\/poll$/.exec(path);
+    if (req.method === 'GET' && poll) {
+      const events = this.runs.get(unprojectBoundId(poll[1]!));
+      return events ? this.send(res, 200, { events }) : this.send(res, 404, { error: 'not_found', message: 'no run' });
+    }
+
+    const m = /^\/trigger-subscriptions\/([^/]+)(\/dead-letters)?$/.exec(path);
+    if (req.method === 'GET' && m) {
+      const auth = String(req.headers['authorization'] ?? '');
+      const sub = this.subs.get(unprojectBoundId(m[1]!));
+      // identity.md §5: tenant B reading acme's bound id is refused 403 before any lookup.
+      if (auth === `Bearer ${OTHER_TENANT_KEY}` && this.defect === 'tenant-404') return this.send(res, 404, { error: 'not_found', message: 'no such subscription' });
+      if (auth === `Bearer ${OTHER_TENANT_KEY}` && this.defect !== 'tenant-leak') return this.send(res, 403, { error: 'id_tenant_mismatch', message: 'tenant segment is not the caller\'s' });
+      if (!sub) return this.send(res, 404, { error: 'not_found', message: 'no such subscription' });
+      if (!m[2]) return this.send(res, 200, { subscription: { subscriptionId: sub.id, source: 'webhook', state: sub.state, ...(this.defect === 'reread-leaks-secret' ? { signingSecret: sub.secret } : {}) } });
+      const limit = Math.min(Number(u.searchParams.get('limit') ?? '100'), 100);
+      const cursor = u.searchParams.get('cursor');
+      let offset = 0;
+      if (cursor !== null) {
+        const [cid, off] = Buffer.from(cursor, 'base64url').toString('utf8').split('|');
+        if (cid !== sub.id && this.defect !== 'cursor-not-bound') return this.send(res, 400, { error: 'validation_error', message: 'cursor is for another subscription' });
+        offset = Number(off);
+      }
+      const size = this.defect === 'limit-ignored' ? sub.dead.length : limit;
+      const page = sub.dead.slice(offset, offset + size);
+      const next = offset + size < sub.dead.length ? Buffer.from(`${sub.id}|${offset + size}`).toString('base64url') : undefined;
+      return this.send(res, 200, { deliveries: page, ...(next ? { nextCursor: next } : {}) });
+    }
+    return this.send(res, 404, { error: 'not_found', message: `no route ${req.method} ${path}` });
+  }
+}

package/src/scenarios/trigger-bridge-delivery.test.ts

@@ -6,11 +6,18 @@
  * under `OPENWOP_REQUIRE_BEHAVIOR=true`. The always-on wire-shape coverage lives
  * in `trigger-bridge-shape.test.ts`.
  *
- * Five legs, each its own requirement (RFC 0230 split the one combined `it`;
- * RFC 0232 split the fourth):
+ * Seven legs, each its own requirement (RFC 0230 split the one combined `it`;
+ * RFC 0232 split the fourth; 2.45.12 added 2b and 2c):
  *
  *   1. DEDUP (§C-1) — a repeated delivery is effectively-once.
  *   2. DEAD-LETTER (§C-2 + RFC 0053) — an exhausted/refused delivery starts no run.
+ *   2b. STALE TIMESTAMP (RFC 0230 §C) — under `required`, a `webhook-timestamp`
+ *      more than 300 s off, either way, answers `401 signature_invalid`, starts
+ *      no run and leaves the subscription `active`.
+ *   2c. SECRET ONCE (RFC 0230 §B, SR-1) — a re-read of the subscription carries
+ *      no `signingSecret` and no `whsec_` value.
+ *   Legs 2b and 2c have only the normative-surface path: they are
+ *   `inapplicable` on a host that does not advertise `inboundSigning`.
  *   3. CAUSATION (§C / RFC 0040) — a delivered run carries the delivery as
  *      `run.started.causationId`.
  *   4a. RUN-LESS ATTEMPT (SR-1) — a dead-lettered `trigger.delivery.attempted`
@@ -71,10 +78,23 @@ import { deadLetterFacet, freshCanary, judge as judgeDeadLetters, readDeadLetter
 
 const R_DEDUP = 'openwop.requirement.0083.trigger-delivery.dedup';
 const R_DEAD_LETTER = 'openwop.requirement.0083.trigger-delivery.dead-letter';
+const R_STALE_TIMESTAMP = 'openwop.requirement.0230.stale-timestamp-refused';
+const R_SECRET_ONCE = 'openwop.requirement.0230.signing-secret-once';
 const R_CAUSATION = 'openwop.requirement.0083.trigger-delivery.causation';
 const R_RUNLESS_ATTEMPT = 'openwop.requirement.0083.trigger-delivery.runless-attempt-content-free';
 const R_RUNLESS_STATE = 'openwop.requirement.0083.trigger-delivery.runless-state-change-content-free';
 
+/** How far off the skew probes are: twice the 300 s bound, so ordinary clock drift cannot pass or fail them. */
+const SKEW_PROBE_SECONDS = 600;
+const NO_SIGNING = 'the host does not advertise triggerBridge.ingestion.inboundSigning ["standard-webhooks-1"]: this rule binds only the RFC 0230 signed ingest, and no seam path witnesses it';
+
+/** True when `v` holds a `signingSecret` key at any depth. */
+function hasSecretKey(v: unknown): boolean {
+  if (Array.isArray(v)) return v.some(hasSecretKey);
+  if (v === null || typeof v !== 'object') return false;
+  return Object.entries(v as Record<string, unknown>).some(([k, x]) => k === 'signingSecret' || hasSecretKey(x));
+}
+
 /** The bad signature every refused-post probe sends. */
 const BAD_SIGNATURE = 'v1,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=';
 
@@ -215,6 +235,45 @@ describe('trigger-bridge-delivery (RFC 0083 §C)', () => {
     notePaths(paths.seam, true);
   });
 
+  it('refuses a webhook-timestamp more than 300 s off without starting a run', async () => {
+    if (!behaviorGate('openwop-trigger-bridge', await isTriggerBridgeProfileAdvertised())) return;
+    if (!(await inboundSigningAdvertised())) return softSkip('inapplicable', NO_SIGNING);
+    const sub = await registerSignedWebhook('required');
+    if ('reason' in sub) throw new Error(req(R_STALE_TIMESTAMP, 'trigger-bridge.md §F.6', `an inboundSigning host MUST return the §B binding on webhook registration: ${sub.reason}`));
+    const body = JSON.stringify({ conformance: 'stale-timestamp' });
+    const now = Math.floor(Date.now() / 1000);
+    for (const [label, ts] of [['stale', now - SKEW_PROBE_SECONDS], ['future', now + SKEW_PROBE_SECONDS]] as const) {
+      // Correctly signed over the skewed timestamp: only the skew can refuse it.
+      const res = await signedIngest(sub, body, { timestamp: String(ts) });
+      expect(res.status, req(R_STALE_TIMESTAMP, 'trigger-bridge.md §F.6', `a ${label} webhook-timestamp (${SKEW_PROBE_SECONDS} s off) under required verification MUST answer 401 (got ${res.status})`)).toBe(401);
+      expect((res.json as { error?: unknown } | undefined)?.error, req(R_STALE_TIMESTAMP, 'trigger-bridge.md §F.6', `the ${label}-timestamp refusal MUST carry signature_invalid`)).toBe('signature_invalid');
+      expect(res.json?.runId, req(R_STALE_TIMESTAMP, 'trigger-bridge.md §F.6', `a ${label}-timestamp post MUST NOT start a run`)).toBeUndefined();
+    }
+    const read = await driver.get(`/v1/trigger-subscriptions/${encodeURIComponent(sub.subscriptionId)}`);
+    const state = (read.json as { subscription?: { state?: unknown } } | undefined)?.subscription?.state;
+    expect(state, req(R_STALE_TIMESTAMP, 'trigger-bridge.md §F.6 (RFC 0230 §C.1)', `a skewed post MUST NOT change the subscription's state (read answered ${read.status}, state ${String(state)})`)).toBe('active');
+    const ok = await signedIngest(sub, body);
+    expect(ok.status, req(R_STALE_TIMESTAMP, 'trigger-bridge.md §F.6', `after the skewed posts the subscription MUST still deliver a current, correctly signed one (got ${ok.status})`)).toBe(202);
+    notePaths(false, true);
+  });
+
+  it('returns the signing secret once: a re-read carries no whsec_ value', async () => {
+    if (!behaviorGate('openwop-trigger-bridge', await isTriggerBridgeProfileAdvertised())) return;
+    if (!(await inboundSigningAdvertised())) return softSkip('inapplicable', NO_SIGNING);
+    const sub = await registerSignedWebhook('none');
+    if ('reason' in sub) throw new Error(req(R_SECRET_ONCE, 'trigger-bridge.md §F.6', `an inboundSigning host MUST return the §B binding on webhook registration: ${sub.reason}`));
+    const read = await driver.get(`/v1/trigger-subscriptions/${encodeURIComponent(sub.subscriptionId)}`);
+    if (read.status === 404 || read.status === 405) {
+      return softSkip('inapplicable', `the host serves no re-read of a trigger subscription (GET answered ${read.status}), so no re-read can return the secret`);
+    }
+    const keyBytes = sub.signingSecret.replace(/^whsec_/, '');
+    expect(read.status, req(R_SECRET_ONCE, 'trigger-bridge.md §F.6', `the re-read of a subscription just registered MUST answer 200 when the host serves it (got ${read.status})`)).toBe(200);
+    expect(hasSecretKey(read.json), req(R_SECRET_ONCE, 'trigger-bridge.md §F.6 (SR-1)', 'a re-read MUST NOT carry signingSecret')).toBe(false);
+    expect(read.text.includes(sub.signingSecret) || (keyBytes.length >= 8 && read.text.includes(keyBytes)), req(R_SECRET_ONCE, 'trigger-bridge.md §F.6 (SR-1)', 'a re-read MUST NOT carry the secret\'s value')).toBe(false);
+    expect(read.text.includes('whsec_'), req(R_SECRET_ONCE, 'trigger-bridge.md §F.6 (SR-1)', 'a re-read MUST NOT carry any whsec_ secret')).toBe(false);
+    notePaths(false, true);
+  });
+
   it('links delivery→run causation on run.started', async () => {
     if (!behaviorGate('openwop-trigger-bridge', await isTriggerBridgeProfileAdvertised())) return;
     const paths = await witnessPaths();

package/src/scenarios/v2-advertised-path-space-served.test.ts

@@ -135,6 +135,15 @@ describe('v2-advertised-path-space-served (RFC 0172 §A.1)', () => {
     if (!new Set(versions.map((v) => v.split('.')[0])).has('2')) {
       return softSkip('inapplicable', `the host advertises [${versions.join(', ') || 'no protocolVersions'}] — it does not claim major 2, so there is no path space to hold it to`);
     }
+    // versioning.md §1.2's obligation is an OVERLAP rule: reach under major 2
+    // what the host already serves under /v1. A host whose protocolVersions[]
+    // carries no 1.x member has retired /v1 (§5 "Retirement is atomic"), so
+    // nothing is served there and there is nothing to pair. Until 2.45.12 a
+    // retired host failed this leg: every /v1 path answers 410 there, and the
+    // leg read 410 as "served under /v1" (openwop-app's v1-cut rehearsal).
+    if (!new Set(versions.map((v) => v.split('.')[0])).has('1')) {
+      return softSkip('inapplicable', `the host advertises [${versions.join(', ')}] with no 1.x member — /v1 is retired (versioning.md §5), so there is no /v1 surface to pair`);
+    }
 
     const paths = parameterlessGets();
     if (paths.length === 0) return softSkip('blocked', 'spec/v2/path-manifest.json is unreadable from this layout');
@@ -146,8 +155,9 @@ describe('v2-advertised-path-space-served (RFC 0172 §A.1)', () => {
       const v1 = await get(`/v1${path}`, false);
       if (v1.status === null) return softSkip('blocked', `the host became unreachable while probing /v1${path}`);
       // The host does not serve this surface in EITHER major. Legitimate, and a
-      // different question from the one asked here.
-      if (v1.status === 404) continue;
+      // different question from the one asked here. 410 Gone says the same of
+      // /v1 (RFC 9110 §15.5.11: no longer available), so it is not a pair either.
+      if (v1.status === 404 || v1.status === 410) continue;
       pairable += 1;
 
       const v2 = await get(path, true);