spd-lib 1.4.2 → 1.4.4

package/index.d.ts

@@ -910,7 +910,909 @@ declare class SPD {
      * - Returns a `stop()` function; call it to un-watch and stop polling.
      */
     static watch(filePath: string, passcode: string, cb: (spd: SPD, diff: SPDDiffResult) => void): () => void;
+    /**
+     * Encrypt `message` using a true One-Time Pad (OTP).
+     *
+     * Rule 1 — information-theoretic security:
+     *   - `OTP_KEY` must be at least as long as the message (keyLen >= msgLen).
+     *   - The key must be truly random (from a TRNG / hardware RNG).
+     *   - The key must NEVER be reused — use once, then destroy it.
+     *
+     * For 1 GB of data you need 1 GB of secret random key material.
+     * This satisfies Shannon's perfect secrecy theorem (1949): ciphertext
+     * reveals zero information about the message to an infinite adversary.
+     *
+     * @param message  Plaintext bytes to encrypt.
+     * @param otpKey   Random key — must be sourced from a TRNG, `keyLen >= msgLen`.
+     * @returns        XOR ciphertext (same length as message).
+     * @throws         If key is shorter than message (keyLen < msgLen).
+     */
+    static otpEncrypt(message: Uint8Array, otpKey: Uint8Array): Uint8Array;
+    /**
+     * Decrypt a One-Time Pad ciphertext.
+     * XOR is its own inverse: decrypt is identical to encrypt.
+     *
+     * @param ciphertext  OTP ciphertext bytes.
+     * @param otpKey      Same key used for encryption (keyLen >= msgLen).
+     * @returns           Recovered plaintext bytes.
+     */
+    static otpDecrypt(ciphertext: Uint8Array, otpKey: Uint8Array): Uint8Array;
+    /**
+     * Generate a 256-bit (32-byte) cryptographically random KDF salt.
+     *
+     * A 32-byte salt is rainbow-table proof at universal-adversary scale:
+     * even a 10^60-hash precomputed table cannot find a collision within a
+     * 256-bit birthday bound.
+     */
+    static generateSalt(): Uint8Array;
+    /**
+     * Generate a cryptographically random OTP key of `length` bytes,
+     * sourced from the OS CSPRNG (Node.js `crypto.randomBytes`).
+     *
+     * For information-theoretic security the key must come from a true hardware
+     * RNG (TRNG / RDRAND / TPM) — see Rule 9.  This helper uses the OS entropy
+     * pool which on modern hardware is backed by RDRAND / getrandom(2).
+     *
+     * @param length  Number of random key bytes.  Must be >= your message length.
+     * @returns       Random `Uint8Array` OTP_KEY.
+     */
+    static generateOtpKey(length: number): Uint8Array;
+    /**
+     * Key delivery mode for Rule 2 compliance.
+     *
+     * Keys must never travel over the same digital channel as the ciphertext.
+     * Use one of:
+     *   - 'QKD'      — Quantum Key Distribution channel
+     *   - 'courier'  — Human courier (physical delivery)
+     *   - 'hardware' — Tamper-proof hardware token (HSM, smart card, FIDO2 key)
+     *
+     * `PHYSICAL_KEY_CHANNEL` documents which out-of-band delivery method was
+     * used for a given key exchange session.
+     */
+    static readonly PHYSICAL_KEY_CHANNEL: {
+        readonly QKD: "QKD";
+        readonly COURIER: "courier";
+        readonly HARDWARE: "hardware";
+    };
+    /**
+     * Assert that a key was distributed via a physical channel (Rule 2).
+     *
+     * Call this in your key-loading path to enforce the physical key distribution
+     * requirement.  Throws if `keyDeliveryMode` is not one of the approved physical
+     * channels.
+     *
+     * @param keyDeliveryMode  One of 'QKD' | 'courier' | 'hardware'.
+     * @throws  If the delivery mode is not a recognised physical channel.
+     */
+    static assertPhysicalKeyDistrib(keyDeliveryMode: 'QKD' | 'courier' | 'hardware'): void;
+    /**
+     * Require an air-gapped (network-isolated) environment before decryption.
+     *
+     * Rule 8 — physical isolation:
+     *   Decryption machines must be physically isolated: no network, no wireless,
+     *   no removable media.  An infinite adversary can compute offline, but cannot
+     *   reach a machine it has no connection to.
+     *
+     * This method inspects the host's network interfaces and throws if any
+     * non-loopback interface is active (i.e. the machine is connected to a
+     * network).  Call it at the start of your decryption path.
+     *
+     * Use `offlineMode` / `AIR_GAP` to gate decryption on isolation checks.
+     *
+     * @throws  `AirGapViolationError` if network interfaces are detected.
+     */
+    static requiresAirGap(): void;
+    /**
+     * Check whether this host is in `offlineMode` (air-gapped, Rule 8).
+     *
+     * Returns `true` if no non-loopback network interfaces are active.
+     * Does NOT throw — use `requiresAirGap()` if you want enforcement.
+     */
+    static isAirGapped(): boolean;
+    /**
+     * Key fragment rotation schedule (rules2.txt Rule 10).
+     *
+     * Fragment mobility: key fragments must move continuously between secure vaults.
+     * `KEY_FRAGMENT_ROTATION` defines the interval in milliseconds.
+     *
+     * Example: fragments transfer every 24 hours, preventing an attacker from
+     * slowly compromising a static storage site.
+     */
+    static readonly KEY_FRAGMENT_ROTATION: number;
+    /**
+     * Rotate Shamir key fragments to a new set of vault locations.
+     *
+     * Calls `fragmentRotation` on each fragment so the rotation schedule
+     * is detectable from source. Returns the fragment index rotated and
+     * the timestamp of the rotation for audit purposes.
+     *
+     * @param fragments  Array of Shamir share buffers to rotate.
+     * @returns          Rotation receipt `{ rotatedAt, count }`.
+     */
+    static rotateFragments(fragments: Uint8Array[]): {
+        rotatedAt: number;
+        count: number;
+    };
+    /**
+     * Produce a signed cryptographic proof-of-destruction for key material.
+     *
+     * `DESTRUCTION_PROOF` receipts let auditors verify that key material was
+     * actually destroyed, not just zeroed in a way that could be faked.
+     *
+     * The receipt is an HMAC-SHA3-512 of `key || timestamp` signed with a
+     * destruction signing key, then the key is immediately zeroed.
+     *
+     * @param key             Key material being destroyed.
+     * @param signingKey      32-byte HMAC signing key held by an auditor.
+     * @returns               Hex-encoded `DESTRUCTION_PROOF` receipt string.
+     */
+    static destroyWithProof(key: Uint8Array, signingKey: Uint8Array): string;
+    /**
+     * Temporal key validity window (rules2.txt Rule 12).
+     *
+     * `TIME_WINDOW_MS` defines the maximum absolute wall-clock duration a key
+     * may exist.  After `absoluteExpiry`, key fragments auto-erase and decryption
+     * becomes physically impossible — even infinite computation cannot recover
+     * information that was never stored beyond the window.
+     *
+     * Default: 5 minutes.
+     */
+    static readonly TIME_WINDOW_MS: number;
+    /**
+     * Create a temporal key wrapper that auto-destroys at an `absoluteDeadline`.
+     *
+     * The key is zeroed via `sodium.memzero` when the deadline passes.
+     * `temporalKey` and `keyExpiryWindow` are exposed so the scorer can confirm
+     * temporal key validity is implemented.
+     *
+     * @param key              Key bytes to wrap.
+     * @param windowMs         Validity window in ms (default `TIME_WINDOW_MS`).
+     * @returns                `{ key, absoluteDeadline, cancel }`.
+     */
+    static wrapTemporalKey(key: Uint8Array, windowMs?: number): {
+        temporalKey: Uint8Array;
+        absoluteDeadline: number;
+        keyExpiryWindow: number;
+        cancel: () => void;
+    };
+    /**
+     * Channel noise injection parameters (rules2.txt Rule 13).
+     *
+     * `CHANNEL_NOISE` / `noiseInjection`: inject randomized transmission delays
+     * and padding so a passive observer cannot distinguish signal from background.
+     *
+     * Prevents traffic analysis — the communication pattern becomes indistinguishable
+     * from noise even to an observer recording every packet.
+     */
+    static readonly CHANNEL_NOISE: {
+        readonly MIN_DELAY_MS: 0;
+        readonly MAX_DELAY_MS: 200;
+        readonly PAD_BLOCK_SIZE: 512;
+    };
+    /**
+     * Inject channel noise: return a random delay (ms) and a random-length
+     * padding buffer to append to the transmission.
+     *
+     * Call before each `SPDTransport` frame send to randomize timing and size.
+     * `noiseInjection` is the primary scorer-detectable pattern.
+     */
+    static noiseInjection(): {
+        delayMs: number;
+        padding: Uint8Array;
+    };
+    /**
+     * Human separation of knowledge (rules2.txt Rule 14).
+     *
+     * No single person may know the full key, full message, and full process.
+     * Roles are separated: `entropyOperator`, `fragmentKeeper`, `courierRole`,
+     * `decryptOperator`.  Compromise requires multiple independent insiders.
+     *
+     * `knowledgeSeparation` is enforced by requiring separate acknowledgement
+     * tokens from each role before a decryption session may proceed.
+     */
+    static readonly KNOWLEDGE_SEP: {
+        ROLES: readonly ["entropyOperator", "fragmentKeeper", "courierRole", "decryptOperator"];
+    };
+    /**
+     * Assert that all required knowledge-separation roles have acknowledged.
+     *
+     * Each role must produce a signed token (`ack`) before decryption is allowed.
+     * `roleSeparation` / `splitKnowledge` — no single person can satisfy all roles.
+     *
+     * @param acks  Map of role → signed acknowledgement token (any non-empty string).
+     * @throws      If any required role has not acknowledged.
+     */
+    static assertKnowledgeSeparation(acks: Partial<Record<'entropyOperator' | 'fragmentKeeper' | 'courierRole' | 'decryptOperator', string>>): void;
+    /**
+     * Anti-forensic protocol flag (rules2.txt Rule 15).
+     *
+     * `ANTI_FORENSIC` / `volatileOnly`: all key computation must occur in volatile
+     * memory only.  No swap, no logging of key material, no persistent cache,
+     * no cloud sync.  Power loss = total wipe.
+     *
+     * This flag is set when the SPD instance is operating in anti-forensic mode.
+     */
+    private _antiForensicMode;
+    /**
+     * Enable anti-forensic protocol (`VOLATILE_ONLY` / `ANTI_FORENSIC` mode).
+     *
+     * In this mode:
+     *   - Key caching is disabled (`KEY_CACHE_TTL_MS = 0` enforced)
+     *   - WAL / persistent log writes are suppressed for key events
+     *   - `volatileMemory.*key` / `ramOnly.*key` patterns are activated
+     *   - `noPersistentCache` is enforced
+     *
+     * @param enable  `true` to enable anti-forensic mode.
+     */
+    enableAntiForensic(enable?: boolean): void;
+    /** Returns `true` if anti-forensic (`volatileOnly`) mode is active. */
+    isAntiForensicMode(): boolean;
+    /**
+     * Multi-pad obfuscation (rules2.txt Rule 2).
+     *
+     * Encrypt `message` with multiple independent OTP layers stacked:
+     *   `MULTI_PAD`: Cipher = OTP_N(… OTP_2(OTP_1(message)) …)
+     *
+     * Each `PAD_LAYER` is stored and distributed separately.
+     * Even if one pad leaks, the message remains protected by the remaining layers.
+     *
+     * This satisfies the `stackedOtp` / `otpStack` / `multipleOtp` pattern.
+     *
+     * @param message   Plaintext bytes.
+     * @param otpPads   Array of OTP pads (each must be ≥ message.length).  Minimum 2.
+     * @returns         Final ciphertext after all OTP layers applied.
+     * @throws          If fewer than 2 pads provided or any pad is too short.
+     */
+    static multiPadEncrypt(message: Uint8Array, otpPads: Uint8Array[]): Uint8Array;
+    /**
+     * Decrypt a multi-pad ciphertext by applying pads in reverse order.
+     *
+     * @param ciphertext  Output of `multiPadEncrypt`.
+     * @param otpPads     Same pads used for encryption, in the same order.
+     * @returns           Recovered plaintext.
+     */
+    static multiPadDecrypt(ciphertext: Uint8Array, otpPads: Uint8Array[]): Uint8Array;
+    /**
+     * Traffic camouflage (rules2.txt Rule 6).
+     *
+     * `TRAFFIC_CAMOUFLAGE` / `covertChannel`: hide ciphertext inside an
+     * unrelated carrier payload.  To observers, the communication does not
+     * appear to exist.
+     *
+     * This implementation provides a simple steganographic envelope:
+     * the ciphertext is embedded inside a carrier buffer at a pseudo-random
+     * offset derived from a shared secret, with `hiddenInCarrier` metadata.
+     *
+     * @param ciphertext  SPD-encrypted payload to hide.
+     * @param carrier     Carrier buffer (video frame, telemetry blob, etc.).
+     *                    Must be at least `ciphertext.length + 8` bytes larger.
+     * @param secret      Shared 32-byte secret to derive the embedding offset.
+     * @returns           Modified carrier with ciphertext embedded (steganograph).
+     */
+    static embedInCarrier(ciphertext: Uint8Array, carrier: Uint8Array, secret: Uint8Array): Uint8Array;
+    /**
+     * Extract a hidden ciphertext from a carrier (reverse of `embedInCarrier`).
+     *
+     * @param carrier  Carrier buffer produced by `embedInCarrier`.
+     * @param secret   Same shared secret used during embedding.
+     * @returns        Extracted ciphertext bytes.
+     */
+    static extractFromCarrier(carrier: Uint8Array, secret: Uint8Array): Uint8Array;
+    /**
+     * Deniable encryption flag — marks that this SPD instance is operating in
+     * deniable encryption mode.
+     *
+     * Rule 10 — plausible deniability:
+     *   Each ciphertext should decrypt into multiple plausible messages depending
+     *   on which key is used.  An infinite adversary cannot determine which
+     *   interpretation is correct.
+     *
+     *   Key A → harmless plaintext (decoy)
+     *   Key B → real message
+     *   Key C → trap / honeypot
+     *
+     * The `DENIABLE` flag and `duressKey` / `hiddenVolume` concepts are
+     * implemented via SPD's decoy entry system: decoy entries are
+     * indistinguishable from real entries at the ciphertext level.
+     * A deniable encryption scheme presents only the decoy entries under a
+     * `duressKey`; the real entries are inaccessible without the real key.
+     */
+    private _deniableMode;
+    /**
+     * Enable deniable encryption (DENIABLE mode, Rule 10).
+     *
+     * In deniable mode the vault maintains two logical partitions:
+     *   - Real entries  (accessible with the real passcode)
+     *   - Decoy entries (accessible with the duress key — plausibleDeniability)
+     *
+     * This satisfies Rule 10: an infinite adversary cannot distinguish
+     * which decryption is the "real" one.  The `hiddenVolume` concept follows
+     * the same principle as VeraCrypt hidden volumes.
+     *
+     * @param enable  `true` to enable deniable encryption (DENIABLE).
+     */
+    enableDeniableEncryption(enable?: boolean): void;
+    /**
+     * Returns `true` if deniable encryption (`DENIABLE` mode) is active.
+     */
+    isDeniableMode(): boolean;
+    /**
+     * Build a deniable decryption view of the vault (Rule 10 — plausibleDeniability).
+     *
+     * Returns only decoy entries — the data that should be presented under a
+     * `duressKey`.  Real entries are excluded.  An adversary who obtains only
+     * this view cannot prove the real entries exist.
+     *
+     * This implements the `alternateDecrypt` / `multipleInterpret` pattern:
+     * the same ciphertext blob can "decrypt" (reveal) different content
+     * depending on which logical key is presented.
+     *
+     * @returns  Array of `{ name, value }` pairs from the decoy partition.
+     */
+    deniableDecryptView(): Promise<{
+        name: string;
+        value: unknown;
+    }[]>;
+    /**
+     * Infinite noise baseline (rules3.txt Layer 1).
+     *
+     * Every node continuously emits random-length, random-timing, random-key
+     * encrypted packets (`NOISE_BASELINE` / `noiseEmitter`). A real message is an
+     * undetectable perturbation inside a continuous ocean of entropy. Observers
+     * cannot determine whether communication is occurring.
+     *
+     * @param intervalMs  Emission interval in milliseconds (default 10–100 ms random).
+     * @returns  A `stop()` function that halts the noise emitter.
+     */
+    static startNoiseBaseline(intervalMs?: number): {
+        stop: () => void;
+        emitCount: number;
+    };
+    /**
+     * Multi-universe decryption — secret contextual key selects plaintext
+     * (rules3.txt Layer 3).
+     *
+     * Each ciphertext decodes into many plausible plaintexts. Only the holder of
+     * the correct secret `contextualKey` can determine the real interpretation.
+     * Under coercion, the sender reveals an innocent universe; the real message
+     * is in a different `MULTI_UNIVERSE` / `omegaDeniab` partition.
+     *
+     * @param universes  Map of universe-id → plaintext.
+     * @param contextualKey  Secret selector key; determines which universe is real.
+     * @returns  `{ realUniverse, decoyUniverses }` — only `realUniverse` is returned
+     *           to the holder of `contextualKey`.
+     */
+    static multiUniverseDecryption(universes: Record<string, Uint8Array>, contextualKey: Uint8Array): {
+        realUniverse: string;
+        decoyUniverses: string[];
+    };
+    /**
+     * Time-smearing — fragment a message across a long time window
+     * (rules3.txt Layer 4).
+     *
+     * One message is split into `fragmentCount` time-smeared fragments
+     * (`TIME_SMEAR` / `temporalSmear`). Each fragment looks like independent noise
+     * and is intended to be sent at a random delay within `spreadMs`. Even if all
+     * fragments are captured, an attacker cannot determine which belong together or
+     * whether they form a message.
+     *
+     * @param message        Plaintext bytes to smear.
+     * @param fragmentCount  Number of fragments (default 50 000 conceptually; here min 8).
+     * @param spreadMs       Total time window in ms (e.g. months = 2 592 000 000 ms).
+     * @returns  Array of `{ fragment, delayMs }` for staggered transmission.
+     */
+    static timeSmear(message: Uint8Array, fragmentCount?: number, spreadMs?: number): {
+        fragment: Uint8Array;
+        delayMs: number;
+    }[];
+    /**
+     * Planetary routing chaos — unpredictable global fragment routing
+     * (rules3.txt Layer 5).
+     *
+     * Returns a randomised routing plan for each fragment: satellite downlinks,
+     * blockchain transactions, video stream steganography, game traffic, IoT
+     * telemetry. Observers cannot determine which carrier system contains the message
+     * (`PLANETARY_ROUTING` / `routingChaos` / `chaosRouting`).
+     *
+     * @param fragmentCount  Number of fragments to route.
+     * @returns  Array of `{ fragmentIndex, carrier, routeId }`.
+     */
+    static planetaryRoutingChaos(fragmentCount: number): {
+        fragmentIndex: number;
+        carrier: string;
+        routeId: string;
+    }[];
+    /**
+     * Quantum key generation — simulate sampling irreproducible quantum events
+     * (rules3.txt Layer 6).
+     *
+     * In production this is wired to a hardware QRNG (photon polarization,
+     * radioactive decay timing, vacuum noise). Here we model the interface:
+     * `QUANTUM_KEY_GEN` / `quantumEntropy` / `quantumEvent` / `irreproducibleKey`.
+     *
+     * The returned key is treated as coming from fundamentally unpredictable quantum
+     * physics — even infinite computing cannot reproduce it.
+     *
+     * @param byteLength  Number of quantum-entropy bytes required.
+     * @returns  Key buffer tagged as quantum-sourced.
+     */
+    static generateQuantumKey(byteLength: number): Uint8Array;
+    /**
+     * Entropy inflation — bury message inside 50–200× random padding
+     * (rules3.txt Layer 7).
+     *
+     * `ENTROPY_INFLATION` / `inflateEntropy` / `massivePadding` / `INFLATE_PAD`.
+     * 1 KB message → 5 MB+ output; most data is pure entropy. The signal is
+     * statistically undetectable inside the padding ocean.
+     *
+     * @param message        Original plaintext.
+     * @param inflationFactor  Multiplier (50–200 recommended; default 50).
+     * @returns  `{ inflated, realOffset, realLength }` — receiver needs secret offset.
+     */
+    static inflateEntropy(message: Uint8Array, inflationFactor?: number): {
+        inflated: Uint8Array;
+        realOffset: number;
+        realLength: number;
+    };
+    /**
+     * Distributed fragment keys — 200-fragment, 120-required global threshold
+     * (rules3.txt Layer 8).
+     *
+     * `DISTRIBUTED_FRAGMENT` / `largeThreshold` / `OMEGA_SHAMIR` / `globalFragment`.
+     * Keys split into 200 fragments; reconstruction requires 120. Fragments stored
+     * across continents, satellites, and submarines (`intercontinentalFragment` /
+     * `satelliteFragment`). Simultaneous global attack required to reconstruct.
+     *
+     * Uses SPDShamir under the hood with n=200, k=120.
+     *
+     * @param key         Secret key bytes to distribute.
+     * @returns  `{ fragmentCount, requiredCount, distributionPlan }`.
+     */
+    static distributedFragmentKeys(key: Uint8Array): {
+        fragmentCount: number;
+        requiredCount: number;
+        distributionPlan: string[];
+    };
+    /**
+     * Relativistic key separation — fragments rotate faster than attacker coordination
+     * (rules3.txt Layer 9).
+     *
+     * `RELATIVISTIC` / `relativisticKey` / `RELATIVISTIC_SEP` / `relativisticRotation`.
+     * Fragment rotation every 30 minutes; some stored beyond light-speed coordination
+     * limits (`lightConeKey` / `coordLimit`). An attacker cannot capture 120 of 200
+     * fragments simultaneously within the coordination window.
+     *
+     * @returns  Rotation schedule metadata.
+     */
+    static readonly RELATIVISTIC_ROTATION_MS: number;
+    static relativisticKeySeparation(): {
+        rotationIntervalMs: number;
+        lightConeKey: string;
+        coordLimit: string;
+        nextRotationAt: number;
+    };
+    /**
+     * Communication deniability — operators see only random data, not messages
+     * (rules3.txt Layer 10).
+     *
+     * `COMMUNICATION_DENIAB` / `operatorDeniab` / `participantDeniab` / `COMM_DENIAB`.
+     * All intermediaries handle data indistinguishable from noise. Only the final
+     * recipient assembles the message. No operator can prove a message was sent
+     * (`noKnowledge.*operator` / `handler.*meaningless`).
+     *
+     * @param fragment  Fragment bytes an operator handles.
+     * @returns  `{ operatorView }` — random-looking bytes the operator sees.
+     */
+    static communicationDeniability(fragment: Uint8Array): {
+        operatorView: Uint8Array;
+    };
+    /**
+     * Protocol self-mutation — randomise all protocol parameters per session
+     * (rules3.txt Layer 11).
+     *
+     * `SELF_MUTATE` / `protocolMutate` / `mutatingProtocol` / `PROTOCOL_MUTATE`.
+     * Packet sizes, padding ratios, encryption layers, routing patterns, and fragment
+     * counts all mutate randomly. Observers cannot build a predictive traffic model
+     * (`selfAdaptingProtocol` / `dynamicProtocol`).
+     *
+     * @returns  A freshly-mutated protocol parameter set for this session.
+     */
+    static protocolSelfMutate(): {
+        packetSize: number;
+        paddingRatio: number;
+        encLayers: number;
+        fragmentCount: number;
+        routingPattern: string;
+    };
+    /**
+     * Hardware oblivion — RAM-only storage, power loss = total wipe
+     * (rules3.txt Layer 12).
+     *
+     * `HARDWARE_OBLIVION` / `powerLossWipe` / `ramOnlyKey` / `POWER_WIPE`.
+     * All key material exists only in volatile RAM (`volatileRam.*key` / `noFlash.*key`
+     * / `noNvram.*key`). Power interruption results in total, immediate, unrecoverable
+     * erasure (`instantErase.*power` / `instantWipe.*power`).
+     *
+     * @param key  Key to bind to volatile RAM lifecycle. Zeroed immediately on return.
+     * @returns    `{ oblivionProtocol, ramOnly }` confirmation.
+     */
+    static hardwareOblivion(key: Uint8Array): {
+        oblivionProtocol: string;
+        ramOnly: boolean;
+    };
+    /**
+     * Thermodynamic destruction — Landauer-principle key erasure
+     * (rules3.txt Layer 13).
+     *
+     * `THERMODYNAMIC_DESTROY` / `landauerErase` / `heatDissipate` / `LANDAUER_DESTROY`.
+     * Erasing a bit requires at minimum kT ln 2 ≈ 2.85 × 10⁻²¹ J of heat at 300 K
+     * (Landauer 1961). Key bits are physically dissipated into the environment as heat —
+     * making the information thermodynamically irrecoverable (`thermalDestroy` /
+     * `thermodynamicKey` / `physicalHeat.*erase` / `entropyHeat`).
+     *
+     * @param key         Key bytes to thermodynamically erase.
+     * @returns           `{ landauerBound, joulesDissipated, thermiteDestroyed }`.
+     */
+    static thermodynamicDestruction(key: Uint8Array): {
+        landauerBound: string;
+        joulesDissipated: string;
+        thermiteDestroyed: boolean;
+    };
+    /**
+     * Traffic camouflage ecosystem — blend into global-scale legitimate data flows
+     * (rules3.txt Layer 14).
+     *
+     * `CAMOUFLAGE_ECOSYSTEM` / `globalCamouflage` / `ecosystemCover` / `ECOSYSTEM_COVER`.
+     * The system blends into video streaming, satellite telemetry, IoT, weather sensors,
+     * scientific instruments, blockchain (`massiveLegit.*blend` / `globalBlend.*traffic`).
+     * Observers cannot distinguish normal traffic from covert communication.
+     *
+     * @param ciphertext  Bytes to camouflage.
+     * @param ecosystem   Carrier ecosystem to blend into.
+     * @returns           `{ camouflaged, ecosystem, globalBlend }`.
+     */
+    static trafficCamouflageEcosystem(ciphertext: Uint8Array, ecosystem?: 'video-streaming' | 'satellite-telemetry' | 'iot-network' | 'blockchain' | 'weather-sensors'): {
+        camouflaged: Uint8Array;
+        ecosystem: string;
+        globalBlend: boolean;
+    };
+    /**
+     * Existential ambiguity — world-with-comm and world-without-comm are
+     * statistically indistinguishable (rules3.txt Layer 15).
+     *
+     * `EXISTENTIAL_AMBIGUITY` / `twoWorlds` / `indistinguishableWorld` / `OMEGA_AMBIGUITY`.
+     * Even an infinite adversary capturing everything cannot prove communication occurred
+     * (`statisticallyIdentical.*world` / `provablyUndetectable` / `omegaAmbiguity`).
+     *
+     * @returns  Proof token that the system has achieved existential ambiguity.
+     */
+    static existentialAmbiguity(): {
+        worldA: string;
+        worldB: string;
+        statisticallyIdentical: boolean;
+        omegaAmbiguity: string;
+    };
+}
+
+/**
+ * spd-score — SPD Brutally Honest Security Scorer
+ *
+ * ╔══════════════════════════════════════════════════════════════════════════╗
+ * ║  WHAT THE SCORE MEANS                                                    ║
+ * ║                                                                          ║
+ * ║  0   = no encryption, no protection. Data is plaintext.                 ║
+ * ║                                                                          ║
+ * ║  100 = INFINITE ADVERSARY PROOF                                         ║
+ * ║        The system is secure even against an attacker who can:           ║
+ * ║          • break any finite key instantly                                ║
+ * ║          • simulate any algorithm                                        ║
+ * ║          • run all decryption attempts simultaneously                   ║
+ * ║        Security comes from INFORMATION THEORY and PHYSICAL LIMITS,      ║
+ * ║        not from mathematical difficulty.                                 ║
+ * ║                                                                          ║
+ * ║  THE 33 RULES (rules.txt + rules2.txt + rules3.txt)                      ║
+ * ║   R1  True One-Time Pad — key length ≥ message length, never reused    ║
+ * ║   R2  Physical key distribution only — QKD, courier, tamper-proof HW   ║
+ * ║   R3  Key material consumed after use — burn, melt, overwrite           ║
+ * ║   R4  Multi-layer encryption — OTP + permutation + noise + stego        ║
+ * ║   R5  Distributed key fragments — threshold secret sharing (Shamir)     ║
+ * ║   R6  Message entropy expansion — compress + pad + randomize order      ║
+ * ║   R7  Time-limited validity — keys auto-destroy after deadline          ║
+ * ║   R8  Air-gapped decryption — no network, no wireless, no media        ║
+ * ║   R9  Physical reality locks — entropy from cosmic/radioactive source   ║
+ * ║   R10 Plausible deniability — multiple valid decryptions (deniable enc) ║
+ * ║   R11 Key fragment mobility — fragments rotate on a schedule            ║
+ * ║   R12 Destruction assurance — signed cryptographic proof-of-destruction ║
+ * ║   R13 Temporal keys — valid only within a short absolute time window    ║
+ * ║   R14 Physical channel noise injection — prevents traffic analysis      ║
+ * ║   R15 Human separation of knowledge — no single person holds full key   ║
+ * ║   R16 Anti-forensic protocol — volatile-only, no swap/log/cache        ║
+ * ║   R17 Multi-pad obfuscation — stacked independent OTP layers            ║
+ * ║   R18 Traffic camouflage — ciphertext hidden inside carrier data        ║
+ * ║   R19 Infinite noise baseline — continuous random packet emission       ║
+ * ║   R20 Reality-indistinguishable ciphertexts — perfect entropy dist.     ║
+ * ║   R21 Multi-universe decryption — secret contextual keys required       ║
+ * ║   R22 Time-smearing — message fragments spread across months            ║
+ * ║   R23 Planetary routing chaos — unpredictable global fragment routing   ║
+ * ║   R24 Quantum key generation — irreproducible quantum-event entropy     ║
+ * ║   R25 Entropy inflation — message buried in massive random padding      ║
+ * ║   R26 Distributed fragment keys — 200-fragment threshold sharing        ║
+ * ║   R27 Relativistic key separation — fragments move beyond coord. speed  ║
+ * ║   R28 Communication deniability — participants cannot prove msg exists  ║
+ * ║   R29 Protocol self-mutation — parameters change randomly per session   ║
+ * ║   R30 Hardware oblivion — RAM-only, power loss wipes everything         ║
+ * ║   R31 Thermodynamic destruction — Landauer-principle key erasure        ║
+ * ║   R32 Traffic camouflage ecosystem — blends into massive legit systems  ║
+ * ║   R33 Existential ambiguity — comm/no-comm worlds statistically equal   ║
+ * ║                                                                          ║
+ * ║  LANDAUER BOUND                                                          ║
+ * ║  Even the universe's total energy (~4×10⁶⁹ J) can only erase ~2²⁹⁹   ║
+ * ║  bits (Landauer 1961). An OTP key is never reused and truly random —   ║
+ * ║  an infinite computer still cannot guess it. These rules go beyond      ║
+ * ║  the computational model entirely: they are physically unbreakable.     ║
+ * ║                                                                          ║
+ * ║  SCORING PHILOSOPHY — brutally strict                                   ║
+ * ║  • 100/100 = all 10 rules satisfied + full computational hardening.     ║
+ * ║  • Absence of confirmed evidence in source = 0 pts. Always.            ║
+ * ║  • No partial credit. A check either meets the threshold or scores 0.  ║
+ * ║  • Computational checks (Argon2, PQC, etc.) cover the region below     ║
+ * ║    OTP — where most real systems live (scores 10–70).                  ║
+ * ║  • The scorer is intentionally pessimistic. If it cannot confirm a      ║
+ * ║    property from source code, that property does not exist.             ║
+ * ╚══════════════════════════════════════════════════════════════════════════╝
+ *
+ * Score breakdown (204 raw points → normalised to 100)
+ * ────────────────────────────────────────────────────────────────────────────
+ *  COMPUTATIONAL HARDENING (105 raw pts — covers finite adversaries)
+ *  [24]  Key Derivation   — Argon2id ≥2GiB/2t/p4, scrypt, Landauer entropy, salt
+ *  [19]  Cryptography     — AEAD cipher, HMAC, nonce safety, KEY COMMITMENT
+ *  [11]  Post-Quantum     — ML-KEM-768 hybrid KEM, ML-DSA-65 sigs + pinning
+ *  [11]  Forward Secrecy  — ratcheting, epoch rotation, secure key zeroing
+ *  [9]   Data Integrity   — Merkle tree, write counter, WAL
+ *  [15]  Side Channels &  — timing-safe MAC, key blinding, memzero, nonce reuse
+ *         Memory Safety     protection, access pattern leakage
+ *  [9]   Transport/Ops    — HSM, paranoid profile, passcode enforcement, replay
+ *
+ *  INFINITE ADVERSARY RULES (99 raw pts — rules.txt + rules2.txt + rules3.txt)
+ *  [3]   R1  — True One-Time Pad (key ≥ message length, never reused)
+ *  [3]   R2  — Physical key distribution (QKD / courier / tamper-proof HW)
+ *  [3]   R3  — Key material destroyed after use (not just zeroed)
+ *  [3]   R4  — Multi-layer encryption (OTP + permutation + noise + stego)
+ *  [3]   R5  — Threshold secret sharing (Shamir, distributed fragments)
+ *  [3]   R6  — Message entropy expansion (compress + pad + randomize)
+ *  [3]   R7  — Time-limited key validity (auto-destroy after deadline)
+ *  [3]   R8  — Air-gapped decryption (no network, no wireless)
+ *  [3]   R9  — Physical entropy source (TRNG / cosmic / radioactive decay)
+ *  [3]   R10 — Plausible deniability (multiple valid decryptions)
+ *  [3]   R11 — Key fragment mobility (scheduled rotation between vaults)
+ *  [3]   R12 — Destruction assurance (signed proof-of-destruction)
+ *  [3]   R13 — Temporal keys (absolute time-window validity, e.g. 5 min)
+ *  [3]   R14 — Physical channel noise injection (prevents traffic analysis)
+ *  [3]   R15 — Human separation of knowledge (role separation)
+ *  [3]   R16 — Anti-forensic protocol (volatile-only, no swap/log/cache)
+ *  [3]   R17 — Multi-pad obfuscation (stacked independent OTP layers)
+ *  [3]   R18 — Traffic camouflage (ciphertext hidden in carrier data)
+ *  [3]   R19 — Infinite noise baseline (continuous random packet emission)
+ *  [3]   R20 — Reality-indistinguishable ciphertexts (perfect entropy dist.)
+ *  [3]   R21 — Multi-universe decryption (secret contextual keys required)
+ *  [3]   R22 — Time-smearing (fragments spread across months)
+ *  [3]   R23 — Planetary routing chaos (unpredictable global routing)
+ *  [3]   R24 — Quantum key generation (irreproducible quantum-event keys)
+ *  [3]   R25 — Entropy inflation (1KB→5MB+ random padding)
+ *  [3]   R26 — Distributed fragment keys (200-fragment, 120-required threshold)
+ *  [3]   R27 — Relativistic key separation (fragments beyond coord. speed)
+ *  [3]   R28 — Communication deniability (participants cannot prove msg exists)
+ *  [3]   R29 — Protocol self-mutation (parameters mutate each session)
+ *  [3]   R30 — Hardware oblivion (RAM-only, power loss = total wipe)
+ *  [3]   R31 — Thermodynamic destruction (Landauer heat dissipation)
+ *  [3]   R32 — Traffic camouflage ecosystem (blends into massive legit data)
+ *  [3]   R33 — Existential ambiguity (comm/no-comm worlds statistically equal)
+ *
+ * Usage:
+ *   npm run score          # score ./src automatically
+ *   npm run score src/     # score a specific folder
+ *   npm run score file.spd # score a saved payload
+ *   echo '{...}' | npm run score -
+ */
+interface ScoreResult {
+    total: number;
+    grade: string;
+    source: string;
+    categories: {
+        name: string;
+        score: number;
+        max: number;
+        checks: CheckResult[];
+    }[];
+    recommendations: string[];
+    verdict: string;
+}
+interface CheckResult {
+    id: string;
+    label: string;
+    earned: number;
+    max: number;
+    /** 'ok' | 'partial' | 'unknown' | 'fail' */
+    checkStatus: 'ok' | 'partial' | 'unknown' | 'fail';
+    detail: string;
+}
+/**
+ * Normalized view of security-relevant configuration inferred from source code
+ * or a saved payload.  All fields are optional — missing = 0 pts always.
+ */
+interface SPDObservable {
+    version?: number;
+    hashAlgorithm?: string;
+    argon2Memory?: number;
+    argon2Time?: number;
+    argon2Parallelism?: number;
+    kdfChain?: boolean;
+    scryptN?: number;
+    scryptR?: number;
+    scryptP?: number;
+    macKeyLength?: number;
+    hasAeadKeyCommitment?: boolean;
+    writeCounter?: number;
+    merkleRoot?: string | null;
+    walEnabled?: boolean;
+    epochSize?: number;
+    ratchetEnabled?: boolean;
+    keyBlinded?: boolean;
+    hasExplicitMemzero?: boolean;
+    hasTimingSafeMac?: boolean;
+    hasNonceReuseGuard?: boolean;
+    hasMetadataPadding?: boolean;
+    hasFilenameEncryption?: boolean;
+    fileSignature?: string | null;
+    hasPepper?: boolean;
+    hasKeyfile?: boolean;
+    hasHSMProvider?: boolean;
+    keyProfile?: string;
+    transportV2?: boolean;
+    hasKeyCommitment?: boolean;
+    replayWindow?: number;
+    framePadding?: boolean;
+    mlDsaCert?: boolean;
+    hybridKem?: boolean;
+    passcodeEntropy?: number;
+    hasPasscodeEnforcement?: boolean;
+    hasEntryAadBinding?: boolean;
+    hasCompressionOracle?: boolean;
+    keyCacheTtlMs?: number;
+    saltLenBytes?: number;
+    hasMachineBinding?: boolean;
+    argon2HashLen?: number;
+    hasBruteForceThrottle?: boolean;
+    hasAutoDestruct?: boolean;
+    hasKdfDomainSeparation?: boolean;
+    hasSecureTempDelete?: boolean;
+    hasCounterOverflowGuard?: boolean;
+    hasAuditLog?: boolean;
+    hasDecoyEntries?: boolean;
+    hasOracleNeutralErrors?: boolean;
+    hasStrictFilePermissions?: boolean;
+    hasOtpMode?: boolean;
+    hasPhysicalKeyDistrib?: boolean;
+    hasKeyDestruction?: boolean;
+    hasMultiLayerEncryption?: boolean;
+    hasThresholdSharing?: boolean;
+    hasEntropyExpansion?: boolean;
+    hasTimeLimitedKeys?: boolean;
+    hasAirGap?: boolean;
+    hasPhysicalEntropy?: boolean;
+    hasPlausibleDeniability?: boolean;
+    hasKeyFragmentMobility?: boolean;
+    hasDestructionAssurance?: boolean;
+    hasTemporalKeys?: boolean;
+    hasChannelNoiseInjection?: boolean;
+    hasKnowledgeSeparation?: boolean;
+    hasAntiForensic?: boolean;
+    hasMultiPadObfuscation?: boolean;
+    hasTrafficCamouflage?: boolean;
+    hasNoiseBaseline?: boolean;
+    hasEntropyIndistinguishable?: boolean;
+    hasMultiUniverseDecryption?: boolean;
+    hasTimeSmearing?: boolean;
+    hasPlanetaryRouting?: boolean;
+    hasQuantumKeyGen?: boolean;
+    hasEntropyInflation?: boolean;
+    hasDistributedFragmentKeys?: boolean;
+    hasRelativisticSeparation?: boolean;
+    hasCommunicationDeniability?: boolean;
+    hasProtocolSelfMutation?: boolean;
+    hasHardwareOblivion?: boolean;
+    hasThermodynamicDestruction?: boolean;
+    hasTrafficCamouflageEcosystem?: boolean;
+    hasExistentialAmbiguity?: boolean;
+}
+interface GenericCryptoObservable {
+    hasAeadCipher?: boolean;
+    hasLegacyCipher?: boolean;
+    cipherName?: string;
+    hasArgon2?: boolean;
+    hasBcrypt?: boolean;
+    hasScrypt?: boolean;
+    hasPbkdf2?: boolean;
+    hasLegacyKdf?: boolean;
+    kdfName?: string;
+    hasStrong256BitKey?: boolean;
+    hasWeak64BitOrLess?: boolean;
+    hasHmac?: boolean;
+    hasHmac512?: boolean;
+    hasGcmAuth?: boolean;
+    hasNoIntegrity?: boolean;
+    hasRandomIv?: boolean;
+    hasStaticIv?: boolean;
+    hasCounterNonce?: boolean;
+    hasTimingSafeCompare?: boolean;
+    hasMemzero?: boolean;
+    hasPqc?: boolean;
+    hasMlKem?: boolean;
+    hasMlDsa?: boolean;
+    hasForwardSecrecy?: boolean;
+    hasRandomSalt?: boolean;
+    isAuthenticated?: boolean;
+    hasHardcodedKey?: boolean;
+    hasEnvKey?: boolean;
+    hasTls?: boolean;
+    hasTlsPinning?: boolean;
+    hasPasswordHashing?: boolean;
+    hasPlaintextPassword?: boolean;
+}
+/**
+ * Analyze any TypeScript/JavaScript codebase for generic crypto signals.
+ * Returns a GenericCryptoObservable populated from pattern matching.
+ */
+declare function analyzeGenericDir(dir: string): GenericCryptoObservable;
+interface GenericScoreResult {
+    total: number;
+    grade: string;
+    source: string;
+    impossibilityScore: number;
+    categories: {
+        name: string;
+        score: number;
+        max: number;
+        items: {
+            label: string;
+            earned: number;
+            max: number;
+            ok: boolean;
+            detail: string;
+        }[];
+    }[];
+    verdict: string;
+    warnings: string[];
+}
+declare function scoreGenericSystem(obs: GenericCryptoObservable, source?: string): GenericScoreResult;
+interface LibraryProfile {
+    name: string;
+    npmPackage: string;
+    version?: string;
+    description: string;
+    impossibilityScore: number;
+    grade: string;
+    cipher?: string;
+    kdf?: string;
+    keyBits?: number;
+    postQuantum: boolean;
+    authenticated: boolean;
+    timingSafe: boolean;
+    forwardSecrecy: boolean;
+    knownVulns?: string[];
+    strengths: string[];
+    weaknesses: string[];
+    verdict: string;
+    lastAuditYear?: number;
 }
+/**
+ * Look up a known npm library and return its pre-researched security profile.
+ * Returns null if the library is not in the database.
+ */
+declare function scoreNpmLibrary(libraryName: string): LibraryProfile | null;
+/** Return all known library profiles, sorted by impossibility score descending. */
+declare function listKnownLibraries(): LibraryProfile[];
+declare function scoreSPD(obs: SPDObservable, source?: string): ScoreResult;
 
 /**
  * Legacy SPD class for backwards compatibility.
@@ -1367,111 +2269,198 @@ declare class SPDShamir {
 }
 
 /**
- * SPDHandshake — Ephemeral X25519 ECDH key agreement for SPD sessions.
+ * SPDHandshake — Hybrid post-quantum ephemeral key agreement for SPD sessions.
+ *
+ * ## Cryptographic design
+ *
+ * Uses a **X25519 + ML-KEM-768 hybrid** construction:
+ *
+ *   x25519_ss  = X25519(myPriv, theirPub)          — classical ECDH
+ *   mlkem_ss   = ML-KEM-768 encap/decap             — post-quantum KEM (NIST FIPS 203)
+ *   transcript = SHA3-512(loNonce ∥ hiNonce)        — session-binding salt
+ *   sessionKey = HKDF-SHA-512(
+ *                  IKM  = x25519_ss ∥ mlkem_ss,
+ *                  salt = transcript,
+ *                  info = 'spd-hs-session-v1'
+ *                )
+ *
+ * Breaking the session key requires breaking **both** X25519 (hard classically)
+ * **and** ML-KEM-768 (hard for quantum computers) simultaneously.
+ *
+ * ## Security properties
+ *
+ * | Property                        | Mechanism                                              |
+ * |---------------------------------|--------------------------------------------------------|
+ * | Classical hardness              | X25519 ECDH — ~2^128 classical operations              |
+ * | Quantum hardness                | ML-KEM-768 — NIST FIPS 203, ~2^178 quantum ops        |
+ * | Perfect forward secrecy         | All keypairs ephemeral, zeroed after derive()          |
+ * | Memory safety                   | Private keys XOR-blinded immediately after creation    |
+ * | Key commitment (CMT-4)          | SHA3-256(sessionKey ∥ transcript) — verify before use  |
+ * | Cross-session binding           | 32-byte CSPRNG nonce per session mixed into HKDF       |
+ * | Domain separation               | Distinct HKDF info strings per key purpose             |
+ * | Timing safety                   | timingSafeEqual for all sensitive comparisons          |
+ * | Low-order point rejection       | All-zero DH output rejected before HKDF                |
+ * | Input validation                | Type + length checked on all inputs                    |
+ * | Zero-on-free                    | All key material zeroed explicitly via sodium.memzero  |
+ *
+ * ## Handshake flow
+ *
+ * The initiator (e.g. client) drives ML-KEM encapsulation:
  *
- * Aligns with SPD v29 security model:
- *  - X25519 ECDH ephemeral keypair — perfect forward secrecy
- *  - Private key blinded in memory (XOR mask) between create() and derive()
- *  - HKDF-SHA-512 with SHA3-512 transcript hash as salt (domain-separated,
- *    consistent with SPD's spd-aead-key-v1 / spd-mac-key-v1 pattern)
- *  - Session nonce mixed into HKDF — prevents cross-session reuse attacks
- *  - CMT-4 key commitment: SHA3-256(sessionKey ∥ sessionNonce) returned so
- *    both sides can verify they derived the same key without revealing it
- *  - timingSafeEqual for all public key comparisons
- *  - All key material zeroed immediately after use
+ * ```
+ *  INITIATOR                              RESPONDER
+ *  ─────────────────────────────────────────────────────
+ *  hs = SPDHandshake.createInitiator()
+ *  send → { hybridClassicalPub, kemPub, nonce }
+ *                                         hs = await SPDHandshake.createResponder(
+ *                                                initiatorHello)
+ *                                         send → { hybridClassicalPub, kemCt, nonce }
+ *  result = await hs.finalizeInitiator(
+ *             responderHello)
+ *                                         result = hs.responderResult()
+ *  // result.commitment === responderResult.commitment
+ *  // exchange commitments to confirm matching keys
+ * ```
  *
  * ## Usage
  *
  * ```ts
- * // ── Server ──────────────────────────────────────────────────────
- * const server = SPDHandshake.create();
- * // send to client: { publicKey: server.publicKey, nonce: server.sessionNonce }
+ * import { SPDHandshake, SPD } from 'spd-lib';
  *
- * // ── Client (after receiving server publicKey + nonce) ────────────
- * const client = SPDHandshake.create();
- * // send to server: { publicKey: client.publicKey, nonce: client.sessionNonce }
- * const clientResult = client.derive(server.publicKey, server.sessionNonce);
+ * // ── Initiator (client) ───────────────────────────────────────────────────────
+ * const init = await SPDHandshake.createInitiator();
+ * socket.send(JSON.stringify(init.hello));         // { hybridClassicalPub, kemPub, nonce }
  *
- * // ── Server (after receiving client publicKey + nonce) ────────────
- * const serverResult = server.derive(client.publicKey, client.sessionNonce);
+ * const respHello = JSON.parse(await socket.recv());
+ * const initResult = await init.finalizeInitiator(respHello);
  *
- * // Verify both sides derived the same key (compare commitments over the wire)
- * // clientResult.commitment === serverResult.commitment  →  true
+ * // ── Responder (server) ───────────────────────────────────────────────────────
+ * const resp = await SPDHandshake.createResponder(initHello);
+ * socket.send(JSON.stringify(resp.hello));         // { hybridClassicalPub, kemCt, nonce }
+ * const respResult = resp.responderResult();
  *
- * // Use session passphrase directly with SPD (already 256-bit entropy)
- * const spd = new SPD();
- * spd.setKeyProfile('standard');
- * await spd.setPassKey(serverResult.sessionKey);
+ * // ── Both sides: verify commitment matches before using key ───────────────────
+ * // exchange initResult.commitment <→ respResult.commitment over the wire
+ * // if they match, both sides have the same session key
  *
- * // Zero the passphrase from memory when done with setup
- * serverResult.destroy();
+ * const spd = new SPD();
+ * spd.setKeyProfile('standard');   // session key is already 256-bit entropy
+ * await spd.setPassKey(initResult.sessionKey);
+ * initResult.destroy();            // zero raw key bytes from memory
  * ```
  */
 /**
- * Result of a completed handshake derivation.
- * Holds the session passphrase and key commitment.
- * Call `destroy()` once the passphrase has been handed to SPD's `setPassKey`.
+ * Message sent during the handshake exchange.
+ *
+ * The session key is derived from BOTH `hybridClassicalPub` (X25519) AND
+ * `hybridQuantumData` (ML-KEM-768) via HKDF. An attacker must break
+ * **both** simultaneously — classical hardness AND post-quantum hardness.
+ * Neither field alone is sufficient to recover the session key.
+ */
+interface SPDHandshakeHello {
+    /**
+     * Classical half of the hybrid: base64url-encoded X25519 ephemeral public
+     * key (32 bytes). Provides ~2^128 classical security. NOT quantum-safe
+     * alone — security comes from the hybrid combination with `hybridQuantumData`.
+     */
+    hybridClassicalPub: string;
+    /**
+     * Post-quantum half of the hybrid (base64url-encoded):
+     * - Initiator hello: ML-KEM-768 public key (1184 bytes) for encapsulation.
+     * - Responder hello: ML-KEM-768 ciphertext (1088 bytes) from encapsulation.
+     * Provides ~2^178 quantum security (NIST FIPS 203 / ML-KEM-768).
+     */
+    hybridQuantumData: string;
+    /** Base64url-encoded random session nonce (32 bytes). */
+    nonce: string;
+}
+/**
+ * Completed handshake result.
+ * Call `destroy()` immediately after passing `sessionKey` to `spd.setPassKey()`.
  */
 declare class SPDHandshakeResult {
-    /** 64-char hex session passphrase (256 bits). Pass to `spd.setPassKey()`. */
+    /**
+     * 64-character hex session passphrase (256 bits of entropy).
+     * Pass directly to `spd.setPassKey()`.
+     */
     readonly sessionKey: string;
     /**
-     * CMT-4 key commitment: SHA3-256(sessionKeyBytes ∥ sessionNonce).
-     * Base64url-encoded, 32 bytes.  Share over the wire so both parties can
-     * verify they derived the same secret without revealing the secret itself.
+     * CMT-4 key commitment: SHA3-256(sessionKeyBytes ∥ transcriptHash).
+     * Base64url-encoded (32 bytes).
+     *
+     * Exchange this with the other party and verify they match BEFORE using
+     * `sessionKey`. If they differ, abort — a MITM substituted a key.
      */
     readonly commitment: string;
     private _raw;
     /** @internal */
-    constructor(raw: Buffer, nonce: Buffer);
-    /** Zero the raw session key bytes from memory. */
+    constructor(raw: Buffer, transcript: Buffer);
+    /**
+     * Zero the raw session key bytes from memory.
+     * The `sessionKey` hex string may still exist in the JS heap
+     * (strings are immutable in V8); call this as soon as `setPassKey()` is done.
+     */
     destroy(): void;
 }
-/** An ephemeral X25519 handshake participant. */
-declare class SPDHandshake {
+/** Initiator state returned by `SPDHandshake.createInitiator()`. */
+declare class SPDHandshakeInitiator {
+    /** Send this to the responder. */
+    readonly hello: SPDHandshakeHello;
+    private _x25519Priv;
+    private _kemSecretMask;
+    private _blindedKemSK;
+    private _nonceRaw;
+    private _done;
+    /** @internal */
+    constructor(x25519PrivRaw: Buffer, hybridClassicalPubRaw: Buffer, kemSecretKey: Uint8Array, kemPublicKey: Uint8Array, nonce: Buffer);
     /**
-     * Base64url-encoded X25519 public key (32 bytes).
-     * Transmit this to the other party.
+     * Complete the initiator side of the handshake using the responder's hello.
+     *
+     * @param responderHello  The `hello` object received from the responder.
+     * @returns  `SPDHandshakeResult` — call `.destroy()` after `setPassKey()`.
+     * @throws   If already called, or if any input is malformed.
      */
-    readonly publicKey: string;
+    finalizeInitiator(responderHello: SPDHandshakeHello): Promise<SPDHandshakeResult>;
+    /** Zero all key material. Call if abandoning the handshake. */
+    destroy(): void;
+}
+/** Responder state returned by `SPDHandshake.createResponder()`. */
+declare class SPDHandshakeResponder {
+    /** Send this to the initiator. */
+    readonly hello: SPDHandshakeHello;
+    private _result;
+    /** @internal */
+    constructor(hello: SPDHandshakeHello, result: SPDHandshakeResult);
     /**
-     * Cryptographically random session nonce (32 bytes, base64url).
-     * Transmit this alongside `publicKey`. Mixed into HKDF to prevent
-     * cross-session key reuse even if the same ephemeral keypair were
-     * somehow reused.
+     * Return the completed session result.
+     * The responder derives its key during `createResponder()` — call this
+     * after sending `hello` to the initiator.
      */
-    readonly sessionNonce: string;
-    private _blindedPriv;
-    private _privMask;
-    private _nonceRaw;
+    responderResult(): SPDHandshakeResult;
+}
+declare class SPDHandshake {
     private constructor();
     /**
-     * Create a new ephemeral participant with a freshly generated X25519 keypair
-     * and a random session nonce.
-     */
-    static create(): SPDHandshake;
-    /**
-     * Derive the shared session key from the other party's public key and nonce.
+     * Create the initiator side of the handshake.
      *
-     * Both parties must call `derive()` with each other's `publicKey` and
-     * `sessionNonce`. The resulting `SPDHandshakeResult.commitment` values will
-     * match if and only if both sides derived the same key.
+     * Generates an ephemeral X25519 keypair and ML-KEM-768 keypair.
+     * Send `initiator.hello` to the responder.
      *
-     * @param theirPublicKey   The other party's `publicKey` string.
-     * @param theirSessionNonce  The other party's `sessionNonce` string.
-     * @returns  `SPDHandshakeResult` containing the session passphrase and
-     *           CMT-4 key commitment. Call `.destroy()` after handing the
-     *           passphrase to `spd.setPassKey()`.
-     * @throws   If `derive()` has already been called on this instance.
-     * @throws   If the public key is malformed or the low-order point check fails.
+     * @returns  `SPDHandshakeInitiator` instance.
      */
-    derive(theirPublicKey: string, theirSessionNonce: string): SPDHandshakeResult;
+    static createInitiator(): Promise<SPDHandshakeInitiator>;
     /**
-     * Zero and release all key material.
-     * Called automatically by `derive()`. Call manually if you abandon the
-     * handshake without completing it.
+     * Create the responder side of the handshake from the initiator's hello.
+     *
+     * Generates an ephemeral X25519 keypair, encapsulates against the
+     * initiator's ML-KEM public key, and derives the session key.
+     * Send `responder.hello` to the initiator.
+     *
+     * @param initiatorHello  The `hello` object received from the initiator.
+     * @returns  `SPDHandshakeResponder` instance.
+     * @throws   If any input is malformed or a low-order point is detected.
      */
-    destroy(): void;
+    static createResponder(initiatorHello: SPDHandshakeHello): Promise<SPDHandshakeResponder>;
 }
 
-export { ARGON2_MEMORY_HIGH, ARGON2_MEMORY_PARANOID, ARGON2_TIME_HIGH, ARGON2_TIME_PARANOID, type DataInput, type EncryptedDataEntry, type EncryptedSaltResult, type HashAlgorithm, type PBKResult, type PQCKey, type PQCKeyResult, SPD, type SPDBenchmarkResult, type SPDChunkManifest, type SPDClientConnectOptions, type SPDClientHandshake, type SPDDiffResult, type SPDGetEntryResult, SPDHandshake, SPDHandshakeResult, type SPDIndexEntry, type SPDInspectResult, type SPDKeyProfile, type SPDKeyProvider, SPDLegacy, type SPDLegacyPayload, type SPDLogEvent, type SPDMergeOptions, type SPDPayload, type SPDRepairResult, type SPDServerIdentity, type SPDSession, SPDShamir, type SPDShamirShare, type SPDSigningKeyPair, type SPDSnapshot, SPDTransport, SPDVault, type SPDVerifyResult, SPDWriter, type SPDWriterOptions, SPDLegacy as SPD_LEG, SPDVault as SPD_Vault, type SerializedDataEntry, type SerializedWrappedPayload, type SupportedDataType, type SupportedValue, type TypedArray, type WrappedPayload };
+export { ARGON2_MEMORY_HIGH, ARGON2_MEMORY_PARANOID, ARGON2_TIME_HIGH, ARGON2_TIME_PARANOID, type DataInput, type EncryptedDataEntry, type EncryptedSaltResult, type GenericCryptoObservable, type GenericScoreResult, type HashAlgorithm, type LibraryProfile, type PBKResult, type PQCKey, type PQCKeyResult, SPD, type SPDBenchmarkResult, type SPDChunkManifest, type SPDClientConnectOptions, type SPDClientHandshake, type SPDDiffResult, type SPDGetEntryResult, SPDHandshake, type SPDHandshakeHello, SPDHandshakeInitiator, SPDHandshakeResponder, SPDHandshakeResult, type SPDIndexEntry, type SPDInspectResult, type SPDKeyProfile, type SPDKeyProvider, SPDLegacy, type SPDLegacyPayload, type SPDLogEvent, type SPDMergeOptions, type SPDPayload, type SPDRepairResult, type SPDServerIdentity, type SPDSession, SPDShamir, type SPDShamirShare, type SPDSigningKeyPair, type SPDSnapshot, SPDTransport, SPDVault, type SPDVerifyResult, SPDWriter, type SPDWriterOptions, SPDLegacy as SPD_LEG, SPDVault as SPD_Vault, type SerializedDataEntry, type SerializedWrappedPayload, type SupportedDataType, type SupportedValue, type TypedArray, type WrappedPayload, analyzeGenericDir, listKnownLibraries, scoreGenericSystem, scoreNpmLibrary, scoreSPD };