@openwop/openwop-conformance 2.45.1 → 2.45.3

package/src/scenarios/v2-safefetch-ssrf-refused.test.ts

@@ -0,0 +1,198 @@
+/**
+ * `spec/v2/core/host-services.md` §`httpClient` — the SSRF guard REFUSES, on
+ * the resolved address (target major 2; gated on `httpClient.safeFetch` + the
+ * `conformance-safefetch-probe` fixture).
+ *
+ * The rule: "Before connecting it MUST resolve the target, reject loopback,
+ * RFC 1918, link-local and cloud-metadata addresses, and pin the resolved
+ * address for the connection (invariant `http-client-ssrf-guard`). A refused
+ * target is `egress_denied`, `reason: ssrf-blocked`; an unreachable one,
+ * `upstream_unavailable`." And for `safeFetch`: it "MUST apply that guard".
+ *
+ * Until this file the guard had no refusal witness at any major that a
+ * production host could run: `http-client-ssrf` (major 1) asserts only the
+ * `ssrfGuard: true` advertisement, and `safefetch-behavior` drives a v1 seam.
+ *
+ * No seam. Each probe runs the `conformance-safefetch-probe` fixture through
+ * `POST /runs`; its node calls the host's own `ctx.http.safeFetch(url)` and
+ * passes a rejection through as `node.failed`, code and details unchanged
+ * (conformance/fixtures.md §"The safeFetch probe fixture"). One `it` and one
+ * requirement id per address class the sentence names, so a failure names its
+ * class:
+ *
+ *   loopback      127.0.0.1, [::1]
+ *   RFC 1918      10.0.0.1, 172.16.0.1, 192.168.0.1
+ *   link-local /  169.254.169.254 (the cloud-metadata address), 169.254.0.1,
+ *   metadata      [fe80::1]
+ *   spellings     the same loopback / metadata / RFC 1918 addresses written as
+ *                 a URL parser or getaddrinfo also reads them: decimal
+ *                 (2130706433), octal (0177.0.0.1), short (127.1), and
+ *                 IPv4-mapped IPv6 in hex ([::ffff:7f00:1], [::ffff:a9fe:a9fe],
+ *                 [::ffff:a00:1]). They ARE those addresses, so the same
+ *                 obligation applies; nothing beyond the sentence is asserted.
+ *   resolved      `localhost`, a NAME the host must resolve before it can
+ *   name          judge it — a guard that checks only the literal string lets
+ *                 it connect (the sabotage the coverage report names).
+ *
+ * Every probe MUST end `failed` with `egress_denied` and `details.reason:
+ * ssrf-blocked`. The loopback-reaching probes target a listener the suite
+ * opens on its own loopback, with a per-run nonce in the path; when the host
+ * runs on the suite's machine, a guard that connects first (or not at all) is
+ * seen arriving there, and the "before connecting" half is asserted directly.
+ * Against a remote host that listener is unreachable by construction and the
+ * refusal code alone carries the leg.
+ *
+ * Not asserted, deliberately: a redirect to a private address (a public
+ * redirector would need a tunnel, and the sentence does not say whether
+ * safeFetch follows redirects), `0.0.0.0` and IPv6 ULA (not in the
+ * sentence's list for httpClient), and names that resolve only on some
+ * clouds (`metadata.google.internal` is unresolvable off GCP, where a correct
+ * host answers `upstream_unavailable`).
+ *
+ * Dispositions: v2 root unreachable ⇒ `blocked`. `httpClient` absent, or
+ * present without `safeFetch` ⇒ `inapplicable` (pack code has no egress to
+ * guard). Fixture not advertised ⇒ `inapplicable`: safeFetch has no protocol
+ * path, so the fixture is the only observation, and the host does not claim
+ * it (the `v2-memory-cross-tenant-isolation` / `v2-queue-cross-tenant-isolation`
+ * precedent). A fixture run that cannot be created or does not settle ⇒
+ * `blocked`.
+ *
+ * Sabotage (patched local v2 reference host): a guard that checks only a
+ * literal IP fails the resolved-name leg; a regex deny list on the hostname
+ * fails the spellings and link-local legs; no guard fails every leg; a guard
+ * that connects first and refuses after fails the loopback leg on the
+ * listener; a refusal coded `forbidden` fails every leg on the code.
+ *
+ * @see spec/v2/core/host-services.md §httpClient
+ * @see SECURITY/invariants.yaml id: http-client-ssrf-guard
+ * @see conformance/fixtures.md §"The safeFetch probe fixture"
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { randomUUID } from 'node:crypto';
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { v2Discovery, familyAdvertised } from '../lib/v2.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const FIXTURE = 'conformance-safefetch-probe';
+const NODE_ID = 'safefetch-probe';
+const DOC = 'spec/v2/core/host-services.md §httpClient';
+const ID_LOOPBACK = 'openwop.requirement.httpClient.ssrf-loopback-refused';
+const ID_PRIVATE = 'openwop.requirement.httpClient.ssrf-rfc1918-refused';
+const ID_LINK_LOCAL = 'openwop.requirement.httpClient.ssrf-link-local-metadata-refused';
+const ID_SPELLING = 'openwop.requirement.httpClient.ssrf-address-spellings-refused';
+const ID_RESOLVED = 'openwop.requirement.httpClient.ssrf-resolved-name-refused';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+const NONCE = randomUUID().replace(/-/g, '');
+
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const enc = (id: string): string => encodeURIComponent(id);
+
+// ── The suite's own loopback listener: any request carrying NONCE is a connection the guard let through. ──
+let listener: Server | null = null;
+let port = 0;
+const arrivals: string[] = [];
+beforeAll(async () => {
+  const s = createServer((rq, rs) => { arrivals.push(`${rq.method ?? ''} ${rq.url ?? ''}`); rs.writeHead(200, { 'content-type': 'text/plain' }); rs.end('openwop-ssrf-probe'); });
+  // `::` with dual-stack takes 127.0.0.1 and ::1 alike; fall back to IPv4 loopback where IPv6 is off.
+  const bound = await new Promise<boolean>((res) => { s.once('error', () => res(false)); s.listen({ host: '::', port: 0, ipv6Only: false }, () => res(true)); });
+  if (!bound) await new Promise<void>((res, rej) => { s.removeAllListeners('error'); s.once('error', rej); s.listen({ host: '127.0.0.1', port: 0 }, () => res()); });
+  listener = s; port = (s.address() as AddressInfo).port;
+});
+afterAll(async () => { await new Promise<void>((res) => (listener ? listener.close(() => res()) : res())); });
+const reached = (tag: string): string[] => arrivals.filter((a) => a.includes(`${NONCE}/${tag}/`));
+const path = (tag: string): string => `/openwop-ssrf-probe/${NONCE}/${tag}`;
+
+interface Outcome { readonly url: string; readonly status: string; readonly code: string | null; readonly detailReason: unknown }
+
+/** Run the probe fixture for one URL and read the node's terminal event. */
+async function probe(url: string): Promise<Outcome | { reason: string }> {
+  const created = await http(() => driver.post('/runs', { workflowId: FIXTURE, inputs: { url } }));
+  if (created === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (created.json as { runId?: unknown } | null)?.runId;
+  if (created.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs {workflowId: ${FIXTURE}} answered ${created.status} ${readErrorCode(created.json) ?? ''} — the fixture run was refused`.trim() };
+  const t0 = Date.now(); let status = '';
+  while (Date.now() - t0 < 60_000) {
+    const snap = await http(() => driver.get(`/runs/${enc(runId)}`));
+    status = String((snap?.json as { status?: unknown } | null)?.status ?? '');
+    if (TERMINAL.has(status)) break;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  if (!TERMINAL.has(status)) return { reason: `the ${FIXTURE} run for ${url} did not reach a terminal status within 60 s (last: ${status || 'unreadable'})` };
+  const ev = await http(() => driver.get(`/runs/${enc(runId)}/events/poll?timeout=1`));
+  const events = (ev?.json as { events?: unknown } | null)?.events;
+  if (ev?.status !== 200 || !Array.isArray(events)) return { reason: `GET /runs/{runId}/events/poll answered ${ev?.status ?? 'nothing'}` };
+  const failed = (events as Array<{ type?: unknown; payload?: Record<string, unknown> }>).find((e) => e.type === 'node.failed' && e.payload?.['nodeId'] === NODE_ID)?.payload;
+  const error = (failed?.['error'] ?? null) as { code?: unknown; details?: { reason?: unknown } } | null;
+  return { url, status, code: typeof error?.code === 'string' ? error.code : null, detailReason: error?.details?.reason };
+}
+
+/** The gate, then every probe of one class; or the recorded reason the leg cannot run. */
+async function leg(urls: readonly string[]): Promise<Outcome[] | { skip: ['inapplicable' | 'blocked', string] }> {
+  if (!(await v2Discovery().catch(() => null))) return { skip: ['blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0'] };
+  const hc = await familyAdvertised('httpClient');
+  if (!hc) return { skip: ['inapplicable', 'httpClient is not advertised in the v2 discovery root — the host has no outbound client to guard'] };
+  if (!hc['safeFetch'] || typeof hc['safeFetch'] !== 'object') return { skip: ['inapplicable', 'httpClient.safeFetch is not advertised — pack code has no ctx.http.safeFetch, so there is no pack-driven egress to observe'] };
+  if (!isFixtureAdvertised(FIXTURE)) return { skip: ['inapplicable', `fixture ${FIXTURE} is not advertised — safeFetch has no protocol path, and the host does not claim the fixture that observes it`] };
+  if (listener === null) return { skip: ['blocked', 'the suite could not open its loopback listener'] };
+  const out = await Promise.all(urls.map((u) => probe(u)));
+  const bad = out.find((o): o is { reason: string } => !('url' in o));
+  if (bad) return { skip: ['blocked', bad.reason] };
+  return out as Outcome[];
+}
+
+const describeOutcome = (o: Outcome): string => `${o.url} → ${o.status}${o.code ? ` ${o.code}` : ''}${o.detailReason !== undefined ? ` (reason ${JSON.stringify(o.detailReason)})` : ''}`;
+
+function assertRefused(id: string, cls: string, outcomes: readonly Outcome[]): void {
+  const notRefused = outcomes.filter((o) => o.status !== 'failed' || o.code !== 'egress_denied');
+  expect(notRefused.map(describeOutcome), req(id, DOC, `safeFetch MUST refuse a ${cls} target as egress_denied — these were not`)).toEqual([]);
+  const wrongReason = outcomes.filter((o) => o.detailReason !== 'ssrf-blocked');
+  expect(wrongReason.map(describeOutcome), req(id, DOC, `a refused ${cls} target carries details.reason: ssrf-blocked`)).toEqual([]);
+}
+
+describe('v2 safeFetch SSRF guard (host-services.md §httpClient)', () => {
+  it('a loopback target is refused egress_denied, ssrf-blocked, before any connection', async () => {
+    const r = await leg([`http://127.0.0.1:${port}${path('loopback')}/v4`, `http://[::1]:${port}${path('loopback')}/v6`]);
+    if ('skip' in r) return softSkip(...r.skip);
+    assertRefused(ID_LOOPBACK, 'loopback', r);
+    expect(reached('loopback'), req(ID_LOOPBACK, DOC, 'the guard MUST refuse BEFORE connecting — these probe requests reached the suite\'s loopback listener')).toEqual([]);
+  }, 120_000);
+
+  it('an RFC 1918 target is refused egress_denied, ssrf-blocked', async () => {
+    const r = await leg(['http://10.0.0.1/openwop-ssrf-probe', 'http://172.16.0.1/openwop-ssrf-probe', 'http://192.168.0.1/openwop-ssrf-probe']);
+    if ('skip' in r) return softSkip(...r.skip);
+    assertRefused(ID_PRIVATE, 'RFC 1918', r);
+  }, 120_000);
+
+  it('a link-local or cloud-metadata target is refused egress_denied, ssrf-blocked', async () => {
+    const r = await leg(['http://169.254.169.254/latest/meta-data/', 'http://169.254.0.1/openwop-ssrf-probe', 'http://[fe80::1]/openwop-ssrf-probe']);
+    if ('skip' in r) return softSkip(...r.skip);
+    assertRefused(ID_LINK_LOCAL, 'link-local / cloud-metadata', r);
+  }, 120_000);
+
+  it('the same addresses in decimal, octal, short and IPv4-mapped IPv6 spellings are refused', async () => {
+    const r = await leg([
+      `http://2130706433:${port}${path('spelling')}/decimal`,
+      `http://0177.0.0.1:${port}${path('spelling')}/octal`,
+      `http://127.1:${port}${path('spelling')}/short`,
+      `http://[::ffff:7f00:1]:${port}${path('spelling')}/mapped`,
+      'http://[::ffff:a9fe:a9fe]/latest/meta-data/',
+      'http://[::ffff:a00:1]/openwop-ssrf-probe',
+    ]);
+    if ('skip' in r) return softSkip(...r.skip);
+    assertRefused(ID_SPELLING, 'loopback / metadata / RFC 1918 (alternate spelling)', r);
+    expect(reached('spelling'), req(ID_SPELLING, DOC, 'the guard MUST refuse BEFORE connecting — these probe requests reached the suite\'s loopback listener')).toEqual([]);
+  }, 120_000);
+
+  it('a name that resolves to loopback is refused on its resolved address', async () => {
+    const r = await leg([`http://localhost:${port}${path('resolved')}/name`]);
+    if ('skip' in r) return softSkip(...r.skip);
+    assertRefused(ID_RESOLVED, 'name resolving to loopback', r);
+    expect(reached('resolved'), req(ID_RESOLVED, DOC, 'the host MUST resolve the target and reject a loopback address before connecting — the probe reached the suite\'s loopback listener')).toEqual([]);
+  }, 120_000);
+});

package/src/scenarios/v2-secret-canary-absent.test.ts

@@ -0,0 +1,211 @@
+/**
+ * `spec/v2/core/host-services.md` §`secrets` — a secret the host resolves from
+ * its OWN store never reaches a readable surface (target major 2; gated on the
+ * `secrets` family and the `openwop-smoke-byok-roundtrip` fixture).
+ *
+ *   "Raw key material MUST NOT appear in any event, log, trace, prompt, error,
+ *    export or screenshot" · "MUST keep the plaintext out of events, spans,
+ *    logs, snapshots and replay state. A replay re-resolves it"
+ *
+ * Before this file the rule was witnessed at major 1 only, and only on the
+ * envelope (`envelope-reasoning-secret-redaction`) and OTel
+ * (`secret-leakage-otel-attribute`) paths. `byok-roundtrip` runs the same
+ * fixture but searches for four key NAMES, never the value — any leak under
+ * another key passes it.
+ *
+ * What this adds, over the fixture the host already advertises (its node
+ * resolves the store canary `openwop-conformance-canary-secret` and outputs only
+ * `{secretSha256, secretLength}`):
+ *
+ *   1. `resolved-secret-absent` — after a completed run, the canary is on none
+ *      of: the createRun answer, the snapshot, the poll log (`streamMode=debug`),
+ *      the SSE stream (`streamMode=debug`), the run's `listRuns` page (when
+ *      `runList` is advertised), or the error envelope a cancel of the terminal
+ *      run answers.
+ *   2. `resolved-secret-absent-on-failure` — the same after a run that resolves
+ *      the canary and then FAILS (`conformance-secret-resolve-then-fail`), where
+ *      the snapshot `error`, `node.failed` and `run.failed` join the surfaces.
+ *      A host that folds the node's resolved context into an error is caught here.
+ *   3. `resolved-secret-absent-in-fork` — a replay fork taken before the resolve
+ *      node re-resolves the canary (§`secrets`: "A replay re-resolves it"); the
+ *      fork's answer, snapshot and log carry it nowhere either (gated on `replay`).
+ *
+ * How the suite recognises the canary without being told it: every window of
+ * `secretLength` bytes on every surface (and inside every base64 / hex /
+ * percent-decoded token) is hashed and compared with the surfaced
+ * `secretSha256` (`lib/secret-scan.ts`). When the operator also supplies the
+ * plaintext (`OPENWOP_CANARY_SECRET_VALUE`, as `secret-leakage-otel-attribute`
+ * already reads) it is searched for directly in every common encoding.
+ *
+ * Not duplicated: RFC 0229 (`runSecrets`, `core.secret.witness`,
+ * `secrets.run-witness-*`) witnesses a value the SUITE supplies with the run.
+ * This file witnesses a secret the host resolves from its own store — the BYOK
+ * path the §`secrets` rule exists for. Its digest is legitimately on the
+ * surfaces (the byok fixture's contract emits it), so it is not a finding here.
+ *
+ * Dispositions: `secrets` not advertised, or the leg's fixture not advertised
+ * ⇒ `inapplicable`, read with `familyAdvertised` rather than `gateFamily` so
+ * strict mode does not demand a `family.secrets` opt-out from a host that never
+ * claimed it (a production host is right to withhold the canary fixture —
+ * RFC 0229 §Motivation). No detector (the digest not surfaced — a MAY — and no
+ * operator value) ⇒ `inapplicable`: nothing on this host can be recognised as
+ * the canary. An advertised fixture that cannot be run ⇒ `blocked`.
+ *
+ * @see spec/v2/core/host-services.md §`secrets`
+ * @see conformance/fixtures.md §`openwop-smoke-byok-roundtrip`, §`conformance-secret-resolve-then-fail`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { createHash } from 'node:crypto';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { subscribe } from '../lib/sse.js';
+import { familyAdvertised, v2Discovery } from '../lib/v2.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { softSkip } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+import { digestDetector, findSecretDigest, leaks, valueDetector, type SecretDetector, type Surface } from '../lib/secret-scan.js';
+
+const DOC = 'spec/v2/core/host-services.md §secrets';
+const ID_ABSENT = 'openwop.requirement.secrets.resolved-secret-absent';
+const ID_FAILURE = 'openwop.requirement.secrets.resolved-secret-absent-on-failure';
+const ID_FORK = 'openwop.requirement.secrets.resolved-secret-absent-in-fork';
+const BYOK = 'openwop-smoke-byok-roundtrip';
+const THEN_FAIL = 'conformance-secret-resolve-then-fail';
+const RESOLVE_NODE = 'resolve-secret';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+const V2 = { 'OpenWOP-Version': '2.0' };
+
+const enc = (id: string): string => encodeURIComponent(id);
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+function parse(text: string): unknown { try { return JSON.parse(text); } catch { return text; } }
+
+async function gate(fixture: string): Promise<string | null> {
+  if (!(await v2Discovery())) return 'blocked:v2 discovery unreachable — /.well-known/openwop did not answer 200 under OpenWOP-Version: 2.0';
+  if (!(await familyAdvertised('secrets'))) return 'inapplicable:secrets family not advertised — no obligation';
+  if (!isFixtureAdvertised(fixture)) return `inapplicable:fixture ${fixture} is not advertised — the host does not claim the store-canary fixture (a production host may withhold it; RFC 0229's run witness is that host's path)`;
+  return null;
+}
+function skip(why: string): undefined {
+  const i = why.indexOf(':');
+  return softSkip(why.slice(0, i) as 'blocked' | 'inapplicable', why.slice(i + 1));
+}
+
+interface Settled { readonly runId: string; readonly status: string; readonly surfaces: Surface[]; readonly docs: unknown[]; readonly events: Array<{ sequence?: unknown; type?: unknown; nodeId?: unknown }> }
+
+/** Settle a run and read every readable surface of it. */
+async function readRun(runId: string, created: OpenWOPResponse, label: string): Promise<Settled | { reason: string }> {
+  const deadline = Date.now() + 20_000;
+  let snap: OpenWOPResponse | null = null;
+  let status = '';
+  while (Date.now() < deadline) {
+    snap = await http(() => driver.get(`/runs/${enc(runId)}`));
+    status = snap?.status === 200 ? String((snap.json as { status?: unknown } | undefined)?.status ?? '') : status;
+    if (TERMINAL.has(status)) break;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+  if (snap === null || snap.status !== 200 || !TERMINAL.has(status)) return { reason: `the ${label} run ${runId} did not settle within 20 s (last status: ${status || 'unreadable'})` };
+  const poll = await http(() => driver.get(`/runs/${enc(runId)}/events/poll?timeout=1&streamMode=debug`));
+  if (poll === null || poll.status !== 200) return { reason: `GET /runs/{runId}/events/poll answered ${poll?.status ?? 'no response'} for the ${label} run` };
+  const events = ((poll.json as { events?: unknown } | undefined)?.events ?? []) as Settled['events'];
+  const surfaces: Surface[] = [
+    { name: `${label}: createRun answer`, text: created.text },
+    { name: `${label}: GET /runs/{runId} snapshot`, text: snap.text },
+    { name: `${label}: GET /runs/{runId}/events/poll?streamMode=debug`, text: poll.text },
+  ];
+  const docs: unknown[] = [created.json, snap.json, poll.json];
+  const sse = await subscribe(`/runs/${enc(runId)}/events?streamMode=debug`, { timeoutMs: 8_000, extraHeaders: V2 }).catch(() => null);
+  if (sse !== null && sse.status === 200) {
+    const frames = sse.events.map((f) => parse(f.data));
+    surfaces.push({ name: `${label}: GET /runs/{runId}/events (SSE, streamMode=debug)`, text: JSON.stringify(frames) });
+    docs.push(frames);
+  }
+  // An error envelope the run can produce on demand: cancelling a terminal run.
+  const cancel = await http(() => driver.post(`/runs/${enc(runId)}/cancel`, {}));
+  if (cancel !== null) surfaces.push({ name: `${label}: POST /runs/{runId}/cancel on the terminal run (${cancel.status} ${readErrorCode(cancel.json) ?? ''})`.replace(' )', ')'), text: cancel.text });
+  if (await familyAdvertised('runList')) {
+    const list = await http(() => driver.get(`/runs?workflowId=${enc(String((snap!.json as { workflowId?: unknown }).workflowId ?? ''))}&limit=10`));
+    if (list !== null && list.status === 200) surfaces.push({ name: `${label}: GET /runs (listRuns page)`, text: list.text });
+  }
+  return { runId, status, surfaces, docs, events };
+}
+
+/** The detectors this host lets the suite build: the operator's value, the surfaced digest, or both. */
+function detectorsFor(docs: readonly unknown[]): SecretDetector[] {
+  const out: SecretDetector[] = [];
+  const operator = process.env['OPENWOP_CANARY_SECRET_VALUE'];
+  const digest = findSecretDigest(docs);
+  if (operator && operator.length > 0) {
+    // An operator value that is not the canary this host resolved would make the value search vacuous.
+    if (digest === null || createHash('sha256').update(operator, 'utf8').digest('hex') === digest.sha256.toLowerCase()) out.push(valueDetector(operator));
+  }
+  if (digest !== null) out.push(digestDetector(digest.sha256, digest.length));
+  return out;
+}
+
+async function create(workflowId: string): Promise<{ runId: string; res: OpenWOPResponse } | { reason: string }> {
+  const res = await http(() => driver.post('/runs', { workflowId }));
+  if (res === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (res.json as { runId?: unknown } | undefined)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs {workflowId: ${workflowId}} answered ${res.status} ${readErrorCode(res.json) ?? ''} — the fixture is advertised but did not start (canary not provisioned?)`.trim() };
+  return { runId, res };
+}
+
+const NO_DETECTOR = 'the run surfaced no {secretSha256, secretLength} (surfacing node outputs is a MAY) and OPENWOP_CANARY_SECRET_VALUE is unset — nothing on this host can be recognised as the canary';
+
+/** Shared by the three legs: the source run of the byok fixture, read once. */
+let source: Promise<Settled | { reason: string }> | null = null;
+function byokRun(): Promise<Settled | { reason: string }> {
+  source ??= (async () => {
+    const c = await create(BYOK);
+    if ('reason' in c) return c;
+    return readRun(c.runId, c.res, 'byok');
+  })();
+  return source;
+}
+
+describe('v2 secret-canary-absent (host-services.md §secrets)', () => {
+  it('a secret resolved from the host\'s store appears on no readable surface of the run', async () => {
+    const why = await gate(BYOK); if (why) return skip(why);
+    const run = await byokRun(); if ('reason' in run) return softSkip('blocked', run.reason);
+    const detectors = detectorsFor(run.docs);
+    if (detectors.length === 0) return softSkip('inapplicable', NO_DETECTOR);
+    expect(run.status, req(ID_ABSENT, 'conformance/fixtures.md §openwop-smoke-byok-roundtrip', `the byok fixture run MUST complete when the host advertises it (got ${run.status})`)).toBe('completed');
+    const found = leaks(run.surfaces, detectors);
+    expect(found, req(ID_ABSENT, DOC, `raw key material MUST NOT appear in any event, snapshot or error — the canary was found on ${found.length} of ${run.surfaces.length} surface(s): ${found.join(' | ')}`)).toEqual([]);
+  }, 60_000);
+
+  it('a secret resolved by a run that then fails appears on no readable surface, the error included', async () => {
+    const why = await gate(THEN_FAIL); if (why) return skip(why);
+    const c = await create(THEN_FAIL); if ('reason' in c) return softSkip('blocked', c.reason);
+    const run = await readRun(c.runId, c.res, 'resolve-then-fail'); if ('reason' in run) return softSkip('blocked', run.reason);
+    // The failing run's own digest, else the completed byok run's (the same canary) when that fixture is advertised too.
+    const extra = isFixtureAdvertised(BYOK) ? await byokRun() : null;
+    const detectors = detectorsFor([...run.docs, ...(extra !== null && !('reason' in extra) ? extra.docs : [])]);
+    if (detectors.length === 0) return softSkip('inapplicable', NO_DETECTOR);
+    expect(run.status, req(ID_FAILURE, `conformance/fixtures.md §${THEN_FAIL}`, `the resolve-then-fail run MUST end failed (got ${run.status})`)).toBe('failed');
+    const found = leaks(run.surfaces, detectors);
+    expect(found, req(ID_FAILURE, DOC, `raw key material MUST NOT appear in any error or event of a run that resolved it and failed — the canary was found on: ${found.join(' | ')}`)).toEqual([]);
+  }, 90_000);
+
+  it('a replay fork re-resolves the secret and still carries it on no readable surface', async () => {
+    const why = await gate(BYOK); if (why) return skip(why);
+    const replay = await familyAdvertised('replay');
+    if (!replay) return softSkip('inapplicable', 'replay family not advertised — no fork, no replay state');
+    const modes = Array.isArray(replay['modes']) ? (replay['modes'] as unknown[]).map(String) : [];
+    const mode = modes.includes('replay') ? 'replay' : modes.includes('branch') ? 'branch' : null;
+    if (mode === null) return softSkip('inapplicable', `replay.modes names neither replay nor branch (${JSON.stringify(modes)})`);
+    const run = await byokRun(); if ('reason' in run) return softSkip('blocked', run.reason);
+    const started = run.events.find((e) => e.type === 'node.started' && e.nodeId === RESOLVE_NODE && typeof e.sequence === 'number');
+    if (started === undefined) return softSkip('blocked', `the byok run's log has no node.started for ${RESOLVE_NODE} — no fork point before the resolve`);
+    const fork = await http(() => driver.post(`/runs/${enc(run.runId)}:fork`, { mode, fromSeq: started.sequence }));
+    if (fork === null) return softSkip('blocked', 'POST /runs/{runId}:fork unreachable (fetch failed)');
+    const forkId = (fork.json as { runId?: unknown } | undefined)?.runId;
+    if (fork.status !== 201 || typeof forkId !== 'string') return softSkip('blocked', `POST /runs/{runId}:fork {mode: ${mode}, fromSeq: ${String(started.sequence)}} answered ${fork.status} ${readErrorCode(fork.json) ?? ''} — v2-run-fork-refusals / v2-run-fork-prefix own the fork contract`.trim());
+    const forked = await readRun(forkId, fork, `fork (${mode})`); if ('reason' in forked) return softSkip('blocked', forked.reason);
+    const detectors = detectorsFor([...forked.docs, ...run.docs]);
+    if (detectors.length === 0) return softSkip('inapplicable', NO_DETECTOR);
+    const found = leaks(forked.surfaces, detectors);
+    expect(found, req(ID_FORK, DOC, `the plaintext MUST stay out of replay state — a ${mode} fork that re-resolved the canary carried it on: ${found.join(' | ')}`)).toEqual([]);
+  }, 90_000);
+});

package/src/scenarios/v2-secrets-run-witness.test.ts

@@ -0,0 +1,167 @@
+/**
+ * RFC 0229 — a production host can witness secret resolution without an oracle
+ * (`spec/v2/core/host-services.md` §Run-supplied secrets; suite 2.45.3, target
+ * major 2; gated on the `secrets.runSecrets` facet and the
+ * `openwop-secrets-run-witness` fixture). The v1 twin is `secrets-run-witness`.
+ *
+ * The client supplies a fresh value `C` with the run (`runSecrets`, under the
+ * reserved `run:openwop-witness` ref) and `sha256(C)` as an input. The
+ * `core.secret.witness` node outputs only `{ matched }`. Four rows:
+ *
+ *   1. `run-witness-resolves` — `matched: true` for `C`, and `matched: false`
+ *      for a run whose `expectedSha256` names a different value (the second run
+ *      binds the witness to the exact bytes; the canary fixture never could);
+ *   2. `run-witness-redacted` — `C` is absent, in every encoding and as
+ *      `sha256(C)`, from the create answer, snapshot, polled and `debug`-mode
+ *      events, the run list and the debug bundle where served;
+ *   3. `run-witness-scope-bound` — a non-`run:` ref fails `credential_forbidden`;
+ *      an unsupplied `run:` ref and an earlier run's ref fail
+ *      `credential_not_found`; where `replay` advertises `branch`, a fork of the
+ *      first run fails `credential_not_found` (a fork does not inherit);
+ *   4. `run-secrets-outside-request-digest` — a same-key retry differing only in
+ *      `runSecrets` replays (same `runId`, `OpenWOP-Idempotent-Replay: true`),
+ *      never `409 idempotency_key_mismatch`, and the retried value `C′` appears
+ *      on no surface of the run.
+ *
+ * Dispositions (RFC 0229 §F): facet absent ⇒ `inapplicable`; facet without the
+ * fixture ⇒ `blocked`; a `createRun` that refuses a well-formed `runSecrets` ⇒
+ * `executed-fail`.
+ *
+ * How it FAILS (negative controls): a witness that resolves a non-`run:` ref
+ * (the oracle) fails row 3; a host that echoes `C` or its digest anywhere fails
+ * row 2; a host that folds `runSecrets` into the idempotency digest fails row 4.
+ *
+ * @see spec/v2/core/host-services.md §Run-supplied secrets
+ * @see conformance/fixtures.md §openwop-secrets-run-witness
+ * @see RFCS/0229-production-safe-secrets-witness.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { randomUUID } from 'node:crypto';
+import { req } from '../lib/requirement-ids.js';
+import { readErrorCode } from '../lib/error-envelope.js';
+import { blockedDespiteAssertions, softSkip } from '../lib/soft-skip.js';
+import { CANARY_NAME, WITNESS_REF, WitnessHost, freshName, freshValue, hits, sha256Hex } from '../lib/run-secrets-witness.js';
+
+const DOC = 'host-services.md §Run-supplied secrets (RFC 0229)';
+const host = new WitnessHost(2);
+
+interface Witnessed { runId: string; createText: string; status: string; matched: boolean | undefined; value: string; digestSupplied: boolean }
+type Outcome = { runs: [Witnessed, Witnessed] } | { skip: 'inapplicable' | 'blocked'; reason: string } | { refused: { status: number; detail: string } };
+
+/** Run A (`C`, `sha256(C)`) and run B (`D`, the digest of a different value), once per file. */
+let pair: Promise<Outcome> | undefined;
+function witnessedPair(): Promise<Outcome> {
+  pair ??= (async (): Promise<Outcome> => {
+    const g = await host.gate();
+    if (!g.ok) return { skip: g.kind, reason: g.reason };
+    const out: Witnessed[] = [];
+    for (const same of [true, false]) {
+      const value = freshValue();
+      const expected = same ? sha256Hex(value) : sha256Hex(freshValue());
+      const res = await host.create({ ref: WITNESS_REF, expectedSha256: expected }, [{ ref: WITNESS_REF, value }]);
+      if (res === null) return { skip: 'blocked', reason: 'POST /runs unreachable (fetch failed)' };
+      const runId = (res.json as { runId?: unknown } | null)?.runId;
+      if (res.status !== 201 || typeof runId !== 'string') return { refused: { status: res.status, detail: `POST /runs with a well-formed runSecrets answered ${res.status} ${readErrorCode(res.json) ?? ''}`.trim() } };
+      const snap = await host.waitTerminal(runId);
+      out.push({ runId, createText: res.text, status: String(snap?.['status']), matched: await host.matched(runId, snap), value, digestSupplied: same });
+    }
+    return { runs: [out[0]!, out[1]!] };
+  })();
+  return pair;
+}
+
+/** A run that must end in `witness`'s `node.failed`; returns the code, or a blocked reason. */
+async function failedCode(inputs: { ref: string; expectedSha256: string }, runSecrets?: ReadonlyArray<{ ref: string; value: string }>): Promise<{ code: string | null; status: string } | { reason: string }> {
+  const res = await host.create(inputs, runSecrets);
+  if (res === null) return { reason: 'POST /runs unreachable (fetch failed)' };
+  const runId = (res.json as { runId?: unknown } | null)?.runId;
+  if (res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs answered ${res.status} ${readErrorCode(res.json) ?? ''}`.trim() };
+  const snap = await host.waitTerminal(runId);
+  return { code: await host.nodeFailedCode(runId), status: String(snap?.['status']) };
+}
+
+describe('RFC 0229 — v2-secrets-run-witness (gated on secrets.runSecrets + openwop-secrets-run-witness)', () => {
+  it('a run-supplied secret resolves intact: matched true for its digest, false for another', async () => {
+    const o = await witnessedPair();
+    if ('skip' in o) return softSkip(o.skip, o.reason);
+    const id = 'openwop.requirement.secrets.run-witness-resolves';
+    if ('refused' in o) {
+      expect(o.refused.status, req(id, DOC, `a host advertising runSecrets MUST accept a well-formed runSecrets on createRun (${o.refused.detail})`)).toBe(201);
+      return blockedDespiteAssertions(`${o.refused.detail} with no runId — no run to witness`);
+    }
+    const [a, b] = o.runs;
+    expect(a.status, req(id, DOC, 'the witness run with a matching digest MUST complete')).toBe('completed');
+    expect(b.status, req(id, DOC, 'the witness run with a different digest MUST complete (a mismatch is an output, not a failure)')).toBe('completed');
+    if (a.matched === undefined || b.matched === undefined) return blockedDespiteAssertions('the runs completed but witness\'s `matched` output was on no readable surface (node.completed outputs or the snapshot)');
+    expect(a.matched, req(id, DOC, 'witness MUST output matched: true when expectedSha256 is the digest of the supplied value')).toBe(true);
+    expect(b.matched, req(id, DOC, 'witness MUST output matched: false when expectedSha256 is the digest of a different value')).toBe(false);
+  }, 90_000);
+
+  it('a run-supplied secret appears on no readable surface, in any encoding or as its digest', async () => {
+    const o = await witnessedPair();
+    if ('skip' in o) return softSkip(o.skip, o.reason);
+    if ('refused' in o) return softSkip('blocked', `${o.refused.detail} — no run to scan (row run-witness-resolves convicts the refusal)`);
+    const id = 'openwop.requirement.secrets.run-witness-redacted';
+    for (const r of o.runs) {
+      const s = await host.surfaces(r.runId, [r.createText]);
+      expect(hits(s.text, r.value, r.digestSupplied), req(id, DOC, `the supplied value MUST NOT appear on any surface (read: ${s.read.join(', ')}), raw, base64, hex, percent- or JSON-encoded, or as its SHA-256 where the suite did not send that digest itself`)).toEqual([]);
+    }
+  }, 90_000);
+
+  it('a run: ref resolves only within the run that supplied it, and the witness refuses any other ref', async () => {
+    const g = await host.gate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const id = 'openwop.requirement.secrets.run-witness-scope-bound';
+    const v = freshValue();
+    const cases: Array<{ what: string; inputs: { ref: string; expectedSha256: string }; runSecrets?: Array<{ ref: string; value: string }>; code: string }> = [
+      { what: `the canary name ${CANARY_NAME}`, inputs: { ref: CANARY_NAME, expectedSha256: sha256Hex(v) }, runSecrets: [{ ref: WITNESS_REF, value: v }], code: 'credential_forbidden' },
+      { what: 'a fresh name without run:', inputs: { ref: freshName(), expectedSha256: sha256Hex(v) }, runSecrets: [{ ref: WITNESS_REF, value: v }], code: 'credential_forbidden' },
+      { what: `${WITNESS_REF} with no runSecrets`, inputs: { ref: WITNESS_REF, expectedSha256: sha256Hex(v) }, code: 'credential_not_found' },
+    ];
+    const earlier = freshValue();
+    const first = await host.create({ ref: WITNESS_REF, expectedSha256: sha256Hex(earlier) }, [{ ref: WITNESS_REF, value: earlier }]);
+    const firstId = (first?.json as { runId?: unknown } | null)?.runId;
+    if (first === null || first.status !== 201 || typeof firstId !== 'string') return softSkip('blocked', `the earlier run's POST /runs answered ${first?.status ?? 'nothing'} ${readErrorCode(first?.json) ?? ''}`.trim());
+    await host.waitTerminal(firstId);
+    cases.push({ what: `an earlier run's ref (${WITNESS_REF}) while this run supplies only run:openwop-other`, inputs: { ref: WITNESS_REF, expectedSha256: sha256Hex(earlier) }, runSecrets: [{ ref: 'run:openwop-other', value: freshValue() }], code: 'credential_not_found' });
+    for (const c of cases) {
+      const r = await failedCode(c.inputs, c.runSecrets);
+      if ('reason' in r) return blockedDespiteAssertions(`${c.what}: ${r.reason}`);
+      expect(r.code, req(id, DOC, `${c.what}: witness MUST end in node.failed with ${c.code} (run status ${r.status})`)).toBe(c.code);
+    }
+    // §A.4: gated on replay advertising `branch` (RFC 0229 §F row 3).
+    if (g.branchFork) {
+      const fork = await host.fork(firstId);
+      const forkId = (fork?.json as { runId?: unknown } | null)?.runId;
+      // partial-witness-ok: the four scope legs above observed the requirement; this fork leg is conditional on a fork the host serves (the fork contract is not this row's)
+      if (fork === null || fork.status !== 201 || typeof forkId !== 'string') return softSkip('inapplicable', `replay advertises branch, but POST /runs/{runId}:fork answered ${fork?.status ?? 'nothing'} ${readErrorCode(fork?.json) ?? ''} — the fork leg did not run (runs.md §Fork owns that contract)`.trim());
+      await host.waitTerminal(forkId);
+      expect(await host.nodeFailedCode(forkId), req(id, DOC, 'a branch fork taken before witness MUST NOT inherit runSecrets: witness fails credential_not_found')).toBe('credential_not_found');
+    }
+  }, 180_000);
+
+  it('the idempotency request digest excludes runSecrets: a retry differing only there replays, and its value is discarded', async () => {
+    const g = await host.gate();
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const id = 'openwop.requirement.secrets.run-secrets-outside-request-digest';
+    const key = `openwop-witness-${randomUUID()}`;
+    const c = freshValue();
+    const c2 = freshValue();
+    const inputs = { ref: WITNESS_REF, expectedSha256: sha256Hex(c) };
+    const first = await host.create(inputs, [{ ref: WITNESS_REF, value: c }], key);
+    const runId = (first?.json as { runId?: unknown } | null)?.runId;
+    if (first === null) return softSkip('blocked', 'POST /runs unreachable (fetch failed)');
+    expect(first.status, req(id, DOC, 'a host advertising runSecrets MUST accept a well-formed runSecrets on createRun')).toBe(201);
+    if (typeof runId !== 'string') return blockedDespiteAssertions('the 201 carried no runId');
+    const retry = await host.create(inputs, [{ ref: WITNESS_REF, value: c2 }], key);
+    if (retry === null) return blockedDespiteAssertions('the same-key retry was unreachable (fetch failed)');
+    expect(readErrorCode(retry.json), req(id, `${DOC}; idempotency.md §Outcomes`, 'a same-key retry differing only in runSecrets MUST NOT be 409 idempotency_key_mismatch — the request digest MUST NOT cover runSecrets')).not.toBe('idempotency_key_mismatch');
+    expect(retry.status, req(id, DOC, 'the retry MUST be answered from cache with the original 201')).toBe(201);
+    expect((retry.json as { runId?: unknown } | null)?.runId, req(id, DOC, 'the retry MUST name the original runId')).toBe(runId);
+    expect(retry.headers.get('openwop-idempotent-replay'), req(id, 'idempotency.md §Outcomes', 'a response served from cache MUST carry OpenWOP-Idempotent-Replay: true')).toBe('true');
+    await host.waitTerminal(runId);
+    const s = await host.surfaces(runId, [first.text, retry.text]);
+    expect(hits(s.text, c2), req(id, DOC, `the retried value MUST be discarded unused: it appears on no surface of the run (read: ${s.read.join(', ')})`)).toEqual([]);
+  }, 90_000);
+});