@openwop/openwop-conformance 1.0.0

package/src/lib/a2a-fake-peer.ts

@@ -0,0 +1,233 @@
+/**
+ * Track 6: in-process synthetic A2A peer for state-projection conformance.
+ *
+ * The A2A protocol (https://a2a-protocol.org/) defines an `AgentCard` for
+ * discovery plus a Task lifecycle whose `TaskState` enum drives most of
+ * the conformance burden. We expose just enough of the HTTP+JSON
+ * transport to let conformance scenarios drive the host through the
+ * four documented drift points from `spec/v1/a2a-integration.md`
+ * §"State projection".
+ *
+ * Endpoints (minimal):
+ *   GET  /agent.json                 — AgentCard
+ *   POST /tasks                      — create a task; returns { taskId, state: 'SUBMITTED' }
+ *   GET  /tasks/{taskId}             — poll task state + last message
+ *   POST /tasks/{taskId}/messages    — append a message (used by host to resume an INPUT_REQUIRED task)
+ *
+ * Test fixtures set the *next* state transition via `setNextState(...)`
+ * so a single scenario can walk the peer through SUBMITTED → WORKING →
+ * INPUT_REQUIRED → COMPLETED (or AUTH_REQUIRED, or REJECTED) without
+ * implementing a real agent.
+ *
+ * @see spec/v1/a2a-integration.md §"State projection"
+ * @see https://a2a-protocol.org/latest/specification/
+ */
+
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+export type A2ATaskState =
+  | 'UNSPECIFIED'
+  | 'SUBMITTED'
+  | 'WORKING'
+  | 'INPUT_REQUIRED'
+  | 'AUTH_REQUIRED'
+  | 'COMPLETED'
+  | 'FAILED'
+  | 'CANCELED'
+  | 'REJECTED';
+
+interface A2ATask {
+  taskId: string;
+  state: A2ATaskState;
+  messages: Array<{ role: 'user' | 'agent'; content: unknown }>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface A2APeerInvocation {
+  readonly method: string;
+  readonly path: string;
+  readonly body: unknown;
+  readonly timestamp: number;
+}
+
+export class A2AFakePeer {
+  private _server: Server | null = null;
+  private _boundPort = 0;
+  private readonly _tasks = new Map<string, A2ATask>();
+  private readonly _invocations: A2APeerInvocation[] = [];
+  private _nextStateOverride: A2ATaskState | null = null;
+  private _taskIdCounter = 0;
+
+  async start(port: number = 0): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const server = createServer((req, res) => this._handle(req, res));
+      server.on('error', reject);
+      server.listen(port, '127.0.0.1', () => {
+        const addr = server.address() as AddressInfo;
+        this._server = server;
+        this._boundPort = addr.port;
+        resolve();
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (!this._server) return;
+    const server = this._server;
+    this._server = null;
+    return new Promise((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  endpoint(): string {
+    return `http://127.0.0.1:${this._boundPort}`;
+  }
+
+  reset(): void {
+    this._tasks.clear();
+    this._invocations.length = 0;
+    this._nextStateOverride = null;
+    this._taskIdCounter = 0;
+  }
+
+  invocations(): readonly A2APeerInvocation[] {
+    return this._invocations;
+  }
+
+  taskCount(): number {
+    return this._tasks.size;
+  }
+
+  /**
+   * Force the next task created to immediately transition to this state.
+   * Used by drift-point scenarios to drive AUTH_REQUIRED / REJECTED /
+   * INPUT_REQUIRED paths deterministically.
+   */
+  setNextState(state: A2ATaskState | null): void {
+    this._nextStateOverride = state;
+  }
+
+  /** Advance an existing task to a new state. Used by host-mediated tests. */
+  advanceTask(taskId: string, state: A2ATaskState): boolean {
+    const task = this._tasks.get(taskId);
+    if (!task) return false;
+    task.state = state;
+    return true;
+  }
+
+  getTask(taskId: string): Readonly<A2ATask> | undefined {
+    return this._tasks.get(taskId);
+  }
+
+  private async _handle(
+    req: import('node:http').IncomingMessage,
+    res: import('node:http').ServerResponse,
+  ): Promise<void> {
+    const url = req.url ?? '/';
+    const chunks: Buffer[] = [];
+    for await (const c of req) chunks.push(c as Buffer);
+    const bodyText = Buffer.concat(chunks).toString('utf8');
+    let body: unknown = null;
+    if (bodyText.length > 0) {
+      try {
+        body = JSON.parse(bodyText);
+      } catch {
+        body = bodyText;
+      }
+    }
+
+    this._invocations.push({
+      method: req.method ?? 'GET',
+      path: url,
+      body,
+      timestamp: Date.now(),
+    });
+
+    // GET /agent.json
+    if (req.method === 'GET' && url.startsWith('/agent.json')) {
+      const card = {
+        protocolVersion: '0.3.0',
+        name: 'openwop-conformance-fake-a2a',
+        description: 'Synthetic A2A peer for openwop conformance suite',
+        url: this.endpoint(),
+        version: '1.0.0',
+        capabilities: { streaming: false },
+        skills: [
+          {
+            id: 'echo',
+            name: 'echo',
+            description: 'Returns input verbatim',
+          },
+        ],
+      };
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(card));
+      return;
+    }
+
+    // POST /tasks — create task
+    if (req.method === 'POST' && url === '/tasks') {
+      const taskId = `task-${++this._taskIdCounter}`;
+      const initial: A2ATaskState = this._nextStateOverride ?? 'SUBMITTED';
+      this._nextStateOverride = null;
+      const task: A2ATask = {
+        taskId,
+        state: initial,
+        messages: body && typeof body === 'object' ? [{ role: 'user', content: body }] : [],
+      };
+      this._tasks.set(taskId, task);
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ taskId, state: task.state }));
+      return;
+    }
+
+    // GET /tasks/{taskId}
+    const getMatch = url.match(/^\/tasks\/([^/?]+)$/);
+    if (req.method === 'GET' && getMatch) {
+      const task = this._tasks.get(decodeURIComponent(getMatch[1]));
+      if (!task) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'not_found' }));
+        return;
+      }
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(task));
+      return;
+    }
+
+    // POST /tasks/{taskId}/messages — host resumes an INPUT_REQUIRED task
+    const msgMatch = url.match(/^\/tasks\/([^/?]+)\/messages$/);
+    if (req.method === 'POST' && msgMatch) {
+      const task = this._tasks.get(decodeURIComponent(msgMatch[1]));
+      if (!task) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'not_found' }));
+        return;
+      }
+      task.messages.push({ role: 'user', content: body });
+      // Move from INPUT_REQUIRED back to WORKING then to COMPLETED for the
+      // simple roundtrip. Tests that need a different next-state set it
+      // via setNextState() before posting the message.
+      task.state = this._nextStateOverride ?? 'COMPLETED';
+      this._nextStateOverride = null;
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ taskId: task.taskId, state: task.state }));
+      return;
+    }
+
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'not_found' }));
+  }
+}
+
+let _instance: A2AFakePeer | null = null;
+
+export function setA2AFakePeer(p: A2AFakePeer | null): void {
+  _instance = p;
+}
+
+export function getA2AFakePeer(): A2AFakePeer | null {
+  return _instance;
+}

package/src/lib/canaries.ts

@@ -0,0 +1,186 @@
+/**
+ * Vendor-neutral canary fixtures + leak detector for redaction
+ * conformance scenarios.
+ *
+ * This is the spec-side companion to host-specific redaction harnesses.
+ * Hosts running `@openwop/openwop-conformance` get vendor-neutral assertions that
+ * their server doesn't leak secrets in observable surfaces — without
+ * pulling in any host-specific code.
+ *
+ * **Why this is here:** spec rule NFR-7 (`capabilities.md` §"Secrets")
+ * — any code path that emits a `RunEvent`, OTel span, log line, error
+ * message, or exported artifact MUST NOT contain raw key material. The
+ * conformance suite needs to verify this against the live HTTP surface
+ * of any OpenWOP-compliant server.
+ *
+ * Canary values are built via runtime string concatenation, NOT as
+ * contiguous string literals, so static-analysis secret scanners
+ * (TruffleHog, gitleaks) don't flag this file. The runtime-assembled
+ * strings have the exact same shape that real-world keys do.
+ *
+ * @see capabilities.md §"Secrets" + NFR-7
+ * @see scenarios/redaction.test.ts
+ */
+
+/** Stable marker substring present in every canary. Detector finds it
+ *  unambiguously; anyone reading a leaked log line sees this and knows
+ *  it's a test fixture, not a real key. */
+export const CANARY_MARKER = 'CANARY-openwop-CONFORMANCE-NEVER-SECRET';
+
+/**
+ * Build a canary value by concatenating an obvious-prefix shape with
+ * the marker + a deterministic body. Pure; same args always return
+ * the same string. Runtime concat exists purely to defeat static
+ * secret-scanners.
+ */
+function buildCanary(prefix: string, body: string): string {
+  return prefix + CANARY_MARKER + '-' + body;
+}
+
+/** Tagged canary value. Opaque so callers can't accidentally treat a
+ *  canary as a generic string. */
+export interface Canary {
+  /** Provider/format label (e.g., "openai", "jwt-bearer"). */
+  readonly label: string;
+  /** The synthetic key/token string. Carries the marker. */
+  readonly value: string;
+}
+
+/**
+ * The canonical canary set. Each value matches the regex shape of a
+ * common provider key but contains the unique marker substring so
+ * leaks are unambiguously identifiable. Real production secrets do
+ * NOT contain this marker, eliminating false positives.
+ *
+ * Format references (rough — server-side regex redactors should not
+ * rely on exact length, only on prefix shape):
+ *   - OpenAI: `sk-...` or `sk-proj-...`
+ *   - Anthropic: `sk-ant-...`
+ *   - Google API key: `AIza...`
+ *   - JWT: `base64url.base64url.base64url`
+ *   - Opaque BYOK secret IDs: vendor-defined
+ */
+export const CANARIES: readonly Canary[] = [
+  { label: 'openai', value: buildCanary('sk-', 'oai9Lt7Nw2QrZ0aB8mYjPpQe') },
+  {
+    label: 'anthropic',
+    value: buildCanary('sk-' + 'ant-', 'ant3Ko0LqFqzv9Sb1J7mNcR'),
+  },
+  {
+    label: 'google',
+    value: 'AIza' + CANARY_MARKER + 'Goog12345abcdef9876',
+  },
+  {
+    label: 'jwt-bearer',
+    value:
+      'eyJhbGciOiJIUzI1NiJ9.' +
+      'eyJjYW5hcnkiOnRydWV9.' +
+      CANARY_MARKER +
+      '-jwt-signature-xyz',
+  },
+  {
+    label: 'byok-credential-ref',
+    value: buildCanary('cred_', 'OpaqueRefAlphaNumX9Y8Z7'),
+  },
+] as const;
+
+/**
+ * A single leak occurrence — what was leaked + roughly where in the
+ * captured surface it appeared.
+ */
+export interface CanaryLeak {
+  readonly label: string;
+  readonly value: string;
+  /** First match position in the captured text. */
+  readonly position: number;
+}
+
+/**
+ * Search a captured surface (response body, header value, etc.) for
+ * any canary value or the canary marker. Returns one entry per leak.
+ *
+ * Implementation: exact substring match against each canary value,
+ * plus a separate scan for the marker so partial leaks (e.g., a
+ * server-side substring extraction) still trip the detector.
+ */
+export function findCanaryLeaks(text: string): readonly CanaryLeak[] {
+  const leaks: CanaryLeak[] = [];
+
+  // Pass 1 — exact canary value matches.
+  for (const c of CANARIES) {
+    const pos = text.indexOf(c.value);
+    if (pos !== -1) {
+      leaks.push({ label: c.label, value: c.value, position: pos });
+    }
+  }
+
+  // Pass 2 — marker-only fallback. Skip positions inside an already-
+  // matched exact canary range (avoid double-counting).
+  let scanFrom = 0;
+  while (scanFrom < text.length) {
+    const pos = text.indexOf(CANARY_MARKER, scanFrom);
+    if (pos === -1) break;
+    const within = leaks.some(
+      (l) => l.position <= pos && pos < l.position + l.value.length,
+    );
+    if (!within) {
+      leaks.push({
+        label: 'marker-only',
+        value: CANARY_MARKER,
+        position: pos,
+      });
+    }
+    scanFrom = pos + CANARY_MARKER.length;
+  }
+
+  return leaks;
+}
+
+/** Pick a canary by label. Throws if not found. */
+export function getCanary(label: string): Canary {
+  const c = CANARIES.find((x) => x.label === label);
+  if (!c) throw new Error(`Unknown canary label: ${label}`);
+  return c;
+}
+
+/**
+ * Stringify a captured value (HTTP response, JSON body, etc.) to a
+ * single string the detector can scan. Idempotent for strings; deep-
+ * stringifies objects + arrays.
+ */
+export function captureToText(captured: unknown): string {
+  if (typeof captured === 'string') return captured;
+  try {
+    return JSON.stringify(captured);
+  } catch {
+    return String(captured);
+  }
+}
+
+/**
+ * Throw a descriptive error if any canary appears in the captured
+ * text. For use in conformance assertions.
+ */
+export function assertNoCanaryLeak(
+  capturedText: string,
+  surfaceLabel: string,
+): void {
+  const leaks = findCanaryLeaks(capturedText);
+  if (leaks.length === 0) return;
+
+  const details = leaks
+    .map((l) => {
+      const start = Math.max(0, l.position - 32);
+      const end = Math.min(capturedText.length, l.position + l.value.length + 32);
+      const excerpt = capturedText.slice(start, end);
+      return `  - [${l.label}] @${l.position}: ...${excerpt}...`;
+    })
+    .join('\n');
+
+  throw new Error(
+    `Canary leak detected in surface "${surfaceLabel}":\n${details}\n\n` +
+      `Per capabilities.md §"Secrets" + NFR-7, this surface MUST NOT ` +
+      `echo back canary content. Either redact at the emission boundary ` +
+      `or document the surface as out-of-scope for redaction obligations.`,
+  );
+}

package/src/lib/driver.ts

@@ -0,0 +1,96 @@
+/**
+ * OpenWOPDriver — thin HTTP client wrapper used by all conformance scenarios.
+ *
+ * Why a wrapper rather than raw fetch in every test:
+ *   1. Auth header is applied once.
+ *   2. URL composition is consistent (base + path).
+ *   3. Failure messages cite the implementation name + version so log
+ *      output identifies the server under test.
+ *   4. JSON decoding errors are surfaced with the raw body for debug.
+ */
+
+import { loadEnv } from './env.js';
+
+export interface OpenWOPResponse {
+  readonly status: number;
+  readonly headers: Headers;
+  readonly text: string;
+  readonly json: unknown;
+}
+
+export interface OpenWOPRequestInit {
+  readonly headers?: Record<string, string>;
+  readonly body?: unknown;
+  readonly authenticated?: boolean;
+}
+
+class OpenWOPDriver {
+  /**
+   * Issue a request and return the decoded body. JSON decode is best-effort —
+   * `json` is `undefined` if the response wasn't JSON.
+   */
+  async request(
+    method: string,
+    path: string,
+    init: OpenWOPRequestInit = {},
+  ): Promise<OpenWOPResponse> {
+    const env = loadEnv();
+    const url = `${env.baseUrl}${path}`;
+
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      ...(init.headers ?? {}),
+    };
+    if (init.body !== undefined && headers['Content-Type'] === undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+    if (init.authenticated !== false) {
+      headers.Authorization = `Bearer ${env.apiKey}`;
+    }
+
+    const fetchInit: RequestInit = { method, headers };
+    if (init.body !== undefined) {
+      fetchInit.body = JSON.stringify(init.body);
+    }
+    const res = await fetch(url, fetchInit);
+
+    const text = await res.text();
+    let json: unknown;
+    try {
+      json = text.length > 0 ? JSON.parse(text) : undefined;
+    } catch {
+      json = undefined;
+    }
+
+    return {
+      status: res.status,
+      headers: res.headers,
+      text,
+      json,
+    };
+  }
+
+  get(path: string, init: OpenWOPRequestInit = {}): Promise<OpenWOPResponse> {
+    return this.request('GET', path, init);
+  }
+
+  post(path: string, body: unknown, init: OpenWOPRequestInit = {}): Promise<OpenWOPResponse> {
+    return this.request('POST', path, { ...init, body });
+  }
+
+  delete(path: string, init: OpenWOPRequestInit = {}): Promise<OpenWOPResponse> {
+    return this.request('DELETE', path, init);
+  }
+
+  /**
+   * Compose a "spec failure" message that cites the implementation under
+   * test plus the spec section that requires the assertion. Use as the
+   * second argument to `expect(...).toBe(..., msg)`-style assertions.
+   */
+  describe(specSection: string, requirement: string): string {
+    const env = loadEnv();
+    return `[${env.implementationName}@${env.implementationVersion}] ${specSection}: ${requirement}`;
+  }
+}
+
+export const driver = new OpenWOPDriver();

package/src/lib/env.ts

@@ -0,0 +1,49 @@
+/**
+ * Env-var validation for the openwop conformance suite.
+ *
+ * Required:
+ *   OPENWOP_BASE_URL — the server root, e.g., https://api.example.com
+ *   OPENWOP_API_KEY  — credential for runs:read / manifest:read scopes
+ *
+ * Optional (cosmetic — surfaced in failure messages):
+ *   OPENWOP_IMPLEMENTATION_NAME    — e.g., "acme-openwop-server"
+ *   OPENWOP_IMPLEMENTATION_VERSION — e.g., "1.0"
+ */
+
+export interface ConformanceEnv {
+  readonly baseUrl: string;
+  readonly apiKey: string;
+  readonly implementationName: string;
+  readonly implementationVersion: string;
+}
+
+let cached: ConformanceEnv | null = null;
+
+export function loadEnv(): ConformanceEnv {
+  if (cached) return cached;
+
+  const baseUrl = process.env.OPENWOP_BASE_URL?.trim();
+  const apiKey = process.env.OPENWOP_API_KEY?.trim();
+
+  if (!baseUrl) {
+    throw new Error(
+      'OPENWOP_BASE_URL env var is required. Example: OPENWOP_BASE_URL=https://api.example.com',
+    );
+  }
+  if (!apiKey) {
+    throw new Error(
+      'OPENWOP_API_KEY env var is required. See auth.md for credential format.',
+    );
+  }
+
+  // Strip trailing slash so URL composition is consistent.
+  const normalizedBase = baseUrl.replace(/\/$/, '');
+
+  cached = {
+    baseUrl: normalizedBase,
+    apiKey,
+    implementationName: process.env.OPENWOP_IMPLEMENTATION_NAME?.trim() ?? 'unknown',
+    implementationVersion: process.env.OPENWOP_IMPLEMENTATION_VERSION?.trim() ?? 'unknown',
+  };
+  return cached;
+}

package/src/lib/fixtures.ts

@@ -0,0 +1,93 @@
+/**
+ * Fixture-gating helper (RFC 0003).
+ *
+ * Reads the host's `/.well-known/openwop` `fixtures` array at suite init,
+ * caches the advertised fixture-id set, and exposes a sync predicate
+ * (`isFixtureAdvertised`) so each scenario can gate with
+ * `it.skipIf(!isFixtureAdvertised('conformance-noop'))`.
+ *
+ * Why a separate module from `profiles.ts`:
+ *   - Profiles answer "does the host claim this surface?" (binary).
+ *   - Fixtures answer "did the host claim THIS specific fixture id?"
+ *     (per-id). Different shape; profile-style derivation can't carry it.
+ *
+ * Cache lifecycle:
+ *   - `setAdvertisedFixtures(...)` populates the cache from a discovery
+ *     payload. Idempotent — calling repeatedly with the same payload is
+ *     a no-op. Calling with a different payload replaces the cache.
+ *   - `isFixtureAdvertised(...)` returns false until the cache is set
+ *     (defensive default — when the cache hasn't loaded yet, scenarios
+ *     skip rather than fail). The setupFile populates it before any
+ *     `describe()` runs.
+ *   - `getAdvertisedFixtures()` returns the cached set or null. Used by
+ *     `discovery.test.ts` to assert the field shape end-to-end.
+ *   - `__resetForTests()` clears the cache for unit tests of this module.
+ *
+ * This module is sync. The async fetch lives in `setup.ts` which calls
+ * `setAdvertisedFixtures(...)` from a top-level `await`.
+ *
+ * @see spec/v1/capabilities.md §`fixtures`
+ * @see spec/v1/profiles.md §`openwop-fixtures`
+ * @see RFCS/0003-fixture-gating.md
+ */
+
+import type { DiscoveryPayload } from './profiles.js';
+
+let _advertisedFixtures: ReadonlySet<string> | null = null;
+
+/**
+ * Populate the cache from a discovery-doc payload. The function is
+ * tolerant of malformed inputs — anything other than a string array
+ * collapses to "no fixtures advertised" rather than throwing, so the
+ * suite remains resilient against host bugs in the discovery surface.
+ */
+export function setAdvertisedFixtures(c: DiscoveryPayload | null | undefined): void {
+  if (c == null || !Array.isArray(c.fixtures)) {
+    _advertisedFixtures = new Set();
+    return;
+  }
+  const ids = c.fixtures.filter(
+    (entry): entry is string => typeof entry === 'string' && entry.length > 0,
+  );
+  _advertisedFixtures = new Set(ids);
+}
+
+/**
+ * Sync predicate — returns true if the host advertised the given
+ * fixture id. Returns false until `setAdvertisedFixtures(...)` has been
+ * called (i.e., before the suite-init setup file populates the cache).
+ *
+ * Use as the predicate inside `it.skipIf(...)` / `describe.skipIf(...)`.
+ * Example:
+ *
+ *   describe.skipIf(!isFixtureAdvertised('conformance-noop'))(
+ *     'runs-lifecycle: ...',
+ *     () => { it('...', async () => { ... }); },
+ *   );
+ */
+export function isFixtureAdvertised(id: string): boolean {
+  return _advertisedFixtures?.has(id) ?? false;
+}
+
+/**
+ * Returns the cached set or `null` if `setAdvertisedFixtures(...)` has
+ * not been called. Used by `discovery.test.ts` and consumers that need
+ * the full advertised set.
+ */
+export function getAdvertisedFixtures(): ReadonlySet<string> | null {
+  return _advertisedFixtures;
+}
+
+/**
+ * `true` once the suite-init setup has populated the cache (even with
+ * an empty set). Useful for distinguishing "host advertises no
+ * fixtures" from "we haven't called setAdvertisedFixtures yet."
+ */
+export function isFixtureCacheReady(): boolean {
+  return _advertisedFixtures !== null;
+}
+
+/** Test-only: reset the module-level cache. */
+export function __resetForTests(): void {
+  _advertisedFixtures = null;
+}