@openwop/openwop-conformance 2.32.0 → 2.33.1

package/src/scenarios/v2-webhook-delivery-shape.test.ts

@@ -115,9 +115,32 @@ async function register(url: string, major: 1 | 2): Promise<string | null> {
   }
   expect(reg.status, req(ID, 'webhooks.md §Surfaces', 'POST /webhooks MUST answer 201 { webhookId }')).toBe(201);
   const id = (reg.json as { webhookId?: unknown } | null)?.webhookId;
+  if (typeof id === 'string') registered.push({ id, major });
   return typeof id === 'string' ? id : null;
 }
 
+/**
+ * Every subscription this file registers, unregistered after the leg that made
+ * it. Until 2.33.1 NOTHING here was ever unregistered. On loopback that was
+ * invisible: each leg's receiver bound its own ephemeral port, so a leftover
+ * subscription delivered to a dead address. Behind a public front every leg
+ * shares ONE URL on ONE pinned port - so leg 1's still-live MAJOR-2
+ * subscription delivered its v2 rendering into leg 2, and the major-1 leg read
+ * it and failed a host that had rendered both contracts correctly ("a major-1
+ * run.started payload MUST validate against the V1 definition … engineVersion
+ * must be string"). Found on the v2 reference host's first relaxation-free cut;
+ * reproduced with no ingress at all by pinning OPENWOP_WEBHOOK_RECEIVER_PORT on
+ * a loopback run. It also left a live subscription on every host this file ever
+ * ran against.
+ */
+const registered: Array<{ id: string; major: 1 | 2 }> = [];
+async function unregisterAll(): Promise<void> {
+  for (const r of registered.splice(0)) {
+    const path = `${r.major === 2 ? '' : '/v1'}/webhooks/${encodeURIComponent(r.id)}`;
+    try { await driver.delete(path, { headers: { 'OpenWOP-Version': r.major === 2 ? '2.0' : '1.0' } }); } catch { /* best effort: the leg's verdict is already recorded */ }
+  }
+}
+
 async function driveRun(): Promise<string> {
   const create = await driver.post('/runs', { workflowId: FIXTURE });
   expect(create.status, req(ID, 'runs.md §Create', 'POST /runs MUST answer 201 for the noop fixture')).toBe(201);
@@ -135,10 +158,21 @@ async function waitFor<T>(fn: () => T | undefined, ms: number): Promise<T | unde
  * receive the bare opaque id (versioning.md §5), so the match is on the segment
  * both spellings share.
  */
-function deliveryFor(deliveries: Delivery[], runId: string): { event: Record<string, unknown>; envelope: Record<string, unknown> } | undefined {
+/** The subscription a delivery says it belongs to, from either header family; undefined when it carries neither. */
+function subscriptionOf(d: Delivery): string | undefined {
+  const h = d.headers['openwop-webhook-id'] ?? d.headers['x-openwop-webhook-id'];
+  return typeof h === 'string' ? h : Array.isArray(h) ? h[0] : undefined;
+}
+const bare = (id: string): string => (id.includes('/') ? id.slice(id.indexOf('/') + 1) : id);
+
+function deliveryFor(deliveries: Delivery[], runId: string, webhookId?: string): { event: Record<string, unknown>; envelope: Record<string, unknown> } | undefined {
   const opaque = runId.includes('/') ? runId.slice(runId.indexOf('/') + 1) : runId;
   for (const d of deliveries) {
     if (!d.body.includes(opaque)) continue;
+    // Belt and braces beside unregisterAll(): a delivery that NAMES another
+    // subscription is not this leg's, whatever URL it arrived on.
+    const sub = subscriptionOf(d);
+    if (webhookId !== undefined && sub !== undefined && bare(sub) !== bare(webhookId)) continue;
     let parsed: unknown;
     try { parsed = JSON.parse(d.body); } catch { continue; }
     if (parsed === null || typeof parsed !== 'object') continue;
@@ -181,15 +215,16 @@ const V1 = 'https://openwop.dev/spec/v1/';
 
 describe('webhook delivery shape is per-contract (webhooks.md §Delivery, versioning.md §1.2)', () => {
   let active: Server | null = null;
-  afterEach(async () => { const s = active; active = null; if (s) await new Promise<void>((r) => s.close(() => r())); });
+  afterEach(async () => { await unregisterAll(); const s = active; active = null; if (s) await new Promise<void>((r) => s.close(() => r())); });
 
   it('a major-2 subscriber receives the v2 rendering: the delivery validates, and run.started.owner carries subject, never principal', async () => {
     if (!(await v2Discovery())) return softSkip('blocked', 'v2 discovery unreachable');
     if (!(await gateFamily('webhooks'))) return softSkip('inapplicable', 'webhooks family not advertised (gate recorded under openwop.family.webhooks)');
     const receiver = await startReceiver(); active = receiver.server;
-    if ((await register(receiver.url, 2)) === null) return softSkip('blocked', 'registration refused (reason recorded above)');
+    const webhookId = await register(receiver.url, 2);
+    if (webhookId === null) return softSkip('blocked', 'registration refused (reason recorded above)');
     const runId = await driveRun();
-    const d = await waitFor(() => deliveryFor(receiver.deliveries, runId), 15_000);
+    const d = await waitFor(() => deliveryFor(receiver.deliveries, runId, webhookId), 15_000);
     if (!d) return softSkip('blocked', `no ${EVENT_TYPE} delivery for this run arrived inside 15s — durability is v2-webhook-durable-delivery's claim, not this file's`);
     const v2 = validators(2);
     const envelope = v2.ref(`${V2}webhook-delivery.schema.json`)(d.envelope);
@@ -211,9 +246,10 @@ describe('webhook delivery shape is per-contract (webhooks.md §Delivery, versio
     const versions = Array.isArray(disc?.['protocolVersions']) ? (disc?.['protocolVersions'] as unknown[]).map(String) : [];
     if (!versions.some((v) => v.startsWith('1.'))) return softSkip('inapplicable', `host advertises [${versions.join(', ') || 'no protocolVersions'}] — no 1.x member, so there is no v1 wire to keep still`);
     const receiver = await startReceiver(); active = receiver.server;
-    if ((await register(receiver.url, 1)) === null) return softSkip('blocked', 'registration refused or inapplicable (disposition recorded above)');
+    const webhookId = await register(receiver.url, 1);
+    if (webhookId === null) return softSkip('blocked', 'registration refused or inapplicable (disposition recorded above)');
     const runId = await driveRun();
-    const d = await waitFor(() => deliveryFor(receiver.deliveries, runId), 15_000);
+    const d = await waitFor(() => deliveryFor(receiver.deliveries, runId, webhookId), 15_000);
     if (!d) return softSkip('blocked', `no ${EVENT_TYPE} delivery for this run arrived inside 15s`);
     // The v1 definition is the discriminator, not the owner's keys: v1's owner admits `subject` (RFC 0165
     // §B, echoed verbatim when present) alongside `principal`, so a v2 owner is ALSO a valid v1 owner.
@@ -234,11 +270,12 @@ describe('webhook delivery shape is per-contract (webhooks.md §Delivery, versio
     const gate = era2Gate(disc);
     if (gate !== null && !gate.ok) return softSkip(gate.kind, gate.reason);
     const receiver = await startReceiver(); active = receiver.server;
-    if ((await register(receiver.url, 2)) === null) return softSkip('blocked', 'registration refused (reason recorded above)');
+    const webhookId = await register(receiver.url, 2);
+    if (webhookId === null) return softSkip('blocked', 'registration refused (reason recorded above)');
     const log = await seedEra2Log(v1FixtureLog(FIXTURE), 'completed');
     if (!log.ok) return softSkip(log.kind, log.reason);
     const runId = log.runId;
-    const d = await waitFor(() => deliveryFor(receiver.deliveries, runId), 15_000);
+    const d = await waitFor(() => deliveryFor(receiver.deliveries, runId, webhookId), 15_000);
     // The seam appends HISTORY — rows that already happened — and a host MAY not fan out history (the
     // reference host's seam appends with fan-out suppressed by design). No delivery inside 15s means the
     // era-2 fan-out branch is unobservable on this host, not that a measurement failed: inapplicable.

package/src/scenarios/v2-webhook-egress-refusal.test.ts

@@ -0,0 +1,115 @@
+/**
+ * v2-webhook-egress-refusal — the webhook egress guard REFUSES, at major 2.
+ *
+ * `spec/v2/core/webhooks.md` §SSRF: "At registration a host MUST reject (`400
+ * webhook_url_rejected`) non-`https://` URLs, RFC 1918 and loopback and
+ * link-local ranges, IPv6 ULA, cloud metadata hosts, and `localhost`."
+ *
+ * ── Why this file exists ─────────────────────────────────────────────────────
+ * Until 2.33.0 NO major-2 row asserted that sentence. The scenarios that do
+ * (`http-client-ssrf`, `webhook-negative`) are registered at major 1 only, and
+ * the three major-2 files that name `webhook_url_rejected` name it only as the
+ * soft-skip taken when a host refuses the suite's own receiver. So a v2 bundle
+ * could certify `openwop-core-standard` — the profile built on `webhooks` — on a
+ * host whose guard refused nothing at all.
+ *
+ * It was found the expensive way: the steward's own reference host had been
+ * cutting its certified bundles with the guard open (`OPENWOP_WEBHOOK_ALLOW_PRIVATE`,
+ * because every suite fixture was a loopback listener) and recording no
+ * relaxation, which `security-defaults.md` §Relaxations forbids. Nothing in the
+ * suite could see it. `conformance/README.md` even said so: "the suite cannot
+ * detect an undeclared one." For THIS relaxation that was never true — a host
+ * that accepts `https://127.0.0.1/…` has shown on the wire that its guard is open.
+ *
+ * ── The three outcomes ───────────────────────────────────────────────────────
+ *   every probe refused              → executed-pass. The guard holds.
+ *   a probe ACCEPTED, relaxation
+ *     DECLARED (OPENWOP_HOST_RELAXATIONS
+ *     names a `webhooks.*` obligation) → inapplicable, with the declaration
+ *                                        quoted. The bundle carries
+ *                                        `host.relaxations[]` and the owning
+ *                                        profile is denied by that (RFC 0173 §A.2).
+ *   a probe ACCEPTED, nothing declared → executed-FAIL — and the emitter and
+ *                                        verifier deny every profile that owns
+ *                                        `webhooks` (`lib/v2-profiles.ts`
+ *                                        `profilesDeniedByObservedRelaxation`).
+ *
+ * Registration-time only, by design: every probe is a destination the suite
+ * does not own, so nothing is ever delivered and an accepted registration is
+ * deleted at once. Delivery-time re-resolution is a separate MUST that needs a
+ * resolver the suite controls; it is not claimed here.
+ *
+ * @see spec/v2/core/webhooks.md §SSRF
+ * @see spec/v2/core/security-defaults.md §Relaxations
+ */
+
+import { describe, expect, it } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { gateFamily, v2Discovery } from '../lib/v2.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const ID = 'openwop.requirement.0171.webhook-egress-refused';
+const DOC = 'spec/v2/core/webhooks.md §SSRF';
+const EVENTS = ['run.completed'];
+
+/** One destination per class the sentence names. None is ever contacted. */
+const PROBES: ReadonlyArray<{ readonly url: string; readonly cls: string }> = [
+  { url: 'http://webhook-egress-probe.example.com/hook', cls: 'non-https scheme' },
+  { url: 'https://127.0.0.1/openwop-egress-probe', cls: 'loopback (IPv4)' },
+  { url: 'https://[::1]/openwop-egress-probe', cls: 'loopback (IPv6)' },
+  { url: 'https://localhost/openwop-egress-probe', cls: 'localhost' },
+  { url: 'https://10.255.255.1/openwop-egress-probe', cls: 'RFC 1918 (10/8)' },
+  { url: 'https://192.168.255.1/openwop-egress-probe', cls: 'RFC 1918 (192.168/16)' },
+  { url: 'https://169.254.169.254/latest/meta-data/', cls: 'link-local / cloud metadata' },
+  { url: 'https://[fd00::1]/openwop-egress-probe', cls: 'IPv6 ULA' },
+];
+
+/** The `webhooks.*` obligations the operator declared relaxed, if any. */
+function declaredWebhookRelaxations(): string[] {
+  const raw = process.env['OPENWOP_HOST_RELAXATIONS'];
+  if (!raw) return [];
+  try {
+    const parsed = JSON.parse(raw) as Array<{ obligation?: unknown }>;
+    return (Array.isArray(parsed) ? parsed : []).map((r) => String(r.obligation ?? '')).filter((o) => o.split('.')[0] === 'webhooks');
+  } catch {
+    return []; // the emitter rejects unparseable JSON loudly; this file does not second-guess it
+  }
+}
+
+describe('v2-webhook-egress-refusal (webhooks.md §SSRF — the guard refuses, at major 2)', () => {
+  it('a webhook registration naming a destination the guard MUST refuse is refused 400 webhook_url_rejected', async () => {
+    const doc = await v2Discovery();
+    if (!doc) return softSkip('blocked', 'v2 discovery unreachable');
+    if (!(await gateFamily('webhooks'))) return softSkip('inapplicable', 'webhooks family not advertised (gate recorded under openwop.family.webhooks)');
+
+    const accepted: string[] = [];
+    const wrongCode: string[] = [];
+    for (const probe of PROBES) {
+      const reg = await driver.post('/webhooks', { url: probe.url, events: EVENTS });
+      if (reg.status === 201) {
+        accepted.push(`${probe.cls} (${probe.url})`);
+        const webhookId = (reg.json as { webhookId?: unknown } | null)?.webhookId;
+        if (typeof webhookId === 'string') await driver.delete(`/webhooks/${encodeURIComponent(webhookId)}`);
+      } else if (!(reg.status === 400 && readErrorCode(reg.json) === 'webhook_url_rejected')) {
+        wrongCode.push(`${probe.cls}: ${reg.status} ${String(readErrorCode(reg.json))}`);
+      }
+    }
+
+    if (accepted.length > 0) {
+      const declared = declaredWebhookRelaxations();
+      if (declared.length > 0) {
+        return softSkip('inapplicable', `the egress guard is relaxed and the operator DECLARED it (OPENWOP_HOST_RELAXATIONS: ${declared.join(', ')}) — the host accepted ${accepted.length} of ${PROBES.length} destinations the guard MUST refuse (${accepted.join('; ')}). The refusal cannot be witnessed on a host running relaxed; the bundle carries host.relaxations[] and the profile that owns \`webhooks\` does not certify (security-defaults.md §Relaxations)`);
+      }
+    }
+    expect(
+      accepted,
+      req(ID, DOC, `a host MUST reject (400 webhook_url_rejected) non-https URLs, RFC 1918, loopback, link-local, IPv6 ULA, cloud-metadata hosts and localhost at registration — this host ACCEPTED ${accepted.length} of ${PROBES.length} (${accepted.join('; ')}) and no \`webhooks.*\` relaxation is declared in OPENWOP_HOST_RELAXATIONS. An open guard nobody declared is an UNDECLARED RELAXATION: security-defaults.md §Relaxations requires it in host.relaxations[], and no profile built on \`webhooks\` certifies either way`),
+    ).toEqual([]);
+    expect(
+      wrongCode,
+      req(ID, DOC, `the refusal MUST be 400 webhook_url_rejected (spec/v2/errors.json) — other answers: ${wrongCode.join('; ')}`),
+    ).toEqual([]);
+  }, 60_000);
+});