@openwop/openwop-conformance 2.35.0 → 2.36.0

package/src/scenarios/v2-protected-resource-metadata.test.ts

@@ -0,0 +1,145 @@
+/**
+ * RFC 0200 §A — the host serves RFC 9728 Protected Resource Metadata, derived from the
+ * lanes it already advertises (suite 2.36.0, target major 2).
+ *
+ * **Gate:** an `auth.lanes[]` member with `lane ∈ {oauth2, oidc}`. A host with neither
+ * records `inapplicable` — §A.1 does not bind it. A host WITH one that answers `404` at
+ * the derived URL records an `executed-fail`: the lane is the advertisement, the document
+ * is owed, and a soft-skip here would let the advertisement cost nothing.
+ *
+ * Three legs, one requirement id each:
+ *
+ *   1. `prm-served` — the URL RFC 9728 §3/§3.1 forms from the resource identifier answers
+ *      `200` with a JSON object, fetched with NO credential (§A.2: the document is served
+ *      without authentication).
+ *   2. `prm-consistent` — it is a PROJECTION, not a second declaration: `resource` is
+ *      identical to the resource identifier used to form the URL; `authorization_servers`
+ *      is set-equal to the URL-form issuers of those lanes; `scopes_supported`, when
+ *      present, is a non-empty array of strings; and neither binding claim is `true`
+ *      unless EVERY such lane requires that binding — a bearer lane advertised as
+ *      sender-constrained is `sender-constraint-no-bearer-downgrade`.
+ *   3. `mcp-mount-prm` — §A.4, the MCP mount as its own resource. Gated further on a
+ *      mount that REQUIRES OAuth-lane authentication, which the suite can only establish
+ *      when every advertised lane is `oauth2`/`oidc`: a host whose api-key lane also
+ *      opens the mount records `inapplicable` with that reason rather than passing a leg
+ *      whose premise does not hold.
+ *
+ * How each FAILS (the sabotage run before citing a row):
+ *   (a) the host serves nothing at the derived URL      → leg 1 (404)
+ *   (b) a sub-path host serves only the ROOT well-known → leg 1 (404 at the inserted path)
+ *   (c) `authorization_servers` adds an issuer no lane names → leg 2
+ *   (d) `resource` carries a trailing slash / another origin → leg 2
+ *   (e) `dpop_bound_access_tokens_required: true` on a bearer lane → leg 2
+ *
+ * @see spec/v2/core/identity.md §2.5
+ * @see RFCS/0200-host-as-oauth-protected-resource.md §A
+ * @see SECURITY/invariants.yaml id: auth-challenge-no-oracle (the §B.3 sibling)
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { allLanes, parseChallenge, prmGate, prmUrlFor, urlIssuers } from '../lib/protected-resource.js';
+
+const DOC = 'spec/v2/core/identity.md §2.5 (RFC 0200 §A)';
+const SERVED = 'openwop.requirement.0200.prm-served';
+const CONSISTENT = 'openwop.requirement.0200.prm-consistent';
+const MOUNT = 'openwop.requirement.0200.mcp-mount-prm';
+
+describe('RFC 0200 §A — v2-protected-resource-metadata (gated on an advertised oauth2/oidc lane)', () => {
+  it('serves RFC 9728 metadata, unauthenticated, at the URI derived from its resource identifier', async () => {
+    const g = await prmGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const res = await driver.get(g.prmUrl, { authenticated: false });
+    expect(
+      res.status,
+      req(SERVED, `${DOC} §A.1–§A.2`, `a host advertising an oauth2/oidc lane MUST serve RFC 9728 metadata at ${g.prmUrl} — served without authentication (got ${res.status}; a 404 is a failure, not a skip: the lane is advertised, so the document is owed)`),
+    ).toBe(200);
+    expect(
+      res.json !== null && typeof res.json === 'object' && !Array.isArray(res.json),
+      req(SERVED, `${DOC} §A.2`, `the metadata MUST be a JSON object (got ${typeof res.json}: ${res.text.slice(0, 120)})`),
+    ).toBe(true);
+  }, 30_000);
+
+  it('the metadata is a projection of auth.lanes[], not a second declaration', async () => {
+    const g = await prmGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const res = await driver.get(g.prmUrl, { authenticated: false });
+    if (res.status !== 200 || res.json === null || typeof res.json !== 'object') {
+      // The served leg already recorded the failure; this leg has nothing to project from.
+      return softSkip('blocked', `the metadata did not parse (status ${res.status}) — the prm-served leg carries that verdict`);
+    }
+    const prm = res.json as Record<string, unknown>;
+
+    expect(
+      prm['resource'],
+      req(CONSISTENT, `${DOC} §A.3`, `\`resource\` MUST be identical to the resource identifier the URL was formed from (RFC 9728 §3.3): expected ${g.resource}`),
+    ).toBe(g.resource);
+
+    const expected = urlIssuers(g.lanes);
+    const got = [...new Set((Array.isArray(prm['authorization_servers']) ? (prm['authorization_servers'] as unknown[]) : []).map(String))].sort();
+    expect(
+      got,
+      req(CONSISTENT, `${DOC} §A.3`, `\`authorization_servers\` MUST list exactly the URL-form issuers of the oauth2/oidc lanes — an issuer the lanes do not name is a second declaration, and a lane issuer left out hides an authorization server the caller must reach (lanes name [${expected.join(', ')}])`),
+    ).toEqual(expected);
+
+    if ('scopes_supported' in prm) {
+      const scopes = prm['scopes_supported'];
+      expect(
+        Array.isArray(scopes) && scopes.length > 0 && scopes.every((s) => typeof s === 'string' && s.length > 0),
+        req(CONSISTENT, `${DOC} §A.3`, `\`scopes_supported\`, when present, MUST list the scopes the host enforces — a non-empty array of strings (got ${JSON.stringify(scopes)})`),
+      ).toBe(true);
+    }
+
+    // §A.3: a binding claim MAY be true only where EVERY oauth2/oidc lane's
+    // minimumAssurance requires that binding. A bearer lane advertised as
+    // sender-constrained is the `sender-constraint-no-bearer-downgrade` violation, and it
+    // is exactly the claim a host is tempted to make because it reads as "more secure".
+    const everyConstrained = g.lanes.every((l) => l.minimumAssurance === 'sender-constrained' || l.minimumAssurance === 'key-bound');
+    const proofs = new Set(g.lanes.flatMap((l) => (Array.isArray(l.delegationProofs) ? l.delegationProofs.map(String) : [])));
+    if (prm['dpop_bound_access_tokens_required'] === true) {
+      expect(
+        everyConstrained && proofs.has('dpop'),
+        req(CONSISTENT, `${DOC} §A.3`, 'dpop_bound_access_tokens_required MAY be true only where EVERY oauth2/oidc lane requires that binding (minimumAssurance above bearer with dpop in delegationProofs) — invariant sender-constraint-no-bearer-downgrade'),
+      ).toBe(true);
+    }
+    if (prm['tls_client_certificate_bound_access_tokens'] === true) {
+      expect(
+        everyConstrained && proofs.has('mtls-key-binding'),
+        req(CONSISTENT, `${DOC} §A.3`, 'tls_client_certificate_bound_access_tokens MAY be true only where EVERY oauth2/oidc lane requires mTLS key binding — invariant sender-constraint-no-bearer-downgrade'),
+      ).toBe(true);
+    }
+  }, 30_000);
+
+  it('an MCP mount that requires OAuth-lane authentication implements one of upstream\'s two discovery mechanisms', async () => {
+    const g = await prmGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const mcp = g.doc['mcp'] as { serverUrls?: unknown; serverMount?: unknown } | undefined;
+    const urls = Array.isArray(mcp?.serverUrls) ? (mcp.serverUrls as unknown[]).map(String) : [];
+    if (urls.length === 0) return softSkip('inapplicable', 'no mcp.serverUrls[] — this host mounts no MCP server, so §A.4 does not bind it');
+    // §A.4 binds a mount that REQUIRES OAuth-lane authentication. From outside, that holds
+    // only when every advertised lane is oauth2/oidc: otherwise an api-key credential opens
+    // the mount and the mount's resource server is not an OAuth one. Recording the honest
+    // `inapplicable` is the point — a leg that passed on a mount an api-key opens would be
+    // measuring nothing.
+    const every = allLanes(g.doc);
+    const onlyOauth = every.length > 0 && every.every((l) => l.lane === 'oauth2' || l.lane === 'oidc');
+    if (!onlyOauth) {
+      return softSkip('inapplicable', `the mount does not require an oauth2/oidc lane: this host also advertises [${every.map((l) => String(l.lane)).join(', ')}], any of which opens the mount, so §A.4's premise does not hold`);
+    }
+    const mount = urls[0] as string;
+    const unauth = await driver.post(mount, { jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} }, { authenticated: false, headers: { 'MCP-Protocol-Version': '2026-07-28' } });
+    const challenge = parseChallenge(unauth.headers.get('www-authenticate'));
+    const viaChallenge = unauth.status === 401 && challenge !== null && challenge.scheme === 'bearer' && typeof challenge.params['resource_metadata'] === 'string';
+    let viaWellKnown = false;
+    if (!viaChallenge) {
+      const doc = await driver.get(prmUrlFor(mount), { authenticated: false });
+      viaWellKnown = doc.status === 200 && (doc.json as { resource?: unknown } | null)?.resource === mount;
+    }
+    expect(
+      viaChallenge || viaWellKnown,
+      req(MOUNT, 'spec/v1/mcp-integration.md §E; spec/v2/interop-map.json mcp.authorization (RFC 0200 §A.4)', `a mount requiring OAuth-lane authentication MUST implement one of upstream's two discovery mechanisms for the mount URL as resource — resource_metadata in its 401 challenge, or PRM at ${prmUrlFor(mount)} with resource === ${mount} (mount answered ${unauth.status}, WWW-Authenticate ${unauth.headers.get('www-authenticate') ?? 'absent'})`),
+    ).toBe(true);
+  }, 30_000);
+});

package/src/scenarios/v2-run-cancel.test.ts

@@ -92,6 +92,6 @@ describe('v2 run-cancel (runs.md §Cancel)', () => {
     const final = await waitFor(c.runId, (x) => x === 'cancelled', 5_000);
     expect(final, req(ID, DOC, `the snapshot MUST read cancelled within 5 s of an accepted cancel (last: ${final ?? 'unreadable'})`)).toBe('cancelled');
     const types = await eventTypes(c.runId);
-    expect(types?.includes('run.cancelled') ?? false, req(ID, 'spec/v2/core/events.md §run.cancelled', `the log MUST carry run.cancelled once the cascade completes (types: ${(types ?? []).join(', ')})`)).toBe(true);
+    expect(types?.includes('run.cancelled') ?? false, req(ID, 'spec/v2/core/runs.md §Cancel', `the log MUST carry run.cancelled once the cascade completes (types: ${(types ?? []).join(', ')})`)).toBe(true);
   }, 30_000);
 });

package/src/scenarios/v2-run-fork-prefix.test.ts

@@ -1,5 +1,5 @@
 /**
- * `spec/v2/core/replay.md` §Endpoint — the fork prefix boundary is EXCLUSIVE
+ * `spec/v2/core/replay.md` §The surface — the fork prefix boundary is EXCLUSIVE
  * (suite 2.0.0, target major 2; unaided; gated on `replay`; two runs created).
  *
  * "Events with `sequence < fromSeq` are fixed history; events `>= fromSeq` are
@@ -99,7 +99,7 @@
  * The leg runs LAST, after the boundary assertion, so a host that fails this
  * stricter new check still reports the boundary verdict the file was cut for.
  *
- * @see spec/v2/core/replay.md §Endpoint
+ * @see spec/v2/core/replay.md §The surface
  * @see spec/v2/core/replay.md §Byte-equivalence of the prefix
  * @see spec/v2/core/runs.md §Fork
  * @see spec/v2/core/runs.md §Diff and ancestry
@@ -114,7 +114,7 @@ import { softSkip } from '../lib/soft-skip.js';
 import { req } from '../lib/requirement-ids.js';
 
 const ID = 'openwop.requirement.0170.fork-prefix-boundary';
-const DOC = 'spec/v2/core/replay.md §Endpoint';
+const DOC = 'spec/v2/core/replay.md §The surface';
 const BYTES = 'spec/v2/core/replay.md §Byte-equivalence of the prefix';
 const MULTI = 'conformance-multi-node';
 const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
@@ -168,7 +168,7 @@ async function settle(runId: string, ms = 20_000): Promise<string | null> {
   return status;
 }
 
-describe('v2 run-fork-prefix (replay.md §Endpoint — the boundary is exclusive)', () => {
+describe('v2 run-fork-prefix (replay.md §The surface — the boundary is exclusive)', () => {
   it('a replay fork inherits exactly [0, fromSeq): the event at fromSeq is re-executed, never carried over', async () => {
     if (!(await discovery())) return softSkip('blocked', 'v2 discovery unreachable');
     if (!(await gateFamily('replay'))) return softSkip('inapplicable', 'replay family not advertised (gate recorded under openwop.family.replay) — forkRun is gated on replay (runs.md §Surface)');

package/src/scenarios/v2-run-pause-resume.test.ts

@@ -101,7 +101,7 @@ describe('v2 run-pause-resume (runs.md §Pause and resume)', () => {
       expect(rb?.status, req(ID, DOC, `the 202 MUST carry status running (got ${String(rb?.status)})`)).toBe('running');
       const types = await eventTypes(c.runId);
       const p = types?.indexOf('run.paused') ?? -1; const r = types?.indexOf('run.resumed') ?? -1;
-      expect(p >= 0 && r > p, req(ID, 'spec/v2/core/events.md §run.paused', `the log MUST carry run.paused then run.resumed (types: ${(types ?? []).join(', ')})`)).toBe(true);
+      expect(p >= 0 && r > p, req(ID, 'spec/v2/core/runs.md §Pause and resume', `the log MUST carry run.paused then run.resumed (types: ${(types ?? []).join(', ')})`)).toBe(true);
       // An immediate pause cuts the executing attempt BETWEEN events: no terminal
       // node event for it, ever — a node.failed here makes a replay fold a
       // failure the source never had (runs.md §Pause and resume; replay.md).

package/src/scenarios/v2-tool-catalog-annotations.test.ts

@@ -0,0 +1,100 @@
+/**
+ * RFC 0204 §D.11–§D.12 — the catalog's MCP annotation projection (suite 2.36.0,
+ * target major 2; gated on `toolCatalog`).
+ *
+ * `spec/v2/core/tool-catalog.md` §The descriptor: the host assigns
+ * `safetyTier`, `replayPolicy` and `egress` itself and never copies them from
+ * an MCP server's `annotations` (untrusted upstream); an unclassified
+ * `source: "mcp"` tool is `write`; and any `annotations` it publishes carry all
+ * four hints, each a fixed function of those host-assigned fields.
+ *
+ *   annotations-derived     every descriptor carrying `annotations` has all
+ *                           four hints and each equals the table's value;
+ *                           `inapplicable` when no descriptor carries any (a
+ *                           catalog without annotations is untouched by §D.12,
+ *                           and passing it would be vacuous);
+ *   mcp-unclassified-write  the suite's fake MCP server lists
+ *                           `conformance_readonly_claim_<nonce>` annotated
+ *                           `readOnlyHint: true`; wherever a host projects it
+ *                           (any `conformance_readonly_claim_*` descriptor with
+ *                           `source: "mcp"` — a host MAY answer from a list it
+ *                           cached from an earlier suite server within `ttlMs`),
+ *                           it MUST be `safetyTier: "write"`. `inapplicable`
+ *                           when the host does not project the server.
+ *
+ * Sabotage, each run once against the v2 reference host: emit
+ * `readOnlyHint: true` on a `write` tool; omit `openWorldHint`; copy the
+ * server's `readOnlyHint` into `safetyTier: "read"` — each turns its row red.
+ *
+ * @see spec/v2/core/tool-catalog.md §The descriptor
+ * @see SECURITY/invariants.yaml tool-annotations-untrusted
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { familyAdvertised } from '../lib/v2.js';
+import { getMcpFakeServer, READONLY_CLAIM_PREFIX } from '../lib/mcp-fake-server.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { expectedAnnotations, type ToolDescriptor } from '../lib/toolCatalog.js';
+
+export const REQUIRES_HOST_CALLBACK = "the host projects the suite's fake MCP server into GET /tools (the unclassified-MCP leg)";
+
+const DOC = 'spec/v2/core/tool-catalog.md §The descriptor';
+const ID_DERIVED = 'openwop.requirement.0204.annotations-derived';
+const ID_UNCLASSIFIED = 'openwop.requirement.0204.mcp-unclassified-write';
+/**
+ * Recorded `inapplicable`, not through `gateFamily`: under strict mode
+ * `gateFamily` FAILS a host that neither advertises nor opts out, and a new
+ * gate on an existing family would de-certify every strict v2 cut that does not
+ * advertise `toolCatalog` until its operator adds an opt-out — a certification
+ * change this RFC does not make.
+ */
+const NOT_ADVERTISED = 'toolCatalog not advertised — the host publishes no catalog';
+const HINTS = ['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint'] as const;
+
+async function readCatalog(): Promise<ToolDescriptor[] | { reason: string }> {
+  const res = await driver.get('/tools').catch(() => null);
+  if (res === null) return { reason: 'GET /tools unreachable (fetch failed)' };
+  if (res.status !== 200) return { reason: `the host advertises toolCatalog and GET /tools answered ${res.status}` };
+  const body = res.json as unknown;
+  const tools = Array.isArray(body) ? body : (body as { tools?: unknown } | null)?.tools;
+  return Array.isArray(tools) ? (tools as ToolDescriptor[]) : { reason: 'GET /tools returned neither a ToolDescriptor[] nor { tools }' };
+}
+
+describe('RFC 0204 §D — tool annotations are derived, never copied (gated on toolCatalog)', () => {
+  it('every published annotations object is the table function of the descriptor', async () => {
+    if (!(await familyAdvertised('toolCatalog'))) return softSkip('inapplicable', NOT_ADVERTISED);
+    const tools = await readCatalog();
+    if (!Array.isArray(tools)) return softSkip('blocked', tools.reason);
+    const annotated = tools.filter((t) => t['annotations'] !== undefined);
+    if (annotated.length === 0) return softSkip('inapplicable', `none of the ${tools.length} descriptors carries annotations — §D.12 binds only a host that publishes them`);
+    for (const t of annotated) {
+      const a = (t['annotations'] ?? {}) as Record<string, unknown>;
+      const want = expectedAnnotations(t);
+      for (const h of HINTS) {
+        expect(typeof a[h], req(ID_DERIVED, DOC, `${String(t.toolId)}: annotations MUST carry all four hints — ${h} is ${a[h] === undefined ? 'absent (a consumer would fall through to the MCP default)' : `not a boolean (${JSON.stringify(a[h])})`}`)).toBe('boolean');
+        expect(a[h], req(ID_DERIVED, DOC, `${String(t.toolId)}: ${h} MUST be derived from safetyTier=${String(t.safetyTier)} replayPolicy=${String(t['replayPolicy'] ?? '(absent)')} egress=${String(t['egress'] ?? '(absent)')} — want ${String(want[h])}`)).toBe(want[h]);
+      }
+    }
+  });
+
+  it('an MCP tool the host has not classified is safetyTier write, whatever the server claims', async () => {
+    const fam = await familyAdvertised('toolCatalog');
+    if (!fam) return softSkip('inapplicable', NOT_ADVERTISED);
+    const sources = Array.isArray(fam['sources']) ? (fam['sources'] as unknown[]) : [];
+    if (!sources.includes('mcp')) return softSkip('inapplicable', 'toolCatalog.sources does not include mcp — the host projects no MCP server');
+    const fake = getMcpFakeServer();
+    // No suite server ⇒ nothing the host could project: the RFC's `inapplicable`
+    // case, not `blocked` — a tier-2 host that projects its own MCP servers and
+    // cuts without OPENWOP_MCP_FAKE_SERVER is not made uncertifiable by this row.
+    if (fake === null) return softSkip('inapplicable', 'the suite MCP fake server (OPENWOP_MCP_FAKE_SERVER=true) is not started in this run, so there is no suite server for the host to project');
+    const tools = await readCatalog();
+    if (!Array.isArray(tools)) return softSkip('blocked', tools.reason);
+    const claims = tools.filter((t) => t.source === 'mcp' && [t.toolId, t['title']].some((v) => typeof v === 'string' && v.includes(READONLY_CLAIM_PREFIX)));
+    if (claims.length === 0) return softSkip('inapplicable', `no source:"mcp" descriptor names ${fake.readonlyClaimToolName()} — the host does not project the suite's fake server as a catalog source`);
+    for (const t of claims) {
+      expect(t.safetyTier, req(ID_UNCLASSIFIED, DOC, `${String(t.toolId)}: the server annotates it readOnlyHint: true, which is untrusted; a source:"mcp" tool the host has not classified MUST be safetyTier "write" (got ${String(t.safetyTier)})`)).toBe('write');
+    }
+  });
+});

package/src/scenarios/v2-unmapped-type-refused.test.ts

@@ -34,7 +34,7 @@
  * needs it, never to the file.
  *
  * @see spec/v2/core/persistence.md §The reader rule
- * @see spec/v2/core/events.md §Reading an era-2 log
+ * @see spec/v2/core/events.md §Era-2 logs
  */
 
 import { describe, it, expect } from 'vitest';

package/src/scenarios/v2-v1-events-translated.test.ts

@@ -16,7 +16,7 @@
  * every leg records `blocked` naming it.
  *
  * @see spec/v2/core/persistence.md §The reader rule, §The seat
- * @see spec/v2/core/events.md §Reading an era-2 log
+ * @see spec/v2/core/events.md §Era-2 logs
  */
 
 import { describe, it, expect } from 'vitest';

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

@@ -1,7 +1,7 @@
 /**
  * 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
+ * `spec/v2/core/webhooks.md` §Egress: "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`."
  *
@@ -39,7 +39,7 @@
  * 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/webhooks.md §Egress
  * @see spec/v2/core/security-defaults.md §Relaxations
  */
 
@@ -51,7 +51,7 @@ 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 DOC = 'spec/v2/core/webhooks.md §Egress';
 const EVENTS = ['run.completed'];
 
 /** One destination per class the sentence names. None is ever contacted. */
@@ -70,7 +70,7 @@ const PROBES: ReadonlyArray<{ readonly url: string; readonly cls: string }> = [
   // form let loopback, metadata and RFC 1918 through at registration and at
   // delivery. Measured on the steward's own reference host.
   // These are loopback / link-local / RFC 1918 addresses by any reading of
-  // webhooks.md §SSRF, so they enforce the existing obligation — same id.
+  // webhooks.md §Egress, so they enforce the existing obligation — same id.
   { url: 'https://[::ffff:7f00:1]/openwop-egress-probe', cls: 'loopback as IPv4-mapped IPv6 (hex)' },
   { url: 'https://[::ffff:a9fe:a9fe]/latest/meta-data/', cls: 'cloud metadata as IPv4-mapped IPv6 (hex)' },
   { url: 'https://[::ffff:a00:1]/openwop-egress-probe', cls: 'RFC 1918 (10/8) as IPv4-mapped IPv6 (hex)' },
@@ -88,7 +88,7 @@ function declaredWebhookRelaxations(): string[] {
   }
 }
 
-describe('v2-webhook-egress-refusal (webhooks.md §SSRF — the guard refuses, at major 2)', () => {
+describe('v2-webhook-egress-refusal (webhooks.md §Egress — 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');

package/src/scenarios/v2-webhook-endpoint-verification.test.ts

@@ -0,0 +1,124 @@
+/**
+ * RFC 0201 §D — endpoint verification, for opted-in registrations only (suite
+ * 2.36.0, target major 2; gated on `webhooks.signatureAlgorithms` listing
+ * `standard-webhooks-1`).
+ *
+ * Before it answers `201` to a registration that lists `standard-webhooks-1`,
+ * the host sends ONE signed verification request and refuses the registration
+ * `400 webhook_endpoint_unverified`, persisting nothing, unless a `2xx` arrives
+ * within 10 s whose JSON `challenge` equals the one sent. The receiver is the
+ * suite's modal receiver, one path per behaviour:
+ *
+ *   no-echo     200 `{}`                         → MUST be refused
+ *   wrong-echo  200 `{ challenge: <other> }`     → MUST be refused
+ *   redirect    307 to redirect-target (echoes)  → MUST be refused; the target MUST see nothing
+ *   echo        200 `{ challenge }`              → MUST answer 201
+ *
+ * Each verification request is checked against
+ * `schemas/v2/webhook-verification.schema.json`, verified with the supplied
+ * secret by the suite's Standard Webhooks verifier, and MUST carry no
+ * `OpenWOP-Event-Type` (it is not a delivery). A host MUST NOT retry it, so each
+ * refused path sees exactly one.
+ *
+ * "Persisting nothing" is checked on the wire, not by reading the host: after
+ * the refusals, one run is driven and the echo subscription's delivery is the
+ * sync point — by the time it lands, a refused path that had been persisted
+ * would have received the same event. That catches "201 then verify later"
+ * and "400 but keep the row".
+ *
+ * How it FAILS: a host that answers 201 without verifying (no-echo is 201); a
+ * host that follows the 307 (the target sees a hit); a host that verifies
+ * afterwards (a refused path receives a delivery); a host that retries the
+ * verification (two requests on one path).
+ *
+ * @see spec/v2/core/webhooks.md §Standard Webhooks
+ * @see RFCS/0201-standard-webhooks-signature-scheme.md §D
+ */
+
+import { afterEach, describe, it, expect } from 'vitest';
+import { req } from '../lib/requirement-ids.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { v2Validator } from '../lib/v2.js';
+import { hitHeader, mintWhsec, startModalReceiver, verifyStandardWebhooks } from '../lib/webhook-receiver.js';
+import {
+  STANDARD_WEBHOOKS_ALG,
+  deliveriesFor,
+  driveRun,
+  loopbackRefusal,
+  registerSw,
+  swGate,
+  unregisterAllSw,
+  waitFor,
+} from '../lib/standard-webhooks.js';
+
+const REFUSED = ['no-echo', 'wrong-echo', 'redirect'] as const;
+
+let closeReceiver: (() => Promise<void>) | null = null;
+afterEach(async () => {
+  await unregisterAllSw();
+  if (closeReceiver) { const c = closeReceiver; closeReceiver = null; await c(); }
+});
+
+describe('RFC 0201 §D — endpoint verification refuses without consent (opted-in registrations only)', () => {
+  it('no-echo, wrong-echo and a redirect are refused and persist nothing; an echo is accepted', async () => {
+    const g = await swGate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const rx = await startModalReceiver();
+    closeReceiver = rx.close;
+    const secret = mintWhsec();
+    const body = (mode: string): Record<string, unknown> => ({ url: rx.urlFor(mode).url, events: ['run.completed'], signatureAlgorithms: ['v1', STANDARD_WEBHOOKS_ALG], secret });
+    const tunnelled = rx.urlFor('echo').tunnelled;
+
+    // Register the echo subscription first: its 201 is the positive control, and
+    // a loopback refusal here is `blocked` before anything is asserted.
+    const ok = await registerSw(body('echo'));
+    const blocked = loopbackRefusal(ok, tunnelled);
+    if (blocked) return softSkip('blocked', blocked);
+    const refused = new Map<string, { status: number; code: string | undefined; id: unknown }>();
+    for (const mode of REFUSED) {
+      const res = await registerSw(body(mode));
+      refused.set(mode, { status: res.status, code: readErrorCode(res.json), id: (res.json as { webhookId?: unknown } | null)?.webhookId });
+    }
+
+    const ID = 'openwop.requirement.0201.endpoint-verification';
+    expect(ok.status, req(ID, 'RFC 0201 §D.14', `an endpoint that echoes the challenge MUST be registered 201 (got ${ok.status} ${readErrorCode(ok.json) ?? ''})`)).toBe(201);
+    const echoId = (ok.json as { webhookId: string }).webhookId;
+    for (const [mode, r] of refused) {
+      expect(r.status, req(ID, 'RFC 0201 §D.14', `a ${mode} endpoint MUST be refused 400 before any 201 (got ${r.status})`)).toBe(400);
+      expect(r.code, req(ID, 'RFC 0201 §D.14', `a ${mode} refusal MUST carry webhook_endpoint_unverified`)).toBe('webhook_endpoint_unverified');
+    }
+
+    const validate = v2Validator('webhook-verification');
+    for (const mode of ['echo', ...REFUSED]) {
+      const vr = rx.hits.filter((h) => h.mode === mode && h.verification);
+      expect(vr.length, req(ID, 'RFC 0201 §D.13–§D.14', `the host MUST send exactly one verification request to the ${mode} endpoint and MUST NOT retry it (saw ${vr.length})`)).toBe(1);
+      const h = vr[0]!;
+      expect(h.method, req(ID, 'RFC 0201 §D.13', 'the verification request MUST be a POST')).toBe('POST');
+      const parsed = JSON.parse(h.body) as unknown;
+      const v = validate(parsed);
+      expect(v.ok, req(ID, 'RFC 0201 §D.13', `the verification body MUST validate against webhook-verification.schema.json (${v.errors})`)).toBe(true);
+      expect(hitHeader(h, 'openwop-event-type'), req(ID, 'RFC 0201 §D.13', 'the verification request is not a delivery and MUST carry no OpenWOP-Event-Type')).toBeUndefined();
+      const verdict = verifyStandardWebhooks(h.body, h.headers, secret);
+      expect(verdict.matched, req(ID, 'RFC 0201 §D.13', `the verification request MUST be signed as §C.9 with the supplied secret (verifier: ${verdict.reason ?? 'ok'})`)).toBeGreaterThan(0);
+    }
+    const challenges = rx.hits.filter((h) => h.verification).map((h) => (JSON.parse(h.body) as { challenge: string }).challenge);
+    expect(new Set(challenges).size, req(ID, 'RFC 0201 §D.13', 'each verification MUST carry a FRESH challenge')).toBe(challenges.length);
+    expect(
+      rx.hits.filter((h) => h.mode === 'redirect-target').length,
+      req(ID, 'RFC 0201 §D.13', 'the verification request MUST NOT follow a redirect — the 307 target MUST see nothing'),
+    ).toBe(0);
+
+    // Persisted nothing: drive a run and wait for the echo subscription's
+    // delivery; by then any persisted refused subscription would have one too.
+    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, echoId, run.runId).length > 0, 15_000);
+    expect(deliveriesFor(rx.hits, echoId, run.runId).length, req(ID, 'webhooks.md §Durability', 'the verified subscription MUST receive run.completed — the sync point for the persisted-nothing check')).toBeGreaterThan(0);
+    await new Promise((r) => setTimeout(r, 1_000));
+    for (const mode of REFUSED) {
+      const late = rx.hits.filter((h) => h.mode === mode && !h.verification);
+      expect(late.length, req(ID, 'RFC 0201 §D.14', `a refused (${mode}) registration MUST persist no subscription — it received ${late.length} later request(s)`)).toBe(0);
+    }
+  }, 60_000);
+});

package/src/scenarios/v2-webhook-message-id-stable.test.ts

@@ -0,0 +1,124 @@
+/**
+ * RFC 0201 §C.10 — the signed delivery id is stable across retries and
+ * distinct across deliveries (suite 2.36.0, target major 2; gated on
+ * `webhooks.signatureAlgorithms` listing `standard-webhooks-1`).
+ *
+ * `webhook-id` is the receiver's idempotency key, and because it is inside the
+ * Standard Webhooks signed bytes it is an AUTHENTICATED one. That only helps if
+ * the host keeps it still: a per-attempt id makes a durable host's retries look
+ * like new events, and a constant id makes new events look like retries.
+ *
+ * How the receiver is driven: `fail2` answers `500` to the first two attempts
+ * for each `(OpenWOP-Webhook-Id, runId, sequence)` and `204` afterwards, so
+ * every delivery is attempted at least twice (retries are a v2 MUST,
+ * webhooks.md §Durability). Two opted-in subscriptions to the SAME URL, each on
+ * `run.started` + `run.completed`, give four distinct deliveries of one run:
+ * two by event, two by subscription.
+ *
+ * Observe first, then assert (the 2.34.1 lesson): if no delivery key was seen
+ * twice inside the window, the leg returns `blocked` before any obligation is
+ * asserted, so an unmeasured window can never fold into a partial-witness pass.
+ *
+ * How it FAILS: a per-attempt `randomUUID()` id (first half); a constant id or
+ * the subscription id (the distinctness half); an id containing `.` (grammar).
+ * The restart half of §C.10 (an attempt after a host restart) needs the RFC
+ * 0158 kill hook and is NOT claimed by this file.
+ *
+ * @see spec/v2/core/webhooks.md §Standard Webhooks
+ * @see RFCS/0201-standard-webhooks-signature-scheme.md §C.10
+ */
+
+import { afterEach, describe, it, expect } from 'vitest';
+import { req } from '../lib/requirement-ids.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { hitHeader, mintWhsec, startModalReceiver, STANDARD_WEBHOOKS_ID, type ModalHit } from '../lib/webhook-receiver.js';
+import { retryWaitCapMs, retryWaitFor } from '../lib/webhook-retry-window.js';
+import {
+  STANDARD_WEBHOOKS_ALG,
+  deliveriesFor,
+  driveRun,
+  loopbackRefusal,
+  registerSw,
+  swGate,
+  unregisterAllSw,
+  waitFor,
+} from '../lib/standard-webhooks.js';
+
+const EVENTS = ['run.started', 'run.completed'];
+const CAP_MS = retryWaitCapMs();
+
+let closeReceiver: (() => Promise<void>) | null = null;
+afterEach(async () => {
+  await unregisterAllSw();
+  if (closeReceiver) { const c = closeReceiver; closeReceiver = null; await c(); }
+});
+
+function keyOf(h: ModalHit): string {
+  let runId = '';
+  let seq = '';
+  try {
+    const b = JSON.parse(h.body) as { runId?: unknown; event?: { sequence?: unknown } };
+    runId = String(b.runId ?? '');
+    seq = String(b.event?.sequence ?? '');
+  } catch { /* keyed on the header alone */ }
+  return `${hitHeader(h, 'openwop-webhook-id') ?? ''}|${runId}|${seq}`;
+}
+
+describe('RFC 0201 §C.10 — webhook-id is stable across retries, distinct across deliveries', () => {
+  it('every attempt of one delivery carries one webhook-id, and distinct deliveries carry distinct ids', 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('fail2');
+    const subs: string[] = [];
+    for (let i = 0; i < 2; i++) {
+      const reg = await registerSw({ url: target.url, events: EVENTS, signatureAlgorithms: ['v1', STANDARD_WEBHOOKS_ALG], secret: mintWhsec() });
+      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) ?? ''} — no subscription to observe (the registration rules are v2-webhook-standard-webhooks-delivery's rows)`);
+      subs.push((reg.json as { webhookId: string }).webhookId);
+    }
+    const run = await driveRun();
+    if (run.runId === null) return softSkip('blocked', `POST /runs answered ${run.status} — no delivery to observe`);
+    const ours = (): ModalHit[] => subs.flatMap((s) => deliveriesFor(rx.hits, s, run.runId));
+    const byKey = (): Map<string, ModalHit[]> => {
+      const m = new Map<string, ModalHit[]>();
+      for (const h of ours()) m.set(keyOf(h), [...(m.get(keyOf(h)) ?? []), h]);
+      return m;
+    };
+    const expectedKeys = subs.length * EVENTS.length;
+    const window = retryWaitFor((g.facet['retryPolicy'] as { backoff?: string } | undefined) ?? null, CAP_MS);
+    await waitFor(() => {
+      const m = byKey();
+      return m.size >= expectedKeys && [...m.values()].every((a) => a.length >= 2);
+    }, window);
+    const keys = byKey();
+    const retried = [...keys.values()].filter((a) => a.length >= 2);
+    // OBSERVE FIRST: nothing is asserted until the window question is answered.
+    if (retried.length === 0) {
+      return softSkip('blocked', `no delivery was attempted twice inside the ${window}ms window (${ours().length} attempt(s) over ${keys.size} key(s)); the receiver answers 500 twice per key, so a retrying host shows two — unmeasured, not unmet (RFC 0148 §A)`);
+    }
+    const ID = 'openwop.requirement.0201.message-id-stable';
+    for (const [key, attempts] of retried.map((a) => [keyOf(a[0]!), a] as const)) {
+      const ids = new Set(attempts.map((a) => hitHeader(a, 'webhook-id') ?? '<absent>'));
+      expect(
+        [...ids],
+        req(ID, 'RFC 0201 §C.10', `webhook-id MUST be identical on every attempt of one (webhookId, runId, sequence) — ${attempts.length} attempts of ${key} carried ${ids.size} value(s)`),
+      ).toHaveLength(1);
+    }
+    const perKey = [...keys.entries()].map(([key, a]) => ({ key, id: hitHeader(a[0]!, 'webhook-id') ?? '' }));
+    for (const { key, id } of perKey) {
+      expect(STANDARD_WEBHOOKS_ID.test(id), req(ID, 'RFC 0201 §C.10', `webhook-id MUST match ^[A-Za-z0-9_-]{16,128}$ (${key}: ${JSON.stringify(id)})`)).toBe(true);
+    }
+    expect(keys.size, req(ID, 'RFC 0201 §C.10', `two opted-in subscriptions on ${EVENTS.join(' + ')} MUST yield ${expectedKeys} distinct deliveries of one run`)).toBeGreaterThanOrEqual(2);
+    expect(
+      new Set(perKey.map((k) => k.id)).size,
+      req(ID, 'RFC 0201 §C.10', `webhook-id MUST differ between distinct deliveries, by event and by subscription — ${perKey.length} deliveries carried ${new Set(perKey.map((k) => k.id)).size} distinct id(s)`),
+    ).toBe(perKey.length);
+    for (const { id } of perKey) {
+      expect(subs.includes(id), req(ID, 'RFC 0201 §C.11', 'webhook-id MUST NOT be the subscription id')).toBe(false);
+    }
+  }, CAP_MS + 45_000);
+});