@openwop/openwop-conformance 1.1.1 → 1.3.0

package/src/scenarios/table-cursor-pagination.test.ts

@@ -0,0 +1,85 @@
+/**
+ * table-cursor-pagination — RFC 0016 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0016 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.tableStorage` block has landed in
+ * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
+ * shape against any host that boots the conformance suite, and keeps the
+ * deeper behavioral assertions as `it.todo()` until a reference host wires
+ * a test seam.
+ *
+ * Summary: query MUST support filter + cursor pagination.
+ *
+ * @see RFCS/0016-*.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["tableStorage"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+describe('table-cursor-pagination: advertisement shape (RFC 0016)', () => {
+  it('capabilities.tableStorage is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return; // host doesn't advertise — skip
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §tableStorage',
+        'capabilities.tableStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+async function call(op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId: 'tenant-a', surface: 'table', op, args });
+}
+
+describe('table-cursor-pagination: behavioral (RFC 0016 §B point 3)', () => {
+  it('first page returns N rows + nextCursor; second page resumes; final page returns nextCursor:null', async () => {
+    const probe = await call('query', { table: '__probe__', limit: 1 });
+    if (probe.status === 404) return; // seam not exposed
+    const table = `pag-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    // Seed 5 rows with deterministic ids so cursor ordering is testable.
+    for (let i = 1; i <= 5; i++) {
+      await call('insert', { table, row: { id: `row-${i.toString().padStart(2, '0')}`, n: i } });
+    }
+    // Page 1: limit=2
+    const p1 = await call('query', { table, limit: 2 });
+    const b1 = p1.json as { rows?: Array<{ id: string }>; nextCursor?: string | null };
+    expect(Array.isArray(b1.rows) && b1.rows.length === 2).toBe(true);
+    expect(
+      typeof b1.nextCursor === 'string' && b1.nextCursor.length > 0,
+      driver.describe('RFC 0016 §B point 3', 'first page MUST surface nextCursor when more results remain'),
+    ).toBe(true);
+
+    // Page 2: cursor from page 1, limit=2
+    const p2 = await call('query', { table, limit: 2, cursor: b1.nextCursor });
+    const b2 = p2.json as { rows?: Array<{ id: string }>; nextCursor?: string | null };
+    expect(b2.rows?.length).toBe(2);
+    expect(
+      b2.rows![0]!.id > b1.rows![1]!.id,
+      driver.describe('RFC 0016 §B point 3', 'second page MUST resume AFTER the last id of the previous page'),
+    ).toBe(true);
+
+    // Page 3: final page — only 1 row left, nextCursor MUST be null
+    const p3 = await call('query', { table, limit: 2, cursor: b2.nextCursor });
+    const b3 = p3.json as { rows?: Array<{ id: string }>; nextCursor?: string | null };
+    expect(b3.rows?.length).toBe(1);
+    expect(
+      b3.nextCursor,
+      driver.describe('RFC 0016 §B point 3', 'final page (no more results) MUST surface nextCursor: null'),
+    ).toBe(null);
+  });
+});

package/src/scenarios/table-schema-enforcement.test.ts

@@ -0,0 +1,84 @@
+/**
+ * table-schema-enforcement — RFC 0016 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0016 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.tableStorage` block has landed in
+ * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
+ * shape against any host that boots the conformance suite, and keeps the
+ * deeper behavioral assertions as `it.todo()` until a reference host wires
+ * a test seam.
+ *
+ * Summary: Subsequent rows MUST conform to the schema established on first insert.
+ *
+ * @see RFCS/0016-*.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["tableStorage"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+describe('table-schema-enforcement: advertisement shape (RFC 0016)', () => {
+  it('capabilities.tableStorage is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return; // host doesn't advertise — skip
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §tableStorage',
+        'capabilities.tableStorage.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+async function call(op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId: 'tenant-a', surface: 'table', op, args });
+}
+
+describe('table-schema-enforcement: behavioral (RFC 0016 §B point 2)', () => {
+  it('first insert declares schema; subsequent insert with wrong column type is rejected', async () => {
+    const probe = await call('insert', { table: '__probe__', row: { id: 'probe-0' } });
+    if (probe.status === 404) return; // seam not exposed
+    const table = `sch-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    // First insert — declares the schema from this row's columns.
+    const first = await call('insert', {
+      table,
+      row: { id: 'row-1', name: 'alice', count: 42, active: true },
+    });
+    expect(first.status).toBe(200);
+
+    // Second insert — matching schema; MUST succeed.
+    const second = await call('insert', {
+      table,
+      row: { id: 'row-2', name: 'bob', count: 7, active: false },
+    });
+    expect(second.status).toBe(200);
+
+    // Third insert — `count` declared as number; sending a string MUST be rejected.
+    const bad = await call('insert', {
+      table,
+      row: { id: 'row-3', name: 'mallory', count: 'oops-a-string', active: true },
+    });
+    expect(
+      bad.status >= 400 && bad.status < 500,
+      driver.describe('RFC 0016 §B point 2', 'type-divergent insert MUST be rejected with 4xx'),
+    ).toBe(true);
+    const body = bad.json as { error?: { code?: string } | string };
+    const code = typeof body.error === 'string' ? body.error : body.error?.code;
+    expect(
+      code,
+      driver.describe('RFC 0016 §B point 2', 'rejection MUST carry the table_schema_violation error code'),
+    ).toBe('table_schema_violation');
+  });
+});

package/src/scenarios/vector-knn-roundtrip.test.ts

@@ -0,0 +1,88 @@
+/**
+ * vector-knn-roundtrip — RFC 0018 advertisement-shape verification + behavioral placeholders.
+ *
+ * Status: ACTIVE (advertisement-shape). RFC 0018 promoted to `Active`
+ * 2026-05-17. The matching `capabilities.vectorStore` block has landed in
+ * `schemas/capabilities.schema.json`. This scenario asserts the advertisement
+ * shape against any host that boots the conformance suite, and keeps the
+ * deeper behavioral assertions as `it.todo()` until a reference host wires
+ * a test seam.
+ *
+ * Summary: upsert then query returns the same vectors in top-k order.
+ *
+ * @see RFCS/0018-*.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+interface DiscoveryDoc {
+  capabilities?: Record<string, unknown>;
+}
+
+async function readCap(): Promise<Record<string, unknown> | null> {
+  const res = await driver.get('/.well-known/openwop');
+  const body = res.json as DiscoveryDoc | undefined;
+  const top = body?.capabilities as Record<string, unknown> | undefined;
+  const final = (top && typeof top === 'object') ? (top as Record<string, unknown>)["vectorStore"] : undefined;
+  return (final && typeof final === 'object' ? (final as Record<string, unknown>) : null);
+}
+
+describe('vector-knn-roundtrip: advertisement shape (RFC 0018)', () => {
+  it('capabilities.vectorStore is either absent or a well-formed object', async () => {
+    const cap = await readCap();
+    if (cap === null) return; // host doesn't advertise — skip
+    expect(
+      typeof cap.supported,
+      driver.describe(
+        'capabilities.schema.json §vectorStore',
+        'capabilities.vectorStore.supported MUST be a boolean when present',
+      ),
+    ).toBe('boolean');
+  });
+});
+
+async function call(op: string, args: Record<string, unknown>) {
+  return driver.post('/v1/host/sample/test/surface', { tenantId: 'tenant-a', surface: 'vector', op, args });
+}
+
+describe('vector-knn-roundtrip: behavioral (RFC 0018 §A.vectorStore)', () => {
+  it('upsert 10 vectors → query with one of them returns it as the top match', async () => {
+    const probe = await call('query', { namespace: '__probe__', vector: [1, 0], topK: 1 });
+    if (probe.status === 404) return; // seam not exposed
+    const namespace = `knn-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const items = Array.from({ length: 10 }, (_, i) => ({
+      id: `vec-${i}`,
+      vector: [Math.cos((i * Math.PI) / 5), Math.sin((i * Math.PI) / 5)],
+    }));
+    const upsertRes = await call('upsert', { namespace, items });
+    expect(upsertRes.status).toBe(200);
+
+    const queryRes = await call('query', { namespace, vector: items[3]!.vector, topK: 1 });
+    expect(queryRes.status).toBe(200);
+    const body = queryRes.json as { matches?: Array<{ id?: string; score?: number }> };
+    expect(Array.isArray(body.matches), 'matches MUST be an array').toBe(true);
+    expect(body.matches!.length).toBeGreaterThan(0);
+    expect(
+      body.matches![0]!.id,
+      driver.describe('RFC 0018 §A.vectorStore', 'query with an indexed vector MUST return it as the top match'),
+    ).toBe('vec-3');
+  });
+
+  it('topK respects the configured limit', async () => {
+    const probe = await call('query', { namespace: '__probe__', vector: [1, 0], topK: 1 });
+    if (probe.status === 404) return;
+    const namespace = `topk-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const items = Array.from({ length: 8 }, (_, i) => ({
+      id: `t-${i}`,
+      vector: [i / 10, 1 - i / 10],
+    }));
+    await call('upsert', { namespace, items });
+    const r3 = await call('query', { namespace, vector: [0.5, 0.5], topK: 3 });
+    const body = r3.json as { matches?: unknown[] };
+    expect(
+      Array.isArray(body.matches) && body.matches.length <= 3,
+      driver.describe('RFC 0018 §A.vectorStore', 'query MUST return at most topK matches'),
+    ).toBe(true);
+  });
+});

package/src/scenarios/webhook-receiver-adversarial.test.ts

@@ -0,0 +1,210 @@
+/**
+ * CF-5 close-out — receiver-side rejection contract per
+ * `spec/v1/webhooks.md` §"Signature recipe" + §"Replay-attack
+ * resistance". The companion to `webhook-signed-delivery.test.ts`
+ * (which verifies the FORWARD direction: host signs correctly) —
+ * this scenario verifies the REVERSE direction: a properly-
+ * implemented receiver MUST reject five named adversarial inputs.
+ *
+ * The reference receiver implementation lives at
+ * `conformance/src/lib/webhook-receiver.ts`. The SDK ships an
+ * identical-behavior `verifyWebhookSignature` helper across all
+ * three reference SDKs (SDK-3 close-out).
+ *
+ * Five adversarial cases:
+ *
+ *   1. Tampered body — host's HMAC is valid for body B; adversary
+ *      delivers body B'. Receiver MUST reject with
+ *      `signature_mismatch`.
+ *   2. Tampered HMAC — body is valid; adversary flips a byte of the
+ *      v1=<hex> signature. Receiver MUST reject with
+ *      `signature_mismatch`.
+ *   3. Stale timestamp — body + HMAC are valid but timestamp is
+ *      older than the default 5-minute window. Receiver MUST reject
+ *      with `timestamp_expired`.
+ *   4. Replayed signature — adversary resends a previously-accepted
+ *      delivery within the window. Receiver MUST reject with
+ *      `duplicate_signature`.
+ *   5. Wrong algorithm — host sends `algorithm: v2` (a future
+ *      version a v1-only receiver doesn't recognize). Receiver MUST
+ *      reject with `wrong_algorithm`.
+ *
+ * This scenario is purely receiver-side; it does NOT touch the host
+ * under test. It runs unconditionally (no capability gating).
+ *
+ * @see spec/v1/webhooks.md
+ * @see conformance/src/lib/webhook-receiver.ts
+ * @see sdk/typescript/src/webhook-helpers.ts
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  createReceiverState,
+  signPayload,
+  verifyWebhookDelivery,
+} from '../lib/webhook-receiver.js';
+
+describe('webhook-receiver-adversarial: receiver rejects five canonical attacks', () => {
+  const secret = 'test-secret-do-not-use-in-prod';
+  const body = JSON.stringify({ runId: 'r-conformance', type: 'run.completed' });
+  const nowSec = 1_715_775_600;
+  const ts = nowSec;
+
+  it('positive control: receiver accepts a freshly-signed valid delivery', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    const result = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(
+      result.accepted,
+      'webhooks.md §"Signature recipe": valid signature + fresh timestamp + correct algorithm MUST be accepted',
+    ).toBe(true);
+  });
+
+  it('case 1: tampered body → signature_mismatch', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    const tamperedBody = JSON.stringify({ runId: 'r-conformance', type: 'run.failed' });
+    const result = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      tamperedBody,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(
+        result.reason,
+        'webhooks.md §"Signature recipe": tampered body MUST be rejected with signature_mismatch',
+      ).toBe('signature_mismatch');
+    }
+  });
+
+  it('case 2: tampered HMAC → signature_mismatch', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    // Flip one hex character of the v1=<hex> signature.
+    const flipIndex = 5;
+    const orig = signatureHeader[flipIndex]!;
+    const replacement = orig === '0' ? '1' : '0';
+    const tampered = signatureHeader.slice(0, flipIndex) + replacement + signatureHeader.slice(flipIndex + 1);
+    const result = verifyWebhookDelivery(
+      secret,
+      tampered,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(result.reason).toBe('signature_mismatch');
+    }
+  });
+
+  it('case 3: stale timestamp → timestamp_expired', () => {
+    const state = createReceiverState();
+    const staleTs = nowSec - 10_000; // way past the 5-minute window
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, staleTs, body);
+    const result = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(
+        result.reason,
+        'webhooks.md §"Replay-attack resistance": timestamp older than freshness window MUST be rejected with timestamp_expired',
+      ).toBe('timestamp_expired');
+    }
+  });
+
+  it('case 4: replayed signature → duplicate_signature', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    // First delivery accepted.
+    const first = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(first.accepted).toBe(true);
+    // Replay — same signature, same body, same timestamp, still
+    // within the window.
+    const replay = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(replay.accepted).toBe(false);
+    if (!replay.accepted) {
+      expect(
+        replay.reason,
+        'webhooks.md §"Replay-attack resistance": replay of an already-accepted signature MUST be rejected with duplicate_signature',
+      ).toBe('duplicate_signature');
+    }
+  });
+
+  it('case 5: wrong algorithm → wrong_algorithm', () => {
+    const state = createReceiverState();
+    const { signatureHeader, timestampHeader } = signPayload(secret, ts, body);
+    const result = verifyWebhookDelivery(
+      secret,
+      signatureHeader,
+      'v2',
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(
+        result.reason,
+        'webhooks.md §"Signature algorithm versioning": algorithm other than v1 MUST be rejected with wrong_algorithm by a v1-only receiver',
+      ).toBe('wrong_algorithm');
+    }
+  });
+
+  it('case 6: malformed signature header → malformed_signature_header', () => {
+    const state = createReceiverState();
+    const { timestampHeader, algorithmHeader } = signPayload(secret, ts, body);
+    const result = verifyWebhookDelivery(
+      secret,
+      'not-a-canonical-header',
+      algorithmHeader,
+      timestampHeader,
+      body,
+      state,
+      { nowSeconds: nowSec },
+    );
+    expect(result.accepted).toBe(false);
+    if (!result.accepted) {
+      expect(result.reason).toBe('malformed_signature_header');
+    }
+  });
+});