p2party 0.8.0 → 0.14.2

package/lib/cryptography/coverCell.d.ts

@@ -0,0 +1,65 @@
+import { type RatchetRootSuite } from "../utils/constants";
+import type { LibCrypto } from "./libcrypto";
+export declare const COVER_CELL_HEADER_BYTES: number;
+export declare const COVER_CELL_PLAINTEXT_BYTES: number;
+export declare const COVER_CELL_BINDING_BYTES = 32;
+export declare const COVER_CELL_ROOT_BYTES = 32;
+export declare const COVER_CELL_TOKEN_BYTES: number;
+export declare const COVER_CELL_MAX_PAYLOAD_BYTES: number;
+export type CoverCellDirection = "initiator-to-responder" | "responder-to-initiator";
+export type CoverCellContent = {
+    readonly subtype: "dummy";
+} | {
+    /** Explicit encrypted CANCEL for exactly one admitted transfer. */
+    readonly subtype: "cancel";
+    readonly merkleRoot: Uint8Array;
+} | {
+    /**
+     * Scheduled receipt (per-cell ack or terminal completion token), scoped
+     * to its transfer root. Never the 65-byte immediate receipt frame.
+     */
+    readonly subtype: "receipt";
+    readonly merkleRoot: Uint8Array;
+    readonly token: Uint8Array;
+};
+export type CoverCellErrorCode = "authentication-failed" | "binding-mismatch" | "epoch-mismatch" | "invalid-cell" | "invalid-direction" | "invalid-padding" | "replayed-counter";
+export declare class CoverCellError extends Error {
+    readonly code: CoverCellErrorCode;
+    constructor(code: CoverCellErrorCode, message: string);
+}
+export interface SealCoverCellOptions {
+    readonly module: LibCrypto;
+    readonly rootSuite: RatchetRootSuite;
+    /** Current epoch's PQ message root (borrowed; never wiped here). */
+    readonly rootKey: Uint8Array;
+    readonly binding: Uint8Array;
+    readonly direction: CoverCellDirection;
+    readonly keyEpoch: bigint;
+    /** Strictly increasing per-direction cover counter (replay ordering). */
+    readonly counter: bigint;
+    readonly content: CoverCellContent;
+}
+export interface OpenCoverCellOptions {
+    readonly module: LibCrypto;
+    readonly rootSuite: RatchetRootSuite;
+    readonly rootKey: Uint8Array;
+    readonly binding: Uint8Array;
+    /** Expected inbound direction; the opposite direction derives another key. */
+    readonly direction: CoverCellDirection;
+    readonly keyEpoch: bigint;
+    /** Highest already-accepted counter; the cell must be strictly newer. */
+    readonly counterAbove?: bigint;
+    readonly frame: Uint8Array;
+}
+export interface OpenedCoverCell {
+    readonly content: CoverCellContent;
+    readonly counter: bigint;
+}
+/** Seal one authenticated fixed-size cover cell (dummy, CANCEL, or receipt). */
+export declare const sealCoverCell: (options: SealCoverCellOptions) => Uint8Array;
+/**
+ * Authenticate one fixed-size cover cell and return its content. The subtype
+ * is knowable only after this authentication succeeds; an unauthentic cell
+ * reveals nothing and terminates nothing.
+ */
+export declare const openCoverCell: (options: OpenCoverCellOptions) => OpenedCoverCell;

package/lib/cryptography/cpace.d.ts

@@ -0,0 +1,41 @@
+import type { LibCrypto } from "./libcrypto";
+/**
+ * CPace draft-21 prepend_len(): unsigned LEB128 byte length followed by value.
+ * Exported so the standards KAT can freeze the transcript encoding independently
+ * of the group operation.
+ */
+export declare const encodeCpaceLength: (length: number) => Uint8Array;
+/**
+ * CPACE-RISTR255-SHA512 generator from draft-irtf-cfrg-cpace-21:
+ *
+ * generator_string =
+ *   lv_cat(DSI, PRS, zero_bytes(len_zpad), CI, sid)
+ *
+ * where len_zpad fills the first SHA-512 input block after DSI and PRS.
+ */
+export declare const deriveGenerator: (pin: Uint8Array, sid: Uint8Array, channelInput: Uint8Array, module: LibCrypto) => Uint8Array;
+/** y <- uniform non-zero ristretto255 scalar; Y = y*G. */
+export declare const cpaceStart: (generator: Uint8Array, module: LibCrypto) => {
+    y: Uint8Array;
+    Y: Uint8Array;
+};
+export interface CpaceFinishParams {
+    /** Caller's one-use private scalar. */
+    y: Uint8Array;
+    /** Remote party's encoded Ristretto255 share. */
+    peerShare: Uint8Array;
+    /** Shared CPace session identifier. */
+    sid: Uint8Array;
+    /** Initiator and responder shares in protocol order. */
+    initiatorShare: Uint8Array;
+    responderShare: Uint8Array;
+    /** Optional associated data; identities are already role-bound in CI here. */
+    initiatorAssociatedData?: Uint8Array;
+    responderAssociatedData?: Uint8Array;
+}
+/**
+ * Finish draft-21 CPace and return only ISK. The intermediate shared point K
+ * never enters JavaScript and is wiped in WASM before return, as required by
+ * draft §10.3.
+ */
+export declare const cpaceFinish: (params: CpaceFinishParams, module: LibCrypto) => Uint8Array;

package/lib/cryptography/ed25519.d.ts

@@ -9,4 +9,3 @@ export declare const keyPairFromSecretKey: (secretKey: Uint8Array, module?: LibC
  */
 export declare const sign: (message: Uint8Array, secretKey: Uint8Array, module?: LibCrypto) => Promise<Uint8Array>;
 export declare const verify: (message: Uint8Array, signature: Uint8Array, publicKey: Uint8Array, module?: LibCrypto) => Promise<boolean>;
-//# sourceMappingURL=ed25519.d.ts.map

package/lib/cryptography/hashStream.d.ts

@@ -0,0 +1,15 @@
+import type { LibCrypto } from "./libcrypto";
+/**
+ * Compute the plain SHA-512 of a File incrementally: read it one
+ * HASH_WINDOW_BYTES slice at a time (O(1) memory — the whole file is never
+ * resident) and feed each slice to the WASM streaming hash in
+ * HASH_WASM_CHUNK_BYTES sub-chunks (the WASM heap buffer is tiny and fixed,
+ * since the merkle module's memory cannot grow). The result is byte-identical
+ * to `crypto.subtle.digest("SHA-512", <whole file>)` (plain SHA-512, no domain
+ * separation), so it drops in for the previous whole-file-in-RAM digest.
+ *
+ * @param file - the File to hash (disk-backed; slices load lazily).
+ * @param module - a LibCrypto exposing _sha512_init/update/final + _malloc/_free.
+ * @returns the 64-byte SHA-512 digest.
+ */
+export declare const hashFileStreaming: (file: File, module: LibCrypto, signal?: AbortSignal) => Promise<Uint8Array>;

package/lib/cryptography/hkdf.d.ts

@@ -0,0 +1,3 @@
+import type { LibCrypto } from "./libcrypto";
+export declare const hkdfExtract: (salt: Uint8Array, ikm: Uint8Array, module: LibCrypto) => Uint8Array;
+export declare const hkdfExpand: (prk: Uint8Array, info: Uint8Array, outLen: number, module: LibCrypto) => Uint8Array;

package/lib/cryptography/identityCrossSig.d.ts

@@ -0,0 +1,7 @@
+import type { LibCrypto } from "./libcrypto";
+/** The signed/verified transcript: IDENTITY_CROSS_SIGN_DOMAIN ‖ X25519_pub. */
+export declare const identityCrossSignMessage: (x25519Pub: Uint8Array) => Uint8Array;
+/** Produce the cross-signature over (DOMAIN ‖ x25519Pub) with the Ed25519 secret. */
+export declare const crossSignIdentityX25519: (x25519Pub: Uint8Array, ed25519Secret: Uint8Array, module?: LibCrypto) => Promise<Uint8Array>;
+/** Verify a cross-signature against the peer's pinned Ed25519 identity pub. */
+export declare const verifyIdentityCrossSig: (x25519Pub: Uint8Array, crossSig: Uint8Array, ed25519Pub: Uint8Array, module?: LibCrypto) => Promise<boolean>;

package/lib/cryptography/interfaces.d.ts

@@ -1,25 +1,33 @@
 export declare const crypto_auth_hmacsha512_BYTES: number;
 export declare const crypto_auth_hmacsha512_KEYBYTES: number;
 export declare const crypto_hash_sha512_BYTES: number;
+export declare const crypto_hash_sha512_STATEBYTES = 208;
 export declare const crypto_sign_ed25519_BYTES: number;
 export declare const crypto_sign_ed25519_SEEDBYTES: number;
 export declare const crypto_sign_ed25519_PUBLICKEYBYTES: number;
 export declare const crypto_sign_ed25519_SECRETKEYBYTES: number;
 export declare const crypto_secretbox_KEYBYTES: number;
 export declare const crypto_secretbox_NONCEBYTES: number;
-export declare const crypto_box_poly1305_AUTHTAGBYTES: number;
-export declare const crypto_box_x25519_PUBLICKEYBYTES: number;
-export declare const crypto_box_x25519_SECRETKEYBYTES: number;
-export declare const crypto_box_x25519_NONCEBYTES: number;
 export declare const crypto_aead_chacha20poly1305_ietf_KEYBYTES: number;
 export declare const crypto_aead_chacha20poly1305_ietf_NPUBBYTES: number;
+export declare const crypto_aead_chacha20poly1305_ietf_ABYTES: number;
 export declare const crypto_pwhash_argon2id_SALTBYTES: number;
+export declare const crypto_core_ristretto255_BYTES: number;
+export declare const crypto_core_ristretto255_HASHBYTES: number;
+export declare const crypto_core_ristretto255_SCALARBYTES: number;
+export declare const crypto_scalarmult_ristretto255_BYTES: number;
+export declare const crypto_scalarmult_curve25519_BYTES: number;
+export declare const crypto_scalarmult_curve25519_SCALARBYTES: number;
+export declare const mlkem768_PUBLICKEYBYTES: number;
+export declare const mlkem768_SECRETKEYBYTES: number;
+export declare const mlkem768_CIPHERTEXTBYTES: number;
+export declare const mlkem768_BYTES: number;
+export declare const mlkem768_KEYPAIRCOINBYTES: number;
+export declare const mlkem768_ENCAPSCOINBYTES: number;
 export interface SignKeyPair {
     publicKey: Uint8Array;
     secretKey: Uint8Array;
 }
-export declare const getEncryptedLen: (dataLen: number) => number;
-export declare const getDecryptedLen: (encryptedLen: number) => number;
 declare const _default: {
     crypto_hash_sha512_BYTES: number;
     crypto_sign_ed25519_BYTES: number;
@@ -28,13 +36,20 @@ declare const _default: {
     crypto_sign_ed25519_SECRETKEYBYTES: number;
     crypto_secretbox_KEYBYTES: number;
     crypto_secretbox_NONCEBYTES: number;
-    crypto_box_poly1305_AUTHTAGBYTES: number;
-    crypto_box_x25519_PUBLICKEYBYTES: number;
-    crypto_box_x25519_SECRETKEYBYTES: number;
-    crypto_box_x25519_NONCEBYTES: number;
     crypto_aead_chacha20poly1305_ietf_KEYBYTES: number;
-    getEncryptedLen: (dataLen: number) => number;
-    getDecryptedLen: (encryptedLen: number) => number;
+    crypto_aead_chacha20poly1305_ietf_NPUBBYTES: number;
+    crypto_aead_chacha20poly1305_ietf_ABYTES: number;
+    crypto_core_ristretto255_BYTES: number;
+    crypto_core_ristretto255_HASHBYTES: number;
+    crypto_core_ristretto255_SCALARBYTES: number;
+    crypto_scalarmult_ristretto255_BYTES: number;
+    crypto_scalarmult_curve25519_BYTES: number;
+    crypto_scalarmult_curve25519_SCALARBYTES: number;
+    mlkem768_PUBLICKEYBYTES: number;
+    mlkem768_SECRETKEYBYTES: number;
+    mlkem768_CIPHERTEXTBYTES: number;
+    mlkem768_BYTES: number;
+    mlkem768_KEYPAIRCOINBYTES: number;
+    mlkem768_ENCAPSCOINBYTES: number;
 };
 export default _default;
-//# sourceMappingURL=interfaces.d.ts.map

package/lib/cryptography/memory.d.ts

@@ -1,16 +1,14 @@
 declare const _default: {
     newKeyPairMemory: () => WebAssembly.Memory;
+    identityX25519KeypairMemory: () => WebAssembly.Memory;
     keyPairFromSeedMemory: () => WebAssembly.Memory;
     keyPairFromSecretKeyMemory: () => WebAssembly.Memory;
     signMemory: (messageLen: number) => WebAssembly.Memory;
     verifyMemory: (messageLen: number) => WebAssembly.Memory;
-    encryptAsymmetricMemory: (messageLen: number, additionalDataLen: number) => WebAssembly.Memory;
-    decryptAsymmetricMemory: (encryptedLen: number, additionalDataLen: number) => WebAssembly.Memory;
+    protocolV3Memory: () => WebAssembly.Memory;
     getMerkleRootMemory: (leavesLen: number) => WebAssembly.Memory;
     getMerkleProofMemory: (leavesLen: number) => WebAssembly.Memory;
     verifyMerkleProofMemory: (proofLen: number) => WebAssembly.Memory;
     argon2Memory: (mnemonicLen: number) => WebAssembly.Memory;
-    getReceiveMessageMemory: () => WebAssembly.Memory;
 };
 export default _default;
-//# sourceMappingURL=memory.d.ts.map

package/lib/cryptography/merkle.d.ts

@@ -40,4 +40,3 @@ export declare const getMerkleRootFromProof: (item: Uint8Array, proof: Uint8Arra
  * byte is either 0 or 1, indicating whether it is to the left or to the right in the tree.
  */
 export declare const verifyMerkleProof: (item: Uint8Array, root: Uint8Array, proof: Uint8Array, module?: LibCrypto) => Promise<boolean>;
-//# sourceMappingURL=merkle.d.ts.map

package/lib/cryptography/mlkem.d.ts

@@ -0,0 +1,117 @@
+import type { LibCrypto } from "./libcrypto";
+export type MlKemParameterSet = 512 | 768 | 1024;
+export declare const ML_KEM_512_PUBLIC_KEY_BYTES = 800;
+export declare const ML_KEM_512_SECRET_KEY_BYTES = 1632;
+export declare const ML_KEM_512_CIPHERTEXT_BYTES = 768;
+export declare const ML_KEM_768_PUBLIC_KEY_BYTES = 1184;
+export declare const ML_KEM_768_SECRET_KEY_BYTES = 2400;
+export declare const ML_KEM_768_CIPHERTEXT_BYTES = 1088;
+export declare const ML_KEM_1024_PUBLIC_KEY_BYTES = 1568;
+export declare const ML_KEM_1024_SECRET_KEY_BYTES = 3168;
+export declare const ML_KEM_1024_CIPHERTEXT_BYTES = 1568;
+export declare const ML_KEM_SHARED_SECRET_BYTES = 32;
+export declare const ML_KEM_KEYPAIR_RANDOM_BYTES = 64;
+export declare const ML_KEM_ENCAPS_RANDOM_BYTES = 32;
+type MlKemKeyPairExport<P extends MlKemParameterSet> = `_mlkem${P}_keypair`;
+type MlKemEncapsExport<P extends MlKemParameterSet> = `_mlkem${P}_encaps`;
+type MlKemDecapsExport<P extends MlKemParameterSet> = `_mlkem${P}_decaps`;
+/**
+ * Complete runtime description of one FIPS 203 parameter set.
+ *
+ * The sizes are carried with the selected suite so callers cannot
+ * accidentally validate an ML-KEM-512 key with ML-KEM-768 constants.
+ */
+export interface MlKemSuiteDescriptor<P extends MlKemParameterSet = MlKemParameterSet> {
+    readonly parameterSet: P;
+    readonly standardName: `ML-KEM-${P}`;
+    readonly publicKeyBytes: number;
+    readonly secretKeyBytes: number;
+    readonly ciphertextBytes: number;
+    readonly sharedSecretBytes: typeof ML_KEM_SHARED_SECRET_BYTES;
+    readonly keyPairRandomBytes: typeof ML_KEM_KEYPAIR_RANDOM_BYTES;
+    readonly encapsRandomBytes: typeof ML_KEM_ENCAPS_RANDOM_BYTES;
+    readonly wasmExports: {
+        readonly keypair: MlKemKeyPairExport<P>;
+        readonly encaps: MlKemEncapsExport<P>;
+        readonly decaps: MlKemDecapsExport<P>;
+    };
+}
+export declare const ML_KEM_512_SUITE: Readonly<MlKemSuiteDescriptor<512>>;
+export declare const ML_KEM_768_SUITE: Readonly<MlKemSuiteDescriptor<768>>;
+export declare const ML_KEM_1024_SUITE: Readonly<MlKemSuiteDescriptor<1024>>;
+export declare const ML_KEM_SUITES: Readonly<{
+    512: Readonly<MlKemSuiteDescriptor<512>>;
+    768: Readonly<MlKemSuiteDescriptor<768>>;
+    1024: Readonly<MlKemSuiteDescriptor<1024>>;
+}>;
+export declare const getMlKemSuite: <P extends MlKemParameterSet>(parameterSet: P) => Readonly<MlKemSuiteDescriptor<P>>;
+type MlKemKeyPairFunction = (publicKey: number, secretKey: number, coins64: number) => number;
+type MlKemEncapsFunction = (ciphertext: number, sharedSecret: number, publicKey: number, coins32: number) => number;
+type MlKemDecapsFunction = (sharedSecret: number, ciphertext: number, secretKey: number) => number;
+/**
+ * The deterministic ABI exported by the pinned, portable mlkem-native build.
+ * JavaScript supplies all entropy; the WASM has no second RNG path.
+ */
+export interface MlKemModule extends LibCrypto {
+    _mlkem512_keypair: MlKemKeyPairFunction;
+    _mlkem512_encaps: MlKemEncapsFunction;
+    _mlkem512_decaps: MlKemDecapsFunction;
+    _mlkem768_keypair: MlKemKeyPairFunction;
+    _mlkem768_encaps: MlKemEncapsFunction;
+    _mlkem768_decaps: MlKemDecapsFunction;
+    _mlkem1024_keypair: MlKemKeyPairFunction;
+    _mlkem1024_encaps: MlKemEncapsFunction;
+    _mlkem1024_decaps: MlKemDecapsFunction;
+}
+/** Compatibility type for protocol-v3 code while suite negotiation lands. */
+export type MlKem768Module = LibCrypto & Pick<MlKemModule, "_mlkem768_keypair" | "_mlkem768_encaps" | "_mlkem768_decaps">;
+export interface MlKemKeyPair {
+    /** A copy suitable for transport or serialization. This is not secret. */
+    readonly publicKey: Uint8Array;
+    /**
+     * Plaintext secret key bytes suitable for encrypted serialization.
+     * Call destroy() as soon as the key is no longer needed.
+     */
+    readonly secretKey: Uint8Array;
+    readonly destroyed: boolean;
+    /** Idempotently wipes this object's secretKey bytes. */
+    destroy(): void;
+}
+export interface MlKemEncapsulation {
+    /** A copy suitable for transport or serialization. This is not secret. */
+    readonly ciphertext: Uint8Array;
+    /** Plaintext shared-secret bytes. Mix into a KDF, then call destroy(). */
+    readonly sharedSecret: Uint8Array;
+    readonly destroyed: boolean;
+    /** Idempotently wipes this object's sharedSecret bytes. */
+    destroy(): void;
+}
+export interface MlKemDecapsulation {
+    /** Plaintext shared-secret bytes. Mix into a KDF, then call destroy(). */
+    readonly sharedSecret: Uint8Array;
+    readonly destroyed: boolean;
+    /** Idempotently wipes this object's sharedSecret bytes. */
+    destroy(): void;
+}
+/**
+ * Async-compatible ML-KEM API. The WASM calls are synchronous, but promises
+ * allow a worker-backed implementation without changing protocol state
+ * machines.
+ */
+export interface MlKemBackend<P extends MlKemParameterSet = MlKemParameterSet> {
+    readonly suite: Readonly<MlKemSuiteDescriptor<P>>;
+    generateKeyPair(): Promise<MlKemKeyPair>;
+    encapsulate(publicKey: Uint8Array): Promise<MlKemEncapsulation>;
+    decapsulate(ciphertext: Uint8Array, secretKey: Uint8Array): Promise<MlKemDecapsulation>;
+}
+/** Compatibility aliases for the currently shipped ML-KEM-768 handshake. */
+export type MlKem768KeyPair = MlKemKeyPair;
+export type MlKem768Encapsulation = MlKemEncapsulation;
+export type MlKem768Decapsulation = MlKemDecapsulation;
+export type MlKem768Backend = MlKemBackend<768>;
+export declare const createMlKemBackend: <P extends MlKemParameterSet>(module: LibCrypto, suite: Readonly<MlKemSuiteDescriptor<P>>) => MlKemBackend<P>;
+/**
+ * Temporary compatibility factory for the protocol-v3 ML-KEM-768 wire suite.
+ */
+export declare const createMlKem768Backend: (module: LibCrypto) => MlKem768Backend;
+export {};

package/lib/cryptography/mnemonic.d.ts

@@ -27,4 +27,3 @@ export declare const validateMnemonic: (mnemonic: string) => Promise<boolean>;
  * @returns An Ed25519 key pair
  */
 export declare const keyPairFromMnemonic: (mnemonic: string, password?: string) => Promise<import("./interfaces").SignKeyPair>;
-//# sourceMappingURL=mnemonic.d.ts.map

package/lib/cryptography/pqHealing.d.ts

@@ -0,0 +1,268 @@
+import { type MlKemBackend, type MlKemParameterSet, type MlKemSuiteDescriptor } from "./mlkem";
+import type { LibCrypto } from "./libcrypto";
+/**
+ * Sparse post-quantum healing state machine.
+ *
+ * This module deliberately does not own transport or persistence. Callers must:
+ *
+ * 1. authenticate/decrypt every inbound record with the current outer channel
+ *    before calling an `acceptAuthenticated*` method;
+ * 2. persist prepared state before putting its record on the network;
+ * 3. encrypt an ADVANCE under its `fromEpoch` key before committing it; and
+ * 4. gate application traffic while `trafficBlocked` is true.
+ *
+ * There is no classical or lower-parameter fallback. The room-selected suite
+ * supplied to the constructor is checked against both FIPS 203 sizes and the
+ * backend. Every ADVANCE embeds the complete OFFER it answers. That makes the
+ * exact suite, channel binding, epochs, counters, public key, and ciphertext a
+ * single deterministic KDF transcript and gives the state machine an exact
+ * byte string with which to reject replays and forks.
+ */
+export declare const PQ_HEALING_BINDING_BYTES = 32;
+export declare const PQ_HEALING_ROOT_BYTES = 32;
+export declare const PQ_HEALING_RECORD_HEADER_BYTES = 64;
+export declare const PQ_HEALING_ACK_BYTES = 64;
+export declare const PQ_HEALING_SNAPSHOT_FORMAT_VERSION = 1;
+export type PqHealingTurn = "local" | "remote";
+export type PqHealingPhase = "idle" | "outbound-offer-prepared" | "outbound-offer-dispatched" | "inbound-offer" | "outbound-advance-prepared" | "outbound-advance-awaiting-ack" | "inbound-advance-prepared" | "inbound-advance-awaiting-ack-dispatch" | "destroyed";
+export type PqHealingErrorCode = "binding-mismatch" | "counter-gap" | "destroyed" | "epoch-gap" | "fork" | "invalid-record" | "invalid-state" | "overflow" | "replay" | "suite-mismatch" | "wrong-turn";
+export declare class PqHealingError extends Error {
+    readonly code: PqHealingErrorCode;
+    constructor(code: PqHealingErrorCode, message: string);
+}
+export interface PqHealingAdvanceAcknowledgement {
+    /**
+     * The newly committed epoch. The transport acknowledgement must be
+     * authenticated under this epoch, proving that the offerer decapsulated.
+     */
+    readonly epoch: bigint;
+    /** Sender counter of the ADVANCE being acknowledged. */
+    readonly advanceCounter: bigint;
+}
+export interface PqHealingOfferRecord {
+    readonly type: "offer";
+    readonly parameterSet: MlKemParameterSet;
+    readonly binding: Uint8Array;
+    readonly senderCounter: bigint;
+    readonly fromEpoch: bigint;
+    readonly toEpoch: bigint;
+    readonly publicKey: Uint8Array;
+}
+export interface PqHealingAdvanceRecord {
+    readonly type: "advance";
+    readonly parameterSet: MlKemParameterSet;
+    readonly binding: Uint8Array;
+    readonly senderCounter: bigint;
+    readonly fromEpoch: bigint;
+    readonly toEpoch: bigint;
+    /** The complete, canonical OFFER answered by this record. */
+    readonly offerBytes: Uint8Array;
+    readonly offer: PqHealingOfferRecord;
+    readonly ciphertext: Uint8Array;
+}
+export type PqHealingRecord = PqHealingOfferRecord | PqHealingAdvanceRecord;
+export interface PqHealingMachineOptions<P extends MlKemParameterSet> {
+    readonly module: LibCrypto;
+    readonly backend: MlKemBackend<P>;
+    /**
+     * Authenticated room-selected suite. This is an input, never a negotiated
+     * result. It must exactly match the backend's parameter set and FIPS sizes.
+     */
+    readonly suite: Readonly<MlKemSuiteDescriptor<P>>;
+    /**
+     * Non-secret, transcript-derived edge binding (for example a truncation of
+     * the authenticated handshake/channel-input hash).
+     */
+    readonly binding: Uint8Array;
+    /** Current, separate PQ root. The constructor takes an owned copy. */
+    readonly rootKey: Uint8Array;
+    /** Which side is allowed to emit the first/next OFFER. */
+    readonly nextOfferer: PqHealingTurn;
+    readonly epoch?: bigint;
+    readonly localCounter?: bigint;
+    readonly remoteCounter?: bigint;
+}
+export interface PqHealingRestoreOptions<P extends MlKemParameterSet> {
+    readonly module: LibCrypto;
+    readonly backend: MlKemBackend<P>;
+    readonly suite: Readonly<MlKemSuiteDescriptor<P>>;
+    /** Authenticated expected edge binding; snapshots from another edge fail. */
+    readonly binding: Uint8Array;
+}
+export type PqHealingSnapshotPhase = {
+    readonly kind: "idle";
+} | {
+    readonly kind: "outbound-offer-prepared" | "outbound-offer-dispatched";
+    readonly offer: Uint8Array;
+    readonly secretKey: Uint8Array;
+} | {
+    readonly kind: "inbound-offer";
+    readonly offer: Uint8Array;
+} | {
+    readonly kind: "outbound-advance-prepared";
+    readonly advance: Uint8Array;
+    readonly nextRoot: Uint8Array;
+} | {
+    readonly kind: "outbound-advance-awaiting-ack";
+    readonly advance: Uint8Array;
+} | {
+    readonly kind: "inbound-advance-prepared";
+    readonly advance: Uint8Array;
+    readonly secretKey: Uint8Array;
+    readonly nextRoot: Uint8Array;
+} | {
+    readonly kind: "inbound-advance-awaiting-ack-dispatch";
+    readonly advance: Uint8Array;
+};
+/**
+ * Owned, plaintext checkpoint of the complete store-free PQ machine.
+ *
+ * Durable integration normally checkpoints only phases whose corresponding
+ * sealed outbox frame is committed in the same transaction. The two
+ * `*-prepared` phases are intentionally representable for clone/rollback and
+ * fault-injection tests, but are transaction-local and must never be persisted
+ * alone or dispatched after restoration without the exact sealed frame.
+ */
+export interface PqHealingSnapshot<P extends MlKemParameterSet = MlKemParameterSet> {
+    readonly formatVersion: typeof PQ_HEALING_SNAPSHOT_FORMAT_VERSION;
+    readonly parameterSet: P;
+    readonly binding: Uint8Array;
+    readonly rootKey: Uint8Array;
+    readonly epoch: bigint;
+    readonly localCounter: bigint;
+    readonly remoteCounter: bigint;
+    readonly nextOfferer: PqHealingTurn;
+    readonly phase: PqHealingSnapshotPhase;
+    readonly lastInboundOffer: Uint8Array | null;
+    readonly lastInboundAdvance: Uint8Array | null;
+}
+export declare const getPqHealingRecordLengths: (suite: Readonly<MlKemSuiteDescriptor>) => {
+    readonly offer: number;
+    readonly advance: number;
+};
+/**
+ * Encode the sole canonical PQ acknowledgement representation:
+ *
+ * `magic(4) | version(1) | type(1) | suite(1) | flags(1) | binding(32) |
+ * advanceCounter(u64 BE) | epoch(u64 BE) | reserved(u64=0)`.
+ */
+export declare const encodePqHealingAck: (acknowledgement: unknown, suite: Readonly<MlKemSuiteDescriptor>, binding: Uint8Array) => Uint8Array;
+/** Decode and validate an exact, edge- and suite-bound 64-byte ACK. */
+export declare const decodePqHealingAck: (record: Uint8Array, suite: Readonly<MlKemSuiteDescriptor>, binding: Uint8Array) => PqHealingAdvanceAcknowledgement;
+/**
+ * Parse a canonical record without changing state. Integration code can use
+ * this for routing and audit logs, but MUST still call the stateful
+ * `acceptAuthenticated*` method only after outer authentication.
+ */
+export declare const inspectPqHealingRecord: (record: Uint8Array, suite: Readonly<MlKemSuiteDescriptor>) => PqHealingRecord;
+/**
+ * One directional-turn PQ healing machine for a single authenticated peer
+ * edge. A room mesh owns one instance per edge; a room-wide policy supplies
+ * the same exact ML-KEM parameter set to every instance.
+ */
+export declare class PqHealingMachine<P extends MlKemParameterSet> {
+    #private;
+    constructor(options: PqHealingMachineOptions<P>);
+    static restore<Q extends MlKemParameterSet>(snapshot: unknown, options: PqHealingRestoreOptions<Q>): PqHealingMachine<Q>;
+    get suite(): Readonly<MlKemSuiteDescriptor<P>>;
+    get phase(): PqHealingPhase;
+    get epoch(): bigint;
+    get localCounter(): bigint;
+    get remoteCounter(): bigint;
+    get nextOfferer(): PqHealingTurn;
+    /**
+     * New-epoch messages must not race the control exchange across independent
+     * WebRTC data channels. The integration must hold application traffic while
+     * this is true.
+     */
+    get trafficBlocked(): boolean;
+    /** Explicit owned copy for the message-key combiner or encrypted checkpoint. */
+    copyRootKey(): Uint8Array;
+    /**
+     * Deep-copy the complete checkpoint, including pending ML-KEM secret keys.
+     * See `PqHealingSnapshot`: prepared phases are transaction-local snapshots.
+     */
+    snapshot(): PqHealingSnapshot<P>;
+    /** Deep-clone this machine into independently owned secret buffers. */
+    clone(): PqHealingMachine<P>;
+    /**
+     * Consume an independently authenticated successor. Superseded live secrets
+     * are wiped and `next` becomes destroyed without wiping the moved secrets.
+     */
+    adopt(next: PqHealingMachine<P>): void;
+    /**
+     * Return the exact public record that should be sent/retransmitted. A caller
+     * must never reconstruct a replacement after the original may have escaped.
+     */
+    copyPendingOutboundRecord(): Uint8Array;
+    prepareOffer(): Promise<Uint8Array>;
+    /**
+     * Mark the persisted OFFER as having possibly escaped to the network. After
+     * this point it cannot be aborted or replaced; only its exact bytes may be
+     * retransmitted.
+     */
+    markOfferDispatched(): void;
+    /**
+     * Safe only while the caller can prove the OFFER has never been sent.
+     * The pending ML-KEM secret key is wiped.
+     */
+    abortUnsentOffer(): void;
+    /**
+     * Accept a full OFFER only after the outer AEAD has authenticated it.
+     */
+    acceptAuthenticatedOffer(record: Uint8Array): void;
+    /**
+     * Prepare an ADVANCE and its candidate root. The caller must outer-encrypt
+     * this exact record under `fromEpoch` before committing, then persist the
+     * committed state and sealed record before sending.
+     */
+    prepareAdvance(): Promise<Uint8Array>;
+    /**
+     * Commit the prepared root after the exact ADVANCE has already been sealed
+     * under the old epoch. The returned record is the only record that may be
+     * sent. Application traffic remains blocked until a new-epoch authenticated
+     * acknowledgement is accepted.
+     */
+    commitPreparedAdvance(): Uint8Array;
+    /**
+     * Close the responder side only after an acknowledgement authenticated under
+     * the new epoch has been received. Exact epoch/counter binding prevents an
+     * unrelated transport receipt from unlocking the next OFFER.
+     */
+    acceptAuthenticatedAdvanceAcknowledgement(acknowledgement: unknown): void;
+    /**
+     * Accept a full ADVANCE only after its outer AEAD has authenticated it under
+     * the old epoch.
+     */
+    acceptAuthenticatedAdvance(record: Uint8Array): Promise<void>;
+    /**
+     * Commit a successfully decapsulated ADVANCE. The returned binding must be
+     * carried by an acknowledgement authenticated under the new epoch. Traffic
+     * remains blocked until `markAdvanceAcknowledgementDispatched` is called.
+     */
+    commitAcceptedAdvance(): PqHealingAdvanceAcknowledgement;
+    /**
+     * Mark the new-epoch acknowledgement as having escaped to the network.
+     * Integration should persist that fact or retain a transport receipt cache
+     * so an exact ADVANCE replay can be answered without rolling state back.
+     */
+    markAdvanceAcknowledgementDispatched(acknowledgement: unknown): void;
+    /**
+     * Idempotent terminal cleanup. All live roots, candidate roots, and pending
+     * ML-KEM secret keys are wiped. Public record copies may remain with callers.
+     */
+    destroy(): void;
+}
+/** Store-free checkpoint helper with an owned result. */
+export declare const snapshotPqHealing: <P extends MlKemParameterSet>(machine: PqHealingMachine<P>) => PqHealingSnapshot<P>;
+/** Restore only after validating suite, binding, records, and phase invariants. */
+export declare const restorePqHealing: <P extends MlKemParameterSet>(snapshot: unknown, options: PqHealingRestoreOptions<P>) => PqHealingMachine<P>;
+/** Deep-clone for mutate/persist/adopt transaction flows. */
+export declare const clonePqHealing: <P extends MlKemParameterSet>(machine: PqHealingMachine<P>) => PqHealingMachine<P>;
+/** Consume `next` as the independently authenticated successor of `live`. */
+export declare const adoptPqHealing: <P extends MlKemParameterSet>(live: PqHealingMachine<P>, next: PqHealingMachine<P>) => void;
+/**
+ * Wipe every byte buffer owned by a plaintext checkpoint, including the PQ
+ * root, pending KEM secret key/candidate root, binding, and public records.
+ */
+export declare const wipePqHealingSnapshot: (snapshot: PqHealingSnapshot) => void;