@vauban-org/agent-sdk 0.16.0

package/src/proof/chain.ts

@@ -0,0 +1,249 @@
+/**
+ * ProofChain — tamper-evident SHA-256 step chain for TRACE_V1.
+ *
+ * Coexists with the legacy Poseidon proof system in `./poseidon.ts`.
+ * This module targets the TRACE_V1 schema (sprint-561:a2/a4).
+ *
+ * buildChain  — builds a ProofChain from a finalized Trace.
+ * verifyChain — runs 7 integrity checks (R8-M4, CH9, AR6).
+ *
+ * rootHash binding (CH9):
+ *   rootHash = sha256(canonical({
+ *     lastStepHash,
+ *     totalSteps,
+ *     configHash,    ← anti config-swap
+ *     agentId,
+ *     agentVersion,
+ *     runId,
+ *   }))
+ *
+ * All-zeros prevStepHash sentinel for step[0]:
+ *   "0000000000000000000000000000000000000000000000000000000000000000"
+ *
+ * @module proof/chain
+ */
+
+import { canonicalize } from "../trace/canonical.js";
+import type { Trace, TraceStep } from "../trace/schema.js";
+import { sha256 } from "./sha256.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface ProofChainEntry {
+  /** Zero-based step index (mirrors TraceStep.index). */
+  index: number;
+  /** SHA-256(canonical({ ...step fields (excl. stepHash), runId })). */
+  stepHash: string;
+}
+
+export interface ProofChain {
+  /** Hash algorithm identifier. Always sha-256 in this schema version. */
+  algorithm: "sha-256";
+  /** One entry per step; ordered by index. */
+  entries: ProofChainEntry[];
+  /**
+   * SHA-256(canonical({ lastStepHash, totalSteps, configHash, agentId, agentVersion, runId })).
+   * Binds config, identity, and chain tail into a single commitment (CH9).
+   */
+  rootHash: string;
+}
+
+/**
+ * Discriminated union returned by verifyChain.
+ * R8-M4: receiptStatus propagated on BOTH branches when present.
+ */
+export type VerifyChainResult =
+  | {
+      valid: true;
+      receiptStatus?: "present" | "pending" | "failed";
+    }
+  | {
+      valid: false;
+      /** Zero-based index of the first tampered step, or -1 for structural errors. */
+      tamperedAt: number;
+      reason: string;
+      receiptStatus?: "present" | "pending" | "failed";
+    };
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/** All-zeros sentinel for prevStepHash of the first step. */
+export const GENESIS_PREV_HASH =
+  "0000000000000000000000000000000000000000000000000000000000000000";
+
+// ─── computeStepHash ─────────────────────────────────────────────────────────
+
+/**
+ * SHA-256(canonical({ ...step fields (excluding stepHash), runId })).
+ *
+ * The stepHash field itself is excluded from its own digest to avoid
+ * circular dependency. runId is included explicitly even though it is
+ * already a step field — this is intentional for AR6 clarity.
+ */
+export async function computeStepHash(
+  step: TraceStep,
+  runId: string,
+): Promise<string> {
+  const {
+    stepHash: _excluded,
+    ...stepWithoutHash
+  } = step;
+  void _excluded;
+  const payload = { ...stepWithoutHash, runId };
+  return sha256(canonicalize(payload));
+}
+
+// ─── buildChain ──────────────────────────────────────────────────────────────
+
+/**
+ * Build a ProofChain from a finalized Trace.
+ *
+ * Recomputes stepHash for every step to produce the entries array,
+ * then computes rootHash = sha256(canonical({ lastStepHash, totalSteps,
+ * configHash, agentId, agentVersion, runId })).
+ *
+ * @throws If the trace has no steps.
+ */
+export async function buildChain(trace: Trace): Promise<ProofChain> {
+  if (trace.steps.length === 0) {
+    throw new Error("buildChain: trace must have at least one step");
+  }
+
+  const entries: ProofChainEntry[] = [];
+
+  for (const step of trace.steps) {
+    const stepHash = await computeStepHash(step, trace.runId);
+    entries.push({ index: step.index, stepHash });
+  }
+
+  const lastStepHash = entries[entries.length - 1].stepHash;
+
+  const rootPayload = {
+    agentId: trace.agentId,
+    agentVersion: trace.agentVersion,
+    configHash: trace.configHash,
+    lastStepHash,
+    runId: trace.runId,
+    totalSteps: trace.totalSteps,
+  };
+
+  const rootHash = await sha256(canonicalize(rootPayload));
+
+  return { algorithm: "sha-256", entries, rootHash };
+}
+
+// ─── verifyChain ─────────────────────────────────────────────────────────────
+
+/**
+ * Verify a ProofChain against a Trace — 7 integrity checks.
+ *
+ * Checks (in order):
+ *   1. steps[i].index === i                    (monotone, anti-deletion)
+ *   2. steps.length === trace.totalSteps        (anti-truncation)
+ *   3. steps[i].runId === trace.runId for all i (anti-splice AR6)
+ *   4. recompute stepHash === step.stepHash     (data integrity)
+ *   5. steps[i].prevStepHash === steps[i-1].stepHash (chain linkage)
+ *   6. rootHash === recomputed rootHash         (root commitment CH9)
+ *   7. trace.configHash === sha256(canonical(trace.config)) (config anti-swap)
+ */
+export async function verifyChain(
+  trace: Trace,
+  chain: ProofChain,
+): Promise<VerifyChainResult> {
+  const receiptStatus = trace.receiptStatus;
+
+  // Check 2 — anti-truncation (check length before iterating)
+  if (trace.steps.length !== trace.totalSteps) {
+    return {
+      valid: false,
+      tamperedAt: -1,
+      reason: "totalSteps mismatch",
+      ...(receiptStatus !== undefined ? { receiptStatus } : {}),
+    };
+  }
+
+  // Checks 1, 3, 4, 5 — per-step loop
+  const computedHashes: string[] = [];
+  for (let i = 0; i < trace.steps.length; i++) {
+    const step = trace.steps[i];
+
+    // Check 1 — monotone index
+    if (step.index !== i) {
+      return {
+        valid: false,
+        tamperedAt: i,
+        reason: "monotone violation",
+        ...(receiptStatus !== undefined ? { receiptStatus } : {}),
+      };
+    }
+
+    // Check 3 — AR6 runId anti-splice
+    if (step.runId !== trace.runId) {
+      return {
+        valid: false,
+        tamperedAt: i,
+        reason: "runId mismatch",
+        ...(receiptStatus !== undefined ? { receiptStatus } : {}),
+      };
+    }
+
+    // Check 4 — recompute stepHash
+    const recomputedHash = await computeStepHash(step, trace.runId);
+    if (recomputedHash !== step.stepHash) {
+      return {
+        valid: false,
+        tamperedAt: i,
+        reason: "step hash mismatch",
+        ...(receiptStatus !== undefined ? { receiptStatus } : {}),
+      };
+    }
+    computedHashes.push(recomputedHash);
+
+    // Check 5 — chain linkage
+    const expectedPrev = i === 0 ? GENESIS_PREV_HASH : computedHashes[i - 1];
+    if (step.prevStepHash !== expectedPrev) {
+      return {
+        valid: false,
+        tamperedAt: i,
+        reason: "prev hash mismatch",
+        ...(receiptStatus !== undefined ? { receiptStatus } : {}),
+      };
+    }
+  }
+
+  // Check 6 — root hash
+  const lastStepHash = computedHashes[computedHashes.length - 1];
+  const rootPayload = {
+    agentId: trace.agentId,
+    agentVersion: trace.agentVersion,
+    configHash: trace.configHash,
+    lastStepHash,
+    runId: trace.runId,
+    totalSteps: trace.totalSteps,
+  };
+  const recomputedRoot = await sha256(canonicalize(rootPayload));
+  if (chain.rootHash !== recomputedRoot) {
+    return {
+      valid: false,
+      tamperedAt: -1,
+      reason: "root hash mismatch",
+      ...(receiptStatus !== undefined ? { receiptStatus } : {}),
+    };
+  }
+
+  // Check 7 — CH9 config hash
+  const recomputedConfigHash = await sha256(canonicalize(trace.config));
+  if (trace.configHash !== recomputedConfigHash) {
+    return {
+      valid: false,
+      tamperedAt: -1,
+      reason: "config hash mismatch",
+      ...(receiptStatus !== undefined ? { receiptStatus } : {}),
+    };
+  }
+
+  return {
+    valid: true,
+    ...(receiptStatus !== undefined ? { receiptStatus } : {}),
+  };
+}

package/src/proof/fallback-adapter.ts

@@ -0,0 +1,117 @@
+/**
+ * FallbackAdapter — cascading TimestampPort composition.
+ *
+ * Pure cascade logic with no ASN.1 / wire-format knowledge.
+ * Adapters are tried in order; the first success wins.
+ * All failures aggregate into AllAdaptersFailedError.
+ *
+ * For verify(): the first adapter whose tsa URL matches the receipt is used.
+ * If none match, falls back to trying each in order.
+ *
+ * @module proof/fallback-adapter
+ */
+
+import type { SignedReceipt } from "../trace/schema.js";
+import type { TimestampPort } from "../ports/timestamp.js";
+
+/**
+ * Thrown when all adapters fail during a `request()` call.
+ * Aggregates individual errors for diagnostics.
+ */
+export class AllAdaptersFailedError extends AggregateError {
+  constructor(errors: Error[], message = "All TimestampPort adapters failed") {
+    super(errors, message);
+    this.name = "AllAdaptersFailedError";
+  }
+}
+
+/**
+ * FallbackAdapter — tries adapters in insertion order.
+ *
+ * Construction throws immediately if the adapters array is empty
+ * (fail-closed; never silently degrade to a misconfigured state).
+ */
+export class FallbackAdapter implements TimestampPort {
+  private readonly _adapters: readonly TimestampPort[];
+
+  constructor(adapters: readonly TimestampPort[]) {
+    if (adapters.length === 0) {
+      throw new Error(
+        "FallbackAdapter requires at least one adapter. " +
+          "Pass one or more TimestampPort implementations.",
+      );
+    }
+    this._adapters = adapters;
+  }
+
+  /**
+   * Try each adapter in order. Returns the first successful receipt.
+   * Throws AllAdaptersFailedError if every adapter throws.
+   */
+  async request(rootHash: string): Promise<SignedReceipt> {
+    const errors: Error[] = [];
+
+    for (const adapter of this._adapters) {
+      try {
+        return await adapter.request(rootHash);
+      } catch (err) {
+        errors.push(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+
+    throw new AllAdaptersFailedError(errors);
+  }
+
+  /**
+   * Verify a receipt.
+   *
+   * Strategy: try the first adapter whose tsa URL matches receipt.tsa first
+   * (fast path). If none match (or the match fails), try all adapters in order
+   * and return the first successful result.
+   *
+   * Returns `{ valid: false }` only when all adapters declare invalid or throw.
+   */
+  async verify(
+    receipt: SignedReceipt,
+    rootHash: string,
+  ): Promise<{ valid: boolean; reason?: string }> {
+    // Fast-path: find an adapter that "owns" this receipt by TSA URL.
+    // Adapters expose their TSA URL via an optional `tsaUrl` property (duck-typed).
+    const matchingIdx = this._adapters.findIndex(
+      (a) =>
+        typeof (a as unknown as Record<string, unknown>)["tsaUrl"] ===
+          "string" &&
+        (a as unknown as Record<string, unknown>)["tsaUrl"] === receipt.tsa,
+    );
+
+    if (matchingIdx !== -1) {
+      try {
+        const result = await this._adapters[matchingIdx].verify(
+          receipt,
+          rootHash,
+        );
+        if (result.valid) return result;
+      } catch {
+        // Fall through to full scan.
+      }
+    }
+
+    // Full scan: try each adapter.
+    let lastReason: string | undefined;
+    for (const adapter of this._adapters) {
+      try {
+        const result = await adapter.verify(receipt, rootHash);
+        if (result.valid) return result;
+        lastReason = result.reason;
+      } catch (err) {
+        lastReason =
+          err instanceof Error ? err.message : "adapter verify threw";
+      }
+    }
+
+    return {
+      valid: false,
+      reason: lastReason ?? "no adapter could verify receipt",
+    };
+  }
+}

package/src/proof/index.ts

@@ -0,0 +1,207 @@
+/**
+ * Universal proof-layer entrypoint for the agent-sdk — sprint-483.
+ * Extended: sprint-521 Bloc 1 — Poseidon proof module.
+ *
+ * Re-exports the leaf builders so external consumers can compute or verify
+ * universal proof leaves WITHOUT depending on the command-center monolith.
+ *
+ * The implementation lives in command-center/src/proof/* and is re-exported
+ * via a thin shim. Cross-language parity is guaranteed by the same SHA-256
+ * + JCS test vectors (tests/proof/cross-lang-vectors.json).
+ *
+ * Usage:
+ *   import { mkProofLeaf, verifyProofInclusion } from "@vauban-org/agent-sdk/proof";
+ *
+ *   const leaf = mkProofLeaf("hitl_approval", row);
+ *   const ok = verifyProofInclusion(leaf.preimage_hash, proof, root);
+ */
+
+import { createHash } from "node:crypto";
+
+// ─── JCS canonical JSON (RFC 8785 subset) ────────────────────────────────────
+
+function normalize(value: unknown): unknown {
+  if (value === null) return null;
+  if (typeof value === "number") {
+    if (Object.is(value, -0)) return 0;
+    return value;
+  }
+  if (Array.isArray(value)) return value.map(normalize);
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = normalize(obj[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+export function canonicalize(data: Record<string, unknown>): string {
+  return JSON.stringify(normalize(data));
+}
+
+export function leafHash(data: Record<string, unknown>): string {
+  return createHash("sha256").update(canonicalize(data), "utf8").digest("hex");
+}
+
+// ─── Merkle proof verification ────────────────────────────────────────────────
+
+function hashPair(left: string, right: string): string {
+  const [a, b] = left <= right ? [left, right] : [right, left];
+  return createHash("sha256")
+    .update(Buffer.from(a, "hex"))
+    .update(Buffer.from(b, "hex"))
+    .digest("hex");
+}
+
+export function verifyProofInclusion(
+  leaf: string,
+  proof: string[],
+  root: string
+): boolean {
+  let current = leaf.startsWith("0x") ? leaf.slice(2) : leaf;
+  for (const sibling of proof) {
+    const sib = sibling.startsWith("0x") ? sibling.slice(2) : sibling;
+    current = hashPair(current, sib);
+  }
+  return current === root;
+}
+
+// ─── Universal source-table dispatch ──────────────────────────────────────────
+
+export type UniversalSourceTable =
+  | "hitl_approval"
+  | "agent_config_history"
+  | "pending_agent_config_change"
+  | "agent_run"
+  | "outcome_ledger";
+
+export interface ProofLeaf {
+  preimage_hash: string;
+  leaf_felt: string;
+}
+
+function req(row: Record<string, unknown>, field: string): unknown {
+  const v = row[field];
+  if (v === undefined) {
+    throw new Error(`[proof] missing field "${field}"`);
+  }
+  return v;
+}
+
+function asISO(v: unknown, field: string): string {
+  if (v instanceof Date) return v.toISOString();
+  if (typeof v === "string") return v;
+  throw new Error(`[proof] field "${field}" must be Date or ISO string`);
+}
+
+function asNullableISO(v: unknown, field: string): string | null {
+  if (v === null || v === undefined) return null;
+  return asISO(v, field);
+}
+
+function asInt(v: unknown, field: string): number {
+  if (typeof v === "number" && Number.isInteger(v)) return v;
+  if (typeof v === "string" && /^-?\d+$/.test(v)) return Number.parseInt(v, 10);
+  if (typeof v === "bigint") return Number(v);
+  throw new Error(`[proof] field "${field}" must be integer`);
+}
+
+function lower(v: unknown, field: string): string {
+  if (typeof v !== "string") {
+    throw new Error(`[proof] field "${field}" must be string`);
+  }
+  return v.toLowerCase();
+}
+
+const CANONICALIZERS: Record<
+  UniversalSourceTable,
+  (row: Record<string, unknown>) => Record<string, unknown>
+> = {
+  hitl_approval: (row) => ({
+    id: String(req(row, "id")),
+    agent_id: String(req(row, "agent_id")),
+    decision: lower(req(row, "decision"), "decision"),
+    evidence_hash: String(req(row, "evidence_hash")),
+    resolved_at: asISO(req(row, "resolved_at"), "resolved_at"),
+  }),
+  agent_config_history: (row) => {
+    const patch = req(row, "patch");
+    if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+      throw new Error(`[proof] patch must be object`);
+    }
+    return {
+      agent_id: String(req(row, "agent_id")),
+      patch: patch as Record<string, unknown>,
+      version: asInt(req(row, "version"), "version"),
+      changed_at: asISO(req(row, "changed_at"), "changed_at"),
+    };
+  },
+  agent_run: (row) => ({
+    id: String(req(row, "id")),
+    agent_id: String(req(row, "agent_id")),
+    status: lower(req(row, "status"), "status"),
+    evidence_hash: String(req(row, "evidence_hash")),
+    duration_ms: asInt(req(row, "duration_ms"), "duration_ms"),
+  }),
+  pending_agent_config_change: (row) => {
+    const patch = req(row, "proposed_patch");
+    if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+      throw new Error(`[proof] proposed_patch must be object`);
+    }
+    return {
+      id: String(req(row, "id")),
+      agent_id: String(req(row, "agent_id")),
+      proposed_patch: patch as Record<string, unknown>,
+      status: lower(req(row, "status"), "status"),
+      resolved_at: asNullableISO(row.resolved_at, "resolved_at"),
+    };
+  },
+  outcome_ledger: (row) => {
+    const v = row.value_centimes;
+    if (typeof v === "number" && !Number.isInteger(v)) {
+      throw new Error(
+        `[proof] outcome_ledger.value_centimes must be integer centimes`
+      );
+    }
+    return {
+      id: String(req(row, "id")),
+      agent_id: String(req(row, "agent_id")),
+      outcome_type: lower(req(row, "outcome_type"), "outcome_type"),
+      value_centimes: asInt(req(row, "value_centimes"), "value_centimes"),
+      recorded_at: asISO(req(row, "recorded_at"), "recorded_at"),
+    };
+  },
+};
+
+export function mkProofLeaf(
+  sourceTable: UniversalSourceTable,
+  row: Record<string, unknown>
+): ProofLeaf {
+  const fn = CANONICALIZERS[sourceTable];
+  if (!fn) throw new Error(`[proof] unknown source: ${sourceTable}`);
+  const hash = leafHash(fn(row));
+  return { preimage_hash: hash, leaf_felt: `0x${hash}` };
+}
+
+// ─── Sprint-521 Bloc 1: Poseidon proof module ─────────────────────────────────
+
+export type {
+  CertState,
+  LogSeverity,
+  RunStep,
+  RunProofCertificate,
+} from "./types.js";
+export {
+  computeLeafHash,
+  computeMerkleRoot,
+  NULL_LEAF,
+} from "@vauban-org/proof-core";
+export type { VerifyResult } from "./verify.js";
+export { verifyProofCertificate } from "./verify.js";
+export type { LoadProofCertificateOptions } from "./load.js";
+export { loadProofCertificate } from "./load.js";
+export type { OtelSpan } from "./otel.js";
+export { toOtelSpan } from "./otel.js";

package/src/proof/load.ts

@@ -0,0 +1,61 @@
+/**
+ * loadProofCertificate — REST client for /api/runs/:runId/proof-certificate.
+ *
+ * Fetches a RunProofCertificate from the Command Center API.
+ * Auth is optional: if getToken is provided it is called and the result is
+ * sent as a Bearer token; otherwise the request is sent unauthenticated
+ * (the endpoint has a public read tier for finalized runs).
+ *
+ * sprint-521 Bloc 1.
+ */
+
+import type { RunProofCertificate } from "./types.js";
+
+export interface LoadProofCertificateOptions {
+  runId: string;
+  baseUrl: string;
+  getToken?: () => Promise<string>;
+}
+
+/**
+ * Fetch a RunProofCertificate from the Command Center REST API.
+ *
+ * @param opts.runId   - UUID of the agent run.
+ * @param opts.baseUrl - Base URL of the Command Center API (no trailing slash).
+ * @param opts.getToken - Optional async function returning a Bearer token.
+ * @returns Parsed RunProofCertificate.
+ * @throws Error with HTTP status and parsed body on 4xx/5xx responses.
+ */
+export async function loadProofCertificate(
+  opts: LoadProofCertificateOptions,
+): Promise<RunProofCertificate> {
+  const { runId, baseUrl, getToken } = opts;
+
+  const url = `${baseUrl}/api/runs/${encodeURIComponent(runId)}/proof-certificate`;
+
+  const headers: Record<string, string> = {
+    Accept: "application/json",
+  };
+
+  if (getToken) {
+    const token = await getToken();
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+
+  const response = await fetch(url, { headers });
+
+  if (!response.ok) {
+    let body: string;
+    try {
+      body = await response.text();
+    } catch {
+      body = "(unreadable)";
+    }
+    throw new Error(
+      `[agent-sdk/proof] loadProofCertificate: HTTP ${response.status} — ${body}`,
+    );
+  }
+
+  const data = (await response.json()) as RunProofCertificate;
+  return data;
+}

package/src/proof/otel.ts

@@ -0,0 +1,74 @@
+/**
+ * toOtelSpan — maps a RunStep to an OpenTelemetry span shape.
+ *
+ * Follows OpenInference semantic conventions for GenAI:
+ *   https://github.com/Arize-ai/openinference/blob/main/spec/semantic_conventions.md
+ *
+ * sprint-521 Bloc 1.
+ */
+
+import type { RunStep } from "./types.js";
+
+export interface OtelSpan {
+  traceId: string;
+  spanId: string;
+  attributes: Record<string, string | number>;
+}
+
+/**
+ * Map a RunStep to an OpenTelemetry-compatible span descriptor.
+ *
+ * Uses OpenInference semantic conventions (gen_ai.*) for GenAI observability.
+ * traceId and spanId fall back to empty strings if not set on the step.
+ *
+ * @param step - RunStep from the proof certificate decision_chain or live run.
+ * @returns OtelSpan with traceId, spanId, and attributes.
+ */
+export function toOtelSpan(step: RunStep): OtelSpan {
+  const traceId = step.otel_trace_id ?? "";
+  const spanId = step.otel_span_id ?? "";
+
+  const attributes: Record<string, string | number> = {
+    // OpenInference GenAI conventions
+    "gen_ai.system": "vauban-command-center",
+    "gen_ai.operation.name": step.type,
+    "gen_ai.response.id": step.id,
+    // Run context
+    "run.id": step.run_id,
+    "run.step_index": step.step_index,
+    "run.step.type": step.type,
+    "run.step.status": step.status,
+    "run.step.started_at": step.started_at,
+  };
+
+  if (step.phase != null) {
+    attributes["run.step.phase"] = step.phase;
+  }
+
+  if (step.finished_at != null) {
+    attributes["run.step.finished_at"] = step.finished_at;
+  }
+
+  if (step.duration_ms != null) {
+    attributes["gen_ai.usage.total_tokens"] = step.duration_ms; // duration proxy
+    attributes["run.step.duration_ms"] = step.duration_ms;
+  }
+
+  if (step.leaf_hash_poseidon != null) {
+    attributes["proof.leaf_hash_poseidon"] = step.leaf_hash_poseidon;
+  }
+
+  if (step.mcp_call_hash != null) {
+    attributes["proof.mcp_call_hash"] = step.mcp_call_hash;
+  }
+
+  if (step.retrieval_proof_hash != null) {
+    attributes["proof.retrieval_proof_hash"] = step.retrieval_proof_hash;
+  }
+
+  if (step.error_message != null) {
+    attributes["exception.message"] = step.error_message;
+  }
+
+  return { traceId, spanId, attributes };
+}