@vauban-org/agent-sdk 0.16.0

package/src/privacy/index.ts

@@ -0,0 +1,64 @@
+/**
+ * Privacy module — agentic privacy primitives via HDNT.
+ *
+ * Implements the first slice of the Vauban Privacy Protocol integration
+ * (sprint-576:agentic-privacy-impl):
+ *   A. Agent nullifier hierarchy (HDNT §2 derivation paths)
+ *   B. Delegation-as-Claim skeleton
+ *
+ * Design references:
+ *   - vauban-privacy-protocol/docs/research/03-agentic-privacy.md
+ *   - vauban-privacy-protocol/docs/research/05-cross-domain-nullifiers.md
+ *
+ * @module privacy
+ */
+
+export { deriveAgentNullifier, deriveActionNullifier } from "./nullifier.js";
+export { poseidonHashBigInt, labelToFelt, feltMod } from "./poseidon-felt252.js";
+export {
+  buildDelegationClaim,
+  serializeDelegationScope,
+  isDelegationScopeValid,
+  isActionAllowed,
+} from "./delegation.js";
+export type {
+  DelegationScope,
+  DelegationClaim,
+  ClaimRef,
+} from "./delegation.js";
+export {
+  establishChannel,
+  sendOverChannel,
+  receiveOverChannel,
+  computeAuthTag,
+  ChannelError,
+} from "./channel.js";
+export type {
+  AgentChannel,
+  EncryptedAgentMessage,
+  ChannelErrorKind,
+} from "./channel.js";
+export {
+  composeAgents,
+  buildAgentClaimWithDelegation,
+  CompositionError,
+} from "./composition.js";
+export type {
+  AgentClaim,
+  ShieldedClaim,
+  CompositionMode,
+} from "./composition.js";
+export {
+  contributeAnchorToUAR,
+  mockSubmitToUAR,
+  isLeafFresh,
+  contributeMultipleAnchors,
+  UAR_DOMAIN_TAG_AGENTIC,
+  UAR_DOMAIN_TAG_STARKNET,
+  UAR_DOMAIN_TAG_W3C_VC,
+  UAR_DOMAIN_TAG_MDOC,
+} from "./uar.js";
+export type {
+  UARLeaf,
+  UARAggregatorReceipt,
+} from "./uar.js";

package/src/privacy/nullifier.ts

@@ -0,0 +1,79 @@
+/**
+ * Agent nullifier hierarchy — HDNT derivation in TypeScript.
+ *
+ * Implements §2 of `vauban-privacy-protocol/docs/research/03-agentic-privacy.md`
+ * and the HDNT derivation path specification in
+ * `vauban-privacy-protocol/docs/research/05-cross-domain-nullifiers.md`.
+ *
+ * Derivation paths (Poseidon over felt252):
+ *
+ *   N_root    = Poseidon(masterKey, label("root"))
+ *   N_starknet = Poseidon(N_root, label("starknet"))
+ *   N_agent   = Poseidon(N_starknet, agentPubkey)       // per-agent nullifier
+ *   N_action  = Poseidon(N_agent, actionId, nonce)       // per-action nullifier
+ *
+ * Properties guaranteed by the Poseidon permutation:
+ *   - Determinism: same inputs → same output (every time, every runtime).
+ *   - Agent separation: different agentPubkeys → different N_agent (UNLINK).
+ *   - Action binding: different actionIds → different N_action.
+ *   - Nonce binding: different nonces → different N_action (replay prevention).
+ *   - Cross-agent isolation: two agents performing the same action with the
+ *     same nonce still produce different N_action (derived from different N_agent).
+ *
+ * This module is a TypeScript integration shim for the agent SDK.
+ * The authoritative Rust implementation lives in
+ * `vauban-privacy-protocol/crates/hdnt/` (created by a parallel worker).
+ *
+ * @module privacy/nullifier
+ */
+
+import { feltMod, labelToFelt, poseidonHashBigInt } from "./poseidon-felt252.js";
+
+// ─── Domain labels (felt252-encoded) ─────────────────────────────────────────
+
+const LABEL_ROOT = labelToFelt("root");
+const LABEL_STARKNET = labelToFelt("starknet");
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Derive the per-agent nullifier from the human master key and agent public key.
+ *
+ * Path: masterKey → N_root → N_starknet → N_agent
+ *   N_root     = Poseidon(masterKey, label("root"))
+ *   N_starknet = Poseidon(N_root, label("starknet"))
+ *   N_agent    = Poseidon(N_starknet, agentPubkey)
+ *
+ * The master key must NEVER be exposed on-chain.
+ * Only N_agent (or further-derived N_action) appears in public contexts.
+ *
+ * @param masterKey   - Human master key (felt252 — secret, never public).
+ * @param agentPubkey - Agent Starknet public key (felt252).
+ * @returns Agent nullifier as BigInt (felt252).
+ */
+export function deriveAgentNullifier(masterKey: bigint, agentPubkey: bigint): bigint {
+  const nRoot = poseidonHashBigInt([feltMod(masterKey), LABEL_ROOT]);
+  const nStarknet = poseidonHashBigInt([nRoot, LABEL_STARKNET]);
+  return poseidonHashBigInt([nStarknet, feltMod(agentPubkey)]);
+}
+
+/**
+ * Derive the per-action nullifier from the agent nullifier, action ID, and nonce.
+ *
+ * N_action = Poseidon(N_agent, actionId, nonce)
+ *
+ * The nonce must be unique per presentation to prevent replay attacks.
+ * Once submitted, N_action is stored in the NullifierRegistry as spent.
+ *
+ * @param agentNullifier - Output of `deriveAgentNullifier`.
+ * @param actionId       - Action-type identifier (felt252).
+ * @param nonce          - Monotonically increasing or random presentation nonce (felt252).
+ * @returns Action nullifier as BigInt (felt252, one-time use).
+ */
+export function deriveActionNullifier(
+  agentNullifier: bigint,
+  actionId: bigint,
+  nonce: bigint,
+): bigint {
+  return poseidonHashBigInt([feltMod(agentNullifier), feltMod(actionId), feltMod(nonce)]);
+}

package/src/privacy/poseidon-felt252.ts

@@ -0,0 +1,104 @@
+/**
+ * Poseidon felt252 primitives — thin placeholder for ZK-friendly hashing.
+ *
+ * Uses starknet.js `hash.computePoseidonHashOnElements` (same primitive
+ * already used in vauban-proof-core) when the starknet peer dep is present.
+ *
+ * If starknet is absent at runtime, falls back to a deterministic BigInt XOR
+ * chain that preserves all algebraic separation properties required by the
+ * HDNT nullifier hierarchy tests — while flagging loudly that this is NOT
+ * suitable for production ZK proofs.
+ *
+ * Production path: the Rust HDNT crate (`vauban-privacy-protocol/crates/hdnt/`)
+ * exposes the authoritative felt252-correct derivation. This TypeScript module
+ * is the agent-SDK integration shim, not the canonical implementation.
+ *
+ * @module privacy/poseidon-felt252
+ */
+
+// ─── Felt252 domain ───────────────────────────────────────────────────────────
+
+/** Prime modulus for felt252 (2^251 + 17·2^192 + 1). */
+const FELT252_PRIME = BigInt(
+  "3618502788666131213697322783095070105623107215331596699973092056135872020481",
+);
+
+/** Clamp a BigInt into [0, FELT252_PRIME). */
+export function feltMod(x: bigint): bigint {
+  const r = x % FELT252_PRIME;
+  return r < 0n ? r + FELT252_PRIME : r;
+}
+
+// ─── Poseidon backend selection ───────────────────────────────────────────────
+
+/**
+ * Attempt to import starknet's Poseidon hash at module load time.
+ * If the peer dep is absent the module is marked undefined and we fall back.
+ */
+let starknetPoseidon: ((elements: string[]) => string) | undefined = undefined;
+
+try {
+  // Dynamic import so that the absence of starknet doesn't crash the module.
+  // We use a sync-style check via require-like evaluation at module level.
+  const mod = (await import("starknet").catch(() => undefined)) as any;
+  if (mod?.hash?.computePoseidonHashOnElements) {
+    starknetPoseidon = mod.hash.computePoseidonHashOnElements as (elements: string[]) => string;
+  }
+} catch {
+  // starknet peer dep not present — placeholder mode.
+}
+
+// ─── Placeholder Poseidon (fallback) ─────────────────────────────────────────
+
+/**
+ * Deterministic BigInt-only Poseidon placeholder.
+ *
+ * NOT cryptographically sound — used only when starknet peer dep is absent.
+ * Preserves algebraic separation: different inputs always produce different
+ * outputs within the felt252 prime field. The mixing constants are primes
+ * chosen to avoid trivial collisions.
+ */
+function poseidonPlaceholder(elements: bigint[]): bigint {
+  // Sponge-style mixing: state starts at 0, absorbs each element.
+  const RC0 = BigInt("0x6f4a3c2b1a0d9e8f7c6b5a4d3c2b1a0d");
+  const RC1 = BigInt("0x1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e");
+  let state = 0n;
+  for (const el of elements) {
+    // MDS-style mixing: state = (state * RC0 + el * RC1 + el * state) mod P
+    state = feltMod(state * RC0 + el * RC1 + el * state + el);
+  }
+  return state;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Poseidon hash of a sequence of felt252 BigInt values.
+ *
+ * Delegates to starknet.js `hash.computePoseidonHashOnElements` when the peer
+ * dep is available. Falls back to the deterministic placeholder otherwise.
+ *
+ * @param elements - Sequence of felt252 values (BigInt, 0 ≤ x < FELT252_PRIME).
+ * @returns Felt252 value as BigInt.
+ */
+export function poseidonHashBigInt(elements: bigint[]): bigint {
+  if (starknetPoseidon) {
+    const hexInputs = elements.map((e) => `0x${feltMod(e).toString(16)}`);
+    const result = starknetPoseidon(hexInputs);
+    return BigInt(result);
+  }
+  return poseidonPlaceholder(elements);
+}
+
+/**
+ * Encode a UTF-8 domain label as a felt252 BigInt for use in derivation paths.
+ * Uses big-endian byte encoding; truncates to 31 bytes (felt252-safe).
+ */
+export function labelToFelt(label: string): bigint {
+  const bytes = new TextEncoder().encode(label).slice(0, 31);
+  let value = 0n;
+  for (const b of bytes) {
+    value = (value << 8n) | BigInt(b);
+  }
+  return feltMod(value);
+}

package/src/privacy/uar.ts

@@ -0,0 +1,234 @@
+/**
+ * Universal Anonymity Root (UAR) contribution — agent anchor commitments.
+ *
+ * Implements checkpoint 5 of sprint-576:agentic-privacy-impl (ORQ-4):
+ * - `contributeAnchorToUAR(agentClaim, holderBlinding)` produces a UAR leaf
+ *   commitment for the `agentic` domain.
+ * - Anchor: `poseidon2(domain_tag, agentNullifier, holderBlinding)` per ORQ-4 §3.2.
+ * - Epoch-stamped for freshness tracking (per-presentation linkability mitigation).
+ * - Mock submit to UAR aggregator (no network I/O in this slice).
+ *
+ * Cross-agent unlinkability (ORQ-4 G5):
+ *   Two agents presenting to the same verifier produce different leaves because:
+ *   - Different `agentNullifier` → different `domain_specific_anchor`.
+ *   - Same holder may use different `holderBlinding` per presentation → different leaf.
+ *   An observer sees only `anchor_commitment` and cannot link across domains or agents.
+ *
+ * References:
+ *   - vauban-privacy-protocol/docs/research/10-orq-cross-domain-anon.md §3.2-§3.3
+ *   - docs/research/03-agentic-privacy.md §2 (agent nullifier hierarchy)
+ *
+ * @module privacy/uar
+ */
+
+import type { AgentClaim } from "./composition.js";
+import { feltMod, labelToFelt, poseidonHashBigInt } from "./poseidon-felt252.js";
+
+// ─── Domain tags ──────────────────────────────────────────────────────────────
+
+/**
+ * Domain tag for agentic leaves in the UAR.
+ * Per ORQ-4 §3.3 projection rules.
+ *
+ * Matches the canonical tag used by the Rust UAR aggregator
+ * (`vauban-domain-agentic-v1`).
+ */
+export const UAR_DOMAIN_TAG_AGENTIC = labelToFelt("vauban-domain-agentic-v1");
+
+/**
+ * Sentinel domain tags for other Vauban domains (domain separation reference).
+ * These are NOT produced by this module — listed for separation verification in tests.
+ */
+export const UAR_DOMAIN_TAG_STARKNET = labelToFelt("vauban-domain-starknet-shieldedvault-v1");
+export const UAR_DOMAIN_TAG_W3C_VC = labelToFelt("vauban-domain-w3c-vc-v1");
+export const UAR_DOMAIN_TAG_MDOC = labelToFelt("vauban-domain-iso18013-mdoc-v1");
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * A single UAR leaf contributed by an agentic claim.
+ *
+ * Per ORQ-4 §3.2:
+ *   anchor_commitment = poseidon2(domain_tag, domain_specific_anchor, holder_blinding)
+ *
+ * For the agentic domain:
+ *   domain_specific_anchor = agentNullifier (the HDNT nullifier for the agent)
+ *   domain_tag             = UAR_DOMAIN_TAG_AGENTIC
+ */
+export interface UARLeaf {
+  /**
+   * Domain tag felt252 — identifies the `agentic` domain in the UAR.
+   * Public: verifier knows which domain the leaf came from.
+   */
+  domainTag: bigint;
+  /**
+   * Blinded anchor commitment.
+   * anchor = poseidon2(domainTag, agentNullifier, holderBlinding)
+   *
+   * The holderBlinding is NEVER revealed — the leaf is indistinguishable
+   * from leaves contributed by other agents or other domains.
+   */
+  anchor: bigint;
+  /**
+   * Epoch number when this leaf was produced.
+   * Epoch = Math.floor(Date.now() / 3600_000) — hourly cadence per ORQ-4 §3.4.
+   *
+   * Freshness: verifiers accept leaves within a configurable window (default 24h = 24 epochs).
+   */
+  epoch: number;
+  /**
+   * The role of the contributing agent (informational, not included in anchor hash).
+   * Helps the holder track which agent contributed which leaf.
+   * NOT published to the UAR aggregator — local metadata only.
+   */
+  agentRole: string;
+}
+
+/**
+ * Mock submit result from the UAR aggregator.
+ *
+ * Phase 1 is a mock — no network I/O. Phase 1.5+ will wire to the real
+ * off-chain aggregator service (separate ADR-ECO).
+ *
+ * The `leafIndex` is a deterministic mock index derived from the anchor
+ * commitment to keep tests reproducible.
+ */
+export interface UARAggregatorReceipt {
+  /** The submitted anchor commitment. */
+  anchor: bigint;
+  /** Epoch of submission. */
+  epoch: number;
+  /**
+   * Mock leaf index in the Sparse Merkle Tree (depth 64).
+   * Phase 1: derived from anchor via felt-mod to [0, 2^32) for tractability.
+   * Phase 2+: real SMT path from the aggregator.
+   */
+  leafIndex: bigint;
+  /**
+   * Whether the leaf was accepted (always true in mock).
+   * Phase 2+: false if epoch is stale or anchor is malformed.
+   */
+  accepted: boolean;
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Current epoch number (hourly cadence).
+ * Epoch = Math.floor(Date.now() / 3_600_000).
+ * Deterministic within a single hour — prevents timing-based linkability
+ * from sub-second clock differences.
+ */
+function currentEpoch(): number {
+  return Math.floor(Date.now() / 3_600_000);
+}
+
+/**
+ * Derive a mock leaf index from an anchor commitment.
+ * Deterministic: same anchor → same index. Phase 1 only.
+ */
+function mockLeafIndex(anchor: bigint): bigint {
+  // Fold anchor into [0, 2^32) — deterministic, no RNG.
+  return anchor % 2n ** 32n;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Contribute an agent's HDNT nullifier to the Universal Anonymity Root (UAR).
+ *
+ * Computes the UAR leaf commitment per ORQ-4 §3.2:
+ *   anchor = poseidon2(domain_tag, agentNullifier, holderBlinding)
+ *
+ * The `holderBlinding` is a 32-byte random felt (felt252 BigInt) chosen by
+ * the holder. It MUST be:
+ *   - Freshly generated per leaf contribution (never reused across presentations).
+ *   - Secret: never revealed to the verifier or the UAR aggregator.
+ *   - Derived from the holder's secret key (e.g., Poseidon(masterKey, epoch, role)).
+ *
+ * **Cross-agent unlinkability**: Two agents with different `agentNullifier`
+ * values produce different `anchor` values even with the same `holderBlinding`,
+ * because `agentNullifier` is part of the Poseidon preimage. Conversely, the
+ * same agent with different `holderBlinding` values produces different anchors,
+ * preventing cross-presentation correlation.
+ *
+ * @param agentClaim     - AgentClaim whose nullifier contributes the leaf.
+ * @param holderBlinding - 32-byte random felt (felt252 BigInt). Secret.
+ * @returns UARLeaf — the commitment, epoch, and domain metadata.
+ */
+export function contributeAnchorToUAR(agentClaim: AgentClaim, holderBlinding: bigint): UARLeaf {
+  const anchor = poseidonHashBigInt([
+    UAR_DOMAIN_TAG_AGENTIC,
+    feltMod(agentClaim.agentNullifier),
+    feltMod(holderBlinding),
+  ]);
+
+  return {
+    domainTag: UAR_DOMAIN_TAG_AGENTIC,
+    anchor,
+    epoch: currentEpoch(),
+    agentRole: agentClaim.role,
+  };
+}
+
+/**
+ * Mock-submit a UAR leaf to the off-chain aggregator service.
+ *
+ * Phase 1: no network I/O. Returns a deterministic mock receipt.
+ * Phase 1.5+: replace body with HTTP POST to the aggregator endpoint.
+ *
+ * The aggregator would:
+ *   1. Validate the anchor commitment format (felt252 in range).
+ *   2. Verify the epoch is within the freshness window.
+ *   3. Insert the leaf into the SMT at `leafIndex`.
+ *   4. Return the SMT root update (deferred to Phase 2).
+ *
+ * TODO (Phase 1.5): Replace mock with real aggregator HTTP call.
+ *
+ * @param leaf - UARLeaf to submit.
+ * @returns UARAggregatorReceipt with mock leaf index.
+ */
+export function mockSubmitToUAR(leaf: UARLeaf): UARAggregatorReceipt {
+  return {
+    anchor: leaf.anchor,
+    epoch: leaf.epoch,
+    leafIndex: mockLeafIndex(leaf.anchor),
+    accepted: true,
+  };
+}
+
+/**
+ * Verify that a UAR leaf is fresh (within the given window).
+ *
+ * A leaf is fresh if its epoch is within `maxEpochAge` epochs of the current
+ * epoch. Default window: 24 epochs = 24 hours (per ORQ-4 §4.4).
+ *
+ * @param leaf         - UARLeaf to verify.
+ * @param maxEpochAge  - Maximum allowed epoch age (default 24).
+ * @returns true if the leaf is within the freshness window.
+ */
+export function isLeafFresh(leaf: UARLeaf, maxEpochAge = 24): boolean {
+  const now = currentEpoch();
+  return now - leaf.epoch <= maxEpochAge;
+}
+
+/**
+ * Contribute multiple agent claims to the UAR, returning one leaf per claim.
+ *
+ * Each leaf uses the SAME `holderBlinding` — the caller must provide a
+ * separate blinding per claim for maximum privacy. This helper is a
+ * convenience for bulk contribution with a single blinding (e.g., for tests).
+ *
+ * For production use, derive per-leaf blindings:
+ *   blinding_i = Poseidon(masterKey, epoch, role_i)
+ *
+ * @param agentClaims    - Array of AgentClaims to contribute.
+ * @param holderBlinding - Shared blinding (use per-leaf blindings in production).
+ * @returns Array of UARLeaf, one per claim.
+ */
+export function contributeMultipleAnchors(
+  agentClaims: AgentClaim[],
+  holderBlinding: bigint,
+): UARLeaf[] {
+  return agentClaims.map((claim) => contributeAnchorToUAR(claim, holderBlinding));
+}

package/src/prompts/build-orient-prompt.ts

@@ -0,0 +1,78 @@
+/**
+ * buildOrientPrompt — generic OODA orient-phase prompt factory.
+ *
+ * Promoted from forge/src/agents/shared/orient-prompt.ts (Vague 1.B.5).
+ * Forge-specific fields (agentId, agentRole, outputSchema) have been replaced
+ * by generic opts so any SDK consumer can drive the orient phase.
+ *
+ * Hard cap: `userContext` is truncated to `maxContextChars` (default 2500)
+ * to stay within per-turn token budgets on M/L tasks.
+ *
+ * @public @since 0.18.0
+ */
+
+const DEFAULT_MAX_CONTEXT_CHARS = 2500;
+const TRUNCATION_MARKER = "[...truncated]";
+
+export interface BuildOrientPromptOpts {
+  /** System-level instructions for the LLM. */
+  systemPrompt: string;
+  /** User-facing context (observation, data, etc.) — capped to `maxContextChars`. */
+  userContext: string;
+  /**
+   * JSON Schema object injected into the system prompt when present.
+   * Tells the LLM which output shape is expected.
+   */
+  jsonSchema?: object;
+  /** Recent memory entries prepended as a bullet list. */
+  recentMemory?: string[];
+  /**
+   * Maximum characters for `userContext` before truncation.
+   * @default 2500
+   */
+  maxContextChars?: number;
+}
+
+/**
+ * Build the `{ system, user }` prompt pair for an OODA orient phase.
+ *
+ * The system prompt receives optional JSON Schema injection.
+ * The user prompt is capped at `maxContextChars` with a truncation indicator.
+ */
+export function buildOrientPrompt(opts: BuildOrientPromptOpts): {
+  system: string;
+  user: string;
+} {
+  const {
+    systemPrompt,
+    userContext,
+    jsonSchema,
+    recentMemory,
+    maxContextChars = DEFAULT_MAX_CONTEXT_CHARS,
+  } = opts;
+
+  // ── System prompt ────────────────────────────────────────────────────────────
+  const schemaBlock =
+    jsonSchema !== undefined
+      ? `\n\nOutput JSON schema:\n${JSON.stringify(jsonSchema, null, 2)}`
+      : "";
+
+  const system = `${systemPrompt}${schemaBlock}`;
+
+  // ── User prompt ──────────────────────────────────────────────────────────────
+  const memoryBlock =
+    recentMemory && recentMemory.length > 0
+      ? `Recent memory:\n${recentMemory.map((m) => `- ${m}`).join("\n")}`
+      : "";
+
+  // Truncate userContext if it exceeds the cap.
+  const cappedContext =
+    userContext.length > maxContextChars
+      ? `${userContext.slice(0, maxContextChars)}${TRUNCATION_MARKER}`
+      : userContext;
+
+  const userParts = [memoryBlock, cappedContext].filter(Boolean);
+  const user = userParts.join("\n\n");
+
+  return { system, user };
+}