@openwop/openwop-conformance 1.0.0 → 1.1.0

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

@@ -1,23 +1,33 @@
 /**
  * RFC 0008 §Conformance — scenario 5/6: memory cap enforcement.
  *
- * Verifies that a host enforces `capabilities.nodePackRuntimes.wasm.maxMemoryBytes`
- * by trapping (or otherwise terminating) a module that exceeds the cap
- * and emitting `cap.breached` with `kind: 'wasm-memory'`.
+ * Two-part scenario per RFCS/0008-wasm-abi.md §K (resource limits):
  *
- * The reference rust-hello pack is well-behaved and does not allocate
- * excessively, so this scenario is OBSERVATIONAL: it asserts the cap
- * is *declared* (the protocol requires it) and that if the host
- * advertises a value, the value is plausible.
+ *   1. **Discovery shape (observational, always-on)** — host advertises
+ *      `capabilities.nodePackRuntimes.wasm.maxMemoryBytes` as a plausible
+ *      integer when WASM is supported.
+ *   2. **Positive path (fixture-gated)** — when the deliberately-
+ *      misbehaving Rust pack at `examples/packs/rust-misbehaving-memory/`
+ *      is built and the host advertises the
+ *      `conformance-wasm-pack-memory-cap-breach` fixture, invoking the
+ *      `vendor.openwop.misbehaving.memory-bomb` typeId MUST emit
+ *      `cap.breached` with `kind: 'wasm-memory'` and drive the run to
+ *      terminal `failed`.
  *
- * Driving a real OOM requires a deliberately misbehaving pack. Such a
- * pack is filed as v1.x follow-up; the framework lives here.
+ * Until the misbehaving pack ships in a host's fixture set, the positive
+ * path soft-skips so the scenario stays green on hosts that haven't
+ * wired up the cap-emit behavior yet.
  *
  * @see RFCS/0008-wasm-abi.md §K (resource limits)
+ * @see schemas/run-event-payloads.schema.json §"capBreached" (kind enum includes wasm-memory)
  */
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+const CAP_BREACH_FIXTURE = 'conformance-wasm-pack-memory-cap-breach';
 
 describe('wasm-pack-memory-cap: host advertises maxMemoryBytes', () => {
   it('capabilities.nodePackRuntimes.wasm.maxMemoryBytes is a plausible number', async () => {
@@ -41,3 +51,48 @@ describe('wasm-pack-memory-cap: host advertises maxMemoryBytes', () => {
     }
   });
 });
+
+describe('wasm-pack-memory-cap: positive path via misbehaving pack', () => {
+  it('misbehaving pack triggers cap.breached with kind=wasm-memory and terminal failed', async () => {
+    if (!isFixtureAdvertised(CAP_BREACH_FIXTURE)) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[wasm-pack-memory-cap] fixture ${CAP_BREACH_FIXTURE} not advertised; skipping positive path. ` +
+          'Build the misbehaving pack at examples/packs/rust-misbehaving-memory/ and ensure the host serves the fixture.',
+      );
+      return;
+    }
+    const disco = await driver.get('/.well-known/openwop');
+    const wasm =
+      (disco.json as {
+        capabilities?: { nodePackRuntimes?: { wasm?: { supported?: boolean } } };
+      }).capabilities?.nodePackRuntimes?.wasm;
+    if (!wasm?.supported) return;
+
+    const create = await driver.post('/v1/runs', {
+      workflowId: CAP_BREACH_FIXTURE,
+      inputs: {},
+    });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+
+    const terminal = await pollUntilTerminal(runId, { timeoutMs: 15_000 });
+    expect(terminal.status, driver.describe(
+      'RFCS/0008-wasm-abi.md §K',
+      'WASM memory-cap breach MUST drive terminal `failed` (RFC 0008 §K: "kill the instance, emit cap.breached")',
+    )).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 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;
+    expect(breachKind, driver.describe(
+      'RFCS/0008-wasm-abi.md §K',
+      'cap.breached payload MUST carry kind: "wasm-memory" for memory-ceiling breaches',
+    )).toBe('wasm-memory');
+  });
+});

package/src/scenarios/webhook-negative.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Webhook negative-path contract (webhooks.md + review hardening).
+ *
+ * Exercises three failure surfaces that the positive `webhook-signed-
+ * delivery.test.ts` doesn't cover:
+ *   1. SSRF guard — `POST /v1/webhooks` with a private-IP destination
+ *      returns 400 `webhook_url_rejected` on hosts that enforce it.
+ *   2. URL validation — malformed `url` returns 400 `validation_error`.
+ *   3. Unregister of unknown subscription — `DELETE /v1/webhooks/{id}`
+ *      returns 404 `subscription_not_found`.
+ *
+ * Capability-gated: skips when the host does not advertise
+ * `capabilities.webhooks.supported = true`.
+ *
+ * SSRF gating: hosts that don't implement the guard (or bypass it via
+ * `OPENWOP_WEBHOOK_ALLOW_PRIVATE=true`) will accept the loopback URL
+ * with 201 — that's acceptable spec behavior, so the SSRF subtest
+ * soft-skips with a warning rather than failing.
+ *
+ * @see spec/v1/webhooks.md
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+async function isWebhookSupported(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  const caps = (disco.json as { capabilities?: { webhooks?: { supported?: boolean } } })
+    .capabilities;
+  return caps?.webhooks?.supported === true;
+}
+
+describe('webhook-negative: SSRF guard rejects private destinations', () => {
+  it('host with SSRF guard returns 400 webhook_url_rejected for loopback', async () => {
+    if (!(await isWebhookSupported())) {
+      // eslint-disable-next-line no-console
+      console.warn('[webhook-negative] host does not advertise webhook support; skipping');
+      return;
+    }
+    const reg = await driver.post('/v1/webhooks', { url: 'http://127.0.0.1:65535/' });
+    if (reg.status === 201) {
+      // Host accepted — SSRF guard not implemented or bypassed.
+      // Soft-skip; this is acceptable per spec.
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[webhook-negative] host accepts loopback destinations; SSRF guard not enforced',
+      );
+      // Cleanup the subscription so we don't leak state.
+      const body = reg.json as { subscriptionId?: string };
+      if (body.subscriptionId) {
+        await driver.delete(`/v1/webhooks/${encodeURIComponent(body.subscriptionId)}`);
+      }
+      return;
+    }
+    expect(reg.status, driver.describe(
+      'webhooks.md + review §"Webhook SSRF guard"',
+      'host with SSRF guard MUST return 400 for loopback / RFC1918 / link-local destinations',
+    )).toBe(400);
+    const body = reg.json as { error?: string };
+    expect(body.error).toBe('webhook_url_rejected');
+  });
+});
+
+describe('webhook-negative: validation errors', () => {
+  it('malformed url returns 400 validation_error', async () => {
+    if (!(await isWebhookSupported())) return;
+    const reg = await driver.post('/v1/webhooks', { url: 'not a url' });
+    expect([400, 422]).toContain(reg.status);
+    const body = reg.json as { error?: string };
+    expect(['validation_error', 'webhook_url_rejected']).toContain(body.error);
+  });
+
+  it('missing url returns 400 validation_error', async () => {
+    if (!(await isWebhookSupported())) return;
+    const reg = await driver.post('/v1/webhooks', { eventTypes: ['run.completed'] });
+    expect(reg.status).toBe(400);
+    const body = reg.json as { error?: string };
+    expect(body.error).toBe('validation_error');
+  });
+});
+
+describe('webhook-negative: unregister of unknown subscription', () => {
+  it('DELETE /v1/webhooks/{unknown} returns 404 subscription_not_found', async () => {
+    if (!(await isWebhookSupported())) return;
+    const del = await driver.delete('/v1/webhooks/wh-does-not-exist');
+    expect(del.status).toBe(404);
+    const body = del.json as { error?: string };
+    expect(body.error).toBe('subscription_not_found');
+  });
+});

package/src/scenarios/webhook-signed-delivery.test.ts

@@ -0,0 +1,178 @@
+/**
+ * End-to-end webhook signed-delivery scenario (webhooks.md).
+ *
+ * Boots a local HTTP receiver, registers it via
+ * `POST /v1/webhooks`, drives a run, and verifies that:
+ *   1. Delivery arrives at the receiver.
+ *   2. `X-openwop-Signature-Algorithm: v1` header is present.
+ *   3. `X-openwop-Signature` is a valid HMAC-SHA256 of
+ *      `${timestamp}.${rawBody}` under the subscription secret.
+ *   4. `X-openwop-Subscription-Id` matches the returned subscription id.
+ *
+ * Capability-gated: skips when the host does not advertise
+ * `capabilities.webhooks.supported = true`.
+ *
+ * Operator contract: hosts that implement a SSRF guard on
+ * `POST /v1/webhooks` (rejecting loopback / RFC1918 / link-local
+ * destinations to protect deployer infrastructure) MUST allow the test
+ * receiver. The SQLite reference host bypasses the guard when the
+ * `OPENWOP_WEBHOOK_ALLOW_PRIVATE=true` env var is set at boot. Test-only
+ * hosts SHOULD provide an equivalent opt-in. When the host rejects with
+ * `400 webhook_url_rejected`, this scenario skips with a warning.
+ *
+ * @see spec/v1/webhooks.md §"Signature scheme"
+ */
+
+import { afterEach, describe, expect, it } from 'vitest';
+import { createHmac } from 'node:crypto';
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { driver } from '../lib/driver.js';
+import { pollUntilTerminal } from '../lib/polling.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+interface DeliveredRequest {
+  readonly headers: Record<string, string>;
+  readonly body: string;
+}
+
+async function startReceiver(): Promise<{ server: Server; url: string; received: DeliveredRequest[] }> {
+  const received: DeliveredRequest[] = [];
+  const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c: Buffer) => chunks.push(c));
+    req.on('end', () => {
+      const body = Buffer.concat(chunks).toString('utf8');
+      const headers: Record<string, string> = {};
+      for (const [k, v] of Object.entries(req.headers)) {
+        if (typeof v === 'string') headers[k.toLowerCase()] = v;
+        else if (Array.isArray(v)) headers[k.toLowerCase()] = v.join(',');
+      }
+      received.push({ headers, body });
+      res.writeHead(204);
+      res.end();
+    });
+  });
+  await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', () => resolve()));
+  const addr = server.address();
+  if (typeof addr !== 'object' || addr === null) throw new Error('receiver address unavailable');
+  return { server, url: `http://127.0.0.1:${addr.port}/`, received };
+}
+
+let activeServer: Server | null = null;
+afterEach(async () => {
+  if (activeServer) {
+    await new Promise<void>((resolve) => activeServer!.close(() => resolve()));
+    activeServer = null;
+  }
+});
+
+async function isWebhookSupported(): Promise<boolean> {
+  const disco = await driver.get('/.well-known/openwop');
+  const caps = (disco.json as { capabilities?: { webhooks?: { supported?: boolean } } }).capabilities;
+  return caps?.webhooks?.supported === true;
+}
+
+describe('webhook-signed-delivery: end-to-end HMAC v1', () => {
+  it('host POSTs run events to subscriber with valid X-openwop-Signature', async () => {
+    if (!(await isWebhookSupported())) {
+      // eslint-disable-next-line no-console
+      console.warn('[webhook-signed-delivery] host does not advertise webhook support; skipping');
+      return;
+    }
+    if (!isFixtureAdvertised('conformance-noop')) {
+      // eslint-disable-next-line no-console
+      console.warn('[webhook-signed-delivery] conformance-noop not advertised; skipping');
+      return;
+    }
+
+    const receiver = await startReceiver();
+    activeServer = receiver.server;
+
+    // Register the webhook.
+    const reg = await driver.post('/v1/webhooks', { url: receiver.url });
+
+    // SSRF guard skip: if the host rejects loopback destinations,
+    // honor the operator contract and skip rather than fail.
+    if (reg.status === 400) {
+      const body = reg.json as { error?: string };
+      if (body.error === 'webhook_url_rejected') {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[webhook-signed-delivery] host SSRF guard rejected the loopback receiver; ' +
+            'set OPENWOP_WEBHOOK_ALLOW_PRIVATE=true on the host (or equivalent) to run',
+        );
+        return;
+      }
+    }
+
+    expect(reg.status, driver.describe(
+      'webhooks.md §"Register"',
+      'POST /v1/webhooks MUST return 201 with subscriptionId + secret on success',
+    )).toBe(201);
+    const sub = reg.json as { subscriptionId: string; secret: string };
+    expect(typeof sub.subscriptionId).toBe('string');
+    expect(typeof sub.secret).toBe('string');
+    expect(sub.secret.length).toBeGreaterThan(0);
+
+    // Drive a run; the host MUST deliver events to the registered receiver.
+    const create = await driver.post('/v1/runs', { workflowId: 'conformance-noop' });
+    expect(create.status).toBe(201);
+    const runId = (create.json as { runId: string }).runId;
+    await pollUntilTerminal(runId, { timeoutMs: 10_000 });
+
+    // Allow a small grace period for fire-and-forget delivery to land.
+    await new Promise((resolve) => setTimeout(resolve, 500));
+
+    // Test-isolation note: when this scenario runs concurrently with
+    // other webhook-bearing scenarios against a stateful host, the
+    // host's webhook registry fans out EVERY run's events to EVERY
+    // registered subscription. Receivers in this scenario MAY observe
+    // deliveries from other tests' concurrent runs. Filter to events
+    // carrying THIS test's runId so the assertion checks the
+    // signature shape on a delivery the host emitted for THIS run.
+    const ourDeliveries = receiver.received.filter((d) => {
+      try {
+        const body = JSON.parse(d.body) as { runId?: unknown };
+        return body.runId === runId;
+      } catch {
+        return false;
+      }
+    });
+    expect(ourDeliveries.length, driver.describe(
+      'webhooks.md §"Delivery"',
+      'host MUST POST at least one event for THIS run to a registered subscriber after run.completed',
+    )).toBeGreaterThan(0);
+
+    // Validate the FIRST delivery's signature contract. Other deliveries
+    // share the same signing rules; checking one is sufficient.
+    const first = ourDeliveries[0]!;
+    expect(first.headers['x-openwop-signature-algorithm'], driver.describe(
+      'webhooks.md §"Signature algorithm versioning"',
+      'every delivery MUST set X-openwop-Signature-Algorithm: v1',
+    )).toBe('v1');
+    expect(first.headers['x-openwop-subscription-id']).toBe(sub.subscriptionId);
+
+    const timestamp = first.headers['x-openwop-signature-timestamp'];
+    expect(typeof timestamp).toBe('string');
+    expect((timestamp ?? '').length).toBeGreaterThan(0);
+
+    const signature = first.headers['x-openwop-signature'];
+    const expected = createHmac('sha256', sub.secret)
+      .update(`${timestamp}.${first.body}`, 'utf8')
+      .digest('hex');
+    expect(signature, driver.describe(
+      'webhooks.md §"Signature scheme"',
+      'X-openwop-Signature MUST be HMAC-SHA256(secret, `${timestamp}.${rawBody}`) hex',
+    )).toBe(expected);
+
+    // Body should parse as JSON with a run event shape.
+    const event = JSON.parse(first.body) as { type?: unknown; runId?: unknown };
+    expect(typeof event.type).toBe('string');
+    expect(event.runId).toBe(runId);
+
+    // Cleanup: unregister.
+    const del = await driver.delete(`/v1/webhooks/${encodeURIComponent(sub.subscriptionId)}`);
+    expect(del.status).toBeGreaterThanOrEqual(200);
+    expect(del.status).toBeLessThan(300);
+  });
+});

package/src/setup.ts

@@ -117,6 +117,30 @@ async function maybeStartOtelCollector(): Promise<void> {
       `Configure the host with OTEL_EXPORTER_OTLP_ENDPOINT=${collector.endpoint()} ` +
       `and OTEL_EXPORTER_OTLP_PROTOCOL=http/json.`,
   );
+
+  // Track 11 — opt into the parallel OTLP/gRPC collector when
+  // `OPENWOP_OTEL_COLLECTOR_GRPC=true`. Same span/metric store; hosts
+  // emitting via either transport surface in `getCollector().spans()`.
+  if (process.env.OPENWOP_OTEL_COLLECTOR_GRPC === 'true') {
+    const grpcPortEnv = process.env.OPENWOP_OTEL_COLLECTOR_GRPC_PORT;
+    const grpcRequestedPort = grpcPortEnv ? Number(grpcPortEnv) : 4317;
+    try {
+      await collector.startGrpc(grpcRequestedPort);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[openwop-conformance setup] OTLP/gRPC collector failed to bind on port ${grpcRequestedPort} ` +
+          `(${(err as Error).message ?? 'unknown'}); falling back to ephemeral port.`,
+      );
+      await collector.startGrpc(0);
+    }
+    // eslint-disable-next-line no-console
+    console.error(
+      `[openwop-conformance setup] OTLP/gRPC collector listening at ${collector.grpcEndpoint()}. ` +
+        `Configure the host with OTEL_EXPORTER_OTLP_ENDPOINT=${collector.grpcEndpoint()} ` +
+        `and OTEL_EXPORTER_OTLP_PROTOCOL=grpc.`,
+    );
+  }
 }
 
 /**
@@ -163,7 +187,7 @@ async function maybeStartA2AFakePeer(): Promise<void> {
   // eslint-disable-next-line no-console
   console.error(
     `[openwop-conformance setup] A2A fake peer listening at ${peer.endpoint()}. ` +
-      `AgentCard at ${peer.endpoint()}/agent.json.`,
+      `AgentCard at ${peer.endpoint()}/.well-known/agent-card.json.`,
   );
 }
 

package/vitest.config.ts

@@ -2,7 +2,11 @@ import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
   test: {
-    include: ['src/scenarios/**/*.test.ts'],
+    // `src/scenarios/**/*.test.ts` are the host-targeted conformance
+    // scenarios; `src/lib/**/*.test.ts` are server-free unit tests for
+    // suite-internal helpers (e.g., the synthetic OIDC issuer harness)
+    // that don't depend on OPENWOP_BASE_URL.
+    include: ['src/scenarios/**/*.test.ts', 'src/lib/**/*.test.ts'],
     testTimeout: 30_000,
     hookTimeout: 30_000,
     globals: true,