@vauban-org/agent-sdk 0.16.0

package/src/trace/schema.ts

@@ -0,0 +1,245 @@
+/**
+ * TRACE_V1 schema — Audit-ready immutable trace format.
+ *
+ * Design:
+ *   - Chain-of-custody via prevStepHash + stepHash (SHA-256 Merkle chain).
+ *   - Anti-splice: every step carries runId (AR6).
+ *   - Anti-truncation: Trace.totalSteps cross-verified against steps.length.
+ *   - HITL transitions: via 'hitl' phase + 'hitl_gate' type (no parentStepIndex — hierarchy via 'handoff_initiated' event, R8-B2).
+ *   - TSA receipt optional (present | pending | failed).
+ *   - Config hash (CH9): configHash = SHA-256(canonical(config)).
+ *   - Agent signature reserved (CH8).
+ *
+ * @module trace/schema
+ */
+
+/** Semver version of this trace schema. Increment MINOR on additive changes,
+ *  MAJOR on breaking changes (new required fields or removed fields). */
+export const TRACE_SCHEMA_VERSION = "0.1.0-draft" as const;
+
+/** Status of an optional TSA receipt for a Trace. */
+export type ReceiptStatus = "present" | "pending" | "failed";
+
+/**
+ * A single step in a ReAct/OODA agent run.
+ * Steps form an append-only chain: each step hashes its predecessor.
+ */
+export interface TraceStep {
+  /** Zero-based monotone index within the run. */
+  index: number;
+
+  /**
+   * Run identifier — repeated on every step to prevent splice attacks (AR6).
+   * Cross-verified against Trace.runId at verification time.
+   */
+  runId: string;
+
+  /**
+   * OODA / ReAct phase of this step.
+   * - observe: input collection / perception
+   * - orient: context enrichment / memory retrieval
+   * - decide: LLM reasoning step
+   * - act: tool execution / side-effect
+   * - feedback: result integration
+   * - guard: safety / policy check
+   * - hitl: human-in-the-loop gate
+   */
+  phase:
+    | "observe"
+    | "orient"
+    | "decide"
+    | "act"
+    | "feedback"
+    | "guard"
+    | "hitl";
+
+  /**
+   * Structural type of this step.
+   * NOTE: hierarchy of sub-agents is encoded via a 'handoff_initiated'
+   * event (R8-B2) — NOT via parentStepIndex, which is intentionally absent.
+   */
+  type:
+    | "llm_call"
+    | "tool_call"
+    | "guard_check"
+    | "phase_transition"
+    | "hitl_gate";
+
+  /** Unix epoch milliseconds when this step started. */
+  timestamp: number;
+
+  /** Wall-clock duration of this step in milliseconds. */
+  durationMs: number;
+
+  /**
+   * SHA-256(canonical(redacted_or_hashed_input)).
+   * Always present regardless of policy.
+   */
+  inputHash: string;
+
+  /**
+   * HMAC-SHA-256(canonical(original_input), out-of-band_key).
+   * Present only when policy is 'hmac'. Allows offline re-verification
+   * without storing plaintext.
+   */
+  inputOriginalHmac?: string;
+
+  /**
+   * Stored payload according to the policy:
+   *   - 'include': full redacted value
+   *   - 'redact': object with PII fields removed
+   *   - 'hmac': undefined (only hash + hmac stored)
+   *   - 'hash-only': undefined
+   */
+  storedInput?: unknown;
+
+  /** SHA-256(canonical(redacted_or_hashed_output)). Always present. */
+  outputHash: string;
+
+  /** HMAC-SHA-256(canonical(original_output), out-of-band_key). Present when policy is 'hmac'. */
+  outputOriginalHmac?: string;
+
+  /** Stored output payload per policy (same semantics as storedInput). */
+  storedOutput?: unknown;
+
+  /**
+   * Effective payload policy for this step.
+   * Derived from PayloadPolicy.kind at trace-build time.
+   */
+  policy: "include" | "redact" | "hmac" | "hash-only";
+
+  /** LLM token usage. Undefined for non-LLM steps. */
+  tokens?: {
+    input: number;
+    output: number;
+    /** Prompt-cache read tokens (Anthropic / OpenAI). */
+    cacheRead?: number;
+  };
+
+  /** Estimated cost in USD for this step. Undefined for non-billable steps. */
+  costUsd?: number;
+
+  /** LLM model that produced this step. Undefined for non-LLM steps. */
+  model?: {
+    provider: string;
+    name: string;
+    version: string;
+  };
+
+  /** Tool name for 'tool_call' steps. */
+  toolName?: string;
+
+  /** Guard name for 'guard_check' steps. */
+  guardName?: string;
+
+  /**
+   * Hash of the previous step's stepHash (or all-zeros for step 0).
+   * Enables chain-of-custody verification: any tampering or reordering
+   * breaks the chain.
+   */
+  prevStepHash: string;
+
+  /**
+   * SHA-256(canonical({ ...step fields (excluding stepHash), runId })).
+   * Computed after all other fields are set.
+   */
+  stepHash: string;
+}
+
+/**
+ * RFC 3161 / TSA-style timestamping receipt.
+ * Optional — traces without a receipt still have integrity via
+ * the Merkle chain; the receipt adds a trusted external timestamp.
+ */
+export interface SignedReceipt {
+  /** TSA endpoint URL that issued this receipt. */
+  tsa: string;
+  /** ISO-8601 timestamp from the TSA. */
+  timestamp: string;
+  /** TSA-issued signature (base64). */
+  signature: string;
+  /** Hash algorithm used. Always sha-256 in this schema version. */
+  algorithm: "sha-256";
+  /** The message hash that was timestamped (= Trace.rootHash). */
+  hashedMessage: string;
+  /** TSA certificate chain (PEM, base64). Optional — may be pinned out-of-band. */
+  certChain?: string[];
+}
+
+/**
+ * A complete, verifiable trace of one agent run.
+ *
+ * Integrity invariants:
+ *   - steps[i].prevStepHash === steps[i-1].stepHash (chain)
+ *   - steps[i].runId === runId (anti-splice)
+ *   - steps.length === totalSteps (anti-truncation)
+ *   - rootHash === SHA-256(canonical(steps.map(s => s.stepHash)))
+ *   - configHash === SHA-256(canonical(config)) (CH9)
+ */
+export interface Trace {
+  /** Schema version for forward-compatibility checks. */
+  schemaVersion: typeof TRACE_SCHEMA_VERSION;
+
+  /** Unique identifier for this run. UUID v4 recommended. */
+  runId: string;
+
+  /** Identifier of the agent that produced this trace. */
+  agentId: string;
+
+  /** Semantic version of the agent code. */
+  agentVersion: string;
+
+  /** Unix epoch milliseconds when the run started. */
+  startedAt: number;
+
+  /** Unix epoch milliseconds when the run finished. */
+  completedAt: number;
+
+  /** Terminal status of the run. */
+  status: "completed" | "failed" | "skipped";
+
+  /** Ordered list of steps. */
+  steps: TraceStep[];
+
+  /**
+   * Anti-truncation guard: must equal steps.length.
+   * A mismatch signals that steps were removed after the trace was finalized.
+   */
+  totalSteps: number;
+
+  /**
+   * SHA-256(canonical(steps.map(s => s.stepHash))).
+   * The root of the step Merkle chain.
+   */
+  rootHash: string;
+
+  /**
+   * Arbitrary run configuration (model IDs, pipeline params, env flags, …).
+   * Stored as-is; hashed separately for tamper-evidence.
+   */
+  config: Record<string, unknown>;
+
+  /**
+   * SHA-256(canonical(config)) — CH9.
+   * Verifiers recompute this to detect config drift between runs.
+   */
+  configHash: string;
+
+  /**
+   * Reserved for a future agent-level signature (CH8).
+   * When present, agentSignature = Sign(rootHash, agentPrivKey).
+   */
+  agentSignature?: string;
+
+  /** TSA receipt if external timestamping was requested. */
+  receipt?: SignedReceipt;
+
+  /** Status of the TSA receipt fetch. */
+  receiptStatus?: ReceiptStatus;
+
+  /**
+   * Unix epoch milliseconds for the next receipt retry attempt.
+   * Set when receiptStatus === 'pending'.
+   */
+  receiptRetryAt?: number;
+}

package/src/trace/strict-pii-detector.ts

@@ -0,0 +1,156 @@
+/**
+ * STRICT_PII_DETECTOR — ultra-conservative, opt-in PIIDetector.
+ *
+ * Detects:
+ *   - Email addresses (RFC 5321 — local-part + domain + TLD ≥ 2 chars)
+ *   - IBANs (ISO 13616 — country code + check digits mod-97 + BBAN)
+ *
+ * Intentionally NOT detecting:
+ *   - Phone numbers: catastrophic false-positive rate on amounts and IDs.
+ *   - SSN / NSS: locale-dependent patterns with high FP on numeric sequences.
+ *
+ * Activation:
+ *   This detector is NEVER activated by defaultPolicy() (R8-I3).
+ *   Opt in explicitly:
+ *     { kind: 'redact', piiFields: ['email'], piiDetector: STRICT_PII_DETECTOR }
+ *
+ * @module trace/strict-pii-detector
+ */
+
+import type { PIIDetector } from "./policy.js";
+
+// ─── Email (RFC 5321) ────────────────────────────────────────────────────────
+//
+// Local-part: printable ASCII except @, <, >, (, ), [, ], :, ;, \, ,, .
+//   except that . is allowed when not leading, trailing, or consecutive.
+// Domain: standard hostname labels (alphanum + hyphen, no leading/trailing hyphen).
+// TLD: at least 2 alpha chars (no all-numeric TLDs accepted).
+//
+// We intentionally reject IP-literal domains ([1.2.3.4]) and quoted strings
+// in the local part — they are valid RFC 5321 but extremely rare in practice
+// and high false-positive risk.
+
+const EMAIL_REGEX =
+  /^[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\.[a-zA-Z]{2,}$/;
+
+function isEmail(value: string): boolean {
+  return EMAIL_REGEX.test(value.trim());
+}
+
+// ─── IBAN (ISO 13616) ────────────────────────────────────────────────────────
+//
+// Structure: CC DD BBAN
+//   CC = 2-letter ISO 3166-1 alpha-2 country code
+//   DD = 2-digit check digits
+//   BBAN = country-specific (alphanumeric, variable length)
+// Total length: 15–34 characters (no spaces in canonical form).
+//
+// Checksum (mod-97-10):
+//   1. Move CC + DD to the end.
+//   2. Replace each letter with its decimal value (A=10, B=11, ..., Z=35).
+//   3. Compute the resulting integer mod 97.
+//   4. Valid IBAN → result === 1.
+//
+// Country codes: hardcoded list of all ISO 13616 registered countries (2026-04-30).
+// We reject any 2-letter prefix NOT in this list to avoid false positives.
+
+const IBAN_COUNTRY_CODES = new Set([
+  "AD", "AE", "AL", "AT", "AZ",
+  "BA", "BE", "BG", "BH", "BR", "BY",
+  "CH", "CR", "CY", "CZ",
+  "DE", "DK", "DO",
+  "EE", "EG", "ES",
+  "FI", "FK", "FO", "FR",
+  "GB", "GE", "GI", "GL", "GR", "GT",
+  "HR", "HU",
+  "IE", "IL", "IQ", "IS",
+  "IT",
+  "JO",
+  "KW", "KZ",
+  "LB", "LC", "LI", "LT", "LU", "LV",
+  "LY",
+  "MC", "MD", "ME", "MK", "MN", "MR", "MT", "MU",
+  "NI", "NL", "NO",
+  "PK", "PL", "PS", "PT",
+  "QA",
+  "RO", "RS", "RU",
+  "SA", "SC", "SD", "SE", "SI", "SK", "SM", "SO", "ST", "SV",
+  "TL", "TN", "TR",
+  "UA",
+  "VA", "VG",
+  "XK",
+  "YE",
+]);
+
+/** Strip whitespace and uppercase for canonical form. */
+function normaliseIban(raw: string): string {
+  return raw.replace(/\s/g, "").toUpperCase();
+}
+
+/**
+ * Compute mod-97 of a large numeric string represented as a string.
+ * We process 9 digits at a time to avoid BigInt or floating-point overflow.
+ */
+function mod97(numericStr: string): number {
+  let remainder = 0;
+  for (let i = 0; i < numericStr.length; i += 9) {
+    const chunk = String(remainder) + numericStr.slice(i, i + 9);
+    remainder = parseInt(chunk, 10) % 97;
+  }
+  return remainder;
+}
+
+/**
+ * Convert IBAN characters to their numeric equivalents:
+ *   A=10, B=11, …, Z=35 ; digits stay as-is.
+ */
+function ibanToNumericString(iban: string): string {
+  let result = "";
+  for (const ch of iban) {
+    const code = ch.charCodeAt(0);
+    if (code >= 65 && code <= 90) {
+      // A-Z → 10-35
+      result += String(code - 55);
+    } else {
+      result += ch;
+    }
+  }
+  return result;
+}
+
+function isIban(value: string): boolean {
+  const normalised = normaliseIban(value);
+
+  // Length check: 15–34 chars
+  if (normalised.length < 15 || normalised.length > 34) return false;
+
+  // Country code check
+  const countryCode = normalised.slice(0, 2);
+  if (!IBAN_COUNTRY_CODES.has(countryCode)) return false;
+
+  // Only alphanumeric characters after country code + check digits
+  if (!/^[A-Z]{2}[0-9]{2}[A-Z0-9]+$/.test(normalised)) return false;
+
+  // Rearrange: move first 4 chars to end
+  const rearranged = normalised.slice(4) + normalised.slice(0, 4);
+
+  // Convert to numeric string and check mod-97
+  const numericStr = ibanToNumericString(rearranged);
+  return mod97(numericStr) === 1;
+}
+
+// ─── PIIDetector implementation ───────────────────────────────────────────────
+
+/**
+ * Ultra-conservative PII detector for strings.
+ * Returns true only for values that match email or IBAN patterns with checksum.
+ *
+ * Note: operates on leaves of the value tree only (non-string values → false).
+ * The redaction logic in policy.ts handles recursive traversal.
+ */
+export const STRICT_PII_DETECTOR: PIIDetector = (value: unknown): boolean => {
+  if (typeof value !== "string") return false;
+  const trimmed = value.trim();
+  if (trimmed.length === 0) return false;
+  return isEmail(trimmed) || isIban(trimmed);
+};

package/src/tracing/traced-port.ts

@@ -0,0 +1,149 @@
+/**
+ * tracedPort — instrument any port implementation with OTel spans.
+ *
+ * Sprint-460 — ships uniform observability for BrainPort / OutcomePort /
+ * DbPort / any host-injected async surface. Wraps every function-valued
+ * method of the impl in a span rooted at the active context; attributes
+ * follow OpenTelemetry Semantic Conventions for GenAI operations where
+ * applicable (gen_ai.system, gen_ai.operation.name).
+ *
+ * Usage:
+ *   const raw: BrainPort = buildHttpBrain(...);
+ *   const traced = tracedPort(raw, { portName: "brain", tracerName: "vauban-agent-sdk" });
+ *   // traced.archiveKnowledge(...) emits a span per call.
+ *
+ * Transparent: the proxy's type is identical to T. Non-function fields
+ * are forwarded unchanged. Sync methods still get a span (they complete
+ * within the synchronous call frame).
+ *
+ * Opt-out: if no tracer is configured (getTracer returns the noop tracer,
+ * which is the OTel default when no SDK is installed), spans become
+ * no-ops — zero runtime cost for consumers who don't want tracing.
+ */
+
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+
+export interface TracedPortOptions {
+  /**
+   * Short port identifier, e.g. "brain", "outcome", "db". Emitted as
+   * `gen_ai.system` attribute and used in span names.
+   */
+  portName: string;
+  /**
+   * OTel tracer name. Defaults to "vauban-agent-sdk".
+   */
+  tracerName?: string;
+  /**
+   * Optional hook to enrich the span with impl-specific attributes
+   * before it completes. Receives the span, method name, and the
+   * args/return-value of the call.
+   */
+  attributeHook?: (ctx: {
+    span: Span;
+    method: string;
+    args: readonly unknown[];
+    result?: unknown;
+  }) => void;
+}
+
+/**
+ * Wrap a port impl. Returns a proxy with the same type, instrumented.
+ */
+export function tracedPort<T extends object>(
+  impl: T,
+  options: TracedPortOptions,
+): T {
+  const tracer = trace.getTracer(options.tracerName ?? "vauban-agent-sdk");
+  const { portName } = options;
+
+  return new Proxy(impl, {
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value !== "function") return value;
+      const methodName = String(prop);
+
+      // Return a wrapper that traces each call. Preserve `this` = impl.
+      const wrapped = function (this: unknown, ...args: unknown[]) {
+        return tracer.startActiveSpan(
+          `${portName}.${methodName}`,
+          {
+            attributes: {
+              "gen_ai.system": portName,
+              "gen_ai.operation.name": methodName,
+            },
+          },
+          (span) => {
+            try {
+              const out = (value as (...a: unknown[]) => unknown).apply(
+                target,
+                args,
+              );
+
+              // Async path: settle the span on promise resolution.
+              if (out instanceof Promise) {
+                return out.then(
+                  (result) => {
+                    options.attributeHook?.({
+                      span,
+                      method: methodName,
+                      args,
+                      result,
+                    });
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    span.end();
+                    return result;
+                  },
+                  (err: unknown) => {
+                    recordError(span, err);
+                    span.end();
+                    throw err;
+                  },
+                );
+              }
+
+              // Sync path.
+              options.attributeHook?.({
+                span,
+                method: methodName,
+                args,
+                result: out,
+              });
+              span.setStatus({ code: SpanStatusCode.OK });
+              span.end();
+              return out;
+            } catch (err) {
+              recordError(span, err);
+              span.end();
+              throw err;
+            }
+          },
+        );
+      };
+      // Preserve function name for stack traces + debugging.
+      Object.defineProperty(wrapped, "name", { value: methodName });
+      return wrapped;
+    },
+  }) as T;
+}
+
+function recordError(span: Span, err: unknown): void {
+  const message =
+    err instanceof Error
+      ? err.message
+      : typeof err === "string"
+        ? err
+        : "error";
+  span.setStatus({ code: SpanStatusCode.ERROR, message });
+  if (err instanceof Error) span.recordException(err);
+  // Surface PortError metadata when present (port-side observability).
+  if (err && typeof err === "object") {
+    const anyErr = err as { port?: unknown; retryable?: unknown };
+    if (typeof anyErr.port === "string") {
+      span.setAttribute("vauban.port.error.port", anyErr.port);
+    }
+    if (typeof anyErr.retryable === "boolean") {
+      span.setAttribute("vauban.port.error.retryable", anyErr.retryable);
+    }
+  }
+}