@omnituum/pqc-shared 0.2.6

package/dist/index.d.cts

@@ -0,0 +1,282 @@
+export { BLAKE3_OUTPUT_LENGTH, BOX_KEY_SIZE, BOX_NONCE_SIZE, BoxPayload, CHACHA20_KEY_SIZE, ClassicalWrap, DILITHIUM_ALGORITHM, DILITHIUM_PUBLIC_KEY_SIZE, DILITHIUM_SECRET_KEY_SIZE, DILITHIUM_SIGNATURE_SIZE, DilithiumKeypair, DilithiumKeypairB64, DilithiumSignature, HybridEnvelope, HybridIdentity, HybridPublicKeys, HybridSecretKeys, KyberEncapsulation, KyberKeypair, KyberKeypairB64, POLY1305_TAG_SIZE, SECRETBOX_KEY_SIZE, SECRETBOX_NONCE_SIZE, SECRETBOX_OVERHEAD, SecretboxPayload, X25519Keypair, X25519KeypairHex, XCHACHA20_NONCE_SIZE, assertLen, b64, blake3, blake3DeriveKey, blake3Hex, blake3Mac, boxDecrypt, boxEncrypt, boxUnwrapWithX25519, boxWrapWithX25519, chaCha20Poly1305Decrypt, chaCha20Poly1305Encrypt, createChaCha20Poly1305, createXChaCha20Poly1305, deriveKeyFromShared, dilithiumSign, dilithiumSignRaw, dilithiumVerify, dilithiumVerifyRaw, fromB64, fromHex, generateDilithiumKeypair, generateDilithiumKeypairFromSeed, generateHybridIdentity, generateKyberKeypair, generateX25519Keypair, generateX25519KeypairFromSeed, getPublicKeys, getSecretKeys, hkdfDerive, hkdfExpand, hkdfExtract, hkdfSha256, hkdfSplitForNoise, hkdfTripleSplitForNoise, hybridDecrypt, hybridDecryptToString, hybridEncrypt, isDilithiumAvailable, isKyberAvailable, kyberDecapsulate, kyberEncapsulate, kyberUnwrapKey, kyberWrapKey, rand12, rand24, rand32, randN, secretboxDecrypt, secretboxDecryptString, secretboxEncrypt, secretboxEncryptString, secretboxOpenRaw, secretboxRaw, sha256, sha256String, textDecoder, textEncoder, toB64, toHex, u8, ub64, x25519SharedSecret, xChaCha20Poly1305Decrypt, xChaCha20Poly1305Encrypt } from './crypto/index.cjs';
+export { E as EncryptedVaultFile, H as HybridIdentityRecord, O as OmnituumVault } from './types-Ch0y-n7K.cjs';
+export { MigrationOptions, MigrationResult, addIdentity, createEmptyVault, createIdentity, decryptVault, encryptVault, getVaultKdfInfo, isV2Vault, migrateEncryptedVault, needsMigration } from './vault/index.cjs';
+export { c as computeIntegrityHash, b as computeKeyFingerprint } from './integrity-Dx9jukMH.cjs';
+export { g as ENVELOPE_AEAD, f as ENVELOPE_SUITE, E as ENVELOPE_VERSION, c as VAULT_ALGORITHM, a as VAULT_ENCRYPTED_VERSION, d as VAULT_ENCRYPTED_VERSION_V2, b as VAULT_KDF, e as VAULT_KDF_V2, V as VAULT_VERSION, i as validateEncryptedVault, h as validateEnvelope, v as validateVault } from './version-BygzPVGs.cjs';
+export { D as DecryptOptions, E as EncryptOptions, c as OQEDecryptResult, O as OQEEncryptResult, d as decryptFile, b as decryptFileWithPassword, e as encryptFile, a as encryptFileWithPassword } from './decrypt-eSHlbh1j.cjs';
+import '@noble/ciphers/utils';
+
+/**
+ * Omnituum PQC Shared - Unified Key Derivation
+ *
+ * Single source of truth for password-based key derivation.
+ * Supports both legacy PBKDF2 (for backwards compatibility) and
+ * Argon2id (recommended for new implementations).
+ *
+ * Security Levels:
+ * - PBKDF2-SHA256: 600K iterations (OWASP 2023)
+ * - Argon2id: 64MB memory, 3 iterations, 4 parallelism (OWASP 2024)
+ */
+type KDFAlgorithm = 'PBKDF2-SHA256' | 'Argon2id';
+interface KDFConfig {
+    algorithm: KDFAlgorithm;
+    pbkdf2Iterations?: number;
+    argon2MemoryCost?: number;
+    argon2TimeCost?: number;
+    argon2Parallelism?: number;
+    saltLength: number;
+    hashLength: number;
+}
+/** Legacy PBKDF2 config (for existing vaults) */
+declare const KDF_CONFIG_PBKDF2: KDFConfig;
+/** Modern Argon2id config (recommended for new vaults) */
+declare const KDF_CONFIG_ARGON2ID: KDFConfig;
+/**
+ * Generate a cryptographically secure salt.
+ */
+declare function generateSalt(length?: number): Uint8Array;
+/**
+ * Derive a key from a password using the specified KDF configuration.
+ *
+ * @param password - User password
+ * @param salt - Random salt (use generateSalt())
+ * @param config - KDF configuration
+ * @returns Derived key as Uint8Array
+ */
+declare function kdfDeriveKey(password: string, salt: Uint8Array, config?: KDFConfig): Promise<Uint8Array>;
+/**
+ * Get the recommended KDF config based on environment capabilities.
+ */
+declare function getRecommendedConfig(): Promise<KDFConfig>;
+/**
+ * Benchmark a KDF configuration.
+ * @returns Time in milliseconds
+ */
+declare function benchmarkKDF(config?: KDFConfig): Promise<number>;
+
+/**
+ * Omnituum PQC Shared - Security Utilities
+ *
+ * Memory hygiene, secure comparison, and session management utilities.
+ * These are critical for enterprise credibility and threat model legitimacy.
+ */
+/**
+ * Securely zero out a Uint8Array to prevent sensitive data from lingering in memory.
+ *
+ * Note: JavaScript garbage collection may still leave copies. This is a best-effort
+ * approach for browser environments. For maximum security, use Web Assembly or
+ * native code.
+ *
+ * @param arr - Array to zero
+ */
+declare function zeroMemory(arr: Uint8Array): void;
+/**
+ * Zero multiple arrays at once.
+ *
+ * @param arrays - Arrays to zero
+ */
+declare function zeroAll(...arrays: (Uint8Array | null | undefined)[]): void;
+/**
+ * Execute a function and zero the result after a callback processes it.
+ * Ensures sensitive data is cleared even if callback throws.
+ *
+ * @param getData - Function that returns sensitive data
+ * @param process - Function to process the data
+ * @returns Result of process function
+ */
+declare function withSecureData<T, R>(getData: () => Promise<Uint8Array>, process: (data: Uint8Array) => Promise<R>): Promise<R>;
+/**
+ * Compare two byte arrays in constant time to prevent timing attacks.
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @returns true if arrays are equal
+ */
+declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+type UnlockReason = 'password' | 'biometric' | 'hardware_key' | 'session_restore' | 'api_token' | 'unknown';
+interface SecureSession {
+    /** Session is currently unlocked */
+    unlocked: boolean;
+    /** Timestamp when session was unlocked (ms since epoch) */
+    unlockedAt: number | null;
+    /** Session timeout in milliseconds (0 = never) */
+    timeoutMs: number;
+    /** How the session was unlocked */
+    unlockReason: UnlockReason | null;
+    /** Optional session identifier */
+    sessionId: string | null;
+    /** Last activity timestamp (ms since epoch) */
+    lastActivityAt: number | null;
+    /** Number of failed unlock attempts */
+    failedAttempts: number;
+    /** Lockout until timestamp (ms since epoch) if too many failed attempts */
+    lockedOutUntil: number | null;
+}
+/**
+ * Create a new locked session.
+ */
+declare function createSession(timeoutMs?: number): SecureSession;
+/**
+ * Unlock a secure session.
+ */
+declare function unlockSecureSession(session: SecureSession, reason?: UnlockReason): SecureSession;
+/**
+ * Lock a secure session and clear sensitive state.
+ */
+declare function lockSecureSession(session: SecureSession): SecureSession;
+/**
+ * Check if session has timed out.
+ */
+declare function isSessionTimedOut(session: SecureSession): boolean;
+/**
+ * Wrapper for sensitive data that auto-zeros on disposal.
+ */
+declare class SecureBuffer {
+    private _data;
+    private _disposed;
+    constructor(data: Uint8Array);
+    /**
+     * Get a copy of the data (original stays protected).
+     */
+    get data(): Uint8Array;
+    /**
+     * Get data length without exposing contents.
+     */
+    get length(): number;
+    /**
+     * Check if buffer has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Zero and dispose the buffer.
+     */
+    dispose(): void;
+    /**
+     * Execute a function with the data, then dispose.
+     */
+    useAndDispose<T>(fn: (data: Uint8Array) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Omnituum Tunnel v1 - Type Definitions
+ *
+ * Post-handshake encrypted tunnel interface.
+ * Handshake-agnostic: any key agreement can feed into this.
+ *
+ * @see pqc-docs/specs/tunnel.v1.md
+ */
+/**
+ * Key material required to establish a tunnel session.
+ * Produced by any key agreement protocol (Noise, TLS, custom).
+ */
+interface TunnelKeyMaterial {
+    /** 32-byte key for outgoing messages */
+    sendKey: Uint8Array;
+    /** 32-byte key for incoming messages */
+    recvKey: Uint8Array;
+    /** 24-byte base nonce for outgoing messages */
+    sendBaseNonce: Uint8Array;
+    /** 24-byte base nonce for incoming messages */
+    recvBaseNonce: Uint8Array;
+}
+/**
+ * A secure tunnel session for post-handshake communication.
+ *
+ * @example
+ * ```ts
+ * import { createTunnelSession } from '@omnituum/pqc-shared';
+ *
+ * const tunnel = createTunnelSession(keys);
+ *
+ * // Send a message
+ * const ciphertext = tunnel.encrypt(plaintext);
+ *
+ * // Receive a message
+ * const plaintext = tunnel.decrypt(ciphertext);
+ * if (!plaintext) throw new Error('Authentication failed');
+ *
+ * // Clean up
+ * tunnel.close();
+ * ```
+ */
+interface PQCTunnelSession {
+    /**
+     * Encrypt plaintext for transmission.
+     * Automatically increments the send counter.
+     *
+     * @param plaintext - Data to encrypt
+     * @param aad - Optional additional authenticated data
+     * @returns Ciphertext with authentication tag
+     * @throws Error if tunnel is closed
+     */
+    encrypt(plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    /**
+     * Decrypt received ciphertext.
+     * Automatically increments the receive counter.
+     *
+     * @param ciphertext - Data to decrypt (includes auth tag)
+     * @param aad - Optional additional authenticated data (must match encryption)
+     * @returns Plaintext, or null if authentication fails
+     * @throws Error if tunnel is closed
+     */
+    decrypt(ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array | null;
+    /**
+     * Securely close the tunnel.
+     * Zeros all key material and rejects further operations.
+     */
+    close(): void;
+    /**
+     * Check if the tunnel is still open.
+     */
+    readonly isOpen: boolean;
+    /**
+     * Get current send counter (for debugging/monitoring).
+     */
+    readonly sendCounter: bigint;
+    /**
+     * Get current receive counter (for debugging/monitoring).
+     */
+    readonly recvCounter: bigint;
+}
+/** Tunnel version string */
+declare const TUNNEL_VERSION: "omnituum.tunnel.v1";
+/** Key size in bytes (32 = 256 bits) */
+declare const TUNNEL_KEY_SIZE = 32;
+/** Base nonce size in bytes (24 for XChaCha20) */
+declare const TUNNEL_NONCE_SIZE = 24;
+
+/**
+ * Omnituum Tunnel v1 - Session Implementation
+ *
+ * XChaCha20-Poly1305 encrypted tunnel with counter-based nonces.
+ * Handshake-agnostic: accepts any TunnelKeyMaterial producer.
+ *
+ * @see pqc-docs/specs/tunnel.v1.md
+ */
+
+/**
+ * Create a secure tunnel session from key material.
+ *
+ * @param keys - Key material from handshake (Noise, TLS, etc.)
+ * @returns Tunnel session for encrypted communication
+ *
+ * @example
+ * ```ts
+ * // From Noise handshake
+ * const keys = toTunnelKeyMaterial(noiseState);
+ * const tunnel = createTunnelSession(keys);
+ *
+ * // Send encrypted message
+ * const ciphertext = tunnel.encrypt(plaintext);
+ * channel.send(ciphertext);
+ *
+ * // Receive encrypted message
+ * const plaintext = tunnel.decrypt(received);
+ *
+ * // Clean up when done
+ * tunnel.close();
+ * ```
+ */
+declare function createTunnelSession(keys: TunnelKeyMaterial): PQCTunnelSession;
+
+export { type KDFAlgorithm, type KDFConfig, KDF_CONFIG_ARGON2ID, KDF_CONFIG_PBKDF2, type PQCTunnelSession, SecureBuffer, type SecureSession, TUNNEL_KEY_SIZE, TUNNEL_NONCE_SIZE, TUNNEL_VERSION, type TunnelKeyMaterial, type UnlockReason, benchmarkKDF, constantTimeEqual, createSession, createTunnelSession, generateSalt, getRecommendedConfig, isSessionTimedOut, kdfDeriveKey, lockSecureSession, unlockSecureSession, withSecureData, zeroAll, zeroMemory };

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+export { BLAKE3_OUTPUT_LENGTH, BOX_KEY_SIZE, BOX_NONCE_SIZE, BoxPayload, CHACHA20_KEY_SIZE, ClassicalWrap, DILITHIUM_ALGORITHM, DILITHIUM_PUBLIC_KEY_SIZE, DILITHIUM_SECRET_KEY_SIZE, DILITHIUM_SIGNATURE_SIZE, DilithiumKeypair, DilithiumKeypairB64, DilithiumSignature, HybridEnvelope, HybridIdentity, HybridPublicKeys, HybridSecretKeys, KyberEncapsulation, KyberKeypair, KyberKeypairB64, POLY1305_TAG_SIZE, SECRETBOX_KEY_SIZE, SECRETBOX_NONCE_SIZE, SECRETBOX_OVERHEAD, SecretboxPayload, X25519Keypair, X25519KeypairHex, XCHACHA20_NONCE_SIZE, assertLen, b64, blake3, blake3DeriveKey, blake3Hex, blake3Mac, boxDecrypt, boxEncrypt, boxUnwrapWithX25519, boxWrapWithX25519, chaCha20Poly1305Decrypt, chaCha20Poly1305Encrypt, createChaCha20Poly1305, createXChaCha20Poly1305, deriveKeyFromShared, dilithiumSign, dilithiumSignRaw, dilithiumVerify, dilithiumVerifyRaw, fromB64, fromHex, generateDilithiumKeypair, generateDilithiumKeypairFromSeed, generateHybridIdentity, generateKyberKeypair, generateX25519Keypair, generateX25519KeypairFromSeed, getPublicKeys, getSecretKeys, hkdfDerive, hkdfExpand, hkdfExtract, hkdfSha256, hkdfSplitForNoise, hkdfTripleSplitForNoise, hybridDecrypt, hybridDecryptToString, hybridEncrypt, isDilithiumAvailable, isKyberAvailable, kyberDecapsulate, kyberEncapsulate, kyberUnwrapKey, kyberWrapKey, rand12, rand24, rand32, randN, secretboxDecrypt, secretboxDecryptString, secretboxEncrypt, secretboxEncryptString, secretboxOpenRaw, secretboxRaw, sha256, sha256String, textDecoder, textEncoder, toB64, toHex, u8, ub64, x25519SharedSecret, xChaCha20Poly1305Decrypt, xChaCha20Poly1305Encrypt } from './crypto/index.js';
+export { E as EncryptedVaultFile, H as HybridIdentityRecord, O as OmnituumVault } from './types-61c7Q9ri.js';
+export { MigrationOptions, MigrationResult, addIdentity, createEmptyVault, createIdentity, decryptVault, encryptVault, getVaultKdfInfo, isV2Vault, migrateEncryptedVault, needsMigration } from './vault/index.js';
+export { c as computeIntegrityHash, b as computeKeyFingerprint } from './integrity-CCYjrap3.js';
+export { g as ENVELOPE_AEAD, f as ENVELOPE_SUITE, E as ENVELOPE_VERSION, c as VAULT_ALGORITHM, a as VAULT_ENCRYPTED_VERSION, d as VAULT_ENCRYPTED_VERSION_V2, b as VAULT_KDF, e as VAULT_KDF_V2, V as VAULT_VERSION, i as validateEncryptedVault, h as validateEnvelope, v as validateVault } from './version-BygzPVGs.js';
+export { D as DecryptOptions, E as EncryptOptions, c as OQEDecryptResult, O as OQEEncryptResult, d as decryptFile, b as decryptFileWithPassword, e as encryptFile, a as encryptFileWithPassword } from './decrypt-eSHlbh1j.js';
+import '@noble/ciphers/utils';
+
+/**
+ * Omnituum PQC Shared - Unified Key Derivation
+ *
+ * Single source of truth for password-based key derivation.
+ * Supports both legacy PBKDF2 (for backwards compatibility) and
+ * Argon2id (recommended for new implementations).
+ *
+ * Security Levels:
+ * - PBKDF2-SHA256: 600K iterations (OWASP 2023)
+ * - Argon2id: 64MB memory, 3 iterations, 4 parallelism (OWASP 2024)
+ */
+type KDFAlgorithm = 'PBKDF2-SHA256' | 'Argon2id';
+interface KDFConfig {
+    algorithm: KDFAlgorithm;
+    pbkdf2Iterations?: number;
+    argon2MemoryCost?: number;
+    argon2TimeCost?: number;
+    argon2Parallelism?: number;
+    saltLength: number;
+    hashLength: number;
+}
+/** Legacy PBKDF2 config (for existing vaults) */
+declare const KDF_CONFIG_PBKDF2: KDFConfig;
+/** Modern Argon2id config (recommended for new vaults) */
+declare const KDF_CONFIG_ARGON2ID: KDFConfig;
+/**
+ * Generate a cryptographically secure salt.
+ */
+declare function generateSalt(length?: number): Uint8Array;
+/**
+ * Derive a key from a password using the specified KDF configuration.
+ *
+ * @param password - User password
+ * @param salt - Random salt (use generateSalt())
+ * @param config - KDF configuration
+ * @returns Derived key as Uint8Array
+ */
+declare function kdfDeriveKey(password: string, salt: Uint8Array, config?: KDFConfig): Promise<Uint8Array>;
+/**
+ * Get the recommended KDF config based on environment capabilities.
+ */
+declare function getRecommendedConfig(): Promise<KDFConfig>;
+/**
+ * Benchmark a KDF configuration.
+ * @returns Time in milliseconds
+ */
+declare function benchmarkKDF(config?: KDFConfig): Promise<number>;
+
+/**
+ * Omnituum PQC Shared - Security Utilities
+ *
+ * Memory hygiene, secure comparison, and session management utilities.
+ * These are critical for enterprise credibility and threat model legitimacy.
+ */
+/**
+ * Securely zero out a Uint8Array to prevent sensitive data from lingering in memory.
+ *
+ * Note: JavaScript garbage collection may still leave copies. This is a best-effort
+ * approach for browser environments. For maximum security, use Web Assembly or
+ * native code.
+ *
+ * @param arr - Array to zero
+ */
+declare function zeroMemory(arr: Uint8Array): void;
+/**
+ * Zero multiple arrays at once.
+ *
+ * @param arrays - Arrays to zero
+ */
+declare function zeroAll(...arrays: (Uint8Array | null | undefined)[]): void;
+/**
+ * Execute a function and zero the result after a callback processes it.
+ * Ensures sensitive data is cleared even if callback throws.
+ *
+ * @param getData - Function that returns sensitive data
+ * @param process - Function to process the data
+ * @returns Result of process function
+ */
+declare function withSecureData<T, R>(getData: () => Promise<Uint8Array>, process: (data: Uint8Array) => Promise<R>): Promise<R>;
+/**
+ * Compare two byte arrays in constant time to prevent timing attacks.
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @returns true if arrays are equal
+ */
+declare function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean;
+type UnlockReason = 'password' | 'biometric' | 'hardware_key' | 'session_restore' | 'api_token' | 'unknown';
+interface SecureSession {
+    /** Session is currently unlocked */
+    unlocked: boolean;
+    /** Timestamp when session was unlocked (ms since epoch) */
+    unlockedAt: number | null;
+    /** Session timeout in milliseconds (0 = never) */
+    timeoutMs: number;
+    /** How the session was unlocked */
+    unlockReason: UnlockReason | null;
+    /** Optional session identifier */
+    sessionId: string | null;
+    /** Last activity timestamp (ms since epoch) */
+    lastActivityAt: number | null;
+    /** Number of failed unlock attempts */
+    failedAttempts: number;
+    /** Lockout until timestamp (ms since epoch) if too many failed attempts */
+    lockedOutUntil: number | null;
+}
+/**
+ * Create a new locked session.
+ */
+declare function createSession(timeoutMs?: number): SecureSession;
+/**
+ * Unlock a secure session.
+ */
+declare function unlockSecureSession(session: SecureSession, reason?: UnlockReason): SecureSession;
+/**
+ * Lock a secure session and clear sensitive state.
+ */
+declare function lockSecureSession(session: SecureSession): SecureSession;
+/**
+ * Check if session has timed out.
+ */
+declare function isSessionTimedOut(session: SecureSession): boolean;
+/**
+ * Wrapper for sensitive data that auto-zeros on disposal.
+ */
+declare class SecureBuffer {
+    private _data;
+    private _disposed;
+    constructor(data: Uint8Array);
+    /**
+     * Get a copy of the data (original stays protected).
+     */
+    get data(): Uint8Array;
+    /**
+     * Get data length without exposing contents.
+     */
+    get length(): number;
+    /**
+     * Check if buffer has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Zero and dispose the buffer.
+     */
+    dispose(): void;
+    /**
+     * Execute a function with the data, then dispose.
+     */
+    useAndDispose<T>(fn: (data: Uint8Array) => Promise<T>): Promise<T>;
+}
+
+/**
+ * Omnituum Tunnel v1 - Type Definitions
+ *
+ * Post-handshake encrypted tunnel interface.
+ * Handshake-agnostic: any key agreement can feed into this.
+ *
+ * @see pqc-docs/specs/tunnel.v1.md
+ */
+/**
+ * Key material required to establish a tunnel session.
+ * Produced by any key agreement protocol (Noise, TLS, custom).
+ */
+interface TunnelKeyMaterial {
+    /** 32-byte key for outgoing messages */
+    sendKey: Uint8Array;
+    /** 32-byte key for incoming messages */
+    recvKey: Uint8Array;
+    /** 24-byte base nonce for outgoing messages */
+    sendBaseNonce: Uint8Array;
+    /** 24-byte base nonce for incoming messages */
+    recvBaseNonce: Uint8Array;
+}
+/**
+ * A secure tunnel session for post-handshake communication.
+ *
+ * @example
+ * ```ts
+ * import { createTunnelSession } from '@omnituum/pqc-shared';
+ *
+ * const tunnel = createTunnelSession(keys);
+ *
+ * // Send a message
+ * const ciphertext = tunnel.encrypt(plaintext);
+ *
+ * // Receive a message
+ * const plaintext = tunnel.decrypt(ciphertext);
+ * if (!plaintext) throw new Error('Authentication failed');
+ *
+ * // Clean up
+ * tunnel.close();
+ * ```
+ */
+interface PQCTunnelSession {
+    /**
+     * Encrypt plaintext for transmission.
+     * Automatically increments the send counter.
+     *
+     * @param plaintext - Data to encrypt
+     * @param aad - Optional additional authenticated data
+     * @returns Ciphertext with authentication tag
+     * @throws Error if tunnel is closed
+     */
+    encrypt(plaintext: Uint8Array, aad?: Uint8Array): Uint8Array;
+    /**
+     * Decrypt received ciphertext.
+     * Automatically increments the receive counter.
+     *
+     * @param ciphertext - Data to decrypt (includes auth tag)
+     * @param aad - Optional additional authenticated data (must match encryption)
+     * @returns Plaintext, or null if authentication fails
+     * @throws Error if tunnel is closed
+     */
+    decrypt(ciphertext: Uint8Array, aad?: Uint8Array): Uint8Array | null;
+    /**
+     * Securely close the tunnel.
+     * Zeros all key material and rejects further operations.
+     */
+    close(): void;
+    /**
+     * Check if the tunnel is still open.
+     */
+    readonly isOpen: boolean;
+    /**
+     * Get current send counter (for debugging/monitoring).
+     */
+    readonly sendCounter: bigint;
+    /**
+     * Get current receive counter (for debugging/monitoring).
+     */
+    readonly recvCounter: bigint;
+}
+/** Tunnel version string */
+declare const TUNNEL_VERSION: "omnituum.tunnel.v1";
+/** Key size in bytes (32 = 256 bits) */
+declare const TUNNEL_KEY_SIZE = 32;
+/** Base nonce size in bytes (24 for XChaCha20) */
+declare const TUNNEL_NONCE_SIZE = 24;
+
+/**
+ * Omnituum Tunnel v1 - Session Implementation
+ *
+ * XChaCha20-Poly1305 encrypted tunnel with counter-based nonces.
+ * Handshake-agnostic: accepts any TunnelKeyMaterial producer.
+ *
+ * @see pqc-docs/specs/tunnel.v1.md
+ */
+
+/**
+ * Create a secure tunnel session from key material.
+ *
+ * @param keys - Key material from handshake (Noise, TLS, etc.)
+ * @returns Tunnel session for encrypted communication
+ *
+ * @example
+ * ```ts
+ * // From Noise handshake
+ * const keys = toTunnelKeyMaterial(noiseState);
+ * const tunnel = createTunnelSession(keys);
+ *
+ * // Send encrypted message
+ * const ciphertext = tunnel.encrypt(plaintext);
+ * channel.send(ciphertext);
+ *
+ * // Receive encrypted message
+ * const plaintext = tunnel.decrypt(received);
+ *
+ * // Clean up when done
+ * tunnel.close();
+ * ```
+ */
+declare function createTunnelSession(keys: TunnelKeyMaterial): PQCTunnelSession;
+
+export { type KDFAlgorithm, type KDFConfig, KDF_CONFIG_ARGON2ID, KDF_CONFIG_PBKDF2, type PQCTunnelSession, SecureBuffer, type SecureSession, TUNNEL_KEY_SIZE, TUNNEL_NONCE_SIZE, TUNNEL_VERSION, type TunnelKeyMaterial, type UnlockReason, benchmarkKDF, constantTimeEqual, createSession, createTunnelSession, generateSalt, getRecommendedConfig, isSessionTimedOut, kdfDeriveKey, lockSecureSession, unlockSecureSession, withSecureData, zeroAll, zeroMemory };