p2party 0.8.0 → 0.14.2

package/lib/handlers/handleSendMessage.d.ts

@@ -1,5 +1,113 @@
 import type { IRTCDataChannel, IRTCPeerConnection } from "../api/webrtc/interfaces";
 import type { LibCrypto } from "../cryptography/libcrypto";
+import type { PqMessageKeyContext } from "../cryptography/pqMessageKey";
+import type { RatchetHeader } from "../cryptography/ratchet";
 import type { BaseQueryApi } from "@reduxjs/toolkit/query";
-export declare const handleSendMessage: (data: string | File, api: BaseQueryApi, label: string, roomId: string, peerConnections: IRTCPeerConnection[], dataChannels: IRTCDataChannel[], encryptionModule: LibCrypto, merkleModule: LibCrypto, minChunks?: number, chunkSize?: number, percentageFilledChunk?: number, metadataSchemaVersion?: number) => Promise<void>;
-//# sourceMappingURL=handleSendMessage.d.ts.map
+export declare const SEND_RECEIPT_WINDOW: number;
+export declare const SEND_WINDOW_STALL_MS = 10000;
+export interface ReceiptWindowParams {
+    readonly windowSize: number;
+    readonly stallTimeoutMs: number;
+    readonly pollMs: number;
+    readonly isOpen: () => boolean;
+    readonly inFlight: () => number;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Resolve once in-flight drops below the window, the channel leaves "open",
+ * or receipt progress stalls for stallTimeoutMs. Any receipt progress while
+ * still over the window resets the stall clock. Throws only on transfer abort.
+ */
+export declare const waitForReceiptWindow: (params: ReceiptWindowParams) => Promise<void>;
+interface TransferCipher {
+    epc: IRTCPeerConnection;
+    messageKey: Uint8Array;
+    header: RatchetHeader;
+    /**
+     * OWNED copy of the PQ message context captured in the same edge
+     * transaction as the ratchet step (v4). Null only on runtime-free
+     * bootstrap/test edges. Wiped with the message key.
+     */
+    pqContext?: PqMessageKeyContext | null;
+}
+/**
+ * Stop a per-message transport without depending on its eventual `close`
+ * event to release protocol accounting. This also covers cancellation while
+ * the SCTP stream is still connecting and has not entered `dataChannels`.
+ */
+export declare const closeTransferChannel: (channel: IRTCDataChannel) => void;
+/**
+ * Own the one normal terminal close for a message-scoped channel. Receipt
+ * handling only records authenticated completion; sendWithReconcile reaches
+ * this boundary after its send/reconcile work settles.
+ */
+export declare const runWithTerminalChannelClose: <T>(currentChannel: () => IRTCDataChannel, operation: () => Promise<T>) => Promise<T>;
+type WaitForRatchetGate = (roomId: string, peerId: string) => Promise<void>;
+type DurableRatchetStep = (epc: IRTCPeerConnection, roomId: string, module: LibCrypto) => Promise<{
+    messageKey: Uint8Array;
+    header: RatchetHeader;
+    pqContext: PqMessageKeyContext | null;
+}>;
+/**
+ * Bind an in-flight message to the active cryptographic transport.
+ *
+ * Reopening only its DataChannel on the SAME RTCPeerConnection retains the
+ * ratchet session, so the per-message key/header remain valid. A replacement
+ * RTCPeerConnection, however, performs a fresh hybrid handshake and owns an
+ * unrelated ratchet. It must advance that ratchet once and reseal the missing
+ * plaintext chunks; replaying the old ciphertext/key/header cannot decrypt.
+ *
+ * Exported only so the transport-identity and key-erasure contract has a focused
+ * unit test. It is not part of the package's public root exports.
+ */
+export declare const bindTransferCipherToConnection: (transfer: TransferCipher, nextEpc: IRTCPeerConnection, roomId: string, module: LibCrypto, waitForGate?: WaitForRatchetGate, ratchetStep?: DurableRatchetStep, signal?: AbortSignal) => Promise<TransferCipher>;
+export declare const isAuthenticatedPeerCancel: (currentEpc: IRTCPeerConnection, peerConnections: IRTCPeerConnection[], roomId: string, peerId: string) => boolean;
+export interface PeerSendTarget {
+    peerId: string;
+    epc?: IRTCPeerConnection;
+}
+export type PeerDeliveryOutcome = {
+    peerId: string;
+    status: "delivered";
+} | {
+    peerId: string;
+    status: "failed";
+    phase: "setup" | "transfer";
+    reason: unknown;
+} | {
+    peerId: string;
+    status: "skipped";
+    reason: "not-connected" | "unauthenticated" | "cancelled";
+};
+export interface PeerSendFanoutResult {
+    outcomes: PeerDeliveryOutcome[];
+    startedTransfers: number;
+}
+type OpenPeerTransferChannel = (target: Required<PeerSendTarget>) => Promise<IRTCDataChannel>;
+type StartPeerTransfer = (target: Required<PeerSendTarget>, channel: IRTCDataChannel) => Promise<void>;
+/**
+ * Set up every eligible room edge and settle every transfer that was started.
+ *
+ * Opening channels remains sequential so it cannot burst through the per-edge
+ * channel budget. Transfer promises run concurrently, however, and are given a
+ * rejection handler immediately. A later setup failure therefore becomes that
+ * peer's outcome instead of unwinding past already-running sends and freeing
+ * their shared `newChunks` staging records.
+ */
+export declare const runPeerSendFanout: (targets: readonly PeerSendTarget[], openChannel: OpenPeerTransferChannel, startTransfer: StartPeerTransfer, signal?: AbortSignal, onTransferStarted?: () => void) => Promise<PeerSendFanoutResult>;
+export interface SendMessageResult extends PeerSendFanoutResult {
+    transferId: string;
+    merkleRootHex: string;
+}
+export declare class MessageDeliveryError extends AggregateError {
+    readonly result: SendMessageResult;
+    constructor(result: SendMessageResult, message: string);
+}
+/**
+ * The sender's history is independent of remote delivery once splitToChunks
+ * has committed its complete local copy. Network/setup failures may annotate
+ * delivery status, but only an explicit local cancel removes that history.
+ */
+export declare const shouldDeleteLocalMessageAfterFailure: (localMessageCommitted: boolean, wireWorkStarted: boolean, explicitlyCancelled: boolean) => boolean;
+export declare const handleSendMessage: (data: string | File, api: BaseQueryApi, label: string, roomId: string, peerConnections: IRTCPeerConnection[], dataChannels: IRTCDataChannel[], encryptionModule: LibCrypto, merkleModule: LibCrypto, transferId: string, minChunks?: number, chunkSize?: number, percentageFilledChunk?: number, metadataSchemaVersion?: number) => Promise<SendMessageResult | undefined>;
+export {};

package/lib/handlers/handleWebSocketMessage.d.ts

@@ -1,5 +1,3 @@
 import type { BaseQueryApi } from "@reduxjs/toolkit/query";
-import type { WSPeerConnection } from "../utils/interfaces";
-declare const handleWebSocketMessage: (event: MessageEvent, ws: WebSocket, api: BaseQueryApi, peerConnections: WSPeerConnection[]) => Promise<void>;
+declare const handleWebSocketMessage: (event: MessageEvent, ws: WebSocket, api: BaseQueryApi) => Promise<void>;
 export default handleWebSocketMessage;
-//# sourceMappingURL=handleWebSocketMessage.d.ts.map

package/lib/handlers/handshakeCore.d.ts

@@ -0,0 +1,95 @@
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { RatchetState } from "../cryptography/ratchet";
+import type { RoomPqMode } from "../roomPolicy";
+export interface ChannelInputParams {
+    channelId: Uint8Array;
+    ikInitiator: Uint8Array;
+    ikResponder: Uint8Array;
+    fpInitiator: Uint8Array;
+    fpResponder: Uint8Array;
+    /** Defaults to the 0.10 ML-KEM-768 suite for source compatibility. */
+    pqMode?: RoomPqMode;
+}
+/**
+ * CPace channel-input transcript (spec §5): CI = channel-id ‖ IK_a ‖ IK_b ‖
+ * fp_a ‖ fp_b ‖ PQ_TAG, with a = initiator, b = responder. Both peers build a
+ * byte-identical CI because they agree on the initiator role (Task 4). Binding
+ * both identity keys + both DTLS fingerprints is what makes a swapped-cert
+ * MITM fail the key-confirmation MAC.
+ *
+ * Deliberately synchronous (unlike the project's async concatUint8Arrays
+ * helper in utils/uint8array.ts, which yields to the microtask queue for
+ * parity with other WASM-backed helpers): CI construction is pure
+ * byte-copying with no WASM/IndexedDB involved, and callers build it inline
+ * while assembling the CPace transcript.
+ */
+export declare const buildChannelInput: (p: ChannelInputParams) => Uint8Array;
+export type HandshakeStep = 1 | 2 | 3;
+/**
+ * Fail-closed pre-auth framing check used before a payload enters the handshake
+ * inbox. This keeps attacker-controlled frames bounded before the crypto core
+ * consumes them; the core repeats the same checks when parsing.
+ */
+export declare const isHandshakePayloadForStep: (payload: Uint8Array, step: HandshakeStep, pqMode?: RoomPqMode) => boolean;
+export interface HandshakeTransport {
+    send(bytes: Uint8Array): void | Promise<void>;
+    recv(): Promise<Uint8Array>;
+}
+export interface HandshakeCoreParams {
+    mode: "pin" | "nopin";
+    /** Exact preselected suite; omission selects the documented 768 default. */
+    pqMode?: RoomPqMode;
+    pin: Uint8Array | null;
+    channelInput: Uint8Array;
+    amInitiator: boolean;
+    idSelfSec: Uint8Array;
+    selfIdentityX25519Pub: Uint8Array;
+    selfIdentityCrossSignature: Uint8Array;
+    peerIdentityEd25519Pub: Uint8Array;
+}
+export interface PqHealingBootstrap {
+    /** Secret root dedicated to sparse post-quantum healing. Caller-owned. */
+    rootKey: Uint8Array;
+    /** Non-secret transcript/edge binding shared by both authenticated peers. */
+    binding: Uint8Array;
+    /** Stable Ed25519 role ordering chooses the first OFFER turn. */
+    nextOfferer: "local" | "remote";
+}
+/**
+ * Three-flight key-confirmed handshake core (spec §5), decoupled from
+ * RTCDataChannel so it is
+ * unit-testable with two linked in-memory transports:
+ *   R1  initiator sends HELLO {sid, EK, Y, ML-KEM pk}; responder encapsulates,
+ *       replies with HELLO {sid, EK, Y, ML-KEM ct}; both derive the 32-byte
+ *       hybrid root from interactive-3DH || ML-KEM (no-PIN) or
+ *       CPace-ISK || interactive-3DH || ML-KEM (PIN).
+ *   R2  responder initRatchet(false,null) → dhPubR and sends
+ *       CONFIRM{dhPubR, mac_R}; initiator seeds against dhPubR and sends
+ *       CONFIRM{dhPubI, mac_I}, where mac_I commits to the received mac_R.
+ *   R3  after verifying mac_I and priming both ratchet chains, responder sends
+ *       FINISH{mac_F}, which commits to both earlier confirmation MACs.
+ *       Initiator returns only after verifying mac_F.
+ *
+ * The room-selected ML-KEM suite is mandatory: this function constructs that
+ * exact backend itself and fails before sending if its WASM exports are
+ * missing. There is deliberately no classical fallback or negotiation bit.
+ * The three chained MACs cover the full ordered HELLO transcript and dhPubR
+ * under distinct role domains; mac_I additionally covers dhPubI + mac_R, and
+ * mac_F covers both earlier proofs. A swapped cert/key, altered KEM field,
+ * ratchet-key tamper, or wrong PIN makes key confirmation fail (or is rejected
+ * as malformed).
+ * Persistence + gate-open happen ONLY in runHandshake, after this resolves, so
+ * a throw here leaves nothing persisted.
+ *
+ * NOTE on the R2 ordering: the initiator publishes its mac_I BEFORE separately
+ * checking mac_R so a wrong-root peer still receives a terminal proof instead
+ * of hanging forever. This is safe because mac_I itself authenticates the exact
+ * mac_R bytes the initiator received: changing mac_R makes the responder reject
+ * mac_I. A valid responder FINISH is therefore required before the initiator
+ * can return an established state.
+ */
+export declare const performHandshakeCore: (transport: HandshakeTransport, params: HandshakeCoreParams, module: LibCrypto) => Promise<{
+    state: RatchetState;
+    secret: Uint8Array;
+    pqHealing: PqHealingBootstrap;
+}>;

package/lib/handlers/messageChunkCrypto.d.ts

@@ -0,0 +1,70 @@
+import type { RatchetState, RatchetHeader } from "../cryptography/ratchet";
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { PqMessageKeyContext } from "../cryptography/pqMessageKey";
+/**
+ * Per-message key-cache key. Production passes the parsed epoch explicitly and
+ * gets an epoch-bound `(dhPub,N,epoch)` identity. Omitting the epoch preserves
+ * the legacy low-level `dhPub:N` identity for raw/bootstrap tests only; this is
+ * needed while those tests still round-trip keys through RatchetState.skipped,
+ * whose historical serializer understands exactly that two-field shape.
+ */
+export declare const messageCacheKey: (dhPub: Uint8Array, N: number, pqEpoch?: bigint) => string;
+/**
+ * Seal ONE chunk under an already-derived classical `messageKey` + `header`.
+ * With a PQ context, an owned copy of the classical key is consumed by the v4
+ * combiner and the resulting key is wiped after this one AEAD operation. The
+ * caller's classical key remains live across streamed chunks/retransmit rounds.
+ * The low-level context-free default emits bootstrap epoch zero and uses the
+ * raw classical key for backwards-compatible tests only.
+ *
+ * This is the streaming/reconcile-friendly primitive the live send path uses: it
+ * seals chunks one-at-a-time as they are read from IndexedDB, so a multi-GB
+ * message is never materialised in RAM. A retransmit re-seals the same plaintext
+ * under the SAME `messageKey` with a FRESH random nonce — cryptographically safe
+ * (distinct 96-bit random nonces under one key) and decryptable by the receiver's
+ * cached per-message key (a HIT on `(dhPub, N)`), so no frame-cache is needed.
+ */
+export declare const sealChunk: (messageKey: Uint8Array, header: RatchetHeader, chunk: Uint8Array, merkleRoot: Uint8Array, module: LibCrypto, pqContext?: PqMessageKeyContext) => Uint8Array;
+export interface DecryptedChunk {
+    /** The DECRYPTED_LEN plaintext `metadata ‖ receiptLeaf ‖ chunk` written by the C
+     *  receive, or `null` when the chunk was dropped (AEAD or Merkle failure). */
+    decrypted: Uint8Array | null;
+    /** True iff C returned 0 — AEAD **and** Merkle both passed. When false the caller
+     *  drops the chunk (but still persists the ratchet if `stateAdvanced`). */
+    ok: boolean;
+    /** True iff this chunk stepped the ratchet (first-arriving chunk of a message
+     *  whose AEAD authenticated). The caller persists `state` when true — even if
+     *  `ok` is false, since the DH step is real once the AEAD authenticates. */
+    stateAdvanced: boolean;
+}
+/**
+ * Resolve an authenticated, currently acceptable PQ epoch. Returning null
+ * rejects unknown/stale/future epochs before a Double-Ratchet clone is touched.
+ */
+export type PqMessageKeyContextResolver = (epoch: bigint) => PqMessageKeyContext | null;
+/**
+ * RECEIVE one chunk frame: derive the per-message key off the ratchet (in TS —
+ * the ratchet state is a TS object), then do ALL the crypto in ONE C call
+ * (`receiveWithKey` → `_receive_message_with_key`: decrypt + leaf-hash + Merkle +
+ * receipt, in place).
+ *
+ * The production `cache` is caller-owned and keyed by
+ * `messageCacheKey(dhPub,N,pqEpoch)`. It stores already-combined active receive
+ * keys separately from classical skipped keys. On a HIT the key is reused
+ * without touching the ratchet. On a MISS, the resolver must authorize the
+ * epoch before the classical key is derived on a clone and combined.
+ *
+ * Clone-rollback (MANDATORY — `ratchetDecrypt` mutates BEFORE the AEAD
+ * authenticates, so a replayed/old-chain header could otherwise fire a spurious
+ * DH-step and desync the session):
+ *   1. `clone = deserializeRatchet(serializeRatchet(state))`.
+ *   2. `messageKey = ratchetDecrypt(clone, header)` — mutates the CLONE only.
+ *   3. C decrypts+verifies. COMMIT (adopt the clone, cache the key) iff the AEAD
+ *      authenticated (`code !== -2`); on `-2` DISCARD the clone — the live `state`
+ *      is byte-for-byte untouched. `ok` (store-vs-drop) then follows `code === 0`.
+ *
+ * Cache lifecycle: the caller evicts a message's key (via `messageCacheKey`) when
+ * the message completes (all leaves present) or on a TTL, so a peer can't pin keys
+ * with never-completing messages.
+ */
+export declare const decryptMessageChunk: (state: RatchetState, frame: Uint8Array, cache: Map<string, Uint8Array>, merkleRoot: Uint8Array, module: LibCrypto, pqContextResolver?: PqMessageKeyContextResolver) => DecryptedChunk;

package/lib/handlers/peerRosterDelta.d.ts

@@ -0,0 +1,12 @@
+import type { Peer } from "../reducers/roomSlice";
+import type { RoomPeer } from "../utils/interfaces";
+export interface SelfPeerIdentity {
+    peerId: string;
+    publicKey: string;
+}
+/**
+ * Server `peers` messages are accepted-peer deltas, not room snapshots.
+ * Preserve prior members and upsert only canonical, non-conflicting additions.
+ * Peer removal belongs to explicit transport teardown/disconnect handling.
+ */
+export declare const mergePeerRosterDelta: (current: readonly Peer[], delta: readonly RoomPeer[], self: SelfPeerIdentity) => Peer[];

package/lib/handlers/pqHealingOrchestrator.d.ts

@@ -0,0 +1,46 @@
+import type { IRTCPeerConnection } from "../api/webrtc/interfaces";
+import type { RatchetState } from "../cryptography/ratchet";
+/** Persist the (unchanged) live ratchet plus one candidate edge checkpoint. */
+export type PersistEdgeCheckpoint = (epc: IRTCPeerConnection, state: RatchetState, roomId: string, serializeCandidate: () => Uint8Array) => Promise<void>;
+export interface PqOrchestratorHooks {
+    /** Dispatch one exact sealed control cell; false when the lane is not open. */
+    readonly sendControlFrame: (frame: Uint8Array) => boolean;
+    /** Fail/reconnect the authenticated edge (retry exhaustion, fork). */
+    readonly failEdge: (reason: Error) => void;
+    /** Injectable clock for deterministic tests. */
+    readonly now?: () => number;
+    /** Injectable persistence for fault-injection tests. */
+    readonly persistEdge?: PersistEdgeCheckpoint;
+    /** Tick cadence for the due/retry timer; 0 disables the interval (tests). */
+    readonly tickMs?: number;
+}
+/**
+ * True while new application sends must not derive a message key on this edge:
+ * either the runtime's machine is mid-exchange, or an inbound control frame is
+ * being processed and the local gate has already closed.
+ */
+export declare const isPqApplicationTrafficBlocked: (epc: IRTCPeerConnection) => boolean;
+/**
+ * Install the live orchestrator after a successful handshake has installed
+ * `epc.pqHealingState`. Idempotent per connection: a replacement handshake on
+ * the same connection object reuses the interval with the fresh runtime.
+ */
+export declare const installPqHealingOrchestrator: (epc: IRTCPeerConnection, roomId: string, hooks: PqOrchestratorHooks) => void;
+export declare const destroyPqHealingOrchestrator: (epc: IRTCPeerConnection) => void;
+/**
+ * One due/retry pass. Retransmits the exact persisted control frame when its
+ * 5-second deadline passed (durably counting the attempt first), fails the
+ * edge after the 8-attempt budget, and starts a due local exchange only when
+ * the stable role owns the turn and the edge is at a quiescent boundary.
+ * Exported for deterministic tests; the installed interval calls it.
+ */
+export declare const tickPqHealing: (epc: IRTCPeerConnection) => Promise<void>;
+/**
+ * Route one authenticated-transport FRAME_TYPE_PQ_CONTROL cell. Closes the
+ * local application gate, drains queued inbound frames to the quiescent
+ * boundary, then runs the exact durable OFFER/ADVANCE/ACK ordering. An exact
+ * duplicate re-emits the exact persisted response without a write. Any
+ * authentication failure is a fork/replay outside the protocol and fails the
+ * authenticated edge.
+ */
+export declare const handleInboundPqControlFrame: (epc: IRTCPeerConnection, roomId: string, frame: Uint8Array) => Promise<void>;

package/lib/handlers/pqHealingRuntime.d.ts

@@ -0,0 +1,82 @@
+import { type PqHealingPhase, type PqHealingTurn } from "../cryptography/pqHealing";
+import { type RoomPqMode } from "../roomPolicy";
+import { type RatchetRootSuite } from "../utils/constants";
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { PqMessageKeyContext } from "../cryptography/pqMessageKey";
+export declare const PQ_HEAL_AFTER_MESSAGES = 64;
+export declare const PQ_HEAL_AFTER_MS: number;
+export declare const PQ_HEAL_RETRY_MS = 5000;
+export declare const PQ_HEAL_MAX_RETRIES = 8;
+export type PqHealingOutboxKind = "offer" | "advance";
+export interface PqHealingOutbox {
+    readonly kind: PqHealingOutboxKind;
+    readonly frame: Uint8Array;
+    readonly attempts: number;
+    readonly nextRetryAt: number;
+}
+export interface PqHealingControlResult {
+    /**
+     * Exact already-sealed cell to dispatch after the candidate checkpoint is
+     * durable. It may be an OFFER, ADVANCE, ACK, or cached duplicate response.
+     */
+    readonly dispatch: Uint8Array | null;
+    /**
+     * False only for an exact duplicate whose cached response can be resent
+     * without another persistence write.
+     */
+    readonly changed: boolean;
+}
+export interface SparsePqHealingOptions {
+    readonly module: LibCrypto;
+    readonly pqMode: RoomPqMode;
+    readonly rootSuite: RatchetRootSuite;
+    readonly binding: Uint8Array;
+    readonly rootKey: Uint8Array;
+    readonly nextOfferer: PqHealingTurn;
+    readonly amInitiator: boolean;
+    readonly now?: number;
+}
+export interface RestoreSparsePqHealingOptions {
+    readonly module: LibCrypto;
+    readonly pqMode: RoomPqMode;
+    readonly rootSuite: RatchetRootSuite;
+    readonly binding: Uint8Array;
+    readonly amInitiator: boolean;
+}
+export declare class SparsePqHealingState {
+    #private;
+    constructor(options: SparsePqHealingOptions);
+    get pqMode(): RoomPqMode;
+    get rootSuite(): RatchetRootSuite;
+    get epoch(): bigint;
+    get phase(): PqHealingPhase;
+    get trafficBlocked(): boolean;
+    get nextOfferer(): PqHealingTurn;
+    get activeReceiveKeys(): Map<string, Uint8Array>;
+    get messagesSinceHealing(): number;
+    get lastHealedAt(): number;
+    currentMessageContext(): PqMessageKeyContext;
+    resolveMessageContext(epoch: bigint): PqMessageKeyContext | null;
+    noteApplicationMessage(): void;
+    healingDue(now?: number): boolean;
+    copyPendingFrame(): Uint8Array | null;
+    get pendingRetryAt(): number | null;
+    get pendingAttempts(): number;
+    markPendingDispatched(now?: number): void;
+    prepareHealingOffer(now?: number): Promise<Uint8Array>;
+    acceptControlFrame(frame: Uint8Array, now?: number): Promise<PqHealingControlResult>;
+    clone(): SparsePqHealingState;
+    adopt(next: SparsePqHealingState): void;
+    serialize(activeReceiveKeys?: ReadonlyMap<string, Uint8Array>): Uint8Array;
+    /**
+     * Read the public edge binding out of a checkpoint without instantiating the
+     * runtime. A store-free consumer that keeps the whole checkpoint under
+     * authenticated encryption (rather than a separate binding) uses this to
+     * supply the expected binding to `restore`. The binding layout is fixed:
+     * magic(8) | version(1) | suite(1) | direction(1) | reserved(1) |
+     * lastHealedAt(8) | messagesSinceHealing(8) | binding(32).
+     */
+    static readCheckpointBinding(bytes: Uint8Array): Uint8Array;
+    static restore(bytes: Uint8Array, options: RestoreSparsePqHealingOptions): SparsePqHealingState;
+    destroy(): void;
+}

package/lib/handlers/ratchetGate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Opaque ownership token for one concrete room/peer transport attempt.
+ *
+ * A reconnect replaces the gate at the same map key. Async completion from the
+ * old transport must present its old lease and is then ignored instead of
+ * opening/rejecting the replacement transport's promise.
+ */
+export interface RatchetGateLease {
+    readonly token: symbol;
+}
+export declare const getRatchetGate: (roomId: string, peerId: string) => Promise<void>;
+/** Claim the gate already created for the current transport attempt. */
+export declare const claimRatchetGate: (roomId: string, peerId: string) => RatchetGateLease;
+export declare const isCurrentRatchetGateLease: (roomId: string, peerId: string, lease: RatchetGateLease) => boolean;
+export declare const isRatchetGateOpen: (roomId: string, peerId: string, lease?: RatchetGateLease) => boolean;
+export declare const openRatchetGate: (roomId: string, peerId: string, lease: RatchetGateLease) => boolean;
+export declare const rejectRatchetGate: (roomId: string, peerId: string, err: unknown, lease?: RatchetGateLease) => boolean;
+export declare const resetRatchetGate: (roomId: string, peerId: string, reason?: unknown) => RatchetGateLease;

package/lib/handlers/ratchetPersist.d.ts

@@ -0,0 +1,53 @@
+import type { LibCrypto } from "../cryptography/libcrypto";
+import type { IRTCPeerConnection } from "../api/webrtc/interfaces";
+import type { PqMessageKeyContext } from "../cryptography/pqMessageKey";
+import type { RatchetHeader, RatchetState } from "../cryptography/ratchet";
+import type { DecryptedChunk } from "./messageChunkCrypto";
+/**
+ * Claim the stable persistence edge before a replacement handshake writes its
+ * seed. The synchronous claim invalidates queued mutations from the old PC;
+ * the edge-wide write lock ensures any already-running old write finishes
+ * before the replacement seed is written last.
+ */
+export declare const claimRatchetPersistence: (epc: IRTCPeerConnection, roomId: string) => void;
+export declare const persistRatchetState: (state: RatchetState, roomId: string, peerPublicKey: string, peerId: string, edgeCryptoState?: Uint8Array | null) => Promise<void>;
+export declare const persistClaimedRatchetState: (epc: IRTCPeerConnection, state: RatchetState, roomId: string, edgeCryptoStateOverride?: () => Uint8Array) => Promise<void>;
+export type PersistInitialRatchetState = (state: RatchetState, roomId: string, peerPublicKey: string, peerId: string, edgeCryptoState?: Uint8Array | null) => Promise<void>;
+export type RollbackInitialRatchetState = (roomId: string, peerPublicKey: string) => Promise<void>;
+/**
+ * Atomically order the initial durable seed and its synchronous gate/RAM
+ * activation under the stable-edge lock. If close/replacement settles the gate
+ * while the worker write is in flight, delete that just-written seed before a
+ * replacement is allowed to write. This prevents a never-established root from
+ * being restored later.
+ */
+export declare const persistAndActivateClaimedRatchetState: (epc: IRTCPeerConnection, state: RatchetState, roomId: string, activate: () => void, persist?: PersistInitialRatchetState, rollback?: RollbackInitialRatchetState) => Promise<void>;
+export type PersistRatchetState = typeof persistRatchetState;
+export declare const withEdgeCryptoMutationLock: <T>(epc: IRTCPeerConnection, mutation: () => Promise<T>) => Promise<T>;
+/**
+ * Advance the sending chain exactly once, durably, before its key/header can be
+ * used to build a frame. The returned message key remains caller-owned, as is
+ * the returned OWNED copy of the current PQ message context (null only on the
+ * bootstrap/test path with no installed PQ runtime). Capturing the context and
+ * counting the application message happen inside the same edge transaction as
+ * the ratchet step, so a concurrent PQ healing transition cannot interleave.
+ */
+export declare const ratchetEncryptDurably: (epc: IRTCPeerConnection, roomId: string, module: LibCrypto, persist?: PersistRatchetState) => Promise<{
+    messageKey: Uint8Array;
+    header: RatchetHeader;
+    pqContext: PqMessageKeyContext | null;
+}>;
+/**
+ * Decrypt one inbound chunk with a staged state/cache. An authenticated ratchet
+ * advance becomes visible only after its snapshot is durable; persistence
+ * failure rejects without advancing live state, caching a key, or exposing the
+ * decrypted bytes. Cache hits do not advance or persist the ratchet.
+ */
+export declare const decryptMessageChunkDurably: (epc: IRTCPeerConnection, roomId: string, frame: Uint8Array, cache: Map<string, Uint8Array>, merkleRoot: Uint8Array, module: LibCrypto, persist?: PersistRatchetState) => Promise<DecryptedChunk>;
+/**
+ * Durably retire the active receive key after the atomic chunk manifest reports
+ * completion, then erase the RAM cache copy. If persistence fails, both copies
+ * remain usable for an idempotent retransmit/retry rather than diverging.
+ */
+export declare const forgetReceiveMessageKeyDurably: (epc: IRTCPeerConnection, roomId: string, cache: Map<string, Uint8Array>, cacheKey: string, persist?: PersistRatchetState) => Promise<void>;
+export declare const persistRatchetSession: (epc: IRTCPeerConnection, roomId: string) => Promise<void>;

package/lib/handlers/receiptFrame.d.ts

@@ -0,0 +1,18 @@
+interface ReceiptSendChannel {
+    readonly readyState: string;
+    readonly bufferedAmount: number;
+    send(data: ArrayBuffer): void;
+}
+/** Encode a chunk token or terminal message hash as one canonical wire frame. */
+export declare const encodeReceiptFrame: (token: Uint8Array) => Uint8Array;
+/** Return the zero-copy token only for the exact tagged receipt geometry. */
+export declare const decodeReceiptFrame: (frame: Uint8Array) => Uint8Array | undefined;
+export declare const sendReceiptFrame: (channel: Pick<ReceiptSendChannel, "readyState" | "send">, token: Uint8Array) => boolean;
+export declare const RECEIPT_REPLAY_BATCH_SIZE = 32;
+export declare const RECEIPT_REPLAY_PAUSE_MS = 10;
+/**
+ * Replay a reconnect have-set without filling SCTP or monopolising the event
+ * loop. The caller may then send the terminal receipt on the same channel.
+ */
+export declare const sendReceiptFramesPaced: (channel: ReceiptSendChannel, tokens: Iterable<Uint8Array>) => Promise<boolean>;
+export {};

package/lib/handlers/receiveMessageKeyLifetime.d.ts

@@ -0,0 +1,24 @@
+import { forgetReceiveMessageKeyDurably } from "./ratchetPersist";
+import type { IRTCPeerConnection } from "../api/webrtc/interfaces";
+import type { MessageData } from "../db/types";
+type ForgetReceiveMessageKey = typeof forgetReceiveMessageKeyDurably;
+type ReceiveProgress = Pick<MessageData, "savedSize" | "totalSize">;
+/**
+ * Bind the authenticated transfer root to the receive-ratchet key used by all
+ * of its cells. Completion of the real bytes does not end this lifetime: valid
+ * padded/cover cells may still be draining from an unordered data channel.
+ */
+export declare const bindReceiveMessageKey: (epc: IRTCPeerConnection, merkleRootHex: string, cacheKey: string) => void;
+/**
+ * Durably retire the key mapped to one transfer. The root binding is removed
+ * only after persistence succeeds, so failure leaves an idempotent retry path.
+ */
+export declare const forgetMappedReceiveMessageKey: (epc: IRTCPeerConnection, roomId: string, merkleRootHex: string, forget?: ForgetReceiveMessageKey) => Promise<boolean>;
+/**
+ * A normal channel close retires a receive key only after its queue drained and
+ * the durable manifest confirms all real bytes. Incomplete transfers retain
+ * their key so a failed transport can resume; explicit cancel uses the
+ * unconditional helper above.
+ */
+export declare const forgetCompletedReceiveMessageKey: (epc: IRTCPeerConnection, roomId: string, merkleRootHex: string, progress: ReceiveProgress | undefined, forget?: ForgetReceiveMessageKey) => Promise<boolean>;
+export {};

package/lib/handlers/reconcile.d.ts

@@ -0,0 +1,16 @@
+export declare const markChunkAcked: (roomId: string, peerId: string, transferId: string, chunkIndex: number) => boolean;
+export declare const getAckedChunks: (roomId: string, peerId: string, transferId: string) => Set<number>;
+export declare const getAckedChunkCount: (roomId: string, peerId: string, transferId: string) => number;
+export declare const markTransferComplete: (roomId: string, peerId: string, transferId: string) => boolean;
+export interface PeerTransferOutcome {
+    readonly roomId: string;
+    readonly peerId: string;
+    readonly transferId: string;
+    readonly ackedChunks: ReadonlySet<number>;
+    readonly complete: boolean;
+}
+/** Accurate, defensive per-peer delivery state for UI/diagnostics consumers. */
+export declare const getPeerTransferOutcome: (roomId: string, peerId: string, transferId: string) => PeerTransferOutcome;
+export declare const isTransferComplete: (roomId: string, peerId: string, transferId: string) => boolean;
+export declare const clearTransfer: (roomId: string, peerId: string, transferId: string) => void;
+export declare const waitForCompletion: (roomId: string, peerId: string, transferId: string, timeoutMs: number, signal?: AbortSignal) => Promise<boolean>;

package/lib/handlers/transferAbort.d.ts

@@ -0,0 +1,42 @@
+export interface TransferAbortHandle {
+    readonly transferId: string;
+    readonly signal: AbortSignal;
+    bindHash(hashHex: string): void;
+    bindMerkleRoot(merkleRootHex: string): void;
+    finish(): void;
+}
+/**
+ * Registers one logical outbound message. Its identifiers are bound as soon as
+ * streaming hashing/Merkle construction learns them, so cancellation remains
+ * message-scoped instead of broadcasting a window-global event.
+ */
+export declare const createTransferId: () => string;
+export declare const beginTransfer: (roomId: string, transferId?: string) => TransferAbortHandle;
+/**
+ * Internal handoff from the public API to the async send pipeline. The public
+ * boundary registers first so `handle.cancel()` works even while WASM is still
+ * loading; the handler later claims that exact live controller.
+ */
+export declare const claimTransfer: (roomId: string, transferId: string) => TransferAbortHandle;
+export interface TransferSelector {
+    transferId?: string;
+    hashHex?: string;
+    merkleRootHex?: string;
+}
+export interface IncomingTransferProgress {
+    fromPeerId: string;
+    savedSize: number;
+    totalSize: number;
+}
+/**
+ * In immediate mode, closing only a message-scoped DataChannel while its
+ * authenticated peer connection remains alive is the remote CANCEL signal.
+ * Delete only an incomplete receive owned by that peer; completed messages and
+ * the sender's local self-copy must survive the ordinary terminal close.
+ */
+export declare const isRemoteCancelClose: (progress: IncomingTransferProgress | undefined, remotePeerId: string, authenticatedTransportStillAlive: boolean) => boolean;
+export declare const abortTransfer: (roomId: string, selector: TransferSelector) => number;
+export declare const abortRoomTransfers: (roomId: string) => number;
+export declare const abortAllTransfers: () => number;
+export declare const throwIfTransferAborted: (signal?: AbortSignal) => void;
+export declare const waitWithTransferAbort: <T>(pending: Promise<T>, signal?: AbortSignal) => Promise<T>;