@vauban-org/agent-sdk 0.16.0

package/src/proof/receipt-queue.ts

@@ -0,0 +1,235 @@
+/**
+ * ReceiptQueue — tamper-evident in-memory queue for TSA receipt retries.
+ *
+ * CH1-r: Every entry is HMAC-SHA-256 authenticated. process() rejects entries
+ * with invalid HMACs before submitting to the TSA — no silent data corruption.
+ *
+ * Backoff schedule: DEFAULT_BACKOFF_MS defines 5 exponential windows.
+ * process() skips entries whose next retry time has not been reached yet
+ * (based on queuedAt + DEFAULT_BACKOFF_MS[attempts - 1]).
+ *
+ * KeyProvider isolation: the key is fetched from the provider at enqueue and
+ * process time — never stored in the entry itself.
+ *
+ * @module proof/receipt-queue
+ */
+
+import { canonicalize } from "../trace/canonical.js";
+import type { KeyProvider } from "../ports/key-provider.js";
+import type { TimestampPort } from "../ports/timestamp.js";
+import type { SignedReceipt } from "../trace/schema.js";
+import { hmacSha256 } from "./sha256.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface ReceiptQueueEntry {
+  runId: string;
+  rootHash: string;
+  /** Unix epoch milliseconds when this entry was first enqueued. */
+  queuedAt: number;
+  /** Number of prior failed attempts (0 on first enqueue). */
+  attempts: number;
+  /**
+   * HMAC-SHA-256(canonical(entry-without-hmac), key from provider).
+   * CH1-r: tamper-evident field. process() rejects if this does not
+   * match a freshly computed HMAC.
+   */
+  hmac: string;
+}
+
+export interface ReceiptQueue {
+  /**
+   * Add a new entry to the queue. Computes and stores the HMAC.
+   *
+   * @param entry       - Entry without hmac/attempts.
+   * @param keyProvider - Provider that supplies the HMAC key.
+   * @param keyId       - Key identifier for keyProvider.getKey().
+   */
+  enqueue(
+    entry: Omit<ReceiptQueueEntry, "hmac" | "attempts">,
+    keyProvider: KeyProvider,
+    keyId: string,
+  ): Promise<void>;
+
+  /** Return all entries currently in the queue (including those in backoff). */
+  pending(): Promise<ReceiptQueueEntry[]>;
+
+  /**
+   * Process up to `batchSize` due entries.
+   *
+   * For each entry:
+   *   - Recompute HMAC; if mismatch → increment `rejected`, do NOT call adapter.
+   *   - If backoff window not elapsed → skip (not counted in any bucket).
+   *   - On success → remove from queue.
+   *   - On failure → increment `entry.attempts`, apply next backoff.
+   *
+   * @returns { processed, failed, rejected }
+   */
+  process(
+    adapter: TimestampPort,
+    keyProvider: KeyProvider,
+    keyId: string,
+    opts?: { batchSize?: number; backoffMs?: readonly number[] },
+  ): Promise<{ processed: number; failed: number; rejected: number }>;
+
+  /** Number of entries currently in the queue. Test helper. */
+  size?(): Promise<number>;
+}
+
+/**
+ * Default exponential backoff schedule (5 levels).
+ * Level 0 = 30s, 1 = 5min, 2 = 1h, 3 = 6h, 4 = 24h.
+ */
+export const DEFAULT_BACKOFF_MS = [
+  30_000,
+  5 * 60_000,
+  60 * 60_000,
+  6 * 60 * 60_000,
+  24 * 60 * 60_000,
+] as const;
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+/**
+ * Thrown internally when a queue entry HMAC fails verification.
+ * The error is caught by process() and counted in the `rejected` bucket.
+ */
+export class HmacInvalidError extends Error {
+  constructor(runId: string) {
+    super(
+      `HmacInvalidError: HMAC verification failed for entry runId="${runId}". ` +
+        "The entry may have been tampered with. Entry rejected without TSA call.",
+    );
+    this.name = "HmacInvalidError";
+  }
+}
+
+// ─── HMAC helpers ─────────────────────────────────────────────────────────────
+
+async function computeEntryHmac(
+  entry: Omit<ReceiptQueueEntry, "hmac">,
+  keyProvider: KeyProvider,
+  keyId: string,
+): Promise<string> {
+  const key = await keyProvider.getKey(keyId);
+  // Canonical representation excludes the hmac field itself.
+  const canonical = canonicalize({
+    attempts: entry.attempts,
+    queuedAt: entry.queuedAt,
+    rootHash: entry.rootHash,
+    runId: entry.runId,
+  });
+  return hmacSha256(key, canonical);
+}
+
+// ─── InMemoryReceiptQueue ─────────────────────────────────────────────────────
+
+/**
+ * In-memory ReceiptQueue implementation.
+ *
+ * Not durable across restarts — for production persistence, implement
+ * ReceiptQueue against a PostgreSQL table (see sprint-562 B2).
+ */
+export class InMemoryReceiptQueue implements ReceiptQueue {
+  private readonly _entries: ReceiptQueueEntry[] = [];
+
+  async enqueue(
+    entry: Omit<ReceiptQueueEntry, "hmac" | "attempts">,
+    keyProvider: KeyProvider,
+    keyId: string,
+  ): Promise<void> {
+    // Emit colocation warning if EnvKeyProvider + TRACE_DB_URL detected.
+    if (keyProvider.hasColocationRisk()) {
+      process.stderr.write(
+        `[WARN] InMemoryReceiptQueue.enqueue: KeyProvider reports colocation risk ` +
+          `(key and TRACE_DB_URL on same host). ` +
+          `For production audit compliance, migrate to ExternalKMSKeyProvider.\n`,
+      );
+    }
+
+    const withAttempts = { ...entry, attempts: 0 };
+    const hmac = await computeEntryHmac(withAttempts, keyProvider, keyId);
+    this._entries.push({ ...withAttempts, hmac });
+  }
+
+  async pending(): Promise<ReceiptQueueEntry[]> {
+    return [...this._entries];
+  }
+
+  async process(
+    adapter: TimestampPort,
+    keyProvider: KeyProvider,
+    keyId: string,
+    opts?: { batchSize?: number; backoffMs?: readonly number[] },
+  ): Promise<{ processed: number; failed: number; rejected: number }> {
+    const backoffMs = opts?.backoffMs ?? DEFAULT_BACKOFF_MS;
+    const batchSize = opts?.batchSize ?? this._entries.length;
+
+    let processed = 0;
+    let failed = 0;
+    let rejected = 0;
+
+    const now = Date.now();
+    const toRemove: number[] = [];
+
+    let count = 0;
+    for (let i = 0; i < this._entries.length && count < batchSize; i++) {
+      const entry = this._entries[i];
+
+      // CH1-r: recompute HMAC and compare before calling adapter.
+      const expectedHmac = await computeEntryHmac(
+        { attempts: entry.attempts, queuedAt: entry.queuedAt, rootHash: entry.rootHash, runId: entry.runId },
+        keyProvider,
+        keyId,
+      );
+      if (entry.hmac !== expectedHmac) {
+        rejected++;
+        toRemove.push(i); // Remove tampered entries immediately.
+        count++;
+        continue;
+      }
+
+      // Backoff check: skip if retry window hasn't elapsed.
+      if (entry.attempts > 0) {
+        const backoffIdx = Math.min(entry.attempts - 1, backoffMs.length - 1);
+        const nextRetryAt = entry.queuedAt + backoffMs[backoffIdx];
+        if (now < nextRetryAt) {
+          // Not due yet — skip but do not count.
+          continue;
+        }
+      }
+
+      count++;
+
+      try {
+        // Try to request the TSA receipt.
+        const _receipt: SignedReceipt = await adapter.request(entry.rootHash);
+        void _receipt;
+        // Success — mark for removal.
+        toRemove.push(i);
+        processed++;
+      } catch {
+        // Failure — increment attempts and recompute HMAC for updated entry.
+        entry.attempts += 1;
+        const newHmac = await computeEntryHmac(
+          { attempts: entry.attempts, queuedAt: entry.queuedAt, rootHash: entry.rootHash, runId: entry.runId },
+          keyProvider,
+          keyId,
+        );
+        entry.hmac = newHmac;
+        failed++;
+      }
+    }
+
+    // Remove processed/rejected entries (reverse order to keep indices stable).
+    for (const idx of toRemove.slice().sort((a, b) => b - a)) {
+      this._entries.splice(idx, 1);
+    }
+
+    return { processed, failed, rejected };
+  }
+
+  async size(): Promise<number> {
+    return this._entries.length;
+  }
+}

package/src/proof/sha256.ts

@@ -0,0 +1,80 @@
+/**
+ * sha256 / hmacSha256 — Web Crypto API wrappers.
+ *
+ * Zero external dependencies. Uses globalThis.crypto.subtle (Node ≥ 19 native,
+ * browser, Deno, Cloudflare Workers). Throws if the runtime does not expose
+ * SubtleCrypto (Node < 19 without --experimental-global-webcrypto).
+ *
+ * @module proof/sha256
+ */
+
+function subtle(): SubtleCrypto {
+  const s = globalThis.crypto?.subtle;
+  if (!s) {
+    throw new Error(
+      "proof/sha256: globalThis.crypto.subtle is unavailable. " +
+        "Require Node.js >= 19 or pass --experimental-global-webcrypto.",
+    );
+  }
+  return s;
+}
+
+/**
+ * Ensure the returned Uint8Array is backed by a plain ArrayBuffer
+ * (not SharedArrayBuffer), as required by SubtleCrypto's BufferSource type.
+ * The explicit return type avoids Uint8Array<ArrayBufferLike> widening.
+ */
+function toBytes(input: string | Uint8Array): Uint8Array<ArrayBuffer> {
+  if (typeof input === "string") {
+    return new TextEncoder().encode(input);
+  }
+  // Always copy into a fresh ArrayBuffer to guarantee the concrete type.
+  const copy = new Uint8Array(input.length);
+  copy.set(input);
+  return copy;
+}
+
+function bufferToHex(buf: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buf))
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * SHA-256 hex digest via Web Crypto.
+ *
+ * @param input - UTF-8 string or raw bytes.
+ * @returns Lowercase hex digest (64 chars).
+ * @throws If SubtleCrypto is unavailable.
+ */
+export async function sha256(input: string | Uint8Array): Promise<string> {
+  const buf = await subtle().digest("SHA-256", toBytes(input));
+  return bufferToHex(buf);
+}
+
+/**
+ * HMAC-SHA-256 hex digest via Web Crypto.
+ *
+ * @param key   - Raw key bytes (min 32 bytes recommended for HMAC-SHA-256).
+ * @param input - UTF-8 string or raw bytes to authenticate.
+ * @returns Lowercase hex MAC (64 chars).
+ * @throws If SubtleCrypto is unavailable or key import fails.
+ */
+export async function hmacSha256(
+  key: Uint8Array,
+  input: string | Uint8Array,
+): Promise<string> {
+  const s = subtle();
+  // Copy key into fresh ArrayBuffer to satisfy SubtleCrypto's BufferSource constraint.
+  const keyBytes = new Uint8Array(key.length);
+  keyBytes.set(key);
+  const cryptoKey = await s.importKey(
+    "raw",
+    keyBytes,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const buf = await s.sign("HMAC", cryptoKey, toBytes(input));
+  return bufferToHex(buf);
+}

package/src/proof/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Proof module types — @vauban-org/agent-sdk v0.5.2 (sprint-521 Bloc 1).
+ *
+ * Mirrors src/proof/run-certificate.ts so cert.json fetched from
+ * /api/runs/:id/proof-certificate parses cleanly into these types.
+ *
+ * Intentionally kept free of server-side dependencies (no DbClient, no crypto).
+ */
+
+export type CertState = "awaiting_anchor" | "anchored" | "verified_on_chain";
+
+export type LogSeverity = "debug" | "info" | "warn" | "error";
+
+export interface RunStep {
+  id: string;
+  run_id: string;
+  step_index: number;
+  parent_step_id?: string | null;
+  type: "retrieval" | "decision" | "execution" | "feedback" | "observation";
+  phase?: string | null;
+  status: "pending" | "done" | "error" | "skipped";
+  started_at: string;
+  finished_at?: string | null;
+  duration_ms?: number | null;
+  payload?: Record<string, unknown> | null;
+  leaf_hash_poseidon?: string | null;
+  mcp_call_hash?: string | null;
+  retrieval_proof_hash?: string | null;
+  otel_trace_id?: string | null;
+  otel_span_id?: string | null;
+  error_message?: string | null;
+}
+
+export interface RunProofCertificate {
+  run_id: string;
+  agent_id: string;
+  started_at: string;
+  finished_at: string;
+  /** Trigger event ID — null if not recorded in run steps. */
+  trigger_event_id: string | null;
+  /** Brain entry IDs from retrieval steps that had an MCP call hash. */
+  brain_context_refs: string[];
+  decision_chain: Array<{
+    step_id: string;
+    step_index: number;
+    type: string;
+    phase: string | null;
+    leaf_hash_poseidon: string;
+    started_at: string;
+    finished_at: string;
+    duration_ms: number | null;
+  }>;
+  merkle_root: string | null;
+  katana_tx: string | null;
+  anchor_block_number: number | null;
+  state: CertState;
+  issued_at: string;
+}

package/src/proof/verify.ts

@@ -0,0 +1,89 @@
+/**
+ * verifyProofCertificate — pure client-side verification of RunProofCertificate.
+ *
+ * Recomputes the Poseidon Merkle root from decision_chain leaf hashes and
+ * compares against cert.merkle_root. No network call, no server trust needed.
+ *
+ * sprint-521 Bloc 1.
+ */
+
+import type { RunProofCertificate } from "./types.js";
+import { computeMerkleRoot } from "@vauban-org/proof-core";
+
+/** Valid CertState values for enum validation. */
+const VALID_CERT_STATES: ReadonlySet<string> = new Set([
+  "awaiting_anchor",
+  "anchored",
+  "verified_on_chain",
+]);
+
+/**
+ * Minimum hex length for a leaf hash (excluding "0x" prefix).
+ *
+ * Poseidon felt252 values are ≤ 252 bits → at most 63 hex chars.
+ * A non-trivial leaf hash will be 62 or 63 hex chars.
+ * We accept anything ≥ 62 hex chars to accommodate both lengths.
+ */
+const MIN_FELT_HEX_LEN = 62;
+
+/**
+ * Validate a hex felt252 leaf hash.
+ * Must start with "0x" and have at least 62 lowercase hex chars after the prefix.
+ */
+function isValidLeaf(leaf: string): boolean {
+  return (
+    typeof leaf === "string" &&
+    leaf.startsWith("0x") &&
+    /^[0-9a-f]+$/i.test(leaf.slice(2)) &&
+    leaf.length >= MIN_FELT_HEX_LEN + 2
+  );
+}
+
+export interface VerifyResult {
+  valid: boolean;
+  reason?: string;
+}
+
+/**
+ * Verify a RunProofCertificate by recomputing its Merkle root.
+ *
+ * Checks:
+ *   1. cert.state is a valid CertState enum value.
+ *   2. All leaf hashes in decision_chain have valid hex felt252 format.
+ *   3. If decision_chain is non-empty, recompute the Merkle root and compare
+ *      against cert.merkle_root. Mismatch → merkle_mismatch.
+ *   4. Empty decision_chain + null merkle_root → valid (degenerate case).
+ *
+ * @param cert - RunProofCertificate to verify (typically fetched from /api/runs/:id/proof-certificate).
+ * @returns { valid: boolean; reason?: string }
+ */
+export function verifyProofCertificate(
+  cert: RunProofCertificate
+): VerifyResult {
+  // ─── 1. State enum validation ─────────────────────────────────────────────
+  if (!VALID_CERT_STATES.has(cert.state)) {
+    return { valid: false, reason: "invalid_state" };
+  }
+
+  // ─── 2. Degenerate case: empty decision_chain ─────────────────────────────
+  if (cert.decision_chain.length === 0) {
+    return { valid: true };
+  }
+
+  // ─── 3. Leaf format validation ────────────────────────────────────────────
+  const leaves = cert.decision_chain.map((s) => s.leaf_hash_poseidon);
+  for (const leaf of leaves) {
+    if (!isValidLeaf(leaf)) {
+      return { valid: false, reason: "invalid_leaf_format" };
+    }
+  }
+
+  // ─── 4. Merkle root recomputation ─────────────────────────────────────────
+  const recomputed = computeMerkleRoot(leaves);
+
+  if (cert.merkle_root === null || recomputed !== cert.merkle_root) {
+    return { valid: false, reason: "merkle_mismatch" };
+  }
+
+  return { valid: true };
+}

package/src/registry/agent-capability.ts

@@ -0,0 +1,48 @@
+/**
+ * AgentCapabilityCard — multi-kind capability descriptor for CC LLM router agents.
+ *
+ * Sprint-580 / registry-multi-kind
+ *
+ * In-memory schema only. SQL persistence via migration
+ * `036_agent_capability_index.sql` (coordinator-applied).
+ */
+
+// ─── Kinds ────────────────────────────────────────────────────────────────────
+
+export const AGENT_KINDS = [
+  "ARCHITECT",
+  "BUILDER",
+  "SCRIBE",
+  "TESTER",
+  "SYNERGY",
+  "OODA",
+  "LLM_ROUTER",
+  "PLUGIN",
+  "MCP",
+] as const;
+
+export type AgentKind = (typeof AGENT_KINDS)[number];
+
+// ─── Tiers ────────────────────────────────────────────────────────────────────
+
+export type CostTier = "low" | "medium" | "high";
+export type LatencyTier = "low" | "medium" | "high";
+
+// ─── Card ─────────────────────────────────────────────────────────────────────
+
+export interface AgentCapabilityCard {
+  /** Stable agent identifier (matches AgentDescriptor.id or AGENT_IDS UUID). */
+  agentId: string;
+  /** Kind classifier for this capability entry. */
+  kind: AgentKind;
+  /** Free-form skill tags, lowercased. */
+  skills: readonly string[];
+  /** Relative cost to invoke this agent. */
+  costTier: CostTier;
+  /** Relative latency of this agent. */
+  latencyTier: LatencyTier;
+  /** pgvector similarity embedding — optional in in-memory mode. */
+  embeddingVector?: readonly number[];
+  /** Unix epoch ms when this card was registered. */
+  createdAt: number;
+}

package/src/registry/agent-card.ts

@@ -0,0 +1,162 @@
+/**
+ * AgentCard — A2A v1.2 (Linux Foundation, 150+ orgs).
+ *
+ * Sprint-563: B8 — AgentCard + A2A v1.2 + Signed Agent Cards (CH8 activation).
+ *
+ * Converts a Vauban AgentDescriptor into an A2A v1.2-compliant AgentCard.
+ * Signed AgentCards activate CH8: Trace.agentSignature is computed from
+ * the agent's identity key.
+ */
+
+// ─── A2A v1.2 Agent Card types ───────────────────────────────────────────────
+
+export interface A2AAgentCapabilities {
+  streaming?: boolean;
+  pushNotifications?: boolean;
+  stateTransitionHistory?: boolean;
+}
+
+export interface A2ASkill {
+  id: string;
+  name: string;
+  description: string;
+  tags?: string[];
+  inputSchema?: Record<string, unknown>;
+  outputSchema?: Record<string, unknown>;
+}
+
+export interface A2AAgentCard {
+  /** Agent Card spec version. */
+  protocolVersion: "1.2";
+  /** Human-readable name. */
+  name: string;
+  /** Natural language description. */
+  description: string;
+  /** Globally unique agent identifier. */
+  url: string;
+  /** Provider/org name. */
+  provider?: string;
+  /** Agent version (semver). */
+  version: string;
+  /** IANA media type for default input (default: application/json). */
+  defaultInputModes?: string[];
+  /** IANA media type for default output. */
+  defaultOutputModes?: string[];
+  /** Agent capabilities (streaming, push, state history). */
+  capabilities: A2AAgentCapabilities;
+  /** Exposed skills. */
+  skills: A2ASkill[];
+  /** Optional signature (CH8 activation). */
+  signature?: string;
+}
+
+// ─── Agent Card options ──────────────────────────────────────────────────────
+
+export interface AgentCardOptions {
+  /** Base URL for the agent (e.g. "https://agents.vauban.tech"). */
+  baseUrl: string;
+  /** Provider/organization name. */
+  provider?: string;
+  /** Capabilities override. */
+  capabilities?: Partial<A2AAgentCapabilities>;
+  /** Signing key for CH8 Signed Agent Cards. */
+  signingKey?: {
+    sign: (payload: string) => Promise<string>;
+  };
+}
+
+// ─── Builder ─────────────────────────────────────────────────────────────────
+
+/**
+ * Convert a Vauban AgentDescriptor into an A2A v1.2 AgentCard.
+ *
+ * Usage:
+ *   import { toAgentCard } from "@vauban-org/agent-sdk";
+ *   const card = await toAgentCard(descriptor, skills, { baseUrl: "https://agents.vauban.tech" });
+ */
+export async function toAgentCard(
+  descriptor: {
+    agentId: string;
+    name: string;
+    description: string;
+    version: string;
+    capabilities?: string[];
+  },
+  skills: Array<{
+    name: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    tags?: string[];
+  }>,
+  opts: AgentCardOptions,
+): Promise<A2AAgentCard> {
+  const card: A2AAgentCard = {
+    protocolVersion: "1.2",
+    name: descriptor.name,
+    description: descriptor.description,
+    url: `${opts.baseUrl}/agents/${descriptor.agentId}`,
+    provider: opts.provider ?? "vauban",
+    version: descriptor.version,
+    defaultInputModes: ["application/json"],
+    defaultOutputModes: ["application/json"],
+    capabilities: {
+      streaming: true,
+      pushNotifications: false,
+      stateTransitionHistory: true,
+      ...opts.capabilities,
+    },
+    skills: skills.map((s) => ({
+      id: `skill:${s.name}`,
+      name: s.name,
+      description: s.description,
+      tags: s.tags,
+      inputSchema: s.inputSchema,
+      outputSchema: s.outputSchema,
+    })),
+  };
+
+  // CH8: Sign the card if a signing key is provided
+  if (opts.signingKey) {
+    const payload = JSON.stringify({
+      name: card.name,
+      url: card.url,
+      version: card.version,
+      skills: card.skills.map((s) => s.id).sort(),
+    });
+    card.signature = await opts.signingKey.sign(payload);
+  }
+
+  return card;
+}
+
+/**
+ * Validate that an AgentCard has all required fields per A2A v1.2 spec.
+ */
+export function validateAgentCard(card: A2AAgentCard): {
+  valid: boolean;
+  errors: string[];
+} {
+  const errors: string[] = [];
+
+  if (card.protocolVersion !== "1.2") {
+    errors.push("protocolVersion must be '1.2'");
+  }
+  if (!card.name || card.name.trim().length === 0) {
+    errors.push("name is required");
+  }
+  if (!card.description || card.description.trim().length === 0) {
+    errors.push("description is required");
+  }
+  if (!card.url || !card.url.startsWith("https://")) {
+    errors.push("url must be a valid HTTPS URL");
+  }
+  if (!card.version) {
+    errors.push("version is required");
+  }
+  if (!card.skills || card.skills.length === 0) {
+    errors.push("at least one skill is required");
+  }
+
+  return { valid: errors.length === 0, errors };
+}