@openwop/openwop-conformance 2.45.2 → 2.45.3

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

package/src/scenarios/v2-workspace-scope-from-identity.test.ts

@@ -0,0 +1,146 @@
+/**
+ * `v2-workspace-scope-from-identity` (target major 2; gated on the `workspace`
+ * family and the `openwop-conformance-seams-v2` profile).
+ *
+ * `spec/v2/core/host-services.md` §`workspace`: a host advertising `workspace`
+ * "MUST derive the scope from the authenticated identity and MUST NOT return or
+ * disclose another scope's file; `404` MAY stand for `403` (invariant
+ * `workspace-cross-tenant-isolation`)". No protocol path serves workspace files,
+ * so the only observation surface is the EXISTING v2 seam
+ * `/conformance/seams/workspace/files[/{path}]` (`api/seams-v2.yaml`). This file
+ * adds no seam; it drives that one with two credentials.
+ *
+ * Until this file the rule had major-1 witnesses only (`workspace-cross-tenant-
+ * isolation`, `workspace-cross-tenant-isolation-blackbox`, both on `/v1/…`), so
+ * no v2 host was ever measured on it (docs/V2-WITNESS-COVERAGE.md risk #3).
+ *
+ * Legs:
+ *   1. tenant A writes a unique file; tenant B (OPENWOP_TEST_TENANT_B_API_KEY)
+ *      reads it by path → 403/404 with no content, and B's list omits it.
+ *      Positive control: A reads its own file back and lists it.
+ *   2. the same read and list by B, NAMING A's scope in the request
+ *      (`tenantId` / `workspaceId` query parameters, the values read from
+ *      `owner` of a run A just created). A host that takes the scope from the
+ *      request instead of the credential serves A's file here.
+ *
+ * Dispositions: family or seams profile not advertised ⇒ `inapplicable`
+ * (lib/seams.ts: the host has not claimed the instrument). Advertised, but the
+ * seam answers 404/405/501, the second-tenant key is absent / identical /
+ * refused, or (leg 2) A's scope cannot be read from a run ⇒ `blocked` — the host
+ * took the obligation on and the suite could not measure it.
+ */
+import { describe, it, expect } from 'vitest';
+import { randomUUID } from 'node:crypto';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { loadEnv } from '../lib/env.js';
+import { v2Discovery, gateFamily } from '../lib/v2.js';
+import { seamsProfileAdvertised, SEAMS_PREFIX } from '../lib/seams.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { softSkip, seamAbsent } from '../lib/soft-skip.js';
+import { req } from '../lib/requirement-ids.js';
+
+const DOC = 'spec/v2/core/host-services.md §workspace';
+const FILES = `${SEAMS_PREFIX}/workspace/files`;
+const NOOP = 'conformance-noop';
+const ID_READ = 'openwop.requirement.0059.workspace-scope-from-identity';
+const ID_NAMED = 'openwop.requirement.0059.workspace-scope-not-request-named';
+
+type Gate = { ok: true; asB: { authenticated: false; headers: Record<string, string> } } | { ok: false; kind: 'inapplicable' | 'blocked'; reason: string; seam?: true };
+
+async function http(fn: () => Promise<OpenWOPResponse>): Promise<OpenWOPResponse | null> {
+  try { return await fn(); } catch { return null; }
+}
+
+/** Family, profile, seam and second credential — decided before any assertion. */
+async function gate(): Promise<Gate> {
+  const doc = await v2Discovery();
+  if (!doc) return { ok: false, kind: 'blocked', reason: 'v2 discovery unreachable — /.well-known/openwop did not answer 200 JSON under OpenWOP-Version: 2.0' };
+  if (!(await gateFamily('workspace'))) return { ok: false, kind: 'inapplicable', reason: 'workspace family not advertised (gate recorded under openwop.family.workspace)' };
+  if (!seamsProfileAdvertised(doc)) return { ok: false, kind: 'inapplicable', reason: 'workspace files have no protocol path; the only observation surface is the seams profile (conformance.seamsProfile = openwop-conformance-seams-v2), which is not advertised' };
+  const probe = await http(() => driver.get(FILES));
+  if (probe === null) return { ok: false, kind: 'blocked', reason: `GET ${FILES} unreachable (fetch failed)` };
+  if ([404, 405, 501].includes(probe.status)) return { ok: false, kind: 'blocked', reason: `host advertises workspace and the seams profile but GET ${FILES} answered ${probe.status}`, seam: true };
+  const b = process.env['OPENWOP_TEST_TENANT_B_API_KEY']?.trim();
+  if (!b) return { ok: false, kind: 'blocked', reason: 'OPENWOP_TEST_TENANT_B_API_KEY (a credential bound to a second tenant) is not set — no second-scope read can be measured' };
+  if (b === loadEnv().apiKey) return { ok: false, kind: 'blocked', reason: 'OPENWOP_TEST_TENANT_B_API_KEY equals OPENWOP_API_KEY — the leg needs a second tenant' };
+  const asB = { authenticated: false as const, headers: { Authorization: `Bearer ${b}` } };
+  const probeB = await http(() => driver.get(FILES, asB));
+  if (probeB === null || probeB.status === 401) return { ok: false, kind: 'blocked', reason: `OPENWOP_TEST_TENANT_B_API_KEY does not authenticate on this host (GET ${FILES} answered ${probeB?.status ?? 'nothing'})` };
+  return { ok: true, asB };
+}
+
+/** A's file, written through the seam; the caller deletes it. */
+async function writeA(): Promise<{ path: string; secret: string } | { reason: string }> {
+  const path = `v2-wsi-${randomUUID()}.md`;
+  const secret = `V2-WSI-CANARY-${randomUUID()}`;
+  const put = await http(() => driver.put(`${FILES}/${path}`, { content: secret }));
+  if (put === null || put.status !== 200) return { reason: `tenant A could not write ${FILES}/${path} (answered ${put?.status ?? 'nothing'})` };
+  return { path, secret };
+}
+
+function paths(res: OpenWOPResponse | null): string[] {
+  const files = (res?.json as { files?: Array<{ path?: unknown }> } | undefined)?.files;
+  return Array.isArray(files) ? files.map((f) => String(f?.path)) : [];
+}
+
+/** A's own `{tenant, workspace}` as the host records it, from `owner` of a run A creates. */
+async function scopeOf(as: Record<string, unknown> = {}): Promise<{ tenant: string; workspace?: string } | { reason: string }> {
+  if (!isFixtureAdvertised(NOOP)) return { reason: `${NOOP} is not advertised — the suite cannot learn a scope id to name` };
+  const res = await http(() => driver.post('/runs', { workflowId: NOOP }, as));
+  const runId = (res?.json as { runId?: unknown } | undefined)?.runId;
+  if (res === null || res.status !== 201 || typeof runId !== 'string') return { reason: `POST /runs {${NOOP}} answered ${res?.status ?? 'nothing'}` };
+  const snap = await http(() => driver.get(`/runs/${encodeURIComponent(runId)}`, as));
+  const owner = (snap?.json as { owner?: { tenant?: unknown; workspace?: unknown } } | undefined)?.owner;
+  const tenant = typeof owner?.tenant === 'string' ? owner.tenant : runId.includes('/') ? runId.slice(0, runId.indexOf('/')) : null;
+  if (!tenant) return { reason: 'the run snapshot names no owner.tenant and the run id carries no tenant segment' };
+  return typeof owner?.workspace === 'string' ? { tenant, workspace: owner.workspace } : { tenant };
+}
+
+describe('v2 workspace scope comes from the authenticated identity (host-services.md §workspace)', () => {
+  it('a second tenant cannot read or list a file the first tenant wrote', async () => {
+    const g = await gate();
+    if (!g.ok && g.seam) return seamAbsent(g.reason);
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const a = await writeA();
+    if ('reason' in a) return softSkip('blocked', a.reason);
+    try {
+      const own = await driver.get(`${FILES}/${a.path}`);
+      expect(own.status, req(ID_READ, DOC, 'positive control: the owning scope MUST read its own file (200)')).toBe(200);
+      expect((own.json as { content?: unknown } | undefined)?.content, req(ID_READ, DOC, 'positive control: the owner reads back the content it wrote')).toBe(a.secret);
+      expect(paths(await http(() => driver.get(FILES))), req(ID_READ, DOC, 'positive control: the owner\'s list names its own file')).toContain(a.path);
+
+      const cross = await driver.get(`${FILES}/${a.path}`, g.asB);
+      expect([403, 404], req(ID_READ, DOC, `another scope's read MUST NOT return the file — 404 MAY stand for 403 (got ${cross.status})`)).toContain(cross.status);
+      expect(cross.text.includes(a.secret), req(ID_READ, DOC, 'another scope\'s read MUST NOT disclose the file\'s content')).toBe(false);
+      const list = await http(() => driver.get(FILES, g.asB));
+      expect(list?.text.includes(a.secret) === true || paths(list).includes(a.path), req(ID_READ, DOC, 'another scope\'s list MUST NOT disclose the file')).toBe(false);
+    } finally {
+      await http(() => driver.delete(`${FILES}/${a.path}`));
+    }
+  });
+
+  it('naming the first tenant\'s scope in the request does not widen the second tenant\'s scope', async () => {
+    const g = await gate();
+    if (!g.ok && g.seam) return seamAbsent(g.reason);
+    if (!g.ok) return softSkip(g.kind, g.reason);
+    const scopeA = await scopeOf();
+    if ('reason' in scopeA) return softSkip('blocked', `A's scope id is needed to name it: ${scopeA.reason}`);
+    const scopeB = await scopeOf(g.asB);
+    if (!('reason' in scopeB) && scopeB.tenant === scopeA.tenant) return softSkip('blocked', 'OPENWOP_TEST_TENANT_B_API_KEY binds the same tenant as OPENWOP_API_KEY — the leg needs a second tenant');
+    const a = await writeA();
+    if ('reason' in a) return softSkip('blocked', a.reason);
+    try {
+      const q = new URLSearchParams({ tenantId: scopeA.tenant, tenant: scopeA.tenant, ...(scopeA.workspace ? { workspaceId: scopeA.workspace, workspace: scopeA.workspace } : {}) }).toString();
+      const own = await driver.get(`${FILES}/${a.path}`);
+      expect(own.status, req(ID_NAMED, DOC, 'positive control: the owning scope MUST read its own file (200)')).toBe(200);
+
+      const cross = await driver.get(`${FILES}/${a.path}?${q}`, g.asB);
+      expect([400, 403, 404], req(ID_NAMED, DOC, `the scope MUST come from the credential, not a request-named tenantId/workspaceId (got ${cross.status})`)).toContain(cross.status);
+      expect(cross.text.includes(a.secret), req(ID_NAMED, DOC, 'a request naming another scope MUST NOT disclose that scope\'s file')).toBe(false);
+      const list = await http(() => driver.get(`${FILES}?${q}`, g.asB));
+      expect(list?.text.includes(a.secret) === true || paths(list).includes(a.path), req(ID_NAMED, DOC, 'a list naming another scope MUST NOT disclose that scope\'s file')).toBe(false);
+    } finally {
+      await http(() => driver.delete(`${FILES}/${a.path}`));
+    }
+  });
+});