@vauban-org/agent-sdk 0.16.0

package/src/privacy/channel.ts

@@ -0,0 +1,283 @@
+/**
+ * Shielded inter-agent communication channels — ML-KEM-768 stub.
+ *
+ * Implements checkpoint 2 of sprint-576:agentic-privacy-impl.
+ *
+ * Design references:
+ *   - vauban-privacy-protocol/docs/research/03-agentic-privacy.md — agent privacy design.
+ *   - vauban-privacy-protocol/docs/research/07-orq-stealth-addressing.md §3.5 — channel-key
+ *     construction adapted for inter-agent use.
+ *
+ * STUB note: The key exchange uses a Poseidon-based derivation as a placeholder for
+ * ML-KEM-768 (CRYSTALS-Kyber, NIST PQC standard). The stream cipher uses a
+ * Poseidon-derived keystream as a placeholder for a proper AEAD (e.g., AES-256-GCM
+ * or ChaCha20-Poly1305). Both are deterministic and separation-preserving but NOT
+ * cryptographically sound for production use.
+ *
+ * TODO (ORQ-1): Replace establishChannel with ML-KEM-768 Encaps + Poseidon2 KDF.
+ * TODO (ORQ-1): Replace sendOverChannel stream cipher with AES-256-GCM or ChaCha20-Poly1305.
+ *
+ * @module privacy/channel
+ */
+
+import { feltMod, labelToFelt, poseidonHashBigInt } from "./poseidon-felt252.js";
+
+// ─── Domain labels ────────────────────────────────────────────────────────────
+
+const LABEL_CHANNEL = labelToFelt("vauban-agent-channel-v1");
+const LABEL_CHANNEL_ID = labelToFelt("channel-id");
+const LABEL_KEYSTREAM = labelToFelt("keystream");
+const LABEL_AUTH_TAG = labelToFelt("auth-tag");
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * A shielded bidirectional channel between two agents.
+ *
+ * The channel is directional: sender and receiver roles are asymmetric.
+ * Swapping sender/receiver produces a different channel_id and shared_secret,
+ * preventing cross-direction replay attacks.
+ */
+export interface AgentChannel {
+  /** Sender's Starknet public key (felt252). */
+  sender_pubkey: bigint;
+  /** Receiver's Starknet public key (felt252). */
+  receiver_pubkey: bigint;
+  /**
+   * Channel identifier — derived from the shared secret.
+   * Safe to include in message headers (public) without revealing the secret.
+   */
+  channel_id: bigint;
+  /**
+   * Shared secret — output of STUB key exchange (Poseidon-derived).
+   * TODO (ORQ-1): Replace with ML-KEM-768 Encaps output + Poseidon2 KDF.
+   * NEVER expose on-chain or in logs.
+   */
+  shared_secret: bigint;
+  /** Unix timestamp (ms) when the channel was established. */
+  established_at: number;
+}
+
+/**
+ * An encrypted message sent over a shielded agent channel.
+ *
+ * The integrity tag (`tag`) authenticates `(channel_id, nonce, ciphertext)` using
+ * the shared secret. A tampered ciphertext or wrong channel produces a tag mismatch.
+ */
+export interface EncryptedAgentMessage {
+  /** Channel this message belongs to (public, used for routing). */
+  channel_id: bigint;
+  /** Monotonically increasing nonce (felt252). Replay protection. */
+  nonce: bigint;
+  /** Encrypted payload — XOR of plaintext with Poseidon-derived keystream (STUB). */
+  ciphertext: Uint8Array;
+  /**
+   * HMAC-style authentication tag.
+   * tag = Poseidon(shared_secret, nonce, hash(ciphertext)).
+   * Verifying this tag before decryption prevents chosen-ciphertext attacks.
+   */
+  tag: bigint;
+}
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+export const ChannelError = {
+  /** The message's channel_id does not match the provided channel. */
+  MismatchedChannel: "MismatchedChannel",
+  /** The authentication tag does not match — ciphertext tampered or wrong key. */
+  InvalidTag: "InvalidTag",
+  /** The message nonce is not strictly greater than the expected previous nonce. */
+  ReplayedNonce: "ReplayedNonce",
+  /** Channel has not been established (stub for future async establishment). */
+  ChannelNotEstablished: "ChannelNotEstablished",
+} as const;
+
+export type ChannelErrorKind = (typeof ChannelError)[keyof typeof ChannelError];
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Hash a Uint8Array into a felt252 BigInt for use in the auth tag computation.
+ * Uses a simple XOR-folding into felt252 — not a cryptographic hash.
+ * TODO (ORQ-1): Replace with Poseidon2 sponge over byte chunks.
+ */
+function hashBytes(bytes: Uint8Array): bigint {
+  // Fold byte array into felt252: accumulate in 31-byte (248-bit) chunks.
+  let acc = 0n;
+  let chunk = 0n;
+  let shift = 0n;
+  for (let i = 0; i < bytes.length; i++) {
+    chunk = chunk | (BigInt(bytes[i] ?? 0) << shift);
+    shift += 8n;
+    if (shift >= 248n || i === bytes.length - 1) {
+      acc = feltMod(acc ^ chunk);
+      chunk = 0n;
+      shift = 0n;
+    }
+  }
+  return acc;
+}
+
+/**
+ * Derive a 248-bit keystream word from the shared secret and a nonce.
+ * Used as a one-time pad for a single 31-byte block of plaintext.
+ * TODO (ORQ-1): Replace with proper AEAD keystream (ChaCha20-Poly1305 or AES-256-GCM).
+ */
+function deriveKeystreamWord(sharedSecret: bigint, nonce: bigint, blockIndex: bigint): bigint {
+  return poseidonHashBigInt([
+    feltMod(sharedSecret),
+    feltMod(nonce),
+    LABEL_KEYSTREAM,
+    feltMod(blockIndex),
+  ]);
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Establish a shielded inter-agent channel.
+ *
+ * STUB implementation: derives shared_secret via Poseidon over (senderSk, receiverPk,
+ * domain label). The channel is directional — sender and receiver roles are asymmetric
+ * by design (swapping them produces a different channel_id).
+ *
+ * TODO (ORQ-1): Replace with ML-KEM-768 Encaps + Poseidon2 KDF per
+ * vauban-privacy-protocol/docs/research/07-orq-stealth-addressing.md §3.5.
+ *
+ * @param senderSk   - Sender's secret key (felt252, NEVER expose).
+ * @param receiverPk - Receiver's public key (felt252).
+ * @returns AgentChannel with shared_secret and channel_id.
+ */
+export function establishChannel(senderSk: bigint, receiverPk: bigint): AgentChannel {
+  // TODO: ML-KEM-768 Encaps + Poseidon2 KDF (ORQ-1)
+  const senderPk = poseidonHashBigInt([feltMod(senderSk), LABEL_CHANNEL]);
+
+  const sharedSecret = poseidonHashBigInt([feltMod(senderSk), feltMod(receiverPk), LABEL_CHANNEL]);
+
+  const channelId = poseidonHashBigInt([sharedSecret, LABEL_CHANNEL_ID]);
+
+  return {
+    sender_pubkey: senderPk,
+    receiver_pubkey: feltMod(receiverPk),
+    channel_id: channelId,
+    shared_secret: sharedSecret,
+    established_at: Date.now(),
+  };
+}
+
+/**
+ * Compute the authentication tag for a message.
+ *
+ * tag = Poseidon(shared_secret, nonce, hash(ciphertext))
+ *
+ * @param sharedSecret - Channel shared secret (felt252).
+ * @param ciphertext   - Encrypted payload bytes.
+ * @param nonce        - Message nonce (felt252).
+ * @returns Authentication tag as felt252 BigInt.
+ */
+export function computeAuthTag(
+  sharedSecret: bigint,
+  ciphertext: Uint8Array,
+  nonce: bigint,
+): bigint {
+  const ciphertextHash = hashBytes(ciphertext);
+  return poseidonHashBigInt([
+    feltMod(sharedSecret),
+    feltMod(nonce),
+    ciphertextHash,
+    LABEL_AUTH_TAG,
+  ]);
+}
+
+/**
+ * Encrypt plaintext and send over a shielded agent channel.
+ *
+ * Uses a Poseidon-derived keystream (XOR cipher, STUB). The nonce_counter is
+ * provided by the caller to support stateless multi-message sessions with replay
+ * protection. Each call must use a strictly increasing nonce.
+ *
+ * TODO (ORQ-1): Replace XOR keystream with ChaCha20-Poly1305 or AES-256-GCM.
+ *
+ * @param channel      - Established AgentChannel.
+ * @param plaintext    - Plaintext bytes to encrypt.
+ * @param nonceCounter - Monotonically increasing nonce (caller-managed). Must be
+ *                       strictly greater than the last nonce used on this channel.
+ * @returns EncryptedAgentMessage ready to transmit.
+ */
+export function sendOverChannel(
+  channel: AgentChannel,
+  plaintext: Uint8Array,
+  nonceCounter: bigint,
+): EncryptedAgentMessage {
+  const ciphertext = new Uint8Array(plaintext.length);
+  const BLOCK_SIZE = 31; // 248 bits — safe within felt252
+
+  for (let i = 0; i < plaintext.length; i++) {
+    const blockIndex = BigInt(Math.floor(i / BLOCK_SIZE));
+    const keystreamWord = deriveKeystreamWord(channel.shared_secret, nonceCounter, blockIndex);
+    // Extract the byte at position (i % BLOCK_SIZE) from the keystream word.
+    const byteOffset = BigInt(i % BLOCK_SIZE);
+    const keystreamByte = Number((keystreamWord >> (byteOffset * 8n)) & 0xffn);
+    ciphertext[i] = ((plaintext[i] ?? 0) ^ keystreamByte) & 0xff;
+  }
+
+  const tag = computeAuthTag(channel.shared_secret, ciphertext, nonceCounter);
+
+  return {
+    channel_id: channel.channel_id,
+    nonce: nonceCounter,
+    ciphertext,
+    tag,
+  };
+}
+
+/**
+ * Receive and decrypt a message from a shielded agent channel.
+ *
+ * Validates:
+ *   1. channel_id matches (MismatchedChannel).
+ *   2. nonce > expectedNoncePrev (ReplayedNonce).
+ *   3. auth tag matches computed tag (InvalidTag).
+ *
+ * @param channel           - Established AgentChannel (must match sender's channel).
+ * @param message           - EncryptedAgentMessage to decrypt.
+ * @param expectedNoncePrev - Last accepted nonce on this channel. The message nonce
+ *                            must be strictly greater than this value.
+ * @returns Decrypted plaintext bytes.
+ * @throws {ChannelErrorKind} On validation failure.
+ */
+export function receiveOverChannel(
+  channel: AgentChannel,
+  message: EncryptedAgentMessage,
+  expectedNoncePrev: bigint,
+): Uint8Array {
+  // 1. Channel ID check (routing validation)
+  if (message.channel_id !== channel.channel_id) {
+    throw new Error(ChannelError.MismatchedChannel);
+  }
+
+  // 2. Replay protection: nonce must be strictly increasing
+  if (message.nonce <= expectedNoncePrev) {
+    throw new Error(ChannelError.ReplayedNonce);
+  }
+
+  // 3. Auth tag verification (verify before decrypt — authentication first)
+  const expectedTag = computeAuthTag(channel.shared_secret, message.ciphertext, message.nonce);
+  if (expectedTag !== message.tag) {
+    throw new Error(ChannelError.InvalidTag);
+  }
+
+  // 4. Decrypt (same XOR keystream as encryption)
+  const plaintext = new Uint8Array(message.ciphertext.length);
+  const BLOCK_SIZE = 31;
+
+  for (let i = 0; i < message.ciphertext.length; i++) {
+    const blockIndex = BigInt(Math.floor(i / BLOCK_SIZE));
+    const keystreamWord = deriveKeystreamWord(channel.shared_secret, message.nonce, blockIndex);
+    const byteOffset = BigInt(i % BLOCK_SIZE);
+    const keystreamByte = Number((keystreamWord >> (byteOffset * 8n)) & 0xffn);
+    plaintext[i] = ((message.ciphertext[i] ?? 0) ^ keystreamByte) & 0xff;
+  }
+
+  return plaintext;
+}

package/src/privacy/composition.ts

@@ -0,0 +1,289 @@
+/**
+ * Multi-agent Claim composition — recursive-AND (∧) operator.
+ *
+ * Implements checkpoint 4 of sprint-576:agentic-privacy-impl (ORQ-2):
+ * - `composeAgents(agents)` produces a recursive-AND ShieldedClaim over n≥2 agents.
+ * - n=2: flat pairwise ∧ (no recursion needed).
+ * - n≥3: left-fold recursive ∧ placeholder — future STARK aggregation via Stwo.
+ *
+ * Scenario: identity → credit-score → loan-approval (3 agents)
+ *   1. Agent A: verifies identity (Glacis nullifier → pseudonym claim)
+ *   2. Agent B: verifies credit (pseudonym + bank data → credit-score claim)
+ *   3. Agent C: approves loan (credit-score claim → loan-approval claim)
+ *   Composition: C_final = ((C_A ∧ C_B) ∧ C_C)
+ *
+ * References:
+ *   - docs/research/03-agentic-privacy.md §3 (Scenario 3: Multi-Agent Composition)
+ *   - docs/research/09-orq-recursive-starks.md §3 (recursive ∧ deferred to Phase 2)
+ *   - vauban-privacy-protocol/sdk/typescript/src/composition.ts (compose operator pattern)
+ *
+ * @module privacy/composition
+ */
+
+import {
+  type DelegationClaim,
+  buildDelegationClaim,
+  isDelegationScopeValid,
+} from "./delegation.js";
+import { feltMod, labelToFelt, poseidonHashBigInt } from "./poseidon-felt252.js";
+
+// ─── Domain labels ────────────────────────────────────────────────────────────
+
+const LABEL_COMPOSE_AND = labelToFelt("vauban-agent-compose-and-v1");
+const LABEL_RECURSIVE = labelToFelt("vauban-recursive-and-v1");
+const LABEL_TRANSCRIPT = labelToFelt("vauban-transcript-v1");
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * A claim produced by a single agent in a multi-agent workflow.
+ *
+ * Each `AgentClaim` carries its agent's nullifier (the cryptographic identity
+ * of the agent in the HDNT hierarchy) and a role label describing its position
+ * in the workflow (e.g. "identity", "credit-score", "loan-approval").
+ *
+ * The `delegationChain` is optional: when present, it anchors the agent's
+ * claim to a parent claim via the Claim Algebra → operator.
+ */
+export interface AgentClaim {
+  /** Agent's nullifier (felt252 BigInt). Output of `deriveAgentNullifier`. */
+  agentNullifier: bigint;
+  /** Role label for this agent in the workflow. Used for domain separation. */
+  role: string;
+  /** Arbitrary claim payload (predicate, evidence, etc.). */
+  payload: Record<string, unknown>;
+  /**
+   * Optional delegation chain anchoring this claim to a parent.
+   * When set, the composition will verify the delegation is still valid.
+   */
+  delegationChain?: DelegationClaim;
+}
+
+/**
+ * The composition mode used for a given invocation of `composeAgents`.
+ *
+ * - `"flat"`: pairwise ∧ for n=2. Proofs are independent (checkpoint 3 style).
+ * - `"recursive"`: left-fold recursive ∧ for n≥3. Phase 2 will replace the
+ *   placeholder with actual Stwo STARK aggregation.
+ */
+export type CompositionMode = "flat" | "recursive";
+
+/**
+ * A ShieldedClaim produced by `composeAgents`.
+ *
+ * The `composedNullifier` is the binding commitment over all participating
+ * agents' nullifiers — it changes if any agent is swapped out.
+ *
+ * The `transcriptDigest` binds the claim to the composition's public inputs
+ * (ordered agent roles + composition mode) for external proof anchoring.
+ */
+export interface ShieldedClaim {
+  /**
+   * Poseidon-derived commitment over all agent nullifiers in order.
+   * Different orderings → different composedNullifier (order matters).
+   */
+  composedNullifier: bigint;
+  /** Merged payload from all agent claims (first agent wins on key conflicts). */
+  payload: Record<string, unknown>;
+  /** Agent roles in composition order. */
+  roles: string[];
+  /** Mode used ("flat" for n=2, "recursive" for n≥3). */
+  mode: CompositionMode;
+  /**
+   * Transcript digest: Poseidon(composedNullifier, rolesFelt, LABEL_TRANSCRIPT).
+   * Binds the ShieldedClaim to its public inputs for proof anchoring (ORQ-5).
+   */
+  transcriptDigest: bigint;
+  /**
+   * Delegation witnesses for any claims that had a `delegationChain`.
+   * Keyed by role label. Empty if no delegations were present.
+   */
+  delegationWitnesses: Map<string, DelegationClaim>;
+  /** Number of agents composed. */
+  n: number;
+}
+
+// ─── Errors ───────────────────────────────────────────────────────────────────
+
+/**
+ * Error thrown by `composeAgents` on invalid input or constraint violation.
+ */
+export class CompositionError extends Error {
+  readonly kind: "EmptyComposition" | "ExpiredDelegation" | "SingleAgent";
+
+  constructor(kind: "EmptyComposition" | "ExpiredDelegation" | "SingleAgent", message?: string) {
+    super(message ?? kind);
+    this.kind = kind;
+    this.name = "CompositionError";
+  }
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Encode an array of role strings as a single felt252 for use in the
+ * transcript digest. Roles are XOR-folded with their position index to
+ * preserve ordering (different orderings → different felt).
+ */
+function rolesToFelt(roles: string[]): bigint {
+  let acc = 0n;
+  for (let i = 0; i < roles.length; i++) {
+    const roleFelt = labelToFelt(roles[i] ?? "");
+    // Mix role felt with position to make ordering matter.
+    acc = feltMod(acc ^ (roleFelt + BigInt(i + 1) * 0x1b1b1b1bn));
+  }
+  return acc;
+}
+
+/**
+ * Pairwise ∧: combine two agent nullifiers into a composed nullifier.
+ * Poseidon(a, b, LABEL_COMPOSE_AND) — order-sensitive by construction.
+ */
+function composePair(aNullifier: bigint, bNullifier: bigint): bigint {
+  return poseidonHashBigInt([feltMod(aNullifier), feltMod(bNullifier), LABEL_COMPOSE_AND]);
+}
+
+/**
+ * Recursive-AND placeholder for n≥3.
+ *
+ * Left-fold: ((a ∧ b) ∧ c) ∧ d … with LABEL_RECURSIVE to domain-separate
+ * from flat ∧. Phase 2 replaces this with Stwo STARK aggregation proof.
+ *
+ * TODO (ORQ-2, Phase 2): Replace with real recursive STARK aggregation via Stwo.
+ */
+function composeRecursive(nullifiers: bigint[]): bigint {
+  // Seed: Poseidon(first, second, LABEL_RECURSIVE)
+  let acc = poseidonHashBigInt([
+    feltMod(nullifiers[0] ?? 0n),
+    feltMod(nullifiers[1] ?? 0n),
+    LABEL_RECURSIVE,
+  ]);
+  // Fold in remaining nullifiers.
+  for (let i = 2; i < nullifiers.length; i++) {
+    acc = poseidonHashBigInt([acc, feltMod(nullifiers[i] ?? 0n), LABEL_RECURSIVE]);
+  }
+  return acc;
+}
+
+/**
+ * Merge payloads from all agents (left-to-right, first agent wins on conflict).
+ */
+function mergePayloads(claims: AgentClaim[]): Record<string, unknown> {
+  const merged: Record<string, unknown> = {};
+  // Iterate in reverse so first agent wins (earlier keys overwrite later).
+  for (let i = claims.length - 1; i >= 0; i--) {
+    const payload = claims[i]?.payload ?? {};
+    for (const [k, v] of Object.entries(payload)) {
+      merged[k] = v;
+    }
+  }
+  return merged;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Compose n≥2 AgentClaims into a single recursive-AND ShieldedClaim.
+ *
+ * Algorithm:
+ *   - n=2: flat pairwise ∧ (Poseidon(a, b, LABEL_AND)).
+ *   - n≥3: left-fold recursive ∧ (Poseidon accumulator with LABEL_RECURSIVE).
+ *
+ * If any agent claim carries a `delegationChain`, its validity is checked
+ * (expiry). Expired delegations cause an `ExpiredDelegation` error.
+ *
+ * The `transcriptDigest` binds the result to the ordered list of roles and
+ * the composedNullifier for external proof anchoring.
+ *
+ * Example (identity → credit-score → loan-approval, n=3):
+ * ```ts
+ * const result = composeAgents([identityClaim, creditClaim, loanClaim]);
+ * // result.mode === "recursive"
+ * // result.n === 3
+ * // result.roles === ["identity", "credit-score", "loan-approval"]
+ * ```
+ *
+ * @param agents - Ordered list of AgentClaims (at least 2).
+ * @returns ShieldedClaim with composedNullifier, transcriptDigest, and merged payload.
+ * @throws {CompositionError} EmptyComposition if agents is empty.
+ * @throws {CompositionError} SingleAgent if only 1 agent is provided.
+ * @throws {CompositionError} ExpiredDelegation if any delegation chain has expired.
+ */
+export function composeAgents(agents: AgentClaim[]): ShieldedClaim {
+  if (agents.length === 0) {
+    throw new CompositionError("EmptyComposition", "composeAgents requires at least 2 agents");
+  }
+  if (agents.length === 1) {
+    throw new CompositionError("SingleAgent", "composeAgents requires at least 2 agents, got 1");
+  }
+
+  // Validate delegation chains.
+  const delegationWitnesses = new Map<string, DelegationClaim>();
+  for (const agent of agents) {
+    if (agent.delegationChain !== undefined) {
+      if (!isDelegationScopeValid(agent.delegationChain.scope)) {
+        throw new CompositionError(
+          "ExpiredDelegation",
+          `delegation for role "${agent.role}" has expired`,
+        );
+      }
+      delegationWitnesses.set(agent.role, agent.delegationChain);
+    }
+  }
+
+  const nullifiers = agents.map((a) => a.agentNullifier);
+  const roles = agents.map((a) => a.role);
+  const n = agents.length;
+
+  // Compose nullifiers.
+  const mode: CompositionMode = n === 2 ? "flat" : "recursive";
+  const composedNullifier =
+    mode === "flat"
+      ? composePair(nullifiers[0] ?? 0n, nullifiers[1] ?? 0n)
+      : composeRecursive(nullifiers);
+
+  // Transcript digest — binds composedNullifier + ordered roles + domain label.
+  const rolesFelt = rolesToFelt(roles);
+  const transcriptDigest = poseidonHashBigInt([composedNullifier, rolesFelt, LABEL_TRANSCRIPT]);
+
+  // Merge payloads.
+  const payload = mergePayloads(agents);
+
+  return {
+    composedNullifier,
+    payload,
+    roles,
+    mode,
+    transcriptDigest,
+    delegationWitnesses,
+    n,
+  };
+}
+
+/**
+ * Build an AgentClaim with an attached DelegationClaim.
+ *
+ * Convenience factory that calls `buildDelegationClaim` from `delegation.ts`
+ * and wires the result into an `AgentClaim.delegationChain`.
+ *
+ * @param agentNullifier     - Derived nullifier of this agent.
+ * @param role               - Workflow role label.
+ * @param payload            - Claim payload.
+ * @param parentClaimDigest  - Parent claim digest bytes (from the authorizing claim).
+ * @param scope              - Delegation scope (allowed actions + expiry).
+ * @returns AgentClaim with populated delegationChain.
+ */
+export function buildAgentClaimWithDelegation(
+  agentNullifier: bigint,
+  role: string,
+  payload: Record<string, unknown>,
+  parentClaimDigest: number[],
+  scope: { allowedActions: string[]; expiry: number },
+): AgentClaim {
+  const delegation = buildDelegationClaim(
+    { digest: parentClaimDigest, "digest-alg": "poseidon-felt252" },
+    agentNullifier,
+    scope,
+  );
+  return { agentNullifier, role, payload, delegationChain: delegation };
+}

package/src/privacy/delegation.ts

@@ -0,0 +1,128 @@
+/**
+ * Delegation-as-Claim skeleton — agent authorization via Claim Algebra.
+ *
+ * Implements the delegation operator from §3 of
+ * `vauban-privacy-protocol/docs/research/03-agentic-privacy.md`.
+ *
+ * A DelegationClaim records that a parent Claim (held by a human or another agent)
+ * authorizes a delegatee pseudonym to act within a bounded scope and time window.
+ *
+ * The full ZK proof of delegation (STARK proof walking the chain) is out of scope
+ * for this TypeScript slice. This module provides the data structures and builder
+ * so the agent SDK can produce delegation-compatible payloads for future proof
+ * generation (handled by the Rust HDNT crate).
+ *
+ * @module privacy/delegation
+ */
+
+// ─── ClaimRef (local mirror of @vauban/claim ClaimRef) ───────────────────────
+// Deliberately not importing @vauban/claim to avoid adding a new dependency.
+// This mirror type is structurally compatible with the package's ClaimRef.
+// Align with vauban-privacy-protocol/docs/research/03-agentic-privacy.md §3.
+
+/**
+ * Minimal Claim reference (digest + optional algorithm tag).
+ * Structurally compatible with `ClaimRef` from the `@vauban/claim` package.
+ */
+export interface ClaimRef {
+  /** SHA-256 or Poseidon-felt252 digest of the parent Claim, as byte array. */
+  digest: number[];
+  /** Hash algorithm used for the digest. Defaults to "sha-256". */
+  "digest-alg"?: "sha-256" | "poseidon-felt252";
+}
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * Scope of actions the delegatee is authorized to perform.
+ *
+ * - `allowedActions`: action-type identifiers the agent may produce N_action for.
+ *   Use `["*"]` for unrestricted delegation (max_depth enforcement still applies).
+ * - `expiry`: Unix timestamp (seconds) after which this delegation is invalid.
+ */
+export interface DelegationScope {
+  allowedActions: string[];
+  expiry: number;
+}
+
+/**
+ * Delegation Claim produced by `buildDelegationClaim`.
+ *
+ * Wire-compatible with the Claim Algebra composition record
+ * (`operator: "delegation"`) from `@vauban-org/claim`.
+ */
+export interface DelegationClaim {
+  /** Reference to the parent Claim that grants authority. */
+  parentClaim: ClaimRef;
+  /** Pseudonym (felt252 BigInt as hex string) of the delegatee agent. */
+  delegateePseudonym: string;
+  /** Authorized scope for the delegatee. */
+  scope: DelegationScope;
+  /** ISO-8601 timestamp of claim issuance. */
+  issuedAt: string;
+  /** Serialized scope for inclusion in a STARK proof witness. */
+  scopeWitness: string;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Serialize a DelegationScope to a deterministic JSON witness string.
+ * Keys are sorted (JCS-compatible) for reproducibility in proof circuits.
+ */
+export function serializeDelegationScope(scope: DelegationScope): string {
+  return JSON.stringify({
+    allowedActions: [...scope.allowedActions].sort(),
+    expiry: scope.expiry,
+  });
+}
+
+/**
+ * Return true if the scope is still valid at the given Unix timestamp.
+ *
+ * @param scope - DelegationScope to check.
+ * @param nowSec - Current time in Unix seconds. Defaults to `Date.now() / 1000`.
+ */
+export function isDelegationScopeValid(
+  scope: DelegationScope,
+  nowSec: number = Math.floor(Date.now() / 1000),
+): boolean {
+  return nowSec < scope.expiry;
+}
+
+/**
+ * Return true if the given action type is permitted by the scope.
+ *
+ * `["*"]` grants permission to all action types (wildcard).
+ */
+export function isActionAllowed(scope: DelegationScope, actionType: string): boolean {
+  return scope.allowedActions.includes("*") || scope.allowedActions.includes(actionType);
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Build a DelegationClaim from a parent ClaimRef, delegatee pseudonym, and scope.
+ *
+ * The returned object is a proof-ready payload. The STARK proof of correct
+ * delegation (proving the delegation chain without revealing identity) is
+ * generated by the Rust HDNT crate from this payload.
+ *
+ * @param parentClaim       - ClaimRef of the root or intermediate claim granting authority.
+ * @param delegateePseudonym - Agent nullifier (felt252 BigInt) for the delegatee.
+ * @param scope             - Authorized action scope and expiry.
+ * @returns DelegationClaim ready for proof generation.
+ */
+export function buildDelegationClaim(
+  parentClaim: ClaimRef,
+  delegateePseudonym: bigint,
+  scope: DelegationScope,
+): DelegationClaim {
+  return {
+    parentClaim,
+    delegateePseudonym: `0x${delegateePseudonym.toString(16)}`,
+    scope,
+    issuedAt: new Date().toISOString(),
+    scopeWitness: serializeDelegationScope(scope),
+  };
+}