@openwop/openwop-conformance 1.21.0 → 1.23.0

package/src/scenarios/version-fold.test.ts

@@ -0,0 +1,193 @@
+/**
+ * version-fold — `version-negotiation.md` §Cross-version interop matrix,
+ * exercised via the test-keys-only `X-Force-Engine-Version` header
+ * (§"Conformance via `X-Force-Engine-Version`"). Consumer of the
+ * `conformance-version-fold` fixture (closes catalog gap F5 — the fixture
+ * previously had no consuming scenario; see `fixtures.md`).
+ *
+ * Gating: `describe.skipIf` on the advertised `conformance-version-fold`
+ * fixture id (RFC 0003). The forced-version seam itself is advertised via
+ * `Capabilities.testing.forceEngineVersionRange = { min, max }` — hosts
+ * that advertise the fixture but not the seam soft-skip with a warning
+ * (mirroring the suite's other test-seam scenarios, e.g. the OTel
+ * collector seams), because the header is a test seam, not a production
+ * surface.
+ *
+ * What's asserted per the fixture driver (`fixtures.md` §`conformance-version-fold`):
+ *   1. For each forced version in `[min, current, max]` (deduped), a run
+ *      of the single-noop fixture reaches terminal `completed`.
+ *   2. `GET /v1/runs/{runId}` returns a readable `RunSnapshot` (the
+ *      projection tolerates the version mismatch via fold-best-effort).
+ *   3. The event log is readable via `GET /v1/runs/{runId}/events/poll`
+ *      and non-empty.
+ *   4. Negative: a forced version outside the advertised range returns
+ *      `400 unsupported_force_engine_version`.
+ *
+ * NOT black-box testable here: the production-key refusal
+ * (`403 force_engine_version_forbidden`) — the suite holds a single API
+ * key, which must be a test key for the positive legs to run at all.
+ * When the host answers `403 force_engine_version_forbidden` the key is
+ * production-scoped and the scenario soft-skips honestly.
+ *
+ * @see spec/v1/version-negotiation.md §"Conformance via `X-Force-Engine-Version`"
+ * @see conformance/fixtures.md §`conformance-version-fold`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+import { capabilityFamily } from '../lib/discovery-capabilities.js';
+
+const FIXTURE_ID = 'conformance-version-fold';
+const SKIP_NO_FIXTURE = !isFixtureAdvertised(FIXTURE_ID);
+
+interface ForceRange {
+  readonly min: number;
+  readonly max: number;
+}
+
+/** Read `testing.forceEngineVersionRange` + the host's current `engineVersion`
+ *  from discovery. Returns null when the host doesn't expose the seam. */
+async function readForceSeam(): Promise<{ range: ForceRange; current: number | null } | null> {
+  const res = await driver.get('/.well-known/openwop');
+  if (res.status !== 200) return null;
+  const testing = capabilityFamily<{ forceEngineVersionRange?: unknown }>(res.json, 'testing');
+  const range = testing?.forceEngineVersionRange as { min?: unknown; max?: unknown } | undefined;
+  if (!range || !Number.isInteger(range.min) || !Number.isInteger(range.max)) return null;
+  const engineVersion = capabilityFamily<unknown>(res.json, 'engineVersion');
+  return {
+    range: { min: range.min as number, max: range.max as number },
+    current: Number.isInteger(engineVersion) ? (engineVersion as number) : null,
+  };
+}
+
+function errCode(json: unknown): string | undefined {
+  const e = (json as { error?: unknown } | undefined)?.error;
+  return typeof e === 'string' ? e : undefined;
+}
+
+async function createForcedRun(version: number): Promise<OpenWOPResponse> {
+  return driver.post(
+    '/v1/runs',
+    { workflowId: FIXTURE_ID },
+    { headers: { 'X-Force-Engine-Version': String(version) } },
+  );
+}
+
+describe.skipIf(SKIP_NO_FIXTURE)('version-fold: forced engine versions fold-best-effort across the advertised range', () => {
+  it('each version in [min, current, max] completes + snapshot and event log stay readable', async () => {
+    const seam = await readForceSeam();
+    if (seam === null) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[version-fold] host does not advertise Capabilities.testing.forceEngineVersionRange; ' +
+          'skipping (the X-Force-Engine-Version seam is test-keys-only and optional)',
+      );
+      return;
+    }
+
+    const candidates = [seam.range.min, ...(seam.current === null ? [] : [seam.current]), seam.range.max];
+    const versions = [...new Set(candidates)].filter(
+      (v) => v >= seam.range.min && v <= seam.range.max,
+    );
+    expect(
+      versions.length,
+      driver.describe(
+        'version-negotiation.md §Conformance via X-Force-Engine-Version',
+        'forceEngineVersionRange MUST describe a non-empty integer range (min <= max)',
+      ),
+    ).toBeGreaterThan(0);
+
+    for (const v of versions) {
+      const create = await createForcedRun(v);
+      if (create.status === 403 && errCode(create.json) === 'force_engine_version_forbidden') {
+        // eslint-disable-next-line no-console
+        console.warn('[version-fold] API key is production-scoped (403 force_engine_version_forbidden); skipping');
+        return;
+      }
+      expect(
+        create.status,
+        driver.describe(
+          'version-negotiation.md §Conformance via X-Force-Engine-Version',
+          `POST /v1/runs with X-Force-Engine-Version: ${v} (within the advertised range) MUST be accepted on a test key`,
+        ),
+      ).toBe(201);
+      const runId = (create.json as { runId: string }).runId;
+
+      // 1) Terminal completed — the fold tolerates the forced version.
+      const terminal = await pollUntilTerminal(runId);
+      expect(
+        terminal.status,
+        driver.describe(
+          'version-negotiation.md §Cross-version interop matrix',
+          `the conformance-version-fold noop run MUST complete under forced engine version ${v} (fold-best-effort)`,
+        ),
+      ).toBe('completed');
+
+      // 2) The projection (RunSnapshot) is readable.
+      const snap = await driver.get(`/v1/runs/${encodeURIComponent(runId)}`);
+      expect(
+        snap.status,
+        driver.describe(
+          'version-negotiation.md §Cross-version interop matrix',
+          `GET /v1/runs/{runId} MUST return a readable RunSnapshot under forced engine version ${v}`,
+        ),
+      ).toBe(200);
+      const snapBody = snap.json as { runId?: unknown; status?: unknown };
+      expect(typeof snapBody.runId).toBe('string');
+      expect(typeof snapBody.status).toBe('string');
+
+      // 3) The event log is readable + non-empty.
+      const events = await driver.get(
+        `/v1/runs/${encodeURIComponent(runId)}/events/poll?lastSequence=0&timeout=1`,
+      );
+      expect(
+        events.status,
+        driver.describe(
+          'version-negotiation.md §Conformance via X-Force-Engine-Version',
+          `the event log MUST be readable via events/poll under forced engine version ${v}`,
+        ),
+      ).toBe(200);
+      const eventList = (events.json as { events?: unknown[] } | undefined)?.events ?? [];
+      expect(
+        eventList.length,
+        driver.describe(
+          'version-negotiation.md §Conformance via X-Force-Engine-Version',
+          `events/poll MUST return a non-empty events[] for the forced-version run (v=${v})`,
+        ),
+      ).toBeGreaterThan(0);
+    }
+  });
+
+  it('a forced version outside the advertised range is rejected with 400 unsupported_force_engine_version', async () => {
+    const seam = await readForceSeam();
+    if (seam === null) {
+      // eslint-disable-next-line no-console
+      console.warn('[version-fold] forceEngineVersionRange not advertised; skipping negative leg');
+      return;
+    }
+
+    const outOfRange = seam.range.max + 1;
+    const create = await createForcedRun(outOfRange);
+    if (create.status === 403 && errCode(create.json) === 'force_engine_version_forbidden') {
+      // eslint-disable-next-line no-console
+      console.warn('[version-fold] API key is production-scoped; skipping negative leg');
+      return;
+    }
+    expect(
+      create.status,
+      driver.describe(
+        'version-negotiation.md §Conformance via X-Force-Engine-Version',
+        `X-Force-Engine-Version: ${outOfRange} (outside the advertised range) MUST return 400`,
+      ),
+    ).toBe(400);
+    expect(
+      errCode(create.json),
+      driver.describe(
+        'version-negotiation.md §Conformance via X-Force-Engine-Version',
+        'the out-of-range refusal MUST carry the canonical unsupported_force_engine_version code',
+      ),
+    ).toBe('unsupported_force_engine_version');
+  });
+});

package/src/scenarios/wasm-pack-memory-cap.test.ts

@@ -80,13 +80,15 @@ describe('wasm-pack-memory-cap: positive path via misbehaving pack', () => {
     )).toBe('failed');
 
     const events = await driver.get(`/v1/runs/${encodeURIComponent(runId)}/events`);
-    const list = (events.json as { events?: Array<{ type: string; data?: unknown }> }).events ?? [];
+    const list = (events.json as { events?: Array<{ type: string; payload?: unknown }> }).events ?? [];
     const breachEvent = list.find((e) => e.type === 'cap.breached');
     expect(breachEvent, driver.describe(
       'RFCS/0008-wasm-abi.md §K',
       'host MUST emit cap.breached when a WASM module exceeds its memory ceiling',
     )).toBeDefined();
-    const breachKind = (breachEvent?.data as { kind?: string } | undefined)?.kind;
+    // Event detail rides under the canonical `payload` envelope field (per
+    // run-event-payloads.schema.json + every other event scenario), not `data`.
+    const breachKind = (breachEvent?.payload as { kind?: string } | undefined)?.kind;
     expect(breachKind, driver.describe(
       'RFCS/0008-wasm-abi.md §K',
       'cap.breached payload MUST carry kind: "wasm-memory" for memory-ceiling breaches',

package/src/scenarios/webhook-tenant-isolation.test.ts

@@ -0,0 +1,184 @@
+/**
+ * webhook-tenant-isolation — RFC 0093 §A.3 + SECURITY/invariants.yaml
+ * `webhook-cross-tenant-isolation`.
+ *
+ * Status: ACTIVE (advertisement + behavioral). RFC 0093 §A.3: a webhook
+ * subscription MUST receive only events from runs within the
+ * subscription's tenant scope (the tenant established at registration
+ * per the webhooks.md registration-time membership gate); cross-tenant
+ * delivery is a protocol violation regardless of filter breadth.
+ *
+ * Delivery itself is not black-box observable from a single-tenant
+ * conformance run (RFC 0093 §Conformance) — the delivery half is carried
+ * by the reference-impl-tier `webhook-delivery-egress-revalidation`
+ * pointers. What this scenario proves, mirroring the existing
+ * cross-tenant-isolation pattern (`kv-cross-tenant-isolation.test.ts`):
+ *
+ *   - Seam-driven two-tenant proof through the optional reference-host
+ *     test seam `POST /v1/host/sample/test/surface` (`surface: "webhooks"`,
+ *     ops `register` / `list` / `unregister`): a subscription registered
+ *     under tenant A MUST NOT appear in tenant B's subscription list.
+ *     Hosts that don't expose the seam (HTTP 404) soft-skip this half.
+ *
+ *   - Black-box single-tenant proxy assertions on the registration
+ *     surface (`webhooks.md` §Register/§Unregister): registering under a
+ *     tenant the caller is not a member of is refused, and a held
+ *     subscription cannot be unregistered through a foreign tenant scope.
+ *
+ * Gated via `behaviorGate('openwop-webhook-tenant-isolation',
+ * webhooks.supported === true)` — soft-skip by default, hard-fail under
+ * `OPENWOP_REQUIRE_BEHAVIOR=true` (root-first family read per RFC 0073).
+ *
+ * @see RFCS/0093-protocol-hardening-webhooks-tokens-idempotency.md §A.3
+ * @see spec/v1/webhooks.md §Endpoints (registration-time membership gate)
+ * @see SECURITY/invariants.yaml — webhook-cross-tenant-isolation
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver, type OpenWOPResponse } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { readCapabilityFamily } from '../lib/discovery-capabilities.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+
+interface WebhooksCap {
+  readonly supported?: unknown;
+}
+
+/** A public, registration-safe delivery URL (https:// per webhooks.md;
+ *  resolves publicly so SSRF guards don't reject it). Never delivered to
+ *  in this scenario — registration only. */
+const SAFE_URL = 'https://example.com/openwop-conformance/webhook-tenant-isolation';
+
+function uniqueSuffix(): string {
+  return `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+async function seam(tenantId: string, op: string, args: Record<string, unknown>): Promise<OpenWOPResponse> {
+  return driver.post('/v1/host/sample/test/surface', { tenantId, surface: 'webhooks', op, args });
+}
+
+async function gateOnWebhooks(): Promise<boolean> {
+  const cap = await readCapabilityFamily<WebhooksCap>('webhooks');
+  return behaviorGate('openwop-webhook-tenant-isolation', cap?.supported === true);
+}
+
+describe.skipIf(HTTP_SKIP)('webhook-tenant-isolation: advertisement shape (webhooks.md)', () => {
+  it('the webhooks block is either absent or carries a boolean supported flag', async () => {
+    const cap = await readCapabilityFamily<WebhooksCap>('webhooks');
+    if (cap === undefined) return; // host doesn't advertise webhooks — conformant
+    expect(
+      typeof cap.supported,
+      driver.describe('capabilities.schema.json §webhooks', 'webhooks.supported MUST be a boolean when present'),
+    ).toBe('boolean');
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('webhook-tenant-isolation: two-tenant proof via the test seam (RFC 0093 §A.3)', () => {
+  it('a subscription registered under tenant A is invisible to tenant B', async () => {
+    if (!(await gateOnWebhooks())) return;
+
+    const reg = await seam('tenant-a', 'register', {
+      url: SAFE_URL,
+      events: ['run.completed'],
+    });
+    if (reg.status === 404) return; // host doesn't expose the test seam — soft-skip
+    expect(reg.status, driver.describe('RFC 0093 §A.3', 'seam register under tenant A MUST succeed')).toBe(200);
+    const webhookId = (reg.json as { webhookId?: string }).webhookId;
+    expect(typeof webhookId, 'seam register MUST return the new webhookId').toBe('string');
+
+    try {
+      const listB = await seam('tenant-b', 'list', {});
+      expect(listB.status).toBe(200);
+      const idsB = ((listB.json as { webhooks?: Array<{ webhookId?: string }> }).webhooks ?? [])
+        .map((w) => w.webhookId);
+      expect(
+        idsB,
+        driver.describe(
+          'SECURITY/invariants.yaml webhook-cross-tenant-isolation',
+          'tenant B MUST NOT see tenant A subscriptions in its list',
+        ),
+      ).not.toContain(webhookId);
+
+      const listA = await seam('tenant-a', 'list', {});
+      const idsA = ((listA.json as { webhooks?: Array<{ webhookId?: string }> }).webhooks ?? [])
+        .map((w) => w.webhookId);
+      expect(
+        idsA,
+        driver.describe('RFC 0093 §A.3', 'tenant A MUST see its own subscription (same-tenant control)'),
+      ).toContain(webhookId);
+    } finally {
+      await seam('tenant-a', 'unregister', { webhookId });
+    }
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('webhook-tenant-isolation: black-box registration-surface scoping (webhooks.md)', () => {
+  it('registering under a tenant the caller is not a member of is refused', async () => {
+    if (!(await gateOnWebhooks())) return;
+
+    const foreignTenant = `openwop-conformance-foreign-${uniqueSuffix()}`;
+    const reg = await driver.post('/v1/webhooks', {
+      url: SAFE_URL,
+      events: ['run.completed'],
+      tenantId: foreignTenant,
+    });
+
+    if (reg.status === 201) {
+      // Leaked registration — clean up before failing the assertion below.
+      const body = reg.json as { webhookId?: string };
+      if (body.webhookId) {
+        await driver.delete(
+          `/v1/webhooks/${encodeURIComponent(body.webhookId)}?tenantId=${encodeURIComponent(foreignTenant)}`,
+        );
+      }
+    }
+    expect(
+      reg.status,
+      driver.describe(
+        'webhooks.md §Endpoints ("the caller MUST be a member of the tenant") + RFC 0093 §A.3',
+        'registration under a tenant the caller is not a member of MUST be refused (403/404/400), never 201',
+      ),
+    ).not.toBe(201);
+  });
+
+  it('a held subscription cannot be unregistered through a foreign tenant scope', async () => {
+    if (!(await gateOnWebhooks())) return;
+
+    // Register under the caller's own tenant (host defaults the scope from
+    // the API key when tenantId is omitted — the same registration shape the
+    // webhook delivery scenarios use).
+    const reg = await driver.post('/v1/webhooks', {
+      url: SAFE_URL,
+      events: ['run.completed'],
+    });
+    if (reg.status !== 201) {
+      // Host requires an explicit tenantId (or rejected the public URL) —
+      // nothing to hold; the membership-gate leg above still applies.
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[webhook-tenant-isolation] could not register a probe subscription (${reg.status}); skipping foreign-unregister leg`,
+      );
+      return;
+    }
+    const webhookId = (reg.json as { webhookId?: string }).webhookId;
+    expect(typeof webhookId, 'registration MUST return webhookId').toBe('string');
+
+    try {
+      const foreignTenant = `openwop-conformance-foreign-${uniqueSuffix()}`;
+      const del = await driver.delete(
+        `/v1/webhooks/${encodeURIComponent(webhookId!)}?tenantId=${encodeURIComponent(foreignTenant)}`,
+      );
+      expect(
+        del.status !== 204 && del.status < 500,
+        driver.describe(
+          'webhooks.md §Unregister (403 non-member / 404 not-in-scope) + RFC 0093 §A.3',
+          `unregister through a foreign tenant scope MUST NOT succeed (got ${del.status})`,
+        ),
+      ).toBe(true);
+    } finally {
+      // Best-effort cleanup in the caller's own scope.
+      await driver.delete(`/v1/webhooks/${encodeURIComponent(webhookId!)}`);
+    }
+  });
+});