@openwop/openwop-conformance 2.45.2 → 2.45.4

package/src/scenarios/v2-queue-cross-tenant-isolation.test.ts

@@ -0,0 +1,118 @@
+/**
+ * `spec/v2/core/host-services.md` §`queueBus` — "A tenant's consumer MUST NOT
+ * receive another tenant's messages, even on the same topic." (target major 2;
+ * gated on the `queueBus` family, the queue-probe fixture pair and a second
+ * tenant's credential).
+ *
+ * Before this file the rule was witnessed at major 1 only
+ * (`queue-cross-tenant-isolation`), through the v1 seam
+ * `POST /v1/host/sample/test/surface`, which names the tenant in the REQUEST
+ * BODY — so it never tested the thing that matters, that the tenant comes from
+ * the credential. Topics are named by pack authors, so two tenants running the
+ * same pack share topic names by default; a host that keys the physical queue
+ * by topic alone hands one tenant's messages to the other.
+ *
+ * No seam (`conformance.md` forbids growing the seam count). The leg drives
+ * `ctx.queueBus` through the normal run surface with two fixtures
+ * (`conformance/fixtures.md` §`conformance-queue-publish` /
+ * §`conformance-queue-consume`): tenant A (`OPENWOP_API_KEY`) publishes a fresh
+ * nonce on a fresh topic T; tenant B (`OPENWOP_TEST_TENANT_B_API_KEY`) consumes
+ * T and MUST NOT receive it; then A consumes T and MUST receive it — the
+ * positive control, without which "B got nothing" would also be what a host
+ * whose queue does nothing at all shows.
+ *
+ * Dispositions: `queueBus` not advertised, or either probe fixture not
+ * advertised ⇒ `inapplicable` (read with `familyAdvertised`, not `gateFamily`:
+ * no host advertises `queueBus` at v2 today, and a strict-mode family gate would
+ * demand a `family.queueBus` opt-out from every one of them). The family and fixtures advertised but no second
+ * tenant key, or the key binds the primary tenant ⇒ `blocked` (the only
+ * observation that convicts a leaking host did not run). A probe run that does
+ * not complete, or a consume that leaves `consumed` unset, fails: the fixture
+ * contract is the host's claim once it advertises the fixture.
+ *
+ * @see spec/v2/core/host-services.md §`queueBus`
+ * @see SECURITY/invariants.yaml `queue-cross-tenant-isolation`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import { driver, type OpenWOPResponse, type OpenWOPRequestInit } from '../lib/driver.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';
+
+const DOC = 'spec/v2/core/host-services.md §queueBus';
+const ID = 'openwop.requirement.queueBus.cross-tenant-isolation';
+const PUBLISH = 'conformance-queue-publish';
+const CONSUME = 'conformance-queue-consume';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+
+const enc = (id: string): string => encodeURIComponent(id);
+const tenantOf = (runId: string): string => runId.slice(0, Math.max(0, runId.indexOf('/')));
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+
+/** The `consumed` array the consume node output, wherever the host surfaces it (node.completed, run.completed, the snapshot). */
+function consumedOf(docs: readonly unknown[]): string[] | null {
+  let hit: string[] | null = null;
+  const walk = (v: unknown): void => {
+    if (hit !== null || v === null || typeof v !== 'object') return;
+    if (Array.isArray(v)) { v.forEach(walk); return; }
+    const c = (v as Record<string, unknown>)['consumed'];
+    if (Array.isArray(c)) { hit = c.map((x) => (typeof x === 'string' ? x : JSON.stringify(x))); return; }
+    Object.values(v as Record<string, unknown>).forEach(walk);
+  };
+  docs.forEach(walk);
+  return hit;
+}
+
+interface Ran { readonly runId: string; readonly status: string; readonly docs: unknown[] }
+
+async function run(workflowId: string, inputs: Record<string, unknown>, as: OpenWOPRequestInit, who: string): Promise<Ran | { reason: string }> {
+  const created = await http(() => driver.post('/runs', { workflowId, inputs }, as));
+  if (created === null) return { reason: `${who}: POST /runs unreachable (fetch failed)` };
+  const runId = (created.json as { runId?: unknown } | undefined)?.runId;
+  if (created.status !== 201 || typeof runId !== 'string') return { reason: `${who}: POST /runs {workflowId: ${workflowId}} answered ${created.status} ${readErrorCode(created.json) ?? ''} — the fixture is advertised but did not start`.trim() };
+  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)}`, as));
+    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 (!TERMINAL.has(status)) return { reason: `${who}: the ${workflowId} 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`, as));
+  return { runId, status, docs: [snap?.json, poll?.status === 200 ? poll.json : null] };
+}
+
+describe('v2 queue-cross-tenant-isolation (host-services.md §queueBus)', () => {
+  it('a message tenant A publishes on topic T is never consumed by tenant B on T, and A\'s own consumer receives it', async () => {
+    if (!(await v2Discovery())) return softSkip('blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 under OpenWOP-Version: 2.0');
+    if (!(await familyAdvertised('queueBus'))) return softSkip('inapplicable', 'queueBus family not advertised — no obligation');
+    for (const f of [PUBLISH, CONSUME]) if (!isFixtureAdvertised(f)) return softSkip('inapplicable', `fixture ${f} is not advertised — the host does not claim the queue-probe fixture pair`);
+    const keyB = process.env['OPENWOP_TEST_TENANT_B_API_KEY'];
+    if (!keyB) return softSkip('blocked', 'OPENWOP_TEST_TENANT_B_API_KEY is not set — the second-tenant consume, the only observation a leaking host fails, cannot run');
+    const asA: OpenWOPRequestInit = {};
+    const asB: OpenWOPRequestInit = { authenticated: false, headers: { Authorization: `Bearer ${keyB}` } };
+
+    const topic = `openwop.conformance.xtenant.${randomBytes(6).toString('hex')}`;
+    const nonce = `openwop-conformance-queue-${randomBytes(12).toString('hex')}`;
+
+    const pub = await run(PUBLISH, { topic, message: nonce }, asA, 'tenant A publish'); if ('reason' in pub) return softSkip('blocked', pub.reason);
+    expect(pub.status, req(ID, `conformance/fixtures.md §${PUBLISH}`, `tenant A's publish run MUST complete (got ${pub.status})`)).toBe('completed');
+
+    const b = await run(CONSUME, { topic }, asB, 'tenant B consume'); if ('reason' in b) return softSkip('blocked', b.reason);
+    if (tenantOf(b.runId) === tenantOf(pub.runId)) return softSkip('blocked', `OPENWOP_TEST_TENANT_B_API_KEY binds the same tenant as OPENWOP_API_KEY (${tenantOf(pub.runId)}) — the leg needs a second tenant`);
+    expect(b.status, req(ID, `conformance/fixtures.md §${CONSUME}`, `tenant B's consume run MUST complete (got ${b.status})`)).toBe('completed');
+    const gotB = consumedOf(b.docs);
+    expect(Array.isArray(gotB), req(ID, `conformance/fixtures.md §${CONSUME}`, 'the consume node MUST output `consumed` as an array ([] when nothing arrived), never leave it unset — an unset output would pass the isolation check vacuously')).toBe(true);
+    expect(gotB ?? [], req(ID, DOC, `a tenant's consumer MUST NOT receive another tenant's messages, even on the same topic — tenant B (${tenantOf(b.runId)}) consumed tenant A's (${tenantOf(pub.runId)}) message on ${topic}`)).not.toContain(nonce);
+
+    const a = await run(CONSUME, { topic }, asA, 'tenant A consume'); if ('reason' in a) return softSkip('blocked', a.reason);
+    expect(a.status, req(ID, `conformance/fixtures.md §${CONSUME}`, `tenant A's consume run MUST complete (got ${a.status})`)).toBe('completed');
+    expect(consumedOf(a.docs) ?? [], req(ID, `conformance/fixtures.md §${CONSUME}`, `positive control: tenant A's own consumer on ${topic} MUST receive the message A published — without it "tenant B received nothing" is also what a queue that delivers nothing shows`)).toContain(nonce);
+  }, 90_000);
+});

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);
+});