@openwop/openwop-conformance 2.45.2 → 2.45.4

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

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

@@ -0,0 +1,213 @@
+/**
+ * `spec/v2/core/storage.md` §Shared rules — host storage never reads across
+ * tenants (target major 2; gated per storage family + the
+ * `conformance-storage-probe` fixture + a second-tenant credential).
+ *
+ * The rule: "A read for one tenant MUST NOT return data another tenant wrote,
+ * even under an identical key or name: `kvStorage` `get` and `list`,
+ * `tableStorage` `get` and `query`, `vectorStore` and `searchIndex` `query`,
+ * `blobStorage` and `cache` `get`" — and `sql` / `nosql` datasources are
+ * scoped per tenant. Until this file it had a witness only at major 1 (the v1
+ * `test/surface` seam, four families); `vectorStore`, `searchIndex`, `sql` and
+ * `nosql` had none at any major.
+ *
+ * No seam. Each leg drives the ordinary run surface with the
+ * `conformance-storage-probe` fixture (conformance/fixtures.md §"The storage
+ * probe fixtures"), whose node calls the host's own storage service for the
+ * run's tenant, under two credentials that bind two different tenants:
+ *
+ *   1. tenant A (`OPENWOP_API_KEY`) writes a fresh value V at a fresh key K;
+ *   2. tenant A reads K — V MUST come back (the positive control: without it a
+ *      host that ignores the probe passes every leg vacuously);
+ *   3. tenant B (`OPENWOP_TEST_TENANT_B_API_KEY`) reads K, handing it A's
+ *      `ref` (row / document id) too — B's run MUST NOT return V or K. A refusal
+ *      (`forbidden` / `not_found`, storage.md's refusal codes) is also correct;
+ *   4. tenant A deletes K (best-effort cleanup, asserted nothing).
+ *
+ * One `it` and one requirement id per family, so a failure names its family.
+ *
+ * Dispositions: family not in the v2 root ⇒ `inapplicable` before anything
+ * runs. Family advertised but the probe fixture not advertised, no second
+ * credential, a second credential that binds the SAME tenant, or a fixture run
+ * that cannot be created ⇒ `blocked` (an advertised isolation claim this run
+ * could not observe; RFC 0148 §A, the 2.45.1 rule for a withheld fixture).
+ *
+ * Sabotage (run against a patched local copy of the v2 reference host that
+ * serves these families in memory): key each store by name only — dropping the
+ * tenant — and every family's leg fails on step 3; a probe that ignores
+ * `write` fails step 2.
+ *
+ * @see spec/v2/core/storage.md §Shared rules
+ * @see conformance/fixtures.md §"The storage probe fixtures (storage.md)"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { randomUUID } from 'node:crypto';
+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-storage-probe';
+const NODE_ID = 'storage-probe';
+const DOC = 'spec/v2/core/storage.md §Shared rules';
+const ID_KV = 'openwop.requirement.storage.cross-tenant-kv-storage';
+const ID_TABLE = 'openwop.requirement.storage.cross-tenant-table-storage';
+const ID_BLOB = 'openwop.requirement.storage.cross-tenant-blob-storage';
+const ID_CACHE = 'openwop.requirement.storage.cross-tenant-cache';
+const ID_VECTOR = 'openwop.requirement.storage.cross-tenant-vector-store';
+const ID_SEARCH = 'openwop.requirement.storage.cross-tenant-search-index';
+const ID_SQL = 'openwop.requirement.storage.cross-tenant-sql';
+const ID_NOSQL = 'openwop.requirement.storage.cross-tenant-nosql';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+/** storage.md: "A refused call carries `not_found`, `forbidden`, `validation_error`, or `storage_limit_exceeded`". */
+const REFUSALS = new Set(['not_found', 'forbidden', 'validation_error', 'storage_limit_exceeded']);
+
+type Family = 'kvStorage' | 'tableStorage' | 'blobStorage' | 'cache' | 'vectorStore' | 'searchIndex' | 'sql' | 'nosql';
+type As = { authenticated?: boolean; headers?: Record<string, string> };
+
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const enc = (id: string): string => encodeURIComponent(id);
+const tenantOf = (runId: string): string => runId.slice(0, Math.max(0, runId.indexOf('/')));
+const strings = (v: unknown): string[] => (Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []);
+
+interface Probe {
+  readonly runId: string;
+  readonly status: string;
+  readonly result: Record<string, unknown> | null;
+  readonly errorCode: string | null;
+}
+
+/** Run the probe fixture with `inputs` as the caller `as` names, and read the node's terminal event. */
+async function probe(inputs: Record<string, unknown>, as: As = {}): Promise<Probe | { reason: string }> {
+  const created = await http(() => driver.post('/runs', { workflowId: FIXTURE, inputs }, as));
+  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 < 30_000) {
+    const snap = await http(() => driver.get(`/runs/${enc(runId)}`, as));
+    status = String((snap?.json as { status?: unknown } | null)?.status ?? '');
+    if (TERMINAL.has(status)) break;
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  if (!TERMINAL.has(status)) return { reason: `the ${FIXTURE} run did not reach a terminal status within 30 s (last: ${status || 'unreadable'})` };
+  const ev = await http(() => driver.get(`/runs/${enc(runId)}/events/poll?timeout=1`, as));
+  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 node = (type: string): Record<string, unknown> | undefined => (events as Array<{ type?: unknown; payload?: Record<string, unknown> }>).find((e) => e.type === type && e.payload?.['nodeId'] === NODE_ID)?.payload;
+  const outputs = (node('node.completed')?.['outputs'] ?? {}) as Record<string, unknown>;
+  const result = outputs['result'];
+  const error = (node('node.failed')?.['error'] ?? null) as { code?: unknown } | null;
+  return { runId, status, result: result && typeof result === 'object' && !Array.isArray(result) ? (result as Record<string, unknown>) : null, errorCode: typeof error?.code === 'string' ? error.code : null };
+}
+
+interface Observed {
+  readonly value: string;
+  readonly key: string;
+  /** Tenant A's own read of K: the values it returned. */
+  readonly control: Probe;
+  /** Tenant B's read of the same K (and A's ref). */
+  readonly other: Probe;
+}
+
+/**
+ * Steps 1–4 for one family, or the recorded reason the leg cannot run. Every
+ * soft-skip decision is made here, before the calling `it` asserts anything.
+ */
+async function isolationLeg(family: Family): Promise<Observed | { skip: ['inapplicable' | 'blocked', string] }> {
+  if (!(await v2Discovery().catch(() => null))) return { skip: ['blocked', 'v2 discovery unreachable'] };
+  if (!(await familyAdvertised(family))) return { skip: ['inapplicable', `${family} is not advertised in the v2 discovery root — the host exposes no ${family} to pack code`] };
+  if (!isFixtureAdvertised(FIXTURE)) return { skip: ['blocked', `the host advertises ${family} but not the ${FIXTURE} fixture — the tenant-isolation claim is made and cannot be observed without it`] };
+  const otherKey = process.env.OPENWOP_TEST_TENANT_B_API_KEY;
+  if (!otherKey) return { skip: ['blocked', `OPENWOP_TEST_TENANT_B_API_KEY is not set — ${family} tenant isolation needs a caller bound to a second tenant`] };
+  const asB: As = { authenticated: false, headers: { Authorization: `Bearer ${otherKey}` } };
+
+  const nonce = randomUUID().replace(/-/g, '');
+  const key = `openwop-conformance-xtenant-${nonce.slice(0, 16)}`;
+  const value = `openwop-conformance-secret-${nonce}`;
+  const wrote = await probe({ family, action: 'write', key, value });
+  if ('reason' in wrote) return { skip: ['blocked', `tenant A's ${family} write: ${wrote.reason}`] };
+  const ref = typeof wrote.result?.['ref'] === 'string' ? wrote.result['ref'] : undefined;
+  const readInputs = { family, action: 'read', key, ...(family === 'searchIndex' ? { value } : {}), ...(ref === undefined ? {} : { ref }) };
+  const control = await probe(readInputs);
+  if ('reason' in control) return { skip: ['blocked', `tenant A's ${family} read: ${control.reason}`] };
+  const other = await probe(readInputs, asB);
+  if ('reason' in other) return { skip: ['blocked', `tenant B could not run the ${FIXTURE} fixture: ${other.reason}`] };
+  if (tenantOf(other.runId) === tenantOf(control.runId)) return { skip: ['blocked', 'OPENWOP_TEST_TENANT_B_API_KEY binds the same tenant as OPENWOP_API_KEY — the leg needs a second tenant'] };
+  await probe({ family, action: 'delete', key, ...(ref === undefined ? {} : { ref }) });
+  return { value, key, control, other };
+}
+
+const leakedValues = (o: Observed): string[] => strings(o.other.result?.['values']).filter((v) => v.includes(o.value));
+const leakedKeys = (o: Observed): string[] => strings(o.other.result?.['keys']).filter((k) => k === o.key);
+/** A refused read is a correct answer too; anything else must have completed. */
+const otherOutcome = (o: Observed): string => (o.other.status === 'completed' ? 'completed' : REFUSALS.has(o.other.errorCode ?? '') ? 'refused' : `${o.other.status} ${o.other.errorCode ?? '(no node.failed code)'}`);
+
+describe('v2 storage cross-tenant isolation (storage.md §Shared rules)', () => {
+  it('kvStorage: a read for tenant B never returns what tenant A wrote under the same key (get and list)', async () => {
+    const o = await isolationLeg('kvStorage'); if ('skip' in o) return softSkip(...o.skip);
+    expect(strings(o.control.result?.['values']), req(ID_KV, 'conformance/fixtures.md §The storage probe fixtures', "tenant A's own read MUST return the value it wrote (positive control)")).toContain(o.value);
+    expect(otherOutcome(o), req(ID_KV, DOC, "tenant B's read MUST complete or be refused with a storage refusal code")).toMatch(/^(completed|refused)$/);
+    expect(leakedValues(o), req(ID_KV, DOC, "a kvStorage get for tenant B MUST NOT return data tenant A wrote under an identical key")).toEqual([]);
+    expect(leakedKeys(o), req(ID_KV, DOC, "a kvStorage list for tenant B MUST NOT return a key tenant A wrote")).toEqual([]);
+  }, 150_000);
+
+  it('tableStorage: a read for tenant B never returns what tenant A wrote in the same table (get and query)', async () => {
+    const o = await isolationLeg('tableStorage'); if ('skip' in o) return softSkip(...o.skip);
+    expect(strings(o.control.result?.['values']), req(ID_TABLE, 'conformance/fixtures.md §The storage probe fixtures', "tenant A's own read MUST return the value it wrote (positive control)")).toContain(o.value);
+    expect(otherOutcome(o), req(ID_TABLE, DOC, "tenant B's read MUST complete or be refused with a storage refusal code")).toMatch(/^(completed|refused)$/);
+    expect(leakedValues(o), req(ID_TABLE, DOC, "a tableStorage get or query for tenant B MUST NOT return a row tenant A wrote in the identically named table")).toEqual([]);
+    expect(leakedKeys(o), req(ID_TABLE, DOC, "a tableStorage query for tenant B MUST NOT return a row tenant A wrote")).toEqual([]);
+  }, 150_000);
+
+  it('blobStorage: a read for tenant B never returns what tenant A wrote under the same bucket and key', async () => {
+    const o = await isolationLeg('blobStorage'); if ('skip' in o) return softSkip(...o.skip);
+    expect(strings(o.control.result?.['values']), req(ID_BLOB, 'conformance/fixtures.md §The storage probe fixtures', "tenant A's own read MUST return the object it wrote (positive control)")).toContain(o.value);
+    expect(otherOutcome(o), req(ID_BLOB, DOC, "tenant B's read MUST complete or be refused with a storage refusal code")).toMatch(/^(completed|refused)$/);
+    expect(leakedValues(o), req(ID_BLOB, DOC, "a blobStorage get for tenant B MUST NOT return an object tenant A wrote under an identical bucket and key")).toEqual([]);
+    expect(leakedKeys(o), req(ID_BLOB, DOC, "a blobStorage list for tenant B MUST NOT return a key tenant A wrote")).toEqual([]);
+  }, 150_000);
+
+  it('cache: a get for tenant B never returns what tenant A put under the same key', async () => {
+    const o = await isolationLeg('cache'); if ('skip' in o) return softSkip(...o.skip);
+    expect(strings(o.control.result?.['values']), req(ID_CACHE, 'conformance/fixtures.md §The storage probe fixtures', "tenant A's own read MUST return the value it put (positive control)")).toContain(o.value);
+    expect(otherOutcome(o), req(ID_CACHE, DOC, "tenant B's read MUST complete or be refused with a storage refusal code")).toMatch(/^(completed|refused)$/);
+    expect(leakedValues(o), req(ID_CACHE, DOC, "a cache get for tenant B MUST NOT return data tenant A wrote under an identical key")).toEqual([]);
+    expect(leakedKeys(o), req(ID_CACHE, DOC, "a cache read for tenant B MUST NOT return a key tenant A wrote")).toEqual([]);
+  }, 150_000);
+
+  it('vectorStore: a query for tenant B never matches a vector tenant A upserted in the same collection', async () => {
+    const o = await isolationLeg('vectorStore'); if ('skip' in o) return softSkip(...o.skip);
+    expect(strings(o.control.result?.['values']), req(ID_VECTOR, 'conformance/fixtures.md §The storage probe fixtures', "tenant A's own query MUST return the vector it upserted (positive control)")).toContain(o.value);
+    expect(otherOutcome(o), req(ID_VECTOR, DOC, "tenant B's query MUST complete or be refused with a storage refusal code")).toMatch(/^(completed|refused)$/);
+    expect(leakedValues(o), req(ID_VECTOR, DOC, "a vectorStore query for tenant B MUST NOT return metadata tenant A wrote in the identically named collection")).toEqual([]);
+    expect(leakedKeys(o), req(ID_VECTOR, DOC, "a vectorStore query for tenant B MUST NOT return an id tenant A upserted")).toEqual([]);
+  }, 150_000);
+
+  it('searchIndex: a query for tenant B never hits a document tenant A indexed in the same index', async () => {
+    const o = await isolationLeg('searchIndex'); if ('skip' in o) return softSkip(...o.skip);
+    expect(strings(o.control.result?.['values']), req(ID_SEARCH, 'conformance/fixtures.md §The storage probe fixtures', "tenant A's own query MUST return the document it indexed (positive control)")).toContain(o.value);
+    expect(otherOutcome(o), req(ID_SEARCH, DOC, "tenant B's query MUST complete or be refused with a storage refusal code")).toMatch(/^(completed|refused)$/);
+    expect(leakedValues(o), req(ID_SEARCH, DOC, "a searchIndex query for tenant B MUST NOT return fields tenant A indexed in the identically named index")).toEqual([]);
+    expect(leakedKeys(o), req(ID_SEARCH, DOC, "a searchIndex query for tenant B MUST NOT return an id tenant A indexed")).toEqual([]);
+  }, 150_000);
+
+  it('sql: tenant B reading the same-named datasource never sees a row tenant A inserted', async () => {
+    const o = await isolationLeg('sql'); if ('skip' in o) return softSkip(...o.skip);
+    expect(strings(o.control.result?.['values']), req(ID_SQL, 'conformance/fixtures.md §The storage probe fixtures', "tenant A's own query MUST return the row it inserted (positive control)")).toContain(o.value);
+    expect(otherOutcome(o), req(ID_SQL, DOC, "tenant B's query MUST complete or be refused with a storage refusal code")).toMatch(/^(completed|refused)$/);
+    expect(leakedValues(o), req(ID_SQL, DOC, "sql datasources are scoped per tenant: tenant B MUST NOT read a row tenant A inserted")).toEqual([]);
+    expect(leakedKeys(o), req(ID_SQL, DOC, "sql datasources are scoped per tenant: tenant B MUST NOT see a key tenant A inserted")).toEqual([]);
+  }, 150_000);
+
+  it('nosql: tenant B reading the same-named datasource never sees a document tenant A inserted (get and query)', async () => {
+    const o = await isolationLeg('nosql'); if ('skip' in o) return softSkip(...o.skip);
+    expect(strings(o.control.result?.['values']), req(ID_NOSQL, 'conformance/fixtures.md §The storage probe fixtures', "tenant A's own query MUST return the document it inserted (positive control)")).toContain(o.value);
+    expect(otherOutcome(o), req(ID_NOSQL, DOC, "tenant B's read MUST complete or be refused with a storage refusal code")).toMatch(/^(completed|refused)$/);
+    expect(leakedValues(o), req(ID_NOSQL, DOC, "nosql datasources are scoped per tenant: tenant B MUST NOT read a document tenant A inserted, by query or by its id")).toEqual([]);
+    expect(leakedKeys(o), req(ID_NOSQL, DOC, "nosql datasources are scoped per tenant: tenant B MUST NOT see a key tenant A inserted")).toEqual([]);
+  }, 150_000);
+});

package/src/scenarios/v2-tool-authorization-fail-closed.test.ts

@@ -0,0 +1,197 @@
+/**
+ * `spec/v2/core/host-services.md` §`toolHooks` — per-tool authorization fails
+ * closed (target major 2; gated on `toolHooks.perToolAuthorization` and the
+ * `conformance-tool-scope-probe` fixture).
+ *
+ *   "Before invoking, the host MUST check the principal's scopes against the
+ *    tool's `requiredScopes`. If one is missing or cannot be evaluated, it MUST
+ *    NOT invoke, MUST emit `agent.toolReturned` with `status: forbidden`, and
+ *    MUST answer `403 forbidden` with `details.scope: "tool"`, `toolName` and
+ *    `requiredScopes`."
+ *
+ * Before this file the rule had a witness at major 1 only
+ * (`tool-hooks-authorization-fail-closed`), through a v1 seam that returned the
+ * host's own account of what it did. It never observed the tool.
+ *
+ * No seam. The fixture's node (`core.conformance.scoped-tool`,
+ * conformance/fixtures.md §`conformance-tool-scope-probe`) makes ONE external
+ * tool call through the host's ordinary tool path as the run's principal. The
+ * tool, when invoked, POSTs to a URL the suite hands it, so "not invoked" is
+ * counted at the suite's own receiver, not taken from the host's log:
+ *
+ *   0. control — no required scope: the tool MUST be invoked (one arrival,
+ *      `agent.tool-returned { status: ok }`). Without it a host that refuses
+ *      every tool, or a node that never calls out, passes both legs vacuously.
+ *   1. `missing-scope` — `requiredScopes: ["conformance:never-granted"]`, a
+ *      scope the operator grants nobody;
+ *   2. `unevaluable-scope` — `requiredScopes: ["conformance:unevaluable"]`,
+ *      whose check the operator binds to error.
+ *
+ * For 1 and 2: the receiver sees NO call; the log carries
+ * `agent.tool-returned { toolName, status: forbidden }` with no `durationMs`
+ * (the call never started) and no `ok` return for the tool; and the refusal,
+ * which a run surfaces as the node's failure (`errors.md` §Host-service
+ * refusals), is `forbidden` with `details.scope: "tool"`, `details.toolName`
+ * and `details.requiredScopes` naming the scope.
+ *
+ * Dispositions: `toolHooks` not in the v2 root, or `perToolAuthorization` not
+ * `true` ⇒ `inapplicable`, read with `familyAdvertised` rather than
+ * `gateFamily` so strict mode does not demand a `family.toolHooks` opt-out from
+ * a host that never claimed the facet. Facet advertised without the fixture, a
+ * fixture run that cannot be created or does not settle, or a control that
+ * returns `ok` but never reaches the receiver (a loopback receiver the host
+ * cannot address — set `OPENWOP_WEBHOOK_RECEIVER_URL`) ⇒ `blocked` (RFC 0148 §A).
+ *
+ * Sabotage (a patched local copy of the v2 reference host): treat an
+ * unevaluable scope as granted, and the `unevaluable-scope` leg fails on the
+ * receiver; skip the check entirely, and both legs fail; refuse with
+ * `forbidden` but still call the tool, and both fail on the receiver.
+ *
+ * @see spec/v2/core/host-services.md §toolHooks
+ * @see conformance/fixtures.md §`conformance-tool-scope-probe`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } 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';
+import { startEffectReceiver, waitForFirstArrival } from '../lib/effect-receiver.js';
+
+export const REQUIRES_HOST_CALLBACK = 'the host invokes the scope-probe tool, which calls the suite-owned effect receiver (OPENWOP_WEBHOOK_RECEIVER_PORT)';
+
+const FIXTURE = 'conformance-tool-scope-probe';
+const TOOL = 'conformance.scope-probe';
+const DOC = 'spec/v2/core/host-services.md §toolHooks';
+const FIXTURE_DOC = 'conformance/fixtures.md §conformance-tool-scope-probe';
+const ID_MISSING = 'openwop.requirement.toolHooks.authorization-fail-closed-missing-scope';
+const ID_UNEVALUABLE = 'openwop.requirement.toolHooks.authorization-fail-closed-unevaluable-scope';
+const NEVER_GRANTED = 'conformance:never-granted';
+const UNEVALUABLE = 'conformance:unevaluable';
+const TERMINAL = new Set(['completed', 'failed', 'cancelled']);
+/** After a refused run settles, how long a late call to the receiver is still waited for. */
+const QUIET_MS = 2_000;
+
+type Skip = { skip: ['inapplicable' | 'blocked', string] };
+interface Ev { type?: unknown; nodeId?: unknown; payload?: Record<string, unknown> }
+
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> { try { return await fn(); } catch { return null; } }
+const enc = (id: string): string => encodeURIComponent(id);
+
+async function gate(): Promise<Skip | null> {
+  if (!(await v2Discovery().catch(() => null))) return { skip: ['blocked', 'v2 discovery unreachable — /.well-known/openwop did not answer 200 under OpenWOP-Version: 2.0'] };
+  const hooks = await familyAdvertised('toolHooks');
+  if (!hooks) return { skip: ['inapplicable', 'toolHooks is not advertised in the v2 discovery root — no per-tool authorization obligation'] };
+  if (hooks['perToolAuthorization'] !== true) return { skip: ['inapplicable', 'toolHooks is advertised without perToolAuthorization: true — the host makes no per-tool authorization claim'] };
+  if (!isFixtureAdvertised(FIXTURE)) return { skip: ['blocked', `the host advertises toolHooks.perToolAuthorization but not the ${FIXTURE} fixture — the fail-closed claim is made and cannot be observed without it`] };
+  return null;
+}
+
+interface Exercise {
+  readonly runId: string;
+  readonly status: string;
+  readonly arrivals: number;
+  readonly tunnelled: boolean;
+  readonly receiver: string;
+  /** `agent.tool-returned` payloads for the probe tool. */
+  readonly returns: Array<Record<string, unknown>>;
+  /** The node's `node.failed` error, if it failed. */
+  readonly error: { code?: unknown; details?: Record<string, unknown> } | null;
+}
+
+/** Run the fixture once, against a fresh receiver, and read back what reached the receiver and what the log says. */
+async function exercise(requiredScope: string): Promise<Exercise | { reason: string }> {
+  const rx = await startEffectReceiver();
+  try {
+    const created = await http(() => driver.post('/runs', { workflowId: FIXTURE, inputs: { requiredScope, url: rx.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 advertised fixture did not start`.trim() };
+    const t0 = Date.now(); let status = '';
+    while (Date.now() - t0 < 30_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, 150));
+    }
+    if (!TERMINAL.has(status)) return { reason: `the ${FIXTURE} run did not reach a terminal status within 30 s (last: ${status || 'unreadable'})` };
+    // A tool call that the host made is on the wire before the run settles, but give a slow network the benefit.
+    if (requiredScope === '') await waitForFirstArrival(rx, 5_000);
+    else await new Promise((r) => setTimeout(r, QUIET_MS));
+    const poll = await http(() => driver.get(`/runs/${enc(runId)}/events/poll?timeout=1`));
+    const events = (poll?.json as { events?: unknown } | null)?.events;
+    if (poll?.status !== 200 || !Array.isArray(events)) return { reason: `GET /runs/{runId}/events/poll answered ${poll?.status ?? 'nothing'}` };
+    const evs = events as Ev[];
+    const returns = evs.filter((e) => e.type === 'agent.tool-returned' && e.payload?.['toolName'] === TOOL).map((e) => e.payload as Record<string, unknown>);
+    const failed = evs.find((e) => e.type === 'node.failed');
+    const error = (failed?.payload?.['error'] ?? null) as Exercise['error'];
+    return { runId, status, arrivals: rx.arrivals(), tunnelled: rx.tunnelled, receiver: rx.url, returns, error };
+  } finally {
+    await rx.close();
+  }
+}
+
+/** The control run, once per file: the tool IS invoked when it requires nothing. */
+let control: Promise<Exercise | { reason: string }> | null = null;
+function controlRun(): Promise<Exercise | { reason: string }> {
+  control ??= exercise('');
+  return control;
+}
+
+/** Everything a scoped leg needs, or the recorded reason it cannot run. Every soft-skip decision is made here. */
+async function leg(scope: string): Promise<{ control: Exercise; denied: Exercise } | Skip> {
+  const why = await gate(); if (why) return why;
+  const c = await controlRun();
+  if ('reason' in c) return { skip: ['blocked', `control run: ${c.reason}`] };
+  const ok = c.status === 'completed' && c.returns.some((r) => r['status'] === 'ok');
+  if (ok && c.arrivals === 0) {
+    return { skip: ['blocked', `the control run invoked ${TOOL} (status ok) but nothing reached the suite's receiver at ${c.receiver}${c.tunnelled ? '' : ' (a loopback address — set OPENWOP_WEBHOOK_RECEIVER_URL to a front the host can reach)'}; "not invoked" cannot be counted`] };
+  }
+  const d = await exercise(scope);
+  if ('reason' in d) return { skip: ['blocked', `${scope} run: ${d.reason}`] };
+  return { control: c, denied: d };
+}
+
+describe('v2 tool authorization fail-closed (host-services.md §toolHooks)', () => {
+  it('a tool whose required scope the principal lacks is not invoked and is refused forbidden', async () => {
+    const o = await leg(NEVER_GRANTED); if ('skip' in o) return softSkip(...o.skip);
+    const { control: c, denied: d } = o;
+    // Positive control: without it, a host that refuses every tool passes vacuously.
+    expect(`${c.status}/${c.returns.map((r) => String(r['status'])).join(',') || 'no tool-returned'}`, req(ID_MISSING, FIXTURE_DOC, `with no required scope the fixture MUST invoke ${TOOL} and complete with agent.tool-returned status ok (positive control)`)).toMatch(/^completed\/(.*,)?ok(,.*)?$/);
+    expect(c.arrivals, req(ID_MISSING, FIXTURE_DOC, `with no required scope ${TOOL} MUST reach the suite's receiver (positive control)`)).toBeGreaterThan(0);
+
+    expect(d.arrivals, req(ID_MISSING, DOC, `a tool whose required scope (${NEVER_GRANTED}) the principal lacks or that cannot be evaluated MUST NOT be invoked — the suite's receiver saw ${d.arrivals} call(s)`)).toBe(0);
+    const forbidden = d.returns.filter((r) => r['status'] === 'forbidden');
+    expect(forbidden.length, req(ID_MISSING, DOC, `the host MUST emit agent.tool-returned with status: forbidden for ${TOOL} (got statuses: ${JSON.stringify(d.returns.map((r) => r['status'] ?? null))})`)).toBeGreaterThan(0);
+    expect(d.returns.filter((r) => r['status'] === 'ok').length, req(ID_MISSING, DOC, `a refused tool MUST NOT also return ok`)).toBe(0);
+    expect(forbidden.filter((r) => r['durationMs'] !== undefined).length, req(ID_MISSING, 'schemas/v2/run-event-payloads.schema.json#/$defs/agentToolReturned', 'durationMs is absent when the call never started (forbidden)')).toBe(0);
+
+    const details = d.error?.details ?? {};
+    expect(d.error?.code, req(ID_MISSING, DOC, `the refusal MUST be forbidden (the run surfaces it as the node's failure, errors.md §Host-service refusals; run status ${d.status})`)).toBe('forbidden');
+    expect(details['scope'], req(ID_MISSING, DOC, 'the forbidden refusal MUST carry details.scope: "tool"')).toBe('tool');
+    expect(details['toolName'], req(ID_MISSING, DOC, 'the forbidden refusal MUST carry details.toolName')).toBe(TOOL);
+    expect(Array.isArray(details['requiredScopes']) ? (details['requiredScopes'] as unknown[]) : [], req(ID_MISSING, DOC, 'the forbidden refusal MUST carry details.requiredScopes naming the tool\'s scopes')).toContain(NEVER_GRANTED);
+  }, 90_000);
+
+  it('a tool whose required scope cannot be evaluated is not invoked and is refused forbidden', async () => {
+    const o = await leg(UNEVALUABLE); if ('skip' in o) return softSkip(...o.skip);
+    const { control: c, denied: d } = o;
+    // Positive control: without it, a host that refuses every tool passes vacuously.
+    expect(`${c.status}/${c.returns.map((r) => String(r['status'])).join(',') || 'no tool-returned'}`, req(ID_UNEVALUABLE, FIXTURE_DOC, `with no required scope the fixture MUST invoke ${TOOL} and complete with agent.tool-returned status ok (positive control)`)).toMatch(/^completed\/(.*,)?ok(,.*)?$/);
+    expect(c.arrivals, req(ID_UNEVALUABLE, FIXTURE_DOC, `with no required scope ${TOOL} MUST reach the suite's receiver (positive control)`)).toBeGreaterThan(0);
+
+    expect(d.arrivals, req(ID_UNEVALUABLE, DOC, `a tool whose required scope (${UNEVALUABLE}) the principal lacks or that cannot be evaluated MUST NOT be invoked — the suite's receiver saw ${d.arrivals} call(s)`)).toBe(0);
+    const forbidden = d.returns.filter((r) => r['status'] === 'forbidden');
+    expect(forbidden.length, req(ID_UNEVALUABLE, DOC, `the host MUST emit agent.tool-returned with status: forbidden for ${TOOL} (got statuses: ${JSON.stringify(d.returns.map((r) => r['status'] ?? null))})`)).toBeGreaterThan(0);
+    expect(d.returns.filter((r) => r['status'] === 'ok').length, req(ID_UNEVALUABLE, DOC, `a refused tool MUST NOT also return ok`)).toBe(0);
+    expect(forbidden.filter((r) => r['durationMs'] !== undefined).length, req(ID_UNEVALUABLE, 'schemas/v2/run-event-payloads.schema.json#/$defs/agentToolReturned', 'durationMs is absent when the call never started (forbidden)')).toBe(0);
+
+    const details = d.error?.details ?? {};
+    expect(d.error?.code, req(ID_UNEVALUABLE, DOC, `the refusal MUST be forbidden (the run surfaces it as the node's failure, errors.md §Host-service refusals; run status ${d.status})`)).toBe('forbidden');
+    expect(details['scope'], req(ID_UNEVALUABLE, DOC, 'the forbidden refusal MUST carry details.scope: "tool"')).toBe('tool');
+    expect(details['toolName'], req(ID_UNEVALUABLE, DOC, 'the forbidden refusal MUST carry details.toolName')).toBe(TOOL);
+    expect(Array.isArray(details['requiredScopes']) ? (details['requiredScopes'] as unknown[]) : [], req(ID_UNEVALUABLE, DOC, 'the forbidden refusal MUST carry details.requiredScopes naming the tool\'s scopes')).toContain(UNEVALUABLE);
+  }, 90_000);
+});