@openwop/openwop-conformance 1.140.0 → 1.141.0

package/README.md

@@ -79,6 +79,8 @@ Run `npm run test` for normal CI cadence; `npm run test:strict` when claiming fu
 | `OPENWOP_OTEL_COLLECTOR_GRPC_PORT=4317`   | Bind the OTLP/gRPC collector on a specific port (default `4317`, OTLP/gRPC convention). The host MUST be configured with `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:<port>` AND `OTEL_EXPORTER_OTLP_PROTOCOL=grpc`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | `OPENWOP_OTEL_COLLECTOR_PORT=14318`       | Bind the OTel collector on a specific port (default `4318`). The host MUST be configured with `OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:<port>`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `OPENWOP_WEBHOOK_ALLOW_PRIVATE=true`      | Relaxes the webhook egress guard for the loopback test receiver used by `webhook-signed-delivery.test.ts`, `webhook-negative.test.ts`, and `replay-fanout-suppression.test.ts`. **The receiver is `http://127.0.0.1:{port}/`, which `webhooks.md` forbids three separate times, and the opt-in MUST relax all three to be witnessable:** (1) the **scheme** check — §"SSRF protection" bullet 1 rejects non-`https://`, and this gate fires FIRST on a host that validates scheme before address; (2) the **registration-time** address check — §"SSRF protection"; and (3) **delivery-time re-resolution** — §"Delivery-time egress validation (RFC 0093)". Gates 2 and 3 are independent MUSTs at different layers, so an opt-in reaching only one layer **cannot** produce a witness: delivery-only leaves registration returning `400 webhook_url_rejected`, registration-only leaves the dispatcher refusing to connect. A host whose opt-in reaches one layer is **not** non-conformant — it cannot witness these scenarios, which is a property of the test posture and not of its webhook signing. The scheme gate went unstated here until 2026-08-25; a tier-2 host validating scheme-then-address was blocked by a gate the documented contract never named. Relaxing gates 2 and 3 is **test-only posture** — see `SECURITY/threat-model-secret-leakage.md` §4.9 for why a registration-time relaxation is the more dangerous of the two. When the host rejects, the scenario records `blocked` (RFC 0148 §A), not a pass.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `OPENWOP_WEBHOOK_RECEIVER_URL=<https-url>` | **The route to a webhook witness that relaxes nothing.** A host refusing the loopback receiver on *two* independent grounds — private address **and** non-`https:` — cannot be unblocked by `OPENWOP_WEBHOOK_ALLOW_PRIVATE`, because the scheme arm still stands. This supplies **the public `https:` front for THIS SUITE'S OWN receiver** (tunnel / TLS-terminating proxy), never an arbitrary endpoint: the scenario asserts on what *this process* received, so pointing registration elsewhere makes every header assertion vacuous while the row turns green. Zero deliveries with it set is a **hard failure**, never a skip. Preferred over the flag — it waives nothing and writes no durable subscription row aimed at a private address (`SECURITY/threat-model-secret-leakage.md` §4.9). Pair with `OPENWOP_WEBHOOK_RECEIVER_PORT`. |
+| `OPENWOP_WEBHOOK_RECEIVER_PORT=<port>`     | Pins the in-process webhook receiver to a known port instead of an ephemeral one. Required in practice by `OPENWOP_WEBHOOK_RECEIVER_URL`: a tunnel must be aimed at a port known **in advance**, and the receiver binds `0` by default. Unset ⇒ ephemeral, as before. |
 | `OPENWOP_MCP_FAKE_SERVER=true`            | Boots the synthetic MCP peer for `mcp-tool-roundtrip.test.ts`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `OPENWOP_MCP_REAL_SERVER_URL=<base-url>`  | Points the MCP wire-shape probe at a real MCP server. The probe POSTs JSON-RPC and reads a single-JSON response — matches MCP's `streamable-http` transport in single-response mode. **Does NOT support** stdio transport (which is what most `modelcontextprotocol/servers` references default to) or SSE-streamed responses; an operator collecting interop evidence today runs a custom `StreamableHTTPServerTransport`-style server that returns a single JSON body per request. Adding SSE-frame parsing is tracked in `docs/PROTOCOL-GAP-CLOSURE-PLAN.md` Track 6. Assertions relax to shape-only. When both this and `OPENWOP_MCP_FAKE_SERVER` are set, the real URL wins. Phase 3 T3.4 interop-evidence path.                                                                                                               |
 | `OPENWOP_A2A_FAKE_PEER=true`              | Boots the synthetic A2A peer for `a2a-task-roundtrip.test.ts`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/openwop-conformance",
-  "version": "1.140.0",
+  "version": "1.141.0",
   "description": "Production-ready black-box conformance suite for OpenWOP v1.0 compliant servers.",
   "repository": {
     "type": "git",

package/schemas/CORPUS-STAMP.json

@@ -1,5 +1,5 @@
 {
   "_comment": "Provenance of this vendored schemas/ copy. See conformance/README.md \u00a7\"Resolving the contract\". Compare against the stamp in your installed @openwop/openwop-conformance to detect a stale hand-copied contract.",
-  "suiteVersion": "1.140.0",
-  "corpusCommit": "8fe8053bfa7436a9c9a2dbbebd304095ecd29b16"
+  "suiteVersion": "1.141.0",
+  "corpusCommit": "de70377b76d34fdec3b1f4b7e27b8ade95a9ba27"
 }

package/src/lib/webhook-receiver.test.ts

@@ -12,13 +12,14 @@
  * @see webhook-receiver.ts, spec/v1/webhooks.md §"Delivery headers"
  */
 
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, afterEach } from 'vitest';
 import { createHmac } from 'node:crypto';
 import {
   SIGNATURE_PREFIX,
   createReceiverState,
   verifyWebhookDelivery,
   signPayload,
+  resolveRegistrationUrl,
 } from './webhook-receiver.js';
 
 const SECRET = 'shhh-not-a-real-secret';
@@ -74,3 +75,70 @@ describe('webhook-receiver: the X-openwop-Signature prefix follows the spec', ()
     expect(algorithmHeader).toBe('v1');
   });
 });
+
+/**
+ * `OPENWOP_WEBHOOK_RECEIVER_URL` validation.
+ *
+ * Each case names the gate it is about, taken from `webhooks.md`, rather than
+ * restating the implementation: the point of the variable is to clear all three
+ * SSRF gates honestly, so a value that cannot clear one of them is an operator
+ * error the suite must refuse LOUDLY. A skip here would hide a
+ * misconfiguration behind a disposition that reads as "the host could not be
+ * exercised", which is a claim about the host and would be false.
+ */
+describe('resolveRegistrationUrl — OPENWOP_WEBHOOK_RECEIVER_URL', () => {
+  const LOCAL = 'http://127.0.0.1:54321/';
+  const saved = process.env.OPENWOP_WEBHOOK_RECEIVER_URL;
+  const set = (v: string | undefined) => {
+    if (v === undefined) delete process.env.OPENWOP_WEBHOOK_RECEIVER_URL;
+    else process.env.OPENWOP_WEBHOOK_RECEIVER_URL = v;
+  };
+  afterEach(() => set(saved));
+
+  it('unset ⇒ registers the local receiver unchanged, not tunnelled', () => {
+    set(undefined);
+    expect(resolveRegistrationUrl(LOCAL)).toEqual({ url: LOCAL, tunnelled: false });
+  });
+
+  it('whitespace-only is treated as unset rather than as a malformed URL', () => {
+    set('   ');
+    expect(resolveRegistrationUrl(LOCAL)).toEqual({ url: LOCAL, tunnelled: false });
+  });
+
+  it('a public https front is used for registration and marked tunnelled', () => {
+    set('https://tunnel.example.com/hook');
+    expect(resolveRegistrationUrl(LOCAL)).toEqual({
+      url: 'https://tunnel.example.com/hook',
+      tunnelled: true,
+    });
+  });
+
+  it('rejects http: — cannot clear gate 1 (webhooks.md §"Register": url MUST be https)', () => {
+    set('http://tunnel.example.com/hook');
+    expect(() => resolveRegistrationUrl(LOCAL)).toThrow(/MUST be https/i);
+  });
+
+  it.each([
+    ['loopback name', 'https://localhost/hook'],
+    ['loopback v4', 'https://127.0.0.1/hook'],
+    ['RFC1918 10/8', 'https://10.1.2.3/hook'],
+    ['RFC1918 192.168/16', 'https://192.168.1.9/hook'],
+    ['RFC1918 172.16/12', 'https://172.20.0.5/hook'],
+    ['link-local', 'https://169.254.169.254/hook'],
+  ])('rejects %s — cannot clear gate 2 (registration-time address check)', (_label, url) => {
+    set(url);
+    expect(() => resolveRegistrationUrl(LOCAL)).toThrow(/publicly-resolvable/i);
+  });
+
+  it('rejects a value that is not a URL at all', () => {
+    set('not a url');
+    expect(() => resolveRegistrationUrl(LOCAL)).toThrow(/not a valid URL/i);
+  });
+
+  it('does not reject a public host that merely LOOKS private (172.32 is public)', () => {
+    // 172.16.0.0/12 ends at 172.31.255.255. A naive /^172\./ check would
+    // reject this and send an operator hunting a nonexistent misconfiguration.
+    set('https://172.32.0.1/hook');
+    expect(resolveRegistrationUrl(LOCAL).tunnelled).toBe(true);
+  });
+});

package/src/lib/webhook-receiver.ts

@@ -184,3 +184,73 @@ export async function discoverOwnedTenant(
   // Pre-S29 hosts that copied the suite's misnamed field: tolerated, never asserted.
   return typeof owner?.tenantId === 'string' && owner.tenantId.length > 0 ? owner.tenantId : undefined;
 }
+
+/**
+ * The public `https:` front for the conformance webhook receiver, when the operator
+ * has wired one (`OPENWOP_WEBHOOK_RECEIVER_URL`).
+ *
+ * This does NOT point the host at some third-party endpoint. The delivery must
+ * still land on the local `startReceiver()` server, because every assertion in
+ * the scenario reads `receiver.received` — an IN-PROCESS array. Registering an
+ * arbitrary URL would send the delivery somewhere the suite cannot observe, and
+ * the row would turn green while every header and HMAC assertion went vacuous.
+ * That is the precise defect this suite exists to catch, so the variable is
+ * specified as "a tunnel or TLS-terminating proxy in front of THIS receiver",
+ * never "an endpoint of your choosing".
+ *
+ * The suite cannot verify that the tunnel actually fronts this process — that
+ * is the operator's contract. What it CAN do is refuse to let a mis-wired
+ * tunnel look like a pass: with the variable set, zero observed deliveries is a
+ * hard assertion failure, never a soft-skip (see the delivery assertion below).
+ *
+ * Validation is deliberately strict and fails LOUDLY rather than skipping: a
+ * malformed value is an operator error, and turning it into a `blocked` row
+ * would hide the misconfiguration behind a disposition that reads as
+ * "the host could not be exercised".
+ */
+export function resolveRegistrationUrl(localUrl: string): { url: string; tunnelled: boolean } {
+  const raw = process.env.OPENWOP_WEBHOOK_RECEIVER_URL?.trim();
+  if (!raw) return { url: localUrl, tunnelled: false };
+
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(
+      `OPENWOP_WEBHOOK_RECEIVER_URL is not a valid URL: ${JSON.stringify(raw)}`,
+    );
+  }
+
+  // Must clear gate 1 (scheme). An `http:` front cannot satisfy a host that
+  // validates scheme before address, which is the ordering that made the
+  // ALLOW_PRIVATE flag insufficient in the first place.
+  if (parsed.protocol !== 'https:') {
+    throw new Error(
+      `OPENWOP_WEBHOOK_RECEIVER_URL MUST be https: (got ${parsed.protocol}). ` +
+        'A plain-http front cannot clear the scheme gate, so it cannot witness this scenario.',
+    );
+  }
+
+  // Must clear gate 2 (registration-time address check). A loopback or private
+  // hostname here is just the local URL wearing a different scheme — it would
+  // be rejected for the same reason, and the operator would read the resulting
+  // failure as a host defect rather than as their own misconfiguration.
+  const host = parsed.hostname.toLowerCase();
+  const isLoopback =
+    host === 'localhost' || host === '::1' || host.startsWith('127.');
+  const isPrivate =
+    /^10\./.test(host) ||
+    /^192\.168\./.test(host) ||
+    /^172\.(1[6-9]|2\d|3[01])\./.test(host) ||
+    /^169\.254\./.test(host) ||
+    /^(fc|fd)/.test(host);
+  if (isLoopback || isPrivate) {
+    throw new Error(
+      `OPENWOP_WEBHOOK_RECEIVER_URL MUST be a publicly-resolvable host (got ${parsed.hostname}). ` +
+        'It is the PUBLIC front for the local receiver — a tunnel or TLS-terminating proxy — ' +
+        'not the receiver address itself.',
+    );
+  }
+
+  return { url: raw, tunnelled: true };
+}

package/src/scenarios/webhook-signed-delivery.test.ts

@@ -63,6 +63,32 @@
  * writes a durable subscription row that survives the flag being turned
  * back off.
  *
+ * `OPENWOP_WEBHOOK_RECEIVER_URL` — the route that relaxes NOTHING (added
+ * 2026-08-28). Set it to a public `https:` tunnel or TLS-terminating proxy
+ * standing in front of this scenario's own local receiver. Registration then
+ * uses that URL and all three gates are satisfied honestly: the scheme is
+ * `https:`, the registered address is public, and delivery-time re-resolution
+ * resolves a public address it is entitled to connect to. No guard is waived,
+ * no durable private-address row is written, and §4.9's hazard does not arise.
+ *
+ * This exists because the ALLOW_PRIVATE contract above is unsatisfiable for a
+ * host whose guard is strongest at registration time: reported by a tier-2
+ * host (2026-08-25) whose `classifyUrl` rejects on scheme AND address as two
+ * independent grounds returning one code, so relaxing the address check leaves
+ * the scheme check standing and the row `blocked` either way. Such a host is
+ * conformant and was simply unmeasurable. It is now measurable.
+ *
+ * Two things it deliberately does NOT do. It is not "register any endpoint":
+ * the assertions read an in-process array, so a third-party destination would
+ * turn the row green while every assertion went vacuous — see
+ * `resolveRegistrationUrl`. And it does not soften a rejection into a skip: a
+ * host that refuses a legitimate public https destination FAILS, because
+ * `blocked` would let it record a missing precondition forever instead of the
+ * finding it earned.
+ *
+ * Paired with a positive control (bottom of this file) so the tunnelled pass
+ * is attributable to a guard that works rather than to a guard that is absent.
+ *
  * When the host rejects with `400 webhook_url_rejected`, this scenario
  * records `blocked` (RFC 0148 §A) — NOT a pass. Under a plain
  * `vitest run` the console still prints "1 passed", because that is
@@ -81,7 +107,7 @@ import { driver } from '../lib/driver.js';
 import { discoveryFamilies } from '../lib/discovery-capabilities.js';
 import { pollUntilTerminal } from '../lib/polling.js';
 import { isFixtureAdvertised } from '../lib/fixtures.js';
-import { discoverOwnedTenant } from '../lib/webhook-receiver.js';
+import { discoverOwnedTenant, resolveRegistrationUrl } from '../lib/webhook-receiver.js';
 
 interface DeliveredRequest {
   readonly headers: Record<string, string>;
@@ -105,7 +131,16 @@ async function startReceiver(): Promise<{ server: Server; url: string; received:
       res.end();
     });
   });
-  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+  // Port 0 (ephemeral) by default — nothing outside this process needs to find
+  // it. But OPENWOP_WEBHOOK_RECEIVER_URL fronts THIS receiver through a tunnel,
+  // and a tunnel has to be pointed at a port the operator knows in ADVANCE. An
+  // ephemeral port makes that variable unusable by anyone not reading the port
+  // out of a running process — a gap found by standing up a real TLS front and
+  // trying to use the feature, not by reading the code. OPENWOP_WEBHOOK_RECEIVER_PORT
+  // pins it so `ngrok http <port>` (or a proxy) has a stable target.
+  const pinned = Number(process.env['OPENWOP_WEBHOOK_RECEIVER_PORT'] ?? '');
+  const bindPort = Number.isInteger(pinned) && pinned > 0 && pinned < 65536 ? pinned : 0;
+  await new Promise<void>((resolve) => server.listen(bindPort, '127.0.0.1', () => resolve()));
   const addr = server.address();
   if (typeof addr !== 'object' || addr === null) throw new Error('receiver address unavailable');
   return { server, url: `http://127.0.0.1:${addr.port}/`, received };
@@ -150,23 +185,43 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
     // tenantId is 403'd by a host that scopes subscriptions by membership
     // (RFC 0093). Single-tenant hosts return undefined ⇒ omit tenantId.
     const ownedTenant = await discoverOwnedTenant(driver);
+    const registration = resolveRegistrationUrl(receiver.url);
     const reg = await driver.post('/v1/webhooks', {
-      url: receiver.url,
+      url: registration.url,
       events: ['run.completed'],
       ...(ownedTenant ? { tenantId: ownedTenant } : {}),
     });
 
-    // SSRF guard skip: if the host rejects loopback destinations,
-    // honor the operator contract and skip rather than fail.
+    // SSRF guard: if the host rejects the destination, what that MEANS depends
+    // on which URL was registered.
+    //
+    //   * No tunnel wired (loopback URL): the host is refusing a private
+    //     address, which webhooks.md REQUIRES it to do. That is correct
+    //     behaviour and the scenario is unwitnessable here — `blocked`.
+    //   * Tunnel wired (public https URL): the host refused a destination the
+    //     spec makes legitimate. RFC 0093 does not permit rejecting a public
+    //     https host, so this is a FINDING, not a missing precondition. Fail.
+    //
+    // Soft-skipping the second case would let a host that rejects everything
+    // record `blocked` forever instead of the failure it earned.
     if (reg.status === 400) {
       const body = reg.json as { error?: string };
       if (body.error === 'webhook_url_rejected') {
-        // eslint-disable-next-line no-console
-        console.warn(
-          '[webhook-signed-delivery] host SSRF guard rejected the loopback receiver; ' +
-            'set OPENWOP_WEBHOOK_ALLOW_PRIVATE=true on the host (or equivalent) to run',
+        if (!registration.tunnelled) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            '[webhook-signed-delivery] host SSRF guard rejected the loopback receiver; ' +
+              'set OPENWOP_WEBHOOK_RECEIVER_URL to a public https tunnel in front of it ' +
+              '(preferred — relaxes no guard), or OPENWOP_WEBHOOK_ALLOW_PRIVATE=true on the host',
+          );
+          return softSkip('blocked', 'precondition not met — `body.error === \'webhook_url_rejected\'` returned early (seam, prior step, or fixture unavailable)');
+        }
+        expect.fail(
+          `host rejected the operator-supplied public https receiver (${registration.url}) with ` +
+            'webhook_url_rejected. A public https destination is legitimate under ' +
+            'webhooks.md §"SSRF protection" and RFC 0093 §"Delivery-time egress validation"; ' +
+            'rejecting it is a host defect, not an unmet precondition.',
         );
-        return softSkip('blocked', 'precondition not met — `body.error === \'webhook_url_rejected\'` returned early (seam, prior step, or fixture unavailable)');
       }
     }
 
@@ -216,9 +271,19 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
         return false;
       }
     });
+    // With a tunnel wired this is the assertion that keeps a mis-wired front
+    // from reading as a pass. Registration succeeded, so the host believes it
+    // has a subscriber; if nothing arrived HERE, the delivery went somewhere
+    // this process cannot see and every assertion below it would be vacuous.
+    // It fails — it must never soft-skip.
     expect(ourDeliveries.length, driver.describe(
       'webhooks.md §"Delivery"',
-      'host MUST POST at least one event for THIS run to a registered subscriber after run.completed',
+      registration.tunnelled
+        ? 'host MUST POST at least one event for THIS run to the registered subscriber. ' +
+          'Registration was accepted, so zero deliveries observed on the local receiver means ' +
+          'either the host did not deliver, or OPENWOP_WEBHOOK_RECEIVER_URL does not actually ' +
+          'front this process. Both are failures; neither is a skip.'
+        : 'host MUST POST at least one event for THIS run to a registered subscriber after run.completed',
     )).toBeGreaterThan(0);
 
     // Validate the FIRST delivery's signature contract. Other deliveries
@@ -268,4 +333,62 @@ describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
     expect(del.status).toBeGreaterThanOrEqual(200);
     expect(del.status).toBeLessThan(300);
   });
+
+  /**
+   * POSITIVE CONTROL for the tunnel path.
+   *
+   * Without this, the tunnel run passes identically on two very different
+   * hosts: one whose SSRF guard is intact and was cleared by a legitimate
+   * public destination, and one that has NO GUARD AT ALL and would have
+   * accepted the loopback URL just as happily. The green would be reporting on
+   * the operator's tunnel rather than on the host's behaviour, and the
+   * variable would be doing no work.
+   *
+   * So: with the tunnel wired, re-register the LOOPBACK url and require that
+   * the host still refuses it. That is what makes the sibling test's pass
+   * attributable to the guard being cleared rather than absent.
+   *
+   * A host that ACCEPTS loopback here is not necessarily non-conformant — it
+   * may be running with `OPENWOP_WEBHOOK_ALLOW_PRIVATE=true`. But in that
+   * configuration the tunnel is demonstrating nothing, and saying so is the
+   * control's whole job.
+   */
+  it('control: with a tunnel wired, the host still refuses the loopback receiver', async () => {
+    if (!(await isWebhookSupported())) {
+      return softSkip('inapplicable', '[webhook-signed-delivery] host does not advertise webhook support; skipping');
+    }
+    if (!process.env.OPENWOP_WEBHOOK_RECEIVER_URL?.trim()) {
+      // No tunnel wired ⇒ the sibling test already registers loopback directly
+      // and this control has nothing to add.
+      return softSkip('inapplicable', 'control applies only when OPENWOP_WEBHOOK_RECEIVER_URL is set');
+    }
+
+    const receiver = await startReceiver();
+    activeServer = receiver.server;
+
+    const ownedTenant = await discoverOwnedTenant(driver);
+    const reg = await driver.post('/v1/webhooks', {
+      url: receiver.url, // deliberately the raw loopback URL, NOT the tunnel
+      events: ['run.completed'],
+      ...(ownedTenant ? { tenantId: ownedTenant } : {}),
+    });
+
+    if (reg.status >= 200 && reg.status < 300) {
+      // Clean up the subscription we just created before failing, so a failed
+      // control does not leave a live loopback subscriber behind.
+      const created = reg.json as { webhookId?: string };
+      if (created?.webhookId) {
+        await driver.delete(`/v1/webhooks/${encodeURIComponent(created.webhookId)}`);
+      }
+    }
+
+    expect(reg.status, driver.describe(
+      'webhooks.md §"SSRF protection"',
+      'the server MUST reject loopback subscription URLs at registration time. ' +
+        'It was accepted here, so this run cannot attribute the tunnelled test\'s pass to ' +
+        'a working guard: a host with no guard produces the same result. Either the guard is ' +
+        'absent (a finding) or OPENWOP_WEBHOOK_ALLOW_PRIVATE is set (in which case drop the ' +
+        'tunnel — it is not doing anything).',
+    )).toBe(400);
+  });
 });