@openwop/openwop-conformance 1.0.0 → 1.1.0

package/src/scenarios/a2a-task-roundtrip.test.ts

@@ -11,19 +11,28 @@
  *
  * Two layers:
  *
- *   - **Direct fake-peer probe** (always when peer started): walks the
- *     fake peer through SUBMITTED → WORKING → INPUT_REQUIRED → COMPLETED
- *     and asserts the AgentCard + task lifecycle wire shape.
+ *   - **Direct peer probe** (always when an A2A endpoint is configured):
+ *     walks the fake peer through SUBMITTED → WORKING → COMPLETED and
+ *     asserts the AgentCard + task lifecycle wire shape. With
+ *     `OPENWOP_A2A_REAL_PEER_URL` set, points at a real reference A2A
+ *     peer with relaxed shape-only assertions.
  *   - **Host-mediated reverse-projection** (gated on fixture
  *     advertisement): when the host advertises
  *     `conformance-a2a-task-roundtrip`, run it against the fake peer
  *     forced into AUTH_REQUIRED / REJECTED to verify the host applies
- *     the documented projections.
+ *     the documented projections. **Real-peer mode does NOT exercise
+ *     drift points** — real peers don't expose a state-forcing API,
+ *     so these subtests stay fake-only.
  *
- * Operator contract: `OPENWOP_A2A_FAKE_PEER=true` on suite side; configure
- * the host to use the printed AgentCard URL.
+ * Operator contract:
+ *   - `OPENWOP_A2A_FAKE_PEER=true` — boots the in-process synthetic
+ *     peer. Asserts the deterministic echo skill + drift-point states.
+ *   - `OPENWOP_A2A_REAL_PEER_URL=<base-url>` — points the direct probe
+ *     at a real A2A reference implementation. Drift-point subtests
+ *     soft-skip in this mode. Phase 3 T3.4 interop-evidence path.
  *
  * @see spec/v1/a2a-integration.md §"State projection"
+ * @see docs/PROTOCOL-GAP-CLOSURE-PLAN.md Phase 3 T3.4
  */
 
 import { describe, it, expect } from 'vitest';
@@ -34,39 +43,149 @@ import { pollUntilTerminal, pollUntilStatus } from '../lib/polling.js';
 
 const ROUNDTRIP_FIXTURE = 'conformance-a2a-task-roundtrip';
 
+/** Resolve the A2A endpoint to probe: real-peer env wins; otherwise the in-process fake. */
+function probePeer(): { url: string; isReal: boolean } | null {
+  const real = process.env.OPENWOP_A2A_REAL_PEER_URL;
+  if (real && real.length > 0) return { url: real.replace(/\/$/, ''), isReal: true };
+  const fake = getA2AFakePeer();
+  if (fake) return { url: fake.endpoint(), isReal: false };
+  return null;
+}
+
+/**
+ * POST a JSON-RPC 2.0 envelope at `endpoint` and return the parsed
+ * response. Throws if the envelope is malformed; surfaces JSON-RPC
+ * error responses as a `{error}` field per spec so callers can assert
+ * on them.
+ */
+async function rpc(
+  endpoint: string,
+  method: string,
+  params: unknown,
+  id: number,
+): Promise<{
+  status: number;
+  result?: Record<string, unknown>;
+  error?: { code: number; message: string };
+}> {
+  const res = await fetch(endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({ jsonrpc: '2.0', id, method, params }),
+  });
+  const body = (await res.json()) as {
+    result?: Record<string, unknown>;
+    error?: { code: number; message: string };
+  };
+  const out: {
+    status: number;
+    result?: Record<string, unknown>;
+    error?: { code: number; message: string };
+  } = { status: res.status };
+  if (body.result !== undefined) out.result = body.result;
+  if (body.error !== undefined) out.error = body.error;
+  return out;
+}
+
 describe('a2a-task-roundtrip: AgentCard + task lifecycle', () => {
-  it('AgentCard exposes protocolVersion + skills; task SUBMITTED → COMPLETED', async () => {
-    const peer = getA2AFakePeer();
-    if (!peer) {
+  it('AgentCard exposes protocolVersion + skills; message/send + tasks/get round-trip per A2A v0.3 JSON-RPC', async () => {
+    const probe = probePeer();
+    if (!probe) {
       // eslint-disable-next-line no-console
-      console.warn('[a2a-task-roundtrip] peer not started; set OPENWOP_A2A_FAKE_PEER=true');
+      console.warn(
+        '[a2a-task-roundtrip] no A2A endpoint configured; set OPENWOP_A2A_FAKE_PEER=true ' +
+          'or OPENWOP_A2A_REAL_PEER_URL=<base-url>',
+      );
       return;
     }
-    peer.reset();
+    if (!probe.isReal) getA2AFakePeer()!.reset();
 
-    // AgentCard fetch.
-    const card = await fetch(`${peer.endpoint()}/agent.json`);
+    // AgentCard at the A2A v0.3 well-known path
+    // (`AGENT_CARD_PATH` from @a2a-js/sdk: `.well-known/agent-card.json`).
+    const card = await fetch(`${probe.url}/.well-known/agent-card.json`);
     expect(card.status).toBe(200);
-    const cardJson = (await card.json()) as { protocolVersion?: string; skills?: unknown[] };
+    const cardJson = (await card.json()) as {
+      protocolVersion?: string;
+      skills?: ReadonlyArray<{ id?: string; name?: string }>;
+      url?: string;
+      additionalInterfaces?: ReadonlyArray<{ url?: string; transport?: string }>;
+    };
     expect(typeof cardJson.protocolVersion).toBe('string');
     expect(Array.isArray(cardJson.skills)).toBe(true);
+    expect((cardJson.skills ?? []).length).toBeGreaterThan(0);
 
-    // Create + poll a task.
-    const create = await fetch(`${peer.endpoint()}/tasks`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ skill: 'echo', input: { text: 'hello' } }),
-    });
-    expect(create.status).toBe(200);
-    const { taskId } = (await create.json()) as { taskId: string; state: string };
+    // Find the JSON-RPC transport endpoint. A2A v0.3 hosts MAY advertise
+    // multiple transports via `additionalInterfaces`; we pick the first
+    // JSONRPC entry, falling back to `card.url`.
+    const jsonrpcIface = (cardJson.additionalInterfaces ?? []).find(
+      (i) => i.transport === 'JSONRPC',
+    );
+    const rpcUrl = jsonrpcIface?.url ?? cardJson.url ?? `${probe.url}/a2a/jsonrpc`;
+    expect(typeof rpcUrl).toBe('string');
+
+    if (probe.isReal) {
+      // Real-peer interop evidence (Phase 3 T3.4). A2A v0.3 returns
+      // EITHER a Task (long-running) OR a Message (direct response)
+      // for `message/send` — both are spec-conformant; we only assert
+      // the envelope shape.
+      const firstSkill = cardJson.skills?.[0];
+      const sendRes = await rpc(
+        rpcUrl,
+        'message/send',
+        {
+          message: {
+            kind: 'message',
+            messageId: `probe-${Date.now()}`,
+            role: 'user',
+            parts: [{ kind: 'text', text: 'interop ping' }],
+          },
+        },
+        1,
+      );
+      expect(sendRes.status).toBe(200);
+      // Spec-conformant: result is either a Task or a Message envelope.
+      const sendResult = sendRes.result ?? {};
+      const kind = (sendResult.kind ?? '') as string;
+      expect(['task', 'message']).toContain(kind);
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[a2a-task-roundtrip] real-peer interop OK against ${probe.url} ` +
+          `(skill=${firstSkill?.id ?? firstSkill?.name}, kind=${kind})`,
+      );
+      return;
+    }
+
+    // Fake-peer path: deterministic state forcing, assert verbatim.
+    const fake = getA2AFakePeer()!;
+    const sendRes = await rpc(
+      rpcUrl,
+      'message/send',
+      {
+        message: {
+          kind: 'message',
+          messageId: 'probe-fake-1',
+          role: 'user',
+          parts: [{ kind: 'text', text: 'hello' }],
+        },
+      },
+      1,
+    );
+    expect(sendRes.status).toBe(200);
+    expect(sendRes.error).toBeUndefined();
+    const task = sendRes.result as { id?: string; kind?: string; status?: { state?: string } };
+    expect(task.kind).toBe('task');
+    expect(typeof task.id).toBe('string');
 
-    // Advance through states.
-    peer.advanceTask(taskId, 'WORKING');
-    peer.advanceTask(taskId, 'COMPLETED');
+    // Advance through WORKING → COMPLETED via the fake's internal API.
+    fake.advanceTask(task.id!, 'WORKING');
+    fake.advanceTask(task.id!, 'COMPLETED');
 
-    const get = await fetch(`${peer.endpoint()}/tasks/${taskId}`);
-    const finalTask = (await get.json()) as { state: string };
-    expect(finalTask.state).toBe('COMPLETED');
+    const getRes = await rpc(rpcUrl, 'tasks/get', { id: task.id }, 2);
+    expect(getRes.status).toBe(200);
+    expect(getRes.error).toBeUndefined();
+    const finalTask = getRes.result as { status?: { state?: string } };
+    // A2A v0.3 wire form uses lowercase-hyphen state names.
+    expect(finalTask.status?.state).toBe('completed');
   });
 });
 

package/src/scenarios/agentConfidenceEscalation.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 1 — confidence-escalation contract (CP-1).
+ * Normative reference: RFCS/0002-agent-identity-and-reasoning-events.md
  *
  * Verifies: when an `agent.decided` event carries `confidence < threshold`,
  * the host MUST emit `node.suspended { reason: 'low-confidence' }` and

package/src/scenarios/agentMemoryCrossTenantIsolation.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 3 — CTI-1 cross-tenant isolation invariant.
+ * Normative reference: RFCS/0004-memory-layer.md
  *
  * Verifies the CTI-1 normative invariant: a `memoryRef` resolved by a
  * MemoryAdapter MUST return entries scoped to a single tenant. If

package/src/scenarios/agentMemoryRedactionContract.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 3 — SR-1 secret-redaction invariant.
+ * Normative reference: RFCS/0004-memory-layer.md
  *
  * Verifies the SR-1 normative invariant: when a memory write contains
  * a value the run's BYOK vault resolved during the run, the persisted

package/src/scenarios/agentMemoryRoundTrip.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 3 — MemoryAdapter list/get round-trip.
+ * Normative reference: RFCS/0004-memory-layer.md
  *
  * Verifies that a host advertising `capabilities.agents.memoryBackends:
  * ['long-term']` resolves `AgentRef.memoryRef` to MemoryEntry results

package/src/scenarios/agentMemoryTtlExpiry.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 3 — TTL expiry semantics for MemoryEntry.
+ * Normative reference: RFCS/0004-memory-layer.md
  *
  * Verifies that memory entries carrying `expiresAt` in the past are
  * NOT surfaced by `MemoryAdapter.list()` / `get()`. The fixture writes

package/src/scenarios/agentMessageReducer.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 1 — `message` reducer idempotency invariant.
+ * Normative reference: RFCS/0002-agent-identity-and-reasoning-events.md
  *
  * Verifies the canonical `message` reducer's contract from
  * `spec/v1/channels-and-reducers.md` §`message`:

package/src/scenarios/agentMetadata.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 1 — agent identity (RunSnapshot.agent / runOrchestrator).
+ * Normative reference: RFCS/0002-agent-identity-and-reasoning-events.md
  *
  * Verifies:
  *   1. Hosts advertising `capabilities.agents.supported: true` populate

package/src/scenarios/agentPackExport.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 2 — agent-pack export round-trips workspace agents → AgentManifest.
+ * Normative reference: RFCS/0003-agent-packs.md
  *
  * Verifies that a host's workspace-scoped agent registry can project
  * agents into the canonical AgentManifest shape for export/distribution.

package/src/scenarios/agentPackInstall.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 2 — agent-pack install registers AgentManifest entries.
+ * Normative reference: RFCS/0003-agent-packs.md
  *
  * Verifies that a pack containing an `agents[]` array surfaces those
  * agent manifests via the host's pack registry. The wire-shape contract

package/src/scenarios/agentPackProvenance.test.ts

@@ -1,5 +1,6 @@
 /**
  * Multi-Agent Shift Phase 2 — sourceManifestId provenance round-trip.
+ * Normative reference: RFCS/0003-agent-packs.md
  *
  * Verifies that when a workspace agent originates from a pack install,
  * the agent's runtime AgentRef AND the exported AgentManifest both

package/src/scenarios/audit-log-integrity.test.ts

@@ -17,6 +17,7 @@
 
 import { describe, it, expect } from 'vitest';
 import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
 
 interface AuditIntegrityCaps {
   hashChain?: boolean;
@@ -39,9 +40,7 @@ async function isProfileAdvertised(): Promise<boolean> {
 
 describe('audit-log-integrity: profile shape', () => {
   it('host that claims the profile advertises required capability fields', async () => {
-    if (!(await isProfileAdvertised())) {
-      // eslint-disable-next-line no-console
-      console.warn('[audit-log-integrity] profile not advertised; skipping');
+    if (!behaviorGate('openwop-audit-log-integrity', await isProfileAdvertised())) {
       return;
     }
 
@@ -64,9 +63,7 @@ describe('audit-log-integrity: profile shape', () => {
 
 describe('audit-log-integrity: verify endpoint returns chainValid', () => {
   it('GET /v1/audit/verify on a recent range reports chainValid: true', async () => {
-    if (!(await isProfileAdvertised())) {
-      // eslint-disable-next-line no-console
-      console.warn('[audit-log-integrity] profile not advertised; skipping');
+    if (!behaviorGate('openwop-audit-log-integrity', await isProfileAdvertised())) {
       return;
     }
 

package/src/scenarios/auth-api-key-rotation.test.ts

@@ -0,0 +1,182 @@
+/**
+ * RFC 0010 §B: openwop-auth-api-key-rotation profile.
+ *
+ * Verifies that hosts claiming the rotation profile satisfy
+ * `spec/v1/auth-profiles.md` §`openwop-auth-api-key-rotation`:
+ *
+ *   1. `capabilities.auth.profiles[]` includes `openwop-auth-api-key-rotation`
+ *      and `capabilities.auth.rotation.supported === true`.
+ *   2. When `minGraceSeconds` is advertised, it's an integer ≥ 0;
+ *      production-profile hosts SHOULD advertise ≥ 86400 (24h) per spec.
+ *   3. When the operator supplies a secondary key via
+ *      `OPENWOP_TEST_SECONDARY_API_KEY`, both keys MUST authenticate the
+ *      same operation. The rotation invariant: both map to the same
+ *      principal/tenant within the grace window.
+ *   4. An invalid bearer (a synthetic canary, not a real key) returns
+ *      401 `invalid_token`; the response body MUST NOT echo the canary
+ *      in any field (`auth.md` §3 credential-redaction MUST).
+ *
+ * The two-key overlap soft-skips when `OPENWOP_TEST_SECONDARY_API_KEY`
+ * is unset. The capability-shape and canary-redaction assertions run
+ * unconditionally when the profile is advertised.
+ *
+ * @see RFCS/0010-auth-profile-conformance.md §B
+ * @see spec/v1/auth-profiles.md §`openwop-auth-api-key-rotation`
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+import { behaviorGate } from '../lib/behavior-gate.js';
+import { isFixtureAdvertised } from '../lib/fixtures.js';
+
+interface RotationCaps {
+  supported?: boolean;
+  minGraceSeconds?: number;
+}
+
+interface AuthCaps {
+  profiles?: string[];
+  rotation?: RotationCaps;
+}
+
+const PROFILE = 'openwop-auth-api-key-rotation';
+const FIXTURE = 'conformance-noop';
+const CANARY = 'hk_openwop_canary_d1d2d3d4_NOT_A_REAL_KEY';
+
+async function readAuthCaps(): Promise<AuthCaps | undefined> {
+  const disco = await driver.get('/.well-known/openwop');
+  return (disco.json as { capabilities?: { auth?: AuthCaps } }).capabilities?.auth;
+}
+
+function isProfileAdvertised(auth: AuthCaps | undefined): boolean {
+  return (
+    Array.isArray(auth?.profiles) &&
+    auth.profiles.includes(PROFILE) &&
+    auth.rotation?.supported === true
+  );
+}
+
+describe('auth-api-key-rotation: capability shape', () => {
+  it('host claiming rotation profile advertises required fields', async () => {
+    const auth = await readAuthCaps();
+
+    if (!behaviorGate(PROFILE, isProfileAdvertised(auth))) {
+      return;
+    }
+
+    expect(auth?.profiles?.includes(PROFILE), driver.describe(
+      'auth-profiles.md §`openwop-auth-api-key-rotation`',
+      'capabilities.auth.profiles MUST include openwop-auth-api-key-rotation when the profile is claimed',
+    )).toBe(true);
+
+    expect(auth?.rotation?.supported, driver.describe(
+      'auth-profiles.md §`openwop-auth-api-key-rotation`',
+      'capabilities.auth.rotation.supported MUST be true when the profile is claimed',
+    )).toBe(true);
+
+    if (auth?.rotation?.minGraceSeconds !== undefined) {
+      expect(
+        Number.isInteger(auth.rotation.minGraceSeconds) &&
+          auth.rotation.minGraceSeconds >= 0,
+        driver.describe(
+          'capabilities.schema.json auth.rotation.minGraceSeconds',
+          'minGraceSeconds MUST be a non-negative integer when advertised',
+        ),
+      ).toBe(true);
+
+      if (auth.rotation.minGraceSeconds < 86400) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          `[auth-api-key-rotation] minGraceSeconds=${auth.rotation.minGraceSeconds} is below the 24h floor auth-profiles.md SHOULDs for production-profile hosts`,
+        );
+      }
+    }
+  });
+});
+
+describe('auth-api-key-rotation: two-key overlap', () => {
+  it('primary + secondary keys both authenticate the same operation', async () => {
+    const auth = await readAuthCaps();
+
+    if (!behaviorGate(PROFILE, isProfileAdvertised(auth))) {
+      return;
+    }
+
+    const secondaryKey = process.env.OPENWOP_TEST_SECONDARY_API_KEY;
+    if (!secondaryKey) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[auth-api-key-rotation] OPENWOP_TEST_SECONDARY_API_KEY not supplied; skipping two-key overlap assertion',
+      );
+      return;
+    }
+
+    if (!isFixtureAdvertised(FIXTURE)) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[auth-api-key-rotation] ${FIXTURE} not advertised; skipping overlap assertion`,
+      );
+      return;
+    }
+
+    // Primary key — uses driver's default Authorization header (env-loaded).
+    const primary = await driver.post('/v1/runs', { workflowId: FIXTURE });
+    expect(primary.status, driver.describe(
+      'auth-profiles.md §`openwop-auth-api-key-rotation`',
+      'primary key MUST authenticate POST /v1/runs during rotation grace',
+    )).toBe(201);
+    const primaryRunId = (primary.json as { runId: string }).runId;
+
+    // Secondary key — supplied via env, sent verbatim.
+    const secondary = await driver.post(
+      '/v1/runs',
+      { workflowId: FIXTURE },
+      {
+        authenticated: false,
+        headers: { Authorization: `Bearer ${secondaryKey}` },
+      },
+    );
+    expect(secondary.status, driver.describe(
+      'auth-profiles.md §`openwop-auth-api-key-rotation`',
+      'secondary key MUST authenticate POST /v1/runs during rotation grace',
+    )).toBe(201);
+    const secondaryRunId = (secondary.json as { runId: string }).runId;
+
+    // Both runs MUST be distinct (different keys are still independent
+    // authentications, not idempotent retries) but MUST have been
+    // accepted, proving overlap is honored.
+    expect(primaryRunId).not.toBe(secondaryRunId);
+  });
+});
+
+describe('auth-api-key-rotation: canary redaction', () => {
+  it('invalid bearer returns 401 without echoing the canary credential', async () => {
+    const auth = await readAuthCaps();
+
+    if (!behaviorGate(PROFILE, isProfileAdvertised(auth))) {
+      return;
+    }
+
+    const res = await driver.post(
+      '/v1/runs',
+      { workflowId: FIXTURE },
+      {
+        authenticated: false,
+        headers: { Authorization: `Bearer ${CANARY}` },
+      },
+    );
+
+    expect(res.status, driver.describe(
+      'auth.md §3',
+      'invalid bearer MUST return 401, not 200 or 403',
+    )).toBe(401);
+
+    // The response body MUST NOT echo the canary in any field. We
+    // check the serialized JSON to catch echoes even in nested fields.
+    const serialized = JSON.stringify(res.json ?? {});
+    expect(serialized.includes(CANARY), driver.describe(
+      'auth.md §"No credential echo" + threat-model-auth-profiles.md A1',
+      'rotation-profile hosts MUST NOT echo the rejected credential in error responses',
+    )).toBe(false);
+  });
+});