@vauban-org/agent-sdk 0.16.0

package/dist/privacy/channel.d.ts

@@ -0,0 +1,137 @@
+/**
+ * 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
+ */
+/**
+ * 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;
+}
+export declare const ChannelError: {
+    /** The message's channel_id does not match the provided channel. */
+    readonly MismatchedChannel: "MismatchedChannel";
+    /** The authentication tag does not match — ciphertext tampered or wrong key. */
+    readonly InvalidTag: "InvalidTag";
+    /** The message nonce is not strictly greater than the expected previous nonce. */
+    readonly ReplayedNonce: "ReplayedNonce";
+    /** Channel has not been established (stub for future async establishment). */
+    readonly ChannelNotEstablished: "ChannelNotEstablished";
+};
+export type ChannelErrorKind = (typeof ChannelError)[keyof typeof ChannelError];
+/**
+ * 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 declare function establishChannel(senderSk: bigint, receiverPk: bigint): AgentChannel;
+/**
+ * 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 declare function computeAuthTag(sharedSecret: bigint, ciphertext: Uint8Array, nonce: bigint): bigint;
+/**
+ * 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 declare function sendOverChannel(channel: AgentChannel, plaintext: Uint8Array, nonceCounter: bigint): EncryptedAgentMessage;
+/**
+ * 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 declare function receiveOverChannel(channel: AgentChannel, message: EncryptedAgentMessage, expectedNoncePrev: bigint): Uint8Array;
+//# sourceMappingURL=channel.d.ts.map

package/dist/privacy/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/privacy/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAaH;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,eAAe,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,mFAAmF;IACnF,UAAU,EAAE,UAAU,CAAC;IACvB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAID,eAAO,MAAM,YAAY;IACvB,oEAAoE;;IAEpE,gFAAgF;;IAEhF,kFAAkF;;IAElF,8EAA8E;;CAEtE,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AA0ChF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY,CAenF;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,UAAU,EACtB,KAAK,EAAE,MAAM,GACZ,MAAM,CAQR;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,YAAY,EACrB,SAAS,EAAE,UAAU,EACrB,YAAY,EAAE,MAAM,GACnB,qBAAqB,CAqBvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,qBAAqB,EAC9B,iBAAiB,EAAE,MAAM,GACxB,UAAU,CA8BZ"}

package/dist/privacy/channel.js

@@ -0,0 +1,196 @@
+/**
+ * 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");
+// ─── 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",
+};
+// ─── 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) {
+    // 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, nonce, blockIndex) {
+    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, receiverPk) {
+    // 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, ciphertext, nonce) {
+    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, plaintext, nonceCounter) {
+    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, message, expectedNoncePrev) {
+    // 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;
+}
+//# sourceMappingURL=channel.js.map

package/dist/privacy/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../../src/privacy/channel.ts"],"names":[],"mappings":"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"}

package/dist/privacy/composition.d.ts

@@ -0,0 +1,140 @@
+/**
+ * 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 } from "./delegation.js";
+/**
+ * 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;
+}
+/**
+ * Error thrown by `composeAgents` on invalid input or constraint violation.
+ */
+export declare class CompositionError extends Error {
+    readonly kind: "EmptyComposition" | "ExpiredDelegation" | "SingleAgent";
+    constructor(kind: "EmptyComposition" | "ExpiredDelegation" | "SingleAgent", message?: string);
+}
+/**
+ * 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 declare function composeAgents(agents: AgentClaim[]): ShieldedClaim;
+/**
+ * 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 declare function buildAgentClaimWithDelegation(agentNullifier: bigint, role: string, payload: Record<string, unknown>, parentClaimDigest: number[], scope: {
+    allowedActions: string[];
+    expiry: number;
+}): AgentClaim;
+//# sourceMappingURL=composition.d.ts.map

package/dist/privacy/composition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composition.d.ts","sourceRoot":"","sources":["../../src/privacy/composition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,iBAAiB,CAAC;AAWzB;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IACzB,4EAA4E;IAC5E,cAAc,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,WAAW,CAAC;AAEnD;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B,gFAAgF;IAChF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,wCAAwC;IACxC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,uDAAuD;IACvD,IAAI,EAAE,eAAe,CAAC;IACtB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAClD,iCAAiC;IACjC,CAAC,EAAE,MAAM,CAAC;CACX;AAID;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,mBAAmB,GAAG,aAAa,CAAC;gBAE5D,IAAI,EAAE,kBAAkB,GAAG,mBAAmB,GAAG,aAAa,EAAE,OAAO,CAAC,EAAE,MAAM;CAK7F;AAkED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,aAAa,CAiDjE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAC3C,cAAc,EAAE,MAAM,EACtB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,iBAAiB,EAAE,MAAM,EAAE,EAC3B,KAAK,EAAE;IAAE,cAAc,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClD,UAAU,CAOZ"}

package/dist/privacy/composition.js

@@ -0,0 +1,182 @@
+/**
+ * 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 { 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");
+// ─── Errors ───────────────────────────────────────────────────────────────────
+/**
+ * Error thrown by `composeAgents` on invalid input or constraint violation.
+ */
+export class CompositionError extends Error {
+    kind;
+    constructor(kind, message) {
+        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) {
+    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, bNullifier) {
+    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) {
+    // 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) {
+    const merged = {};
+    // 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) {
+    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();
+    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 = 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, role, payload, parentClaimDigest, scope) {
+    const delegation = buildDelegationClaim({ digest: parentClaimDigest, "digest-alg": "poseidon-felt252" }, agentNullifier, scope);
+    return { agentNullifier, role, payload, delegationChain: delegation };
+}
+//# sourceMappingURL=composition.js.map