p2party 0.14.3 → 0.14.10

package/docs/protocol-v4-security.md

@@ -17,9 +17,9 @@ There are three different acknowledgements in the system:
 2. The protocol-v4 handshake runs over the open main channel. After HELLO,
    responder CONFIRM, initiator CONFIRM, and responder FINISH, the peers have
    authenticated the same hybrid root and initial ratchet keys.
-3. Authenticated 65-byte receipt frames acknowledge message chunks and final
-   transfer completion. They are delivery/reconciliation signals, not handshake
-   establishment.
+3. Immediate 65-byte receipts on authenticated message channels, or encrypted
+   scheduled control cells, acknowledge chunks and transfer completion. They
+   are delivery/reconciliation signals, not handshake establishment.
 
 An open data channel therefore is necessary transport readiness, not an
 established p2party crypto session.
@@ -66,15 +66,65 @@ byte so the sparse post-quantum healing epoch cannot wrap.
 
 The fixed frame geometry absorbs the ratchet and AEAD overhead into the cell
 budget. Random padding and decoy slots can hide the exact payload length within
-one transfer's chosen number of frames. Receipts have a distinct fixed 65-byte
-geometry. Handshake flights are suite- and step-dependent rather than
-65,490-byte cells.
+one transfer's chosen number of frames. Immediate receipts have a distinct
+65-byte geometry and immediate pause/cancel controls are 66 bytes. Scheduled
+receipt batches, terminal receipts and CANCELs occupy existing 65,490-byte
+cover slots. Handshake flights are suite- and step-dependent.
 
 Per-message channels give each transfer an independent lifecycle for
 cancellation, bounded channel accounting, receipts, selective retransmission,
 and reconnect resume. Channel isolation is a UX and reliability property; it
 does not make timing or channel count invisible.
 
+### Durable selective resume and cancellation
+
+A chunk acknowledgement becomes live only after its per-recipient outbox
+update commits. Receipt acceptance binds room, peer ID, peer public key,
+random transfer ID, Merkle root and original chunk index. Scheduled cells
+add direction, PQ epoch, AEAD and counter replay checks; their terminal token
+must equal the transfer root. Stale asynchronous storage responses cannot
+advance a replacement owner's live state. Recipient refusal is persisted
+separately from completion and stops only that recipient's retry.
+
+Scheduled chunk receipts use a separate encrypted subtype with up to 64 tokens
+per root. Existing subtype 3 remains terminal-only: older clients interpreted
+any token in that subtype as completion. Older protocol-v4 clients drop the
+new subtype and retain terminal-only scheduled delivery, including full replay
+when necessary. Selective scheduled resume therefore requires supporting peers.
+
+Have-set membership is O(1) in memory and does not allocate a set copy per
+scheduled slot. A resume scans indices once, sends missing real chunks and
+may send one completion probe. Storage lookup costs, initial file preparation
+and scanning remain; this is not a claim of sublinear total file processing.
+Batching and selective resume reduce real work within the existing schedule,
+whose observable cell count remains fixed.
+
+Immediate resume uses the channel protocol `p2party-resume-v1` and a capability
+echo to distinguish pause from explicit cancellation. Type-6 controls are
+authenticated by the concrete DTLS/SCTP channel and current identity gate,
+with an exact-root check; they do not have a separate application AEAD.
+Legacy peers retain close-as-cancel behavior. A fresh immediate attempt
+rebuilds its have-set from paced receiver receipts instead of assuming a
+legacy receiver retained its partial. Remote cancellation drains pending
+writes, then atomically checks room, sender and incomplete status before
+deleting receiver data; completed files and sender self-copies are preserved.
+
+### Sparse-PQ healing during scheduled sends
+
+Local healing waits for queued or admitted real jobs, message channels,
+derive-to-enqueue reservations and queued receive work to drain. An atomic
+application reservation closes the race between deriving a message key and
+admitting its scheduled producer. Dummy cover does not block healing.
+
+An incoming exchange blocks new admission and drains reservations, then
+persists its new epoch before adopting it. Epoch adoption invalidates old-key
+real producers on the same scheduler and wakes bounded sender recovery.
+Recovery requires an actual epoch advance when reusing that runtime and
+re-derives the missing chunks. If sealing was already in flight, its retired
+cell is wiped and the slot remains dummy; pending explicit CANCEL is resealed
+under the new epoch. Lane timing continues throughout this transition.
+Persistence failure leaves the prior live epoch unchanged for exact retry.
+
 ## Guarantees, assuming authenticated peer keys
 
 With a correctly pinned peer Ed25519 identity, uncompromised endpoints, matching
@@ -126,6 +176,46 @@ Putting the capability in a URL fragment keeps it out of ordinary HTTP
 requests and common access logs, but the shipped legacy signaling path still
 receives its normalized value. A fragment is not a server-blind meeting point.
 
+## Signaling and TURN correctness boundary
+
+SDK 0.14.10 makes legacy signaling state transitions correlated and bounded; it
+does not make that signaling path blind.
+
+- A room response is accepted only for the exact current socket, room
+  capability, and UUIDv4 request. A delayed response cannot configure another
+  room.
+- Caller ICE configuration and signaling-managed TURN credentials are separate
+  inputs. Managed credentials carry an absolute expiry, are applied to every
+  live room edge before an ICE restart, refresh proactively, and are removed or
+  failed closed when they expire.
+- `purgeRoom()` tears down local transports and durable state before waiting
+  for a correlated server acknowledgement. The leave is keyed by the stable
+  room capability rather than the server-assigned room UUID, so a purge racing
+  an in-flight join still revokes that membership. Matching `p2party-server`
+  0.1.1 unlinks the authenticated peer from the room before acknowledging. An
+  offline or non-acknowledging server produces
+  `RemoteRoomRevocationUnconfirmedError`; it is never reported as confirmed.
+- Signaling ingress, room rosters, live mesh edges, pending ICE, and channel
+  registries have explicit client-side bounds. Those bounds limit one client's
+  exposure; they are not server-side Sybil resistance or a global availability
+  proof.
+
+TURN is a transport relay, not a privacy proxy. The legacy REST username is
+expiry-bound but contains the client's Ed25519 public key, and the TURN
+operator can observe source addresses, allocations, timing, and byte volume.
+Neither relay use nor TLS makes the signaling operator unable to read SDP, ICE,
+room capabilities, or membership.
+
+The current challenge proves possession of the presented Ed25519 key to the
+server by signing a fresh nonce. Its transcript is not bound to a server
+identity or origin, so it does not resist a malicious server relaying another
+server's nonce as a signing oracle. The legacy service also has no
+cross-instance session-generation fence or Byzantine quorum. Consequently none
+of malicious-rendezvous blindness, two-server BFT, social-graph hiding,
+server-bound authentication, shutdown survival, or post-quantum signaling
+authentication is a property of this path. Those remain requirements of the
+versioned blind-rendezvous design.
+
 ## Shipped, implemented core, and research
 
 | Status                    | Exact boundary in 0.14                                                                                                                                                                                                                                                                                                                                                                                                  |

package/docs/references.md

@@ -13,13 +13,33 @@ These are compiled into the shipped `libcrypto.wasm` or bundled into the
 package. Licences and notices are reproduced in
 [THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md).
 
-| Project                 | Used for                                                           | Link                                                                                       |
-| ----------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
-| libsodium               | X25519, Ed25519, ChaCha20-Poly1305, BLAKE2b, HKDF, Argon2, SHA-512 | [github.com/jedisct1/libsodium](https://github.com/jedisct1/libsodium)                     |
-| mlkem-native            | ML-KEM-512/768/1024 (FIPS 203)                                     | [github.com/pq-code-package/mlkem-native](https://github.com/pq-code-package/mlkem-native) |
-| Emscripten              | Compiles the C cryptography to the pinned WASM module              | [emscripten.org](https://emscripten.org/)                                                  |
-| BIP-39 English wordlist | The 24-word room-capability encoding                               | [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md)       |
-| Redux Toolkit           | Browser-root state store                                           | [redux-toolkit.js.org](https://redux-toolkit.js.org/)                                      |
+| Project                 | Used for                                                                                        | Link                                                                                       |
+| ----------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| libsodium               | X25519, Ed25519, ChaCha20-Poly1305, BLAKE2b, HKDF, Argon2, SHA-512                              | [github.com/jedisct1/libsodium](https://github.com/jedisct1/libsodium)                     |
+| mlkem-native            | ML-KEM-512/768/1024 (FIPS 203)                                                                  | [github.com/pq-code-package/mlkem-native](https://github.com/pq-code-package/mlkem-native) |
+| Emscripten              | Compiles the C cryptography to the pinned WASM module                                           | [emscripten.org](https://emscripten.org/)                                                  |
+| BIP-39 English wordlist | The 2,048 words only, shared by room invites and identity recovery phrases — see the note below | [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md)       |
+| Redux Toolkit           | Browser-root state store                                                                        | [redux-toolkit.js.org](https://redux-toolkit.js.org/)                                      |
+
+`src/utils/wordlist.json` is the BIP-39 English list, and that is the whole
+extent of the relationship. Two unrelated encodings share it, and **neither
+uses BIP-39 checksum semantics**:
+
+- the 24-word room invite (`src/roomInvite.ts`), which encodes a 32-byte room
+  capability and checksums it with SHA-256 over the domain separator
+  `p2party/room-invite/checksum/v1\0`, under its own wordlist id
+  `p2party-invite-en-v1`; and
+- the identity recovery phrase (`src/cryptography/mnemonic.ts`), which takes
+  128–512 bits of entropy (12–48 words), checksums with the leading bits of
+  SHA-512, and derives its seed with argon2id rather than PBKDF2-HMAC-SHA512.
+  This is the phrase
+  [identity backup and restore](../README.md#back-up-and-restore-your-identity)
+  derives an Ed25519 identity from; the invite encodes a room capability and
+  restores no identity at all.
+
+Both reject the canonical BIP-39 English test vectors — the invite decoder with
+`Room invite checksum is invalid`, `validateMnemonic()` by returning `false` —
+and no BIP-39 tool can restore either. Do not describe them as BIP-39.
 
 ## 2. Standards the wire format implements
 
@@ -152,6 +172,6 @@ third-party security audit. Cite the implementation:
 @software{p2party,
   title  = {p2party: protocol-v4 end-to-end encryption over a WebRTC room mesh},
   url    = {https://github.com/p2party/p2party-js},
-  note   = {Version 0.14.3}
+  note   = {Version 0.14.10}
 }
 ```

package/docs/session-api.md

@@ -381,6 +381,15 @@ The bootstrap ML-KEM exchange protects the initial root. Healing periodically
 re-runs it so a later post-quantum compromise cannot unwind an old session.
 The session owns the state machine; the caller owns scheduling and transport.
 
+The browser SDK separately coordinates queued scheduled producers with epoch
+changes, persists per-recipient chunk receipts, and implements WebRTC pause and
+CANCEL controls. Those transport/outbox services are not part of
+`p2party/session`. A session integrator must coordinate its own pending output
+and recovery when `pqEpoch` changes; the session does not selectively resend
+previously returned frames or interpret cover receipt subtypes. See the
+[wire format](wire-format.md#scheduled-control-cells--65490-bytes) for the browser
+contract.
+
 Control frames are the same 65,490-byte size as chunk frames, so the outer
 framing MUST record which kind a record is — the session will reject a control
 frame handed to `decrypt()` and vice versa.
@@ -450,8 +459,16 @@ interface SessionCryptoOptions {
 
 Supplying bytes is the reproducible, offline-safe path. Resolve the exported
 `p2party/libcrypto.wasm` package subpath or pin a self-hosted copy from the same
-release. When `wasmBinary` is omitted, the loader fetches the immutable
-versioned p2party CDN artifact and checks the build-pinned SHA-384 SRI.
+release.
+
+Omitting `wasmBinary` does not always mean a network call. On Node and Bun the
+loader reads this release's WASM from the installed package — the file next to
+the bundle — and hashes it against the build-pinned SHA-384 before use, so an
+offline or air-gapped install needs no configuration. It falls back to the
+immutable versioned p2party CDN artifact, under the same SRI, only when that
+read fails or the digest does not match. In a browser, where there is no
+filesystem, the CDN fetch is the only path. An explicit `setWasmSourceUrl()` is
+honoured everywhere, including on Node, in preference to the packaged copy.
 
 See [Protocol-v4 security](protocol-v4-security.md) for the exact claims and
 non-claims of the session this API constructs.

package/docs/wire-format.md

@@ -1,26 +1,29 @@
 # Wire format
 
-Every byte here is derived from
-[`src/utils/constants.ts`](../src/utils/constants.ts), which is the single
-source of truth and is byte-matched in `utils.h`. For what these frames do and
-do not protect, read the
+Chunk geometry is defined in
+[`src/utils/constants.ts`](../src/utils/constants.ts) and byte-matched in
+`utils.h`. Scheduled control subtypes are defined in
+[`coverCell.ts`](../src/cryptography/coverCell.ts); immediate transfer controls
+are defined in [`immediateDisposition.ts`](../src/handlers/immediateDisposition.ts).
+For what these frames do and do not protect, read the
 [protocol-v4 security boundary](protocol-v4-security.md).
 
-
 ## Outer frame types
 
 One tag byte leads every frame on a data channel.
 
-| Tag | Name         | Size on the wire | Carries                         |
-| --- | ------------ | ---------------- | ------------------------------- |
-| 1   | `HANDSHAKE`  | step-dependent   | HELLO, CONFIRM, FINISH          |
-| 2   | `CHUNK`      | 65,490 B         | one fixed application cell      |
-| 3   | `RECEIPT`    | 65 B             | SHA-512 acknowledgement token   |
-| 4   | `COVER`      | 65,490 B         | a scheduled cell, real or decoy |
-| 5   | `PQ_CONTROL` | 65,490 B         | sparse-PQ OFFER / ADVANCE / ACK |
+| Tag | Name                    | Size on the wire | Carries                               |
+| --- | ----------------------- | ---------------- | ------------------------------------- |
+| 1   | `HANDSHAKE`             | step-dependent   | HELLO, CONFIRM, FINISH                |
+| 2   | `CHUNK`                 | 65,490 B         | one fixed application cell            |
+| 3   | `RECEIPT`               | 65 B             | SHA-512 acknowledgement token         |
+| 4   | `COVER`                 | 65,490 B         | scheduled dummy or encrypted control  |
+| 5   | `PQ_CONTROL`            | 65,490 B         | sparse-PQ OFFER / ADVANCE / ACK       |
+| 6   | `IMMEDIATE_DISPOSITION` | 66 B             | immediate resume capability or CANCEL |
 
-Tags 2, 4, and 5 are deliberately identical in size. An observer cannot tell an
-application cell from a decoy or from a healing exchange by looking at the wire.
+Tags 2, 4, and 5 have equal payload lengths. The frame tags travel inside
+WebRTC's DTLS transport; packetization, timing and total traffic remain
+observable. Scheduled real data uses tag 2 in a scheduled lane slot.
 
 ## Chunk frame — 65,490 bytes
 
@@ -52,6 +55,81 @@ application cell from a decoy or from a healing exchange by looking at the wire.
 
 Both per-chunk acknowledgements and the terminal content-hash acknowledgement
 use this exact geometry, so a completion is not distinguishable by size.
+Chunk tokens bind the transfer Merkle root, original chunk index and leaf hash.
+The sender resolves them through its staged chunk index and persists the
+per-recipient acknowledgement before updating the live have-set. A terminal
+immediate receipt must equal the message's content hash. These frames use the
+authenticated concrete message channel and its current identity gate.
+
+## Scheduled control cells — 65,490 bytes
+
+```text
+type=4(1) || edge binding(32) || counter(8) || reserved zero(8) ||
+PQ epoch(8) || nonce(12) || ciphertext(65,405) || AEAD tag(16)
+```
+
+All 69 header bytes are authenticated. The key binds the room's suite, edge,
+direction and PQ epoch. After authentication and counter replay rejection,
+the plaintext is `subtype(1) || payload length(4, BE) || payload || zero pad`:
+
+| Subtype | Meaning          | Payload                                                                |
+| ------- | ---------------- | ---------------------------------------------------------------------- |
+| 1       | Dummy            | Empty                                                                  |
+| 2       | CANCEL           | Transfer Merkle root (64 B)                                            |
+| 3       | Terminal receipt | Transfer Merkle root (64 B), followed by the same root as token (64 B) |
+| 4       | Chunk receipts   | Transfer Merkle root (64 B), followed by 1–64 chunk tokens (64 B each) |
+
+Subtype 4's authenticated payload length determines the token count; partial
+tokens, empty batches and batches over 64 tokens are rejected. Only tokens for
+one transfer root share a batch. A subtype 3 token unequal to its root cannot
+complete a send. Each chunk token must resolve to the tracked transfer, root
+and a valid original index. The durable owner also binds room, recipient ID
+and public key; a stale owner cannot advance live state after a storage await.
+A recipient's CANCEL records refusal only for that recipient.
+
+Receipts and CANCELs replace dummy slots in the existing schedule. The pending
+outbound control queue is bounded to 4,096 token/control units; dropping a
+queued acknowledgement may require a later retransmission. A terminal receipt
+supersedes unsent chunk acknowledgements for the same root, preserving the
+first available reverse slot for completion even at long cadences. Other roots
+and queued CANCEL controls retain their order. Live have-set
+membership uses an O(1) `Set` lookup without copying the set per slot. A resumed
+producer scans original indices once and emits missing chunks. It also selects
+index zero once per attempt to recover a lost terminal receipt: if that index
+was already acknowledged, this costs one extra completion probe. Index scanning
+and durable token lookups do not imply globally sublinear processing, and fewer
+real chunks do not reduce the fixed scheduled cell count.
+
+Subtype 4 is a protocol-v4 wire addition. Earlier clients reject and drop this
+unknown subtype and keep using subtype 3 completion. They cannot selectively
+resume scheduled chunks; a missing terminal receipt can require whole-transfer
+replay. Subtype 3 is never reused for chunk tokens, because earlier clients
+treated any subtype 3 receipt for a tracked root as completion. These additions
+do not introduce a fallback to an earlier cryptographic protocol version.
+
+## Immediate pause and cancellation — 66 bytes
+
+```text
+type=6(1) || kind(1) || transfer Merkle root(64)
+```
+
+Kind 0 announces resume support; kind 1 is explicit CANCEL. An immediate
+message channel opened with DCEP protocol `p2party-resume-v1` promises that a
+bare close may pause the transfer. A supporting receiver echoes kind 0 after
+the identity gate opens; the opener then also treats a bare remote close as
+pause. CANCEL is accepted once per concrete channel, only under its current
+authenticated gate and exact root. Malformed, unknown, stale and cross-root
+controls have no effect. This control relies on the authenticated DTLS/SCTP
+channel; it has no separate application AEAD envelope.
+
+An explicit cancellation sends kind 1 before closing. A transient failed
+attempt closes without CANCEL, allowing a supporting receiver to retain its
+partial data for bounded resume. Earlier clients ignore type 6 and retain
+their close-as-cancel behavior. At a fresh immediate attempt the new sender
+starts a fresh live chunk have-set and rebuilds it from the receiver's paced
+receipt replay, so deleted legacy partials cause full resend
+instead of trusting stale acknowledgements. The store-free session API does
+not implement this WebRTC channel contract.
 
 ## Handshake ladder
 
@@ -88,6 +166,16 @@ rather than something both sides have to reconcile. Each side persists its
 mutated state **before** dispatching, and application traffic is blocked while
 an epoch is in flight.
 
+The browser scheduler starts a local exchange only when no real producer,
+derive-to-enqueue reservation, message channel or queued receive work remains.
+Dummy/control cover alone does not hold it back. A remote exchange blocks new
+application admission and drains reservations before the durable transition;
+it does not wait for a long scheduled send to finish. A committed new epoch
+retires old-key real producers and publishes a cover generation change on the
+same runtime. The sender re-derives the remaining transfer under that epoch;
+fixed lane timing continues with dummy tails. An unrelated generation notice
+cannot authorize reuse of the same runtime without an actual PQ epoch advance.
+
 ## Room policy — 32 bytes
 
 A room's policy is a fixed 32-byte record (magic `"P2RP"`) that pins the ML-KEM

package/lib/api/signalingServerApi.d.ts

@@ -1,15 +1,64 @@
+import { type RequestRoomLeaveOptions } from "../utils/roomLeaveCoordinator";
 import type { BaseQueryFn } from "@reduxjs/toolkit/query";
-import type { WebSocketMessageCandidateSend, WebSocketMessageDescriptionSend, WebSocketMessageChallengeResponse, WebSocketMessageRoomIdRequest, WebSocketMessagePeersRequest, WebSocketMessageConnectionResponse, WebSocketMessagePongResponse, WebSocketPeerConnectionParams } from "../utils/interfaces";
+import type { WebSocketMessageCandidateSend, WebSocketMessageDescriptionSend, WebSocketMessageChallengeResponse, WebSocketMessageRoomIdRequest, WebSocketMessagePeersRequest, WebSocketMessageConnectionResponse, WebSocketMessagePongResponse, WebSocketMessageLeaveRoomRequest, WebSocketPeerConnectionParams, WebSocketMessagePeerConnectionRequest } from "../utils/interfaces";
+import type { BaseQueryApi } from "@reduxjs/toolkit/query";
 export interface WebSocketParams {
     signalingServerUrl: string;
 }
 export interface WebSocketMessage {
-    content: WebSocketMessagePongResponse | WebSocketMessageCandidateSend | WebSocketMessageDescriptionSend | WebSocketMessageChallengeResponse | WebSocketMessageRoomIdRequest | WebSocketMessagePeersRequest | WebSocketMessageConnectionResponse;
+    content: WebSocketMessagePongResponse | WebSocketMessageCandidateSend | WebSocketMessageDescriptionSend | WebSocketMessageChallengeResponse | WebSocketMessageRoomIdRequest | WebSocketMessageLeaveRoomRequest | WebSocketMessagePeersRequest | WebSocketMessageConnectionResponse | WebSocketMessagePeerConnectionRequest;
 }
+/**
+ * The host the reconnect controller reads Redux state from and dispatches
+ * through. Bound on every connect attempt; the tests rebind it directly. It is
+ * NOT the store import, so this module keeps its existing dependency edges.
+ */
+type SignalingReconnectHost = {
+    dispatch: (action: unknown) => unknown;
+    getState: () => unknown;
+};
+export declare const setSignalingReconnectHost: (host: SignalingReconnectHost | null) => void;
+/**
+ * Record how a socket ended, so the reconnect ladder can refuse a close the
+ * server means as final. `selfInitiated` is what keeps the SDK's own protective
+ * closes out of the policy: `onOverflow` closes with 1008 when this tab's
+ * ingress backlog is exceeded, and local overload is exactly what bounded
+ * backoff is for.
+ */
+export declare const noteSignalingSocketClose: (close: Readonly<{
+    code: number;
+    selfInitiated: boolean;
+}>) => void;
+/**
+ * A ladder rung is a floor, never shortened, and at most 25 % longer. Without
+ * this every client a server restart disconnected walks the identical
+ * 1/2/4/8 s ladder and re-handshakes in lockstep, which is the same stampede
+ * the restart caused. The spread lives here rather than in the controller
+ * because the controller's ladder is exact by contract and its tests assert
+ * exact delays; the scheduler this module injects is the seam that perturbs it.
+ */
+export declare const signalingReconnectDelayWithJitter: (delayMs: number) => number;
+/**
+ * C4: a socket close that carries no browser wake event is otherwise terminal.
+ * `settleClosedSocket` detects; this reconnects. Shared by the close handler,
+ * the error handler and the heartbeat watchdog, so a peer whose socket died
+ * while its edges stayed authenticated is found again within 1-30 s instead of
+ * never.
+ */
+export declare const signalingReconnect: import("../utils/signalingReconnectController").SignalingReconnectController;
+type CurrentSocketApi = Pick<BaseQueryApi, "dispatch" | "getState">;
+/**
+ * Send a correlated leave on the exact authenticated socket and wait for its
+ * exact acknowledgement. The caller must make local room transport terminal
+ * before invoking this network-only boundary.
+ */
+export declare const requestCurrentSocketRoomLeave: (api: CurrentSocketApi, roomUrl: string, options?: RequestRoomLeaveOptions) => Promise<void>;
 declare const signalingServerApi: import("@reduxjs/toolkit/query").Api<BaseQueryFn<WebSocketParams, undefined>, {
     connectWebSocket: import("@reduxjs/toolkit/query").MutationDefinition<string, BaseQueryFn<WebSocketParams, undefined>, never, undefined, "signalingServerApi", undefined>;
     disconnectWebSocket: import("@reduxjs/toolkit/query").MutationDefinition<undefined, BaseQueryFn<WebSocketParams, undefined>, never, undefined, "signalingServerApi", undefined>;
     sendMessage: import("@reduxjs/toolkit/query").MutationDefinition<WebSocketMessage, BaseQueryFn<WebSocketParams, undefined>, never, undefined, "signalingServerApi", undefined>;
     connectWithPeer: import("@reduxjs/toolkit/query").MutationDefinition<WebSocketPeerConnectionParams, BaseQueryFn<WebSocketParams, undefined>, never, undefined, "signalingServerApi", undefined>;
 }, "signalingServerApi", never, typeof import("@reduxjs/toolkit/query").coreModuleName>;
+/** Queue one room request or reject immediately when RTK reports no send. */
+export declare const sendRoomRequestMessage: (api: Pick<BaseQueryApi, "dispatch">, request: WebSocketMessageRoomIdRequest) => Promise<void>;
 export default signalingServerApi;

package/lib/api/webrtc/interfaces.d.ts

@@ -3,11 +3,20 @@ import type { RatchetState } from "../../cryptography/ratchet";
 import type { RatchetGateLease } from "../../handlers/ratchetGate";
 import type { CoverRuntime } from "../../handlers/coverRuntime";
 import type { SparsePqHealingState } from "../../handlers/pqHealingRuntime";
+import type { PeerHandshakeFailureReason } from "../../reducers/roomSlice";
+import type { PeerSocketGenerationSource } from "./peerSocketGeneration";
 export interface IRTCPeerConnection extends RTCPeerConnection {
     /** The room this transport belongs to. A room/peer pair owns one PC. */
     roomId: string;
     withPeerId: string;
     withPeerPublicKey: string;
+    /**
+     * The peer signaling socket this transport was built against. A different
+     * generation for the same peerId means the peer's session was replaced, and
+     * this transport can never be signalled again (C1). Absent against a
+     * pre-generation server, where it must never be read as a change.
+     */
+    peerSocketGeneration?: string;
     makingOffer: boolean;
     ignoreOffer: boolean;
     receiveMessageModule: LibCrypto;
@@ -16,8 +25,42 @@ export interface IRTCPeerConnection extends RTCPeerConnection {
     mainChannel?: IRTCDataChannel;
     /** Gate ownership captured when this concrete transport is created. */
     ratchetGateLease: RatchetGateLease;
+    /**
+     * Set when this edge's handshake failed for a reason a fresh transport
+     * cannot fix (a wrong PIN, a PIN throttle, a policy/suite mismatch). The
+     * `main` channel's close handler consults it so a terminal failure is never
+     * followed by a re-dial. Cleared only by building a new transport.
+     */
+    handshakeTerminalFailure?: PeerHandshakeFailureReason;
+    /**
+     * How many times this RTCPeerConnection has been re-bound IN PLACE onto a
+     * new remote DTLS certificate since it last authenticated. The re-bind
+     * budget (see decideRemoteTransportChangeResponse) reads it to guarantee
+     * that a peer which keeps presenting fresh certificates converges on a
+     * replacement transport instead of looping; the handshake success path
+     * clears it.
+     */
+    remoteTransportRebinds: number;
+    /**
+     * Deadline armed by the in-place re-bind above: if this transport has not
+     * re-authenticated when it fires, the edge is torn down and rebuilt instead
+     * of waiting out the peer's 30 s handshake step timeout. Cleared by the
+     * handshake success path, by the teardown, and re-armed by a later re-bind.
+     */
+    rebindDeadline?: ReturnType<typeof setTimeout>;
+    /**
+     * The `clearTimeout` that matches whatever scheduled `rebindDeadline`. The
+     * arming site owns the scheduler (tests inject one), while the clearing
+     * sites — handshake success, peer teardown — only hold the connection.
+     */
+    rebindDeadlineClear?: (handle: ReturnType<typeof setTimeout>) => void;
     /** Resolves once the per-transport WASM dependency is ready. */
     initialization?: Promise<void>;
+    /**
+     * Re-proves signaling and applies the latest room ICE configuration before
+     * any restart. Installed by the connection owner and shared by repair paths.
+     */
+    ensureFreshIceConfiguration?: () => Promise<boolean | void>;
     ratchetState?: RatchetState;
     ratchetEstablished?: Promise<void>;
     messageKeyCache?: Map<string, Uint8Array>;
@@ -61,6 +104,13 @@ export interface IRTCDataChannel extends RTCDataChannel {
      * delete its storage artifacts after the active handler reaches quiescence.
      */
     cancelReceiveTransfer?: () => Promise<void>;
+    /**
+     * Set by any close THIS side initiated (the pre-authentication frame guard,
+     * the transfer's terminal-close runner, the resume path's cleanup). Read by
+     * `isAuthenticatedPeerCancel` so our own close is never reported as the peer
+     * cancelling the transfer (C7).
+     */
+    closedLocally?: boolean;
 }
 export interface IRTCMessage {
     id: string;
@@ -79,6 +129,15 @@ export interface RTCPeerConnectionParams {
     peerPublicKey: string;
     roomId: string;
     rtcConfig?: RTCConfiguration;
+    /** The peer's signaling-socket generation, as last named by the server. */
+    peerSocketGeneration?: string;
+    /**
+     * Which inbound frame named that generation. Only a `connection` frame
+     * proves a fresh remote transport; a roster introduction is record-only
+     * while this side's transport is connected (see peerSocketGeneration).
+     * Omitted means advisory.
+     */
+    peerSocketGenerationSource?: PeerSocketGenerationSource;
 }
 export interface RTCSetDescriptionParams {
     peerId: string;
@@ -92,6 +151,14 @@ export interface RTCSetCandidateParams {
     roomId: string;
     candidate: RTCIceCandidateInit | RTCIceCandidate;
 }
+export interface RTCApplyRoomConfigurationParams {
+    roomId: string;
+    rtcConfig: RTCConfiguration;
+    /** Gather a new ICE generation after every live PC accepts the config. */
+    restartIce?: boolean;
+    /** Expiry must close on failure; rollback would restore expired secrets. */
+    failurePolicy?: "rollback" | "close";
+}
 export interface RTCOpenChannelParams {
     roomId: string;
     channel: string | RTCDataChannel;
@@ -103,7 +170,7 @@ export interface RTCOpenChannelParams {
 export interface RTCSendMessageParams {
     /** Random 32-byte lowercase-hex identity allocated by the public API. */
     transferId: string;
-    data: string | File;
+    data?: string | File;
     label: string;
     roomId: string;
     minChunks?: number;
@@ -148,6 +215,8 @@ export interface RTCDisconnectFromPeerParams {
     roomId?: string;
     alsoDeleteData?: boolean;
 }
+/** Internal dependency injected into bulk teardown queries to avoid API cycles. */
+export type DisconnectPeerTransport = (params: RTCDisconnectFromPeerParams) => Promise<void>;
 export interface RTCDisconnectFromChannelLabelParams {
     roomId: string;
     label: string;

package/lib/api/webrtc/peerSocketGeneration.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Whether a peerId still names the same signaling session.
+ *
+ * The server binds one stable peerId to an identity public key, so a second
+ * tab or a phrase-restored second device reconnects as the SAME peerId and
+ * evicts its predecessor. Without a per-socket generation the edge stayed
+ * bound to the evicted socket: the transport never failed (no SDP, no ICE
+ * event), so nothing rebuilt it, and a responder on the new session creates no
+ * channel and can never offer — the split was permanent (C1).
+ *
+ * "unknown" is the fail-safe verdict: an absent or malformed generation (a
+ * pre-generation server, or a fresh transport that has not recorded one yet)
+ * must behave exactly as 0.14.7 does, never as a teardown trigger. The server
+ * leaves the field empty until a socket has proved ownership of its key and
+ * empties it again whenever a fresh challenge is issued, so "" and undefined
+ * are the same statement: no information.
+ */
+export type PeerSocketGenerationVerdict = "unknown" | "unchanged" | "changed";
+/**
+ * Which inbound frame carried a generation, and therefore how much authority
+ * it has.
+ *
+ * - "connection": the peer's own `connection` frame. It is emitted from one
+ *   place only (handleConnectToPeer's connectWithPeer), and that place is
+ *   reachable only after a FRESH transport has been built — both baseQuery and
+ *   handleConnectToPeer early-return on a live one. A changed generation there
+ *   always means a genuinely new remote transport.
+ * - "roster": a `peers` introduction. The roster is re-requested on join, on
+ *   re-dial AND on reconcile, and a signaling socket now reconnects on its
+ *   own, so a benign reconnect of a healthy session routinely delivers a
+ *   changed generation for an edge that is working perfectly. Acting on that
+ *   is a regression of cluster C4, so it is record-only while the local
+ *   transport is connected.
+ */
+export type PeerSocketGenerationSource = "connection" | "roster";
+export declare const isCanonicalSocketGeneration: (value: unknown) => value is string;
+export declare const comparePeerSocketGeneration: (recorded: string | undefined, observed: unknown) => PeerSocketGenerationVerdict;
+export declare const markPeerSocketGenerationRetired: (roomId: string, peerId: string, generation: unknown) => void;
+export declare const isPeerSocketGenerationRetired: (roomId: string, peerId: string, generation: unknown) => boolean;
+export declare const clearRetiredPeerSocketGenerations: (roomId: string, peerId: string) => void;
+export interface PeerSocketGenerationObservation {
+    roomId: string;
+    peerId: string;
+    /** The generation the local transport was built against, if any. */
+    recorded: string | undefined;
+    /** The generation this frame names for the peer. */
+    observed: unknown;
+    /** Which inbound frame carried it; an unattributed frame is advisory. */
+    source: PeerSocketGenerationSource | undefined;
+    /** The local transport's current state. */
+    connectionState: RTCPeerConnectionState;
+}
+/**
+ * Whether an observed generation is reason enough to retire the local
+ * transport for this edge and rebuild it against the peer's live session.
+ *
+ * Deliberately conservative in two directions. A roster introduction is acted
+ * on only when the local transport is demonstrably not working — a healthy
+ * edge must survive an ordinary signaling reconnect (C4). And a generation
+ * this edge has already retired never triggers a second teardown, however it
+ * arrives.
+ *
+ * "not working" excludes "disconnected". handleConnectToPeer answers that state
+ * with an ICE restart and only tears the edge down if it is still disconnected
+ * 8 s later, and the restart usually succeeds — so a roster frame arriving in
+ * that window would replace a transport that was about to heal itself.
+ */
+export declare const shouldRetireTransportForSocketGeneration: ({ roomId, peerId, recorded, observed, source, connectionState, }: PeerSocketGenerationObservation) => boolean;

package/lib/cryptography/coverCell.d.ts

@@ -5,6 +5,8 @@ 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;
+/** Bound token lookup/persistence work per authenticated scheduled cell. */
+export declare const MAX_COVER_CHUNK_RECEIPTS = 64;
 export declare const COVER_CELL_MAX_PAYLOAD_BYTES: number;
 export type CoverCellDirection = "initiator-to-responder" | "responder-to-initiator";
 export type CoverCellContent = {
@@ -21,6 +23,11 @@ export type CoverCellContent = {
     readonly subtype: "receipt";
     readonly merkleRoot: Uint8Array;
     readonly token: Uint8Array;
+} | {
+    /** Subtype 4: old clients drop this unknown subtype, never treat it as completion. */
+    readonly subtype: "chunk-receipts";
+    readonly merkleRoot: Uint8Array;
+    readonly tokens: readonly Uint8Array[];
 };
 export type CoverCellErrorCode = "authentication-failed" | "binding-mismatch" | "epoch-mismatch" | "invalid-cell" | "invalid-direction" | "invalid-padding" | "replayed-counter";
 export declare class CoverCellError extends Error {