@openwop/openwop-conformance 1.0.0 → 1.1.1

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,