@openwop/openwop-conformance 2.35.0 → 2.36.0

package/src/lib/protected-resource.ts

@@ -0,0 +1,88 @@
+/**
+ * RFC 0200 §A — the shared gate and the derived URL for the protected-resource
+ * scenarios.
+ *
+ * The gate is the lane, not a `.supported` seat: §A.1 binds a host that advertises an
+ * `auth.lanes[]` member with `lane ∈ {oauth2, oidc}` and binds no other. A host with
+ * neither records `inapplicable`; a host with one that then answers `404` at the derived
+ * URL records an `executed-fail`, never a soft-skip — the lane is the advertisement and
+ * the document is owed.
+ *
+ * @see spec/v2/core/identity.md §2.5
+ * @see RFCS/0200-host-as-oauth-protected-resource.md §A, §B
+ */
+
+import { loadEnv } from './env.js';
+import { v2Discovery } from './v2.js';
+import type { SoftSkipKind } from './soft-skip.js';
+
+export const PRM_SEGMENT = '/.well-known/oauth-protected-resource';
+
+export interface Lane {
+  readonly lane?: unknown;
+  readonly issuers?: unknown;
+  readonly minimumAssurance?: unknown;
+  readonly delegationProofs?: unknown;
+}
+
+export type PrmGate =
+  | { readonly ok: true; readonly doc: Record<string, unknown>; readonly lanes: readonly Lane[]; readonly resource: string; readonly prmUrl: string }
+  | { readonly ok: false; readonly kind: SoftSkipKind; readonly reason: string };
+
+/**
+ * RFC 9728 §3 / §3.1 — insert `/.well-known/oauth-protected-resource` between the host
+ * component and any path of the resource identifier, removing a terminating slash after
+ * the host. A root-mounted host gets `https://h.example/.well-known/…`; a host under
+ * `/api` gets `https://h.example/.well-known/…/api`.
+ */
+export function prmUrlFor(resource: string): string {
+  const u = new URL(resource);
+  const path = u.pathname.replace(/\/$/, '');
+  return `${u.origin}${PRM_SEGMENT}${path}`;
+}
+
+/** The lanes §A.1 gates on, read off the live discovery document. */
+export function oauthLanes(doc: Record<string, unknown>): Lane[] {
+  const auth = doc['auth'] as { lanes?: unknown } | undefined;
+  const lanes = Array.isArray(auth?.lanes) ? (auth.lanes as Lane[]) : [];
+  return lanes.filter((l) => l.lane === 'oauth2' || l.lane === 'oidc');
+}
+
+/** Every lane the host advertises, OAuth or not — the mount leg reads this. */
+export function allLanes(doc: Record<string, unknown>): Lane[] {
+  const auth = doc['auth'] as { lanes?: unknown } | undefined;
+  return Array.isArray(auth?.lanes) ? (auth.lanes as Lane[]) : [];
+}
+
+/**
+ * The URL-form issuers of the OAuth lanes. `identity.md` §2.5 says
+ * `authorization_servers` MUST list exactly these: a `urn:` trust root (the api-key,
+ * session and anonymous lanes) is not an authorization server and is excluded.
+ */
+export function urlIssuers(lanes: readonly Lane[]): string[] {
+  return [...new Set(lanes.flatMap((l) => (Array.isArray(l.issuers) ? l.issuers.map(String) : [])).filter((i) => /^https?:\/\//.test(i)))].sort();
+}
+
+export async function prmGate(): Promise<PrmGate> {
+  let doc: Record<string, unknown> | null = null;
+  try { doc = await v2Discovery(); } catch { doc = null; }
+  if (!doc) return { ok: false, kind: 'blocked', reason: 'v2 discovery unreachable — the lanes cannot be read, so nothing is gated' };
+  const lanes = oauthLanes(doc);
+  if (lanes.length === 0) {
+    return { ok: false, kind: 'inapplicable', reason: 'no auth.lanes[] member has lane oauth2 or oidc — RFC 0200 §A.1 does not bind this host (serving the metadata anyway is RECOMMENDED, not required, and is not measured here)' };
+  }
+  const resource = loadEnv().baseUrl;
+  return { ok: true, doc, lanes, resource, prmUrl: prmUrlFor(resource) };
+}
+
+/** Parse a `WWW-Authenticate: Bearer k="v", …` value into its scheme and auth-params. */
+export function parseChallenge(raw: string | null): { scheme: string; params: Record<string, string> } | null {
+  if (raw === null || raw.trim() === '') return null;
+  const m = /^\s*([A-Za-z0-9!#$%&'*+.^_`|~-]+)\s*(.*)$/s.exec(raw);
+  if (!m) return null;
+  const params: Record<string, string> = {};
+  for (const p of (m[2] ?? '').matchAll(/([A-Za-z0-9!#$%&'*+.^_`|~-]+)\s*=\s*(?:"([^"]*)"|([^,\s]+))/g)) {
+    params[(p[1] as string).toLowerCase()] = (p[2] ?? p[3] ?? '');
+  }
+  return { scheme: (m[1] as string).toLowerCase(), params };
+}

package/src/lib/standard-webhooks.ts

@@ -0,0 +1,120 @@
+/**
+ * RFC 0201 — shared plumbing for the four `v2-webhook-*` Standard Webhooks
+ * scenarios: the gate, the registration call, the run that produces a
+ * delivery, and cleanup. The verifier and the modal receiver live in
+ * `webhook-receiver.ts`; this file only drives the host.
+ *
+ * Gating (RFC 0201 §Conformance): every leg reads the v2 `webhooks` facet. A
+ * host that does not list `standard-webhooks-1` records `inapplicable`; a host
+ * whose egress guard refuses the loopback receiver records `blocked`, as the
+ * other webhook scenarios do; `OPENWOP_WEBHOOK_RECEIVER_URL` (a public https
+ * front for the receiver) waives nothing and is the certification posture.
+ *
+ * @see spec/v2/core/webhooks.md §Standard Webhooks
+ * @see RFCS/0201-standard-webhooks-signature-scheme.md
+ */
+
+import { driver, type OpenWOPResponse } from './driver.js';
+import { v2Discovery, gateFamily } from './v2.js';
+import { readErrorCode } from './error-envelope.js';
+import type { SoftSkipKind } from './soft-skip.js';
+import { projectBoundId } from './bound-id.js';
+import { hitHeader, type ModalHit } from './webhook-receiver.js';
+
+export const STANDARD_WEBHOOKS_ALG = 'standard-webhooks-1';
+export const SW_FIXTURE = 'conformance-noop';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+export type SwGate =
+  | { readonly ok: true; readonly doc: Record<string, unknown>; readonly facet: Record<string, unknown> }
+  | { readonly ok: false; readonly kind: SoftSkipKind; readonly reason: string };
+
+/**
+ * The gate every RFC 0201 leg shares. A refusal carries its disposition so the
+ * leg records it at the return site (`check-req-only` rule (c)):
+ * `const g = await swGate(); if (!g.ok) return softSkip(g.kind, g.reason);`.
+ */
+export async function swGate(): Promise<SwGate> {
+  let doc: Record<string, unknown> | null = null;
+  try { doc = await v2Discovery(); } catch { doc = null; }
+  if (!doc) return { ok: false, kind: 'blocked', reason: 'v2 discovery unreachable' };
+  const facet = await gateFamily('webhooks');
+  if (!facet) return { ok: false, kind: 'inapplicable', reason: 'webhooks family not advertised (gate recorded under openwop.family.webhooks)' };
+  const algs = Array.isArray(facet['signatureAlgorithms']) ? (facet['signatureAlgorithms'] as unknown[]) : [];
+  if (!algs.includes(STANDARD_WEBHOOKS_ALG)) {
+    return { ok: false, kind: 'inapplicable', reason: `webhooks.signatureAlgorithms does not list ${STANDARD_WEBHOOKS_ALG} (RFC 0201 §A.3) — the companion scheme is not offered` };
+  }
+  const fixtures = Array.isArray(doc['fixtures']) ? (doc['fixtures'] as unknown[]) : [];
+  if (!fixtures.includes(SW_FIXTURE)) return { ok: false, kind: 'inapplicable', reason: `${SW_FIXTURE} fixture not advertised — no run to deliver` };
+  return { ok: true, doc, facet };
+}
+
+const registered: string[] = [];
+
+/** `POST /webhooks`; every 201 is remembered for `unregisterAllSw()`. */
+export async function registerSw(body: Record<string, unknown>): Promise<OpenWOPResponse> {
+  const res = await driver.post('/webhooks', body);
+  const id = (res.json as { webhookId?: unknown } | null)?.webhookId;
+  if (res.status === 201 && typeof id === 'string') registered.push(id);
+  return res;
+}
+
+/**
+ * The `blocked` reason when the host's SSRF guard refused the loopback receiver,
+ * else `null`. A refusal of the operator's PUBLIC front is a finding, not a
+ * block, and throws.
+ */
+export function loopbackRefusal(res: OpenWOPResponse, tunnelled: boolean): string | null {
+  if (res.status === 400 && readErrorCode(res.json) === 'webhook_url_rejected') {
+    if (tunnelled) throw new Error('host rejected the operator-supplied public https receiver with webhook_url_rejected — a public https destination is legitimate under webhooks.md §Egress');
+    return 'host SSRF guard rejected the loopback receiver (webhooks.md §Egress requires it); set OPENWOP_WEBHOOK_RECEIVER_URL to a public https front for the suite receiver to witness';
+  }
+  return null;
+}
+
+/** Unregister every subscription this worker registered (best effort; the verdict is already recorded). */
+export async function unregisterAllSw(): Promise<void> {
+  for (const id of registered.splice(0)) {
+    try { await driver.delete(`/webhooks/${projectBoundId(id)}`); } catch { /* best effort */ }
+  }
+}
+
+/** Start one run of the noop fixture and wait (bounded) for it to finish. */
+export async function driveRun(timeoutMs = 10_000): Promise<{ status: number; runId: string | null }> {
+  const create = await driver.post('/runs', { workflowId: SW_FIXTURE });
+  const runId = create.status === 201 ? ((create.json as { runId?: unknown } | null)?.runId as string | undefined) ?? null : null;
+  if (runId !== null) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+      const res = await driver.get(`/runs/${encodeURIComponent(runId)}`);
+      const st = res.status === 200 ? String((res.json as { status?: unknown } | null)?.status ?? '') : '';
+      if (TERMINAL.has(st) || Date.now() > deadline) break;
+      await new Promise((r) => setTimeout(r, 200));
+    }
+  }
+  return { status: create.status, runId };
+}
+
+export async function waitFor(pred: () => boolean, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (pred()) return true;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  return pred();
+}
+
+/** The DELIVERIES (not verification requests) one subscription received for one run. */
+export function deliveriesFor(hits: readonly ModalHit[], webhookId: string, runId: string | null): ModalHit[] {
+  return hits.filter((h) => {
+    if (h.verification) return false;
+    if ((hitHeader(h, 'openwop-webhook-id') ?? hitHeader(h, 'x-openwop-webhook-id')) !== webhookId) return false;
+    if (runId === null) return true;
+    try { return (JSON.parse(h.body) as { runId?: unknown }).runId === runId; } catch { return false; }
+  });
+}
+
+/** Every `webhook-*` header name on a hit (RFC 0201 §B.8 reads this as "must be empty" on a non-opted subscription). */
+export function standardWebhooksHeaderNames(hit: ModalHit): string[] {
+  return Object.keys(hit.headers).filter((k) => k.toLowerCase().startsWith('webhook-'));
+}

package/src/lib/toolCatalog.ts

@@ -21,14 +21,47 @@
  */
 import { driver } from './driver.js';
 import { readCapabilityFamily } from './discovery-capabilities.js';
+import { behaviorGate } from './behavior-gate.js';
+import { targetMajor } from './seams.js';
+import { familyAdvertised } from './v2.js';
+import { softSkip } from './soft-skip.js';
+
+/**
+ * The catalog path for the major in play (RFC 0204 G3). `GET /tools` is the v2
+ * spelling (`spec/v2/path-manifest.json`); the driver never rewrites a `/v1/`
+ * address that is not a seam, so a hard-coded `/v1/tools` on a v2 host is a
+ * suite 404 reported as a host defect.
+ */
+export const toolsPath = (suffix = ''): string => `${targetMajor() === 2 ? '' : '/v1'}/tools${suffix}`;
 
 /** Reads `toolCatalog` from discovery (root-first per RFC 0073); null when
- *  unadvertised. */
+ *  unadvertised. At major 2 the record's presence is the claim (RFC 0169 §A.2). */
 export async function readToolCatalogCap(): Promise<Record<string, unknown> | null> {
+  if (targetMajor() === 2) return familyAdvertised('toolCatalog');
   const tc = await readCapabilityFamily<Record<string, unknown>>('toolCatalog');
   return tc && typeof tc === 'object' ? tc : null;
 }
 
+/**
+ * The gate the three `tool-catalog-*` files share, major-aware (RFC 0204 G3).
+ * Major 1: the v1 `supported` / sub-flag seat through `behaviorGate`, unchanged.
+ * Major 2: there is no `supported` field — the record is the claim, a facet is
+ * present or absent — and an unadvertised family is recorded `inapplicable`
+ * rather than failed under strict mode, so promoting these files to both majors
+ * de-certifies no v2 host that never advertised `toolCatalog`.
+ * `facet` names the sub-flag (`compactView`) a leg needs, if any.
+ */
+export async function toolCatalogGate(profile: string, facet?: string): Promise<Record<string, unknown> | null> {
+  const cap = await readToolCatalogCap();
+  if (targetMajor() === 2) {
+    if (cap === null) { softSkip('inapplicable', 'toolCatalog not advertised at major 2 — the host publishes no catalog'); return null; }
+    if (facet !== undefined && cap[facet] !== true) { softSkip('inapplicable', `toolCatalog.${facet} not advertised at major 2`); return null; }
+    return cap;
+  }
+  const on = facet === undefined ? cap?.supported === true : cap?.[facet] === true;
+  return behaviorGate(profile, on) ? (cap ?? {}) : null;
+}
+
 export interface ToolDescriptor {
   toolId?: string;
   source?: string;
@@ -39,7 +72,7 @@ export interface ToolDescriptor {
 /** GET the NORMATIVE tool catalog (RFC 0078 §B `GET /v1/tools`); null when the
  *  host doesn't serve it (404/405/501). */
 export async function listTools(): Promise<ToolDescriptor[] | null> {
-  const res = await driver.get('/v1/tools');
+  const res = await driver.get(toolsPath());
   if (res.status === 404 || res.status === 405 || res.status === 501) return null;
   return (res.json as ToolDescriptor[] | undefined) ?? [];
 }
@@ -50,7 +83,7 @@ export async function listTools(): Promise<ToolDescriptor[] | null> {
 export async function getTool(
   toolId: string,
 ): Promise<{ status: number; descriptor: ToolDescriptor | undefined }> {
-  const res = await driver.get(`/v1/tools/${encodeURIComponent(toolId)}`);
+  const res = await driver.get(toolsPath(`/${encodeURIComponent(toolId)}`));
   return { status: res.status, descriptor: res.json as ToolDescriptor | undefined };
 }
 
@@ -91,7 +124,7 @@ export interface CompactToolDescriptor {
  *  null when the host doesn't serve the read (404/405/501) or the body isn't
  *  the expected envelope shape. */
 export async function listToolsCompact(): Promise<CompactToolDescriptor[] | null> {
-  const res = await driver.get('/v1/tools?view=compact');
+  const res = await driver.get(toolsPath('?view=compact'));
   if (res.status === 404 || res.status === 405 || res.status === 501) return null;
   const body = res.json;
   if (!body || typeof body !== 'object') return null;
@@ -168,3 +201,20 @@ export const SAFETY_TIERS = ['pure', 'read', 'write', 'exec'];
 /** Content keys a `ToolDescriptor` / `tool.session.*` MUST NEVER carry (SR-1):
  *  no credential/secret material. */
 export const TOOL_CONTENT_FORBIDDEN = ['secret', 'credential', 'credentials', 'token', 'apiKey', 'password'];
+
+/**
+ * RFC 0204 §D.12 (`spec/v2/core/tool-catalog.md` §The descriptor): the four MCP
+ * hints as a function of the descriptor's OWN host-assigned fields — never of
+ * MCP's defaults (`destructiveHint` and `openWorldHint` default to `true`
+ * upstream) and never of anything a server said.
+ */
+export function expectedAnnotations(d: ToolDescriptor): Record<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint', boolean> {
+  const tier = d.safetyTier;
+  const rp = d['replayPolicy'];
+  return {
+    readOnlyHint: tier === 'pure' || tier === 'read',
+    destructiveHint: tier === 'write' || tier === 'exec',
+    idempotentHint: rp === 'deterministic' || rp === 'idempotent',
+    openWorldHint: d['egress'] !== 'none',
+  };
+}

package/src/lib/trace-context.ts

@@ -0,0 +1,98 @@
+/**
+ * RFC 0207 — W3C Trace Context carriers across MCP and A2A.
+ *
+ * One place that knows the `traceparent` grammar and the two carriers a host
+ * may use, so the v1 and v2 carrier scenarios cannot disagree on what counts:
+ *
+ *   MCP  — `params._meta.traceparent` (unprefixed; MCP 2026-07-28 `_meta`,
+ *          SEP-414) OR the HTTP `traceparent` header of the request.
+ *   A2A  — `params.message.metadata.openwop.traceparent` OR the HTTP header.
+ *
+ * Either carrier conforms (decisions log D4); the in-message one is SHOULD.
+ * `classifyCarriers` reports which it found so the row's detail keeps the
+ * SHOULD visible (`header-only`) without failing a conforming host.
+ *
+ * @see RFCS/0207-trace-context-across-mcp-and-a2a.md §A, §B
+ * @see https://www.w3.org/TR/trace-context/ §3.2 (traceparent)
+ */
+import { randomBytes } from 'node:crypto';
+
+export interface Traceparent {
+  readonly version: string;
+  readonly traceId: string;
+  readonly parentId: string;
+  readonly flags: string;
+}
+
+const ZERO_TRACE = '0'.repeat(32);
+const ZERO_SPAN = '0'.repeat(16);
+const GRAMMAR = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/;
+
+/** A fresh, valid version-00 `traceparent` with a random trace id and span id, sampled. */
+export function makeTraceparent(): Traceparent & { readonly header: string } {
+  let traceId = randomBytes(16).toString('hex');
+  while (traceId === ZERO_TRACE) traceId = randomBytes(16).toString('hex');
+  let parentId = randomBytes(8).toString('hex');
+  while (parentId === ZERO_SPAN) parentId = randomBytes(8).toString('hex');
+  return { version: '00', traceId, parentId, flags: '01', header: `00-${traceId}-${parentId}-01` };
+}
+
+/**
+ * Parse a `traceparent` per W3C Trace Context §3.2: lowercase hex, version
+ * `ff` invalid, all-zero trace id or parent id invalid, and a version-00 value
+ * has exactly four fields. Returns null for anything else.
+ */
+export function parseTraceparent(value: unknown): Traceparent | null {
+  if (typeof value !== 'string') return null;
+  const v = value.trim();
+  // A future version may append fields after a '-'; version 00 has exactly four.
+  const m = GRAMMAR.exec(v.slice(0, 55));
+  if (m === null) return null;
+  const version = m[1]!; const traceId = m[2]!; const parentId = m[3]!; const flags = m[4]!;
+  if (version === 'ff') return null;
+  if (v.length > 55 && (version === '00' || v[55] !== '-')) return null;
+  if (traceId === ZERO_TRACE || parentId === ZERO_SPAN) return null;
+  return { version, traceId, parentId, flags };
+}
+
+/** `params._meta.traceparent` of a recorded MCP request, or undefined. Only the UNPREFIXED key counts. */
+export function mcpMetaTraceparent(params: unknown): unknown {
+  const meta = (params as { _meta?: unknown } | null | undefined)?._meta;
+  if (meta === null || typeof meta !== 'object' || Array.isArray(meta)) return undefined;
+  return (meta as Record<string, unknown>)['traceparent'];
+}
+
+/** `params.message.metadata.openwop.traceparent` of a recorded A2A JSON-RPC body, or undefined. */
+export function a2aMetadataTraceparent(body: unknown): unknown {
+  const message = (body as { params?: { message?: unknown } } | null | undefined)?.params?.message;
+  const metadata = (message as { metadata?: unknown } | null | undefined)?.metadata;
+  const openwop = (metadata as { openwop?: unknown } | null | undefined)?.openwop;
+  if (openwop === null || typeof openwop !== 'object' || Array.isArray(openwop)) return undefined;
+  return (openwop as Record<string, unknown>)['traceparent'];
+}
+
+export type CarrierVerdict =
+  | { readonly ok: true; readonly detail: 'both' | 'in-message' | 'header-only' }
+  | { readonly ok: false; readonly reason: string };
+
+/**
+ * The D4 verdict for one recorded outbound request.
+ *
+ *   - neither carrier present                        → fail
+ *   - a present carrier does not parse                → fail (W3C grammar)
+ *   - a present carrier's trace id is not `traceId`   → fail (the host minted a new trace)
+ *   - otherwise pass; detail names what was found — `header-only` when the
+ *     in-message carrier (SHOULD) is absent.
+ */
+export function classifyCarriers(inMessage: unknown, header: string | undefined, traceId: string, names: { inMessage: string }): CarrierVerdict {
+  const hasMsg = inMessage !== undefined;
+  const hasHdr = header !== undefined;
+  if (!hasMsg && !hasHdr) return { ok: false, reason: `neither carrier is present: no ${names.inMessage} and no HTTP traceparent header` };
+  for (const [where, raw] of [[names.inMessage, hasMsg ? inMessage : undefined], ['the HTTP traceparent header', hasHdr ? header : undefined]] as const) {
+    if (raw === undefined) continue;
+    const tp = parseTraceparent(raw);
+    if (tp === null) return { ok: false, reason: `${where} is not a valid W3C traceparent: ${JSON.stringify(raw)}` };
+    if (tp.traceId !== traceId.toLowerCase()) return { ok: false, reason: `${where} carries trace id ${tp.traceId}, not the suite's ${traceId} — the host started a new trace instead of propagating the run's` };
+  }
+  return { ok: true, detail: hasMsg && hasHdr ? 'both' : hasMsg ? 'in-message' : 'header-only' };
+}

package/src/lib/v2.ts

@@ -60,3 +60,9 @@ export function v2Validator(name: string): (doc: unknown) => { ok: boolean; erro
   const validate = a.getSchema(id) ?? a.compile(JSON.parse(readFileSync(join(SCHEMAS_DIR, 'v2', ...name.split('/')), 'utf8')) as Record<string, unknown>);
   return (doc: unknown) => ({ ok: validate(doc) as boolean, errors: a.errorsText(validate.errors, { separator: '; ' }) });
 }
+/** A validator for a `$ref` into the v2 tree (`<file>.schema.json#/$defs/<name>`), resolved against the registered v2 schemas. */
+export function v2RefValidator(ref: string): (doc: unknown) => { ok: boolean; errors: string } {
+  const a = v2Ajv();
+  const validate = a.getSchema(`https://openwop.dev/spec/v2/${ref}`) ?? a.compile({ $ref: `https://openwop.dev/spec/v2/${ref}` });
+  return (doc: unknown) => ({ ok: validate(doc) as boolean, errors: a.errorsText(validate.errors, { separator: '; ' }) });
+}

package/src/lib/webhook-receiver.ts

@@ -15,7 +15,8 @@
  *      implementation; this file is a conformance-suite mirror)
  */
 
-import { createHmac, timingSafeEqual } from 'node:crypto';
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
 
 /**
  * The `X-openwop-Signature` value prefix, per `webhooks.md` §"Delivery headers"
@@ -343,3 +344,202 @@ export function receiverBinding(): { bind: string; advertise: string } {
   if (!advertise) return { bind: '127.0.0.1', advertise: '127.0.0.1' };
   return { bind: '0.0.0.0', advertise };
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RFC 0201 — the Standard Webhooks 1.0.0 companion scheme (`standard-webhooks-1`)
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// Implemented FROM THE SPEC RECIPE, not by importing the upstream library, so
+// that a library defect cannot make a leg pass: Standard Webhooks 1.0.0
+// §"Signature scheme" — "the message's: ID, timestamp and body are concatenated
+// … `msg_id.timestamp.payload`", HMAC-SHA256, base64, prefixed `v1,`; the
+// secret is `whsec_` + base64 of 24–64 random bytes, and the KEY is the
+// decoded bytes; §"Webhook headers" — `webhook-signature` is a space-delimited
+// list, and a verifier tries each entry. `webhook-receiver.test.ts` pins this
+// against the upstream reference library's own `sign` test vector.
+
+/** RFC 0201 §C.10 — `webhook-id` grammar (Standard Webhooks forbids `.` in the id). */
+export const STANDARD_WEBHOOKS_ID = /^[A-Za-z0-9_-]{16,128}$/;
+export const WHSEC_PREFIX = 'whsec_';
+
+/** The HMAC key of a `whsec_` secret: its base64 body, decoded. `null` when the secret is not that form or decodes outside 24–64 bytes. */
+export function decodeWhsec(secret: string): Buffer | null {
+  if (!secret.startsWith(WHSEC_PREFIX)) return null;
+  const body = secret.slice(WHSEC_PREFIX.length);
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(body)) return null;
+  const key = Buffer.from(body, 'base64');
+  return key.length >= 24 && key.length <= 64 ? key : null;
+}
+
+/** A fresh `whsec_` secret of `bytes` random bytes (default 32). */
+export function mintWhsec(bytes = 32): string {
+  return `${WHSEC_PREFIX}${randomBytes(bytes).toString('base64')}`;
+}
+
+/** One `webhook-signature` entry, `v1,<base64>`, over `{id}.{timestamp}.{rawBody}`. */
+export function standardWebhooksSign(secret: string, id: string, timestamp: string | number, rawBody: string | Buffer): string {
+  const key = decodeWhsec(secret);
+  if (key === null) throw new Error('standardWebhooksSign: secret is not a whsec_ secret of 24–64 bytes');
+  const bodyStr = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
+  return `v1,${createHmac('sha256', key).update(`${id}.${String(timestamp)}.${bodyStr}`, 'utf8').digest('base64')}`;
+}
+
+export type StandardWebhooksRejection =
+  | 'missing_headers'
+  | 'malformed_id'
+  | 'malformed_timestamp'
+  | 'timestamp_out_of_tolerance'
+  | 'no_matching_signature';
+
+export interface StandardWebhooksVerdict {
+  readonly accepted: boolean;
+  readonly reason?: StandardWebhooksRejection;
+  /** Every space-separated entry of `webhook-signature`. */
+  readonly entries: readonly string[];
+  /** How many of `entries` verify under the given secret. */
+  readonly matched: number;
+}
+
+type HeaderBag = Record<string, string | string[] | undefined>;
+
+function header(headers: HeaderBag, name: string): string | undefined {
+  const lower = name.toLowerCase();
+  for (const [k, v] of Object.entries(headers)) {
+    if (k.toLowerCase() === lower) return Array.isArray(v) ? v.join(', ') : v;
+  }
+  return undefined;
+}
+
+/**
+ * Verify a Standard Webhooks delivery the way an unmodified receiver would:
+ * constant-time compare of every `v1,` entry, ±5 minutes tolerance (the
+ * reference library's default, and the window v1/v2 §Verification set).
+ * Non-`v1,` entries (`v1a,` — the asymmetric scheme) are listed but never match.
+ */
+export function verifyStandardWebhooks(
+  rawBody: string | Buffer,
+  headers: HeaderBag,
+  secret: string,
+  options: { toleranceSeconds?: number; nowSeconds?: number } = {},
+): StandardWebhooksVerdict {
+  const id = header(headers, 'webhook-id');
+  const ts = header(headers, 'webhook-timestamp');
+  const sig = header(headers, 'webhook-signature');
+  if (id === undefined || ts === undefined || sig === undefined) return { accepted: false, reason: 'missing_headers', entries: [], matched: 0 };
+  const entries = sig.split(' ').filter((e) => e.length > 0);
+  if (id.includes('.') || id.length === 0) return { accepted: false, reason: 'malformed_id', entries, matched: 0 };
+  if (!/^\d+$/.test(ts)) return { accepted: false, reason: 'malformed_timestamp', entries, matched: 0 };
+  const tolerance = options.toleranceSeconds ?? DEFAULT_FRESHNESS_WINDOW_SECONDS;
+  const now = options.nowSeconds ?? Math.floor(Date.now() / 1000);
+  if (Math.abs(now - Number(ts)) > tolerance) return { accepted: false, reason: 'timestamp_out_of_tolerance', entries, matched: 0 };
+  const expected = Buffer.from(standardWebhooksSign(secret, id, ts, rawBody).slice(3), 'base64');
+  let matched = 0;
+  for (const entry of entries) {
+    const comma = entry.indexOf(',');
+    if (comma < 0 || entry.slice(0, comma) !== 'v1') continue;
+    const given = Buffer.from(entry.slice(comma + 1), 'base64');
+    if (given.length === expected.length && timingSafeEqual(given, expected)) matched += 1;
+  }
+  return matched > 0 ? { accepted: true, entries, matched } : { accepted: false, reason: 'no_matching_signature', entries, matched };
+}
+
+/** One request the modal receiver saw. `mode` is the path segment it was routed by. */
+export interface ModalHit {
+  readonly mode: string;
+  readonly path: string;
+  readonly method: string;
+  readonly headers: HeaderBag;
+  readonly body: string;
+  readonly status: number;
+  readonly verification: boolean;
+  readonly at: number;
+}
+
+/**
+ * RFC 0201 — the suite receiver with a VERIFICATION MODE per path.
+ *
+ * One server, many behaviours, routed by the path segment after a per-scenario
+ * nonce (`/<nonce>/<mode>`), because behind a public front every scenario shares
+ * ONE tunnelled URL and ONE pinned port: the mode has to travel in the URL the
+ * host is given, not in which local server happens to be listening.
+ *
+ *   echo        verification → 200 `{ challenge }`; delivery → 204
+ *   no-echo     verification → 200 `{}`;            delivery → 204
+ *   wrong-echo  verification → 200 `{ challenge: <another value> }`; delivery → 204
+ *   redirect    anything → 307 to `redirect-target` (a host MUST NOT follow it)
+ *   redirect-target  echo, but every hit is recorded so a followed redirect shows
+ *   fail2       verification → echo; delivery → 500 for the first two attempts of
+ *               each `(OpenWOP-Webhook-Id, runId, sequence)`, then 204
+ *
+ * A request is a VERIFICATION when its JSON body's `type` is
+ * `openwop.webhook.verification`; every hit is recorded either way.
+ */
+export async function startModalReceiver(): Promise<{
+  server: Server;
+  nonce: string;
+  hits: ModalHit[];
+  /** The URL to register for `mode` — the public front when `OPENWOP_WEBHOOK_RECEIVER_URL` is set, else loopback. */
+  urlFor: (mode: string) => { url: string; tunnelled: boolean };
+  close: () => Promise<void>;
+}> {
+  const nonce = randomBytes(6).toString('hex');
+  const hits: ModalHit[] = [];
+  const failures = new Map<string, number>();
+  const server = createServer((request: IncomingMessage, res: ServerResponse) => {
+    const chunks: Buffer[] = [];
+    request.on('data', (c: Buffer) => chunks.push(c));
+    request.on('end', () => {
+      const body = Buffer.concat(chunks).toString('utf8');
+      const path = request.url ?? '/';
+      const segs = path.split('?')[0]!.split('/').filter((x) => x.length > 0);
+      const at = segs.indexOf(nonce);
+      const mode = at >= 0 && at + 1 < segs.length ? segs[at + 1]! : '';
+      let parsed: Record<string, unknown> | null = null;
+      try { const j = JSON.parse(body) as unknown; parsed = j && typeof j === 'object' && !Array.isArray(j) ? (j as Record<string, unknown>) : null; } catch { /* not JSON */ }
+      const verification = parsed?.['type'] === 'openwop.webhook.verification';
+      const challenge = typeof parsed?.['challenge'] === 'string' ? (parsed['challenge'] as string) : undefined;
+      const record = (status: number): void => { hits.push({ mode, path, method: request.method ?? '', headers: request.headers, body, status, verification, at: Date.now() }); };
+      const json = (status: number, obj: unknown): void => { record(status); res.writeHead(status, { 'Content-Type': 'application/json' }); res.end(JSON.stringify(obj)); };
+      const empty = (status: number, extra: Record<string, string> = {}): void => { record(status); res.writeHead(status, extra); res.end(); };
+      switch (mode) {
+        case 'echo':
+        case 'redirect-target':
+          return verification ? json(200, { challenge }) : empty(204);
+        case 'no-echo':
+          return verification ? json(200, {}) : empty(204);
+        case 'wrong-echo':
+          return verification ? json(200, { challenge: challenge === undefined ? 'not-the-challenge' : `${challenge}x` }) : empty(204);
+        case 'redirect':
+          return empty(307, { Location: path.replace(`/${nonce}/redirect`, `/${nonce}/redirect-target`) });
+        case 'fail2': {
+          if (verification) return json(200, { challenge });
+          const ev = parsed?.['event'] as { sequence?: unknown } | undefined;
+          const key = `${String(header(request.headers, 'openwop-webhook-id') ?? header(request.headers, 'x-openwop-webhook-id') ?? '')}|${String(parsed?.['runId'] ?? '')}|${String(ev?.sequence ?? '')}`;
+          const n = (failures.get(key) ?? 0) + 1;
+          failures.set(key, n);
+          return empty(n <= 2 ? 500 : 204);
+        }
+        default:
+          return empty(404);
+      }
+    });
+  });
+  const pinned = Number(process.env['OPENWOP_WEBHOOK_RECEIVER_PORT'] ?? '');
+  const bindPort = Number.isInteger(pinned) && pinned > 0 && pinned < 65536 ? pinned : 0;
+  const binding = receiverBinding();
+  await new Promise<void>((resolve) => server.listen(bindPort, binding.bind, () => resolve()));
+  const addr = server.address();
+  if (typeof addr !== 'object' || addr === null) throw new Error('receiver address unavailable');
+  const local = `http://${binding.advertise}:${addr.port}`;
+  const urlFor = (mode: string): { url: string; tunnelled: boolean } => {
+    const front = resolveRegistrationUrl(`${local}/`);
+    return { url: `${front.url.replace(/\/+$/, '')}/${nonce}/${mode}`, tunnelled: front.tunnelled };
+  };
+  const close = (): Promise<void> => new Promise<void>((resolve) => server.close(() => resolve()));
+  return { server, nonce, hits, urlFor, close };
+}
+
+/** Header lookup over a recorded hit, case-insensitive. */
+export function hitHeader(hit: { headers: HeaderBag }, name: string): string | undefined {
+  return header(hit.headers, name);
+}

package/src/scenarios/artifact-type-pack-manifest-validation.test.ts

@@ -125,7 +125,16 @@ describe('category: artifact-type-pack manifest validation', () => {
     const manifest = validManifest();
     manifest.artifactTypes[0]!.exportFormats = ['PPTX']; // uppercase, unprefixed
     const errs = failsWith(manifest, 'pattern');
-    expect(errs.length, req('openwop.it.artifact-type-pack-manifest-validation.negative-a-non-conforming-exportformats-identifier-is-rejected-reserved-core-ven', 'artifact-type-packs.md', 'artifact-type-packs.md: exportFormats identifiers are lowercase core ids OR vendor.*/x- extensions')).toBeGreaterThan(0);
+    expect(errs.length, req('openwop.it.artifact-type-pack-manifest-validation.negative-a-non-conforming-exportformats-identifier-is-rejected-reserved-core-ven', 'artifact-type-packs.md', 'artifact-type-packs.md: exportFormats identifiers are reserved-core + vendor.*/x- + lowercase media type (RFC 0205 §C.9) — PPTX is none of them')).toBeGreaterThan(0);
+  });
+
+  it('positive: lowercase media types validate beside the reserved aliases; Application/PDF does not (RFC 0205 §C.9)', () => {
+    const m = validManifest();
+    m.artifactTypes[0]!.exportFormats = ['application/pdf', 'model/step', 'application/vnd.openxmlformats-officedocument.presentationml.presentation', 'pdf'];
+    expect(validate(m), req('openwop.it.artifact-type-pack-manifest-validation.positive-lowercase-media-types-validate-beside-the-reserved-aliases-application', 'RFC 0205 §C.9', `media types (including the 73-char pptx type) MUST validate beside the aliases. Errors: ${JSON.stringify(validate.errors)}`)).toBe(true);
+    const bad = validManifest();
+    bad.artifactTypes[0]!.exportFormats = ['Application/PDF'];
+    expect(failsWith(bad, 'pattern').length, req('openwop.it.artifact-type-pack-manifest-validation.positive-lowercase-media-types-validate-beside-the-reserved-aliases-application', 'RFC 0205 §C.9', 'a media type MUST be lowercase')).toBeGreaterThan(0);
   });
 
   it('positive: the validation field accepts "open"/"closed" and rejects other values (RFC 0075)', () => {