/**
 * 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