p2party 0.14.2 → 0.14.7

package/README.md

@@ -38,15 +38,24 @@ Apache-2.0 · [LICENSE.md](LICENSE.md)
   Browser builds use IndexedDB and, where available, OPFS for disk-backed large
   file receipt.
 - Room capabilities have a compact 43-character base64url form, a versioned
-  fragment invite, and an optional checksum-protected 24-word
-  [BIP-39](https://github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md)
-  representation.
+  fragment invite, and an optional checksum-protected 24-word representation
+  drawn from the
+  [BIP-39 English wordlist](https://github.com/bitcoin/bips/blob/master/bip-0039/bip-0039-wordlists.md).
+  It borrows the words, not the format: the checksum is SHA-256 over p2party's
+  own domain separator, so a BIP-39 phrase is not a valid invite. See
+  [docs/references.md](docs/references.md).
+- An identity created from a recovery phrase can be restored on another device:
+  12 to 48 words drawn from the same wordlist, checksummed with SHA-512 and
+  stretched into the Ed25519 seed with argon2id. The derivation runs one way, so
+  a randomly generated identity cannot be exported — it can only be replaced by
+  a recoverable one. See
+  [Back up and restore your identity](#back-up-and-restore-your-identity).
 - `p2party/session` exposes the cryptography without
   [Redux](https://redux-toolkit.js.org/), IndexedDB, WebRTC, signaling,
   `window`, or `localStorage`.
 
 Immediate delivery over the existing signaling rendezvous is the shipped
-default. Scheduled timing cover is also wired as of 0.14.2: a room policy may
+default. Scheduled timing cover is also wired: a room policy may
 pin a cadence, lane count, and frames per cell, and every edge in the room then
 emits fixed-size cells on that schedule whether or not there is data to send.
 Sparse post-quantum healing (the OFFER/ADVANCE/ACK epoch exchange) is likewise
@@ -81,7 +90,7 @@ npm audit signatures
 
 To build the artifact yourself instead, see
 [Building from source](CONTRIBUTING.md#building-from-source). That path needs an
-exact toolchain (Node 24, Emscripten 6.0.3, pinned submodules), because the
+exact toolchain (Node 24, Emscripten 6.0.9, pinned submodules), because the
 release build reproduces the pinned WASM and refuses to emit an artifact it
 cannot attest.
 
@@ -192,6 +201,63 @@ protocol-v4 acknowledgement: p2party next runs its authenticated HELLO plus
 three chained confirmation flights over the main channel. Message receipts are
 a third, delivery-level acknowledgement.
 
+### When a peer sleeps
+
+A phone that backgrounds with its radio off for less than WebRTC's ~30 s ICE
+consent timeout used to wake into a permanent split. Its peer had already torn
+that edge down and built a fresh one, but the woken side still read
+`connected`, reused the dead transport, and let its zombie `main` channel block
+a replacement — so no handshake ever ran on the peer's new transport. One side
+showed the peer reachable and every send failed undelivered; the other showed
+no handshake at all and its sends hung forever. Only a manual reconnect cleared
+it.
+
+Seven behaviours now hold the edge together, and each is what the library does
+rather than a guarantee about your network:
+
+- **A peer edge is bound to the DTLS certificate it authenticated against.**
+  When the remote certificate changes, an already-authenticated transport is
+  replaced outright. One that never authenticated is re-authenticated in place
+  instead, at most once, so a peer that keeps presenting fresh certificates
+  still converges on a replacement rather than looping.
+- **Descriptions from a retired transport are discarded**, so an answer
+  belonging to a dead connection can no longer poison the one that replaced it.
+- **Every failure teardown re-dials the room** under its own debounce budget.
+  Deliberate teardowns — `disconnectFromPeer`, leaving, address-book removal —
+  do not. A superseded handshake attempt dies quietly instead of tearing down
+  the transport that superseded it.
+- **A send to a peer that never authenticates fails inside a bounded wait**
+  with a stated reason, rather than hanging on the ratchet gate forever.
+- **A half-open signaling socket is detected**, by a heartbeat watchdog (25 s
+  with no server ping) and on wake events, and marked disconnected so a
+  reconnect can run.
+- **RTCPeerConnection operations settle when the connection closes underneath
+  them**, so a closing connection cannot strand the per-peer lock and wedge the
+  socket's ingress queue.
+- **An interrupted transfer resumes across an edge re-authentication.** The
+  transfer's cipher and its cancel detection follow the cryptographic
+  generation rather than the connection object, so a channel closed by a
+  re-authentication reads as a resume, not as a peer cancelling on you.
+
+Verified with two separate headless-Chromium processes against a Bun relay
+mirroring the signaling server, one process SIGSTOPped whole-tree with its UDP
+host-candidate buffers flooded — a phone asleep with the radio off. Across
+seven scenarios (baseline, socket drop, a 20 s freeze in each identity role
+with the socket dropped and with it kept, and a 45 s freeze) both sides
+reconverge and exchange byte-exact messages 0.5–6.5 s after wake, and four
+in-flight 8 MiB transfer configurations finish byte-exact with the sender
+reporting `delivered`.
+
+Two limits, since they are as real as the fixes. Resume follows a live page: a
+send in flight does not survive reloading the sending page, though a reloaded
+receiver replays receipts for what it already holds so a still-live sender
+resends only the gaps. And when a frozen identity responder is carrying an
+in-flight transfer, reconvergence takes about 37 s rather than the usual 5–7 s
+— the surviving SCTP association accepts our new streams but not the peer's, so
+recovery waits out the 30 s handshake step timeout. The transfer completes
+correctly; the latency is a known open item on the
+[roadmap](ROADMAP.md#near-term).
+
 ## Wire format
 
 Fixed 65,490-byte cells, a 65-byte receipt frame, and outer frame tags that make
@@ -331,6 +397,98 @@ shape; [docs/getting-started.md](docs/getting-started.md#send-cancel-and-read)
 covers reading inbound messages and the metadata-only read that avoids
 materializing large files.
 
+## Back up and restore your identity
+
+An identity is an Ed25519 key pair in browser storage. Lose the profile and you
+lose the identity — unless it was created from a recovery phrase, because the
+phrase is the only thing that can reproduce it.
+
+Three calls, introduced together: `getIdentityBackupStatus()` reports whether
+the identity in use can be backed up at all, `createRecoverableIdentity()`
+replaces it with one a phrase derives and hands back that phrase once, and
+`restoreIdentityFromMnemonic()` adopts the identity a phrase encodes — on this
+device or any other.
+
+```ts
+// Can the identity in use be backed up at all?
+const status = await p2party.getIdentityBackupStatus();
+// status.derivation === "mnemonic" -> a phrase restores it
+// status.derivation === "random"   -> nothing can; it can only be replaced
+// status.derivation === null       -> unknown: no identity is stored yet, or
+//                                     one whose provenance was never recorded.
+//                                     Treat it as having no backup.
+
+if (status.derivation !== "mnemonic") {
+  // Replaces the identity in use and hands back the only copy of the phrase.
+  const { mnemonic, publicKey } = await p2party.createRecoverableIdentity({
+    strength: 256, // 24 words; 128 gives 12. Default 256.
+    // password: folded into the derivation, and just as unrecoverable.
+  });
+
+  // Show it once, in the UI. Never log it: console output is storage, and
+  // devtools, extensions and webview log shippers all keep it.
+  showRecoveryPhraseOnce(mnemonic);
+  console.log("recoverable identity", publicKey);
+}
+```
+
+On another device, before connecting, adopt the identity a phrase encodes:
+
+```ts
+try {
+  const { publicKey } = await p2party.restoreIdentityFromMnemonic(
+    typedPhrase,
+    password, // omit unless one was used at creation
+  );
+  console.log("restored", publicKey);
+} catch (error) {
+  if (error instanceof p2party.InvalidRecoveryPhraseError) {
+    // A typo. Nothing was disconnected and nothing was replaced, so keep the
+    // form open and let the user fix it.
+  }
+}
+
+// Both calls leave signaling disconnected. Come back online yourself.
+await p2party.connect(roomUrl);
+```
+
+**What the phrase is.** 12 to 48 words from the shared wordlist, checksummed
+with SHA-512 and stretched by argon2id — salted with the optional password —
+into the Ed25519 seed. It borrows the BIP-39 English words and nothing else, so
+no BIP-39 wallet can restore one of these identities —
+[docs/references.md](docs/references.md) has the exact differences. The
+derivation runs one way: an identity can be _created_ from a phrase, never
+exported to one.
+
+**Existing identities cannot be exported.** Every identity the SDK generated
+before this — and any it still generates on first connect — comes from a random
+seed, so no phrase describes it. A newly generated one is recorded as
+`"random"`; one that predates the record, or whose record no longer binds to
+the stored key, reads `null`. Both mean the same thing to an app, and reporting
+it is the point: say the identity has no backup instead of offering one that
+cannot exist. The only route to a recoverable identity is
+`createRecoverableIdentity()`, which _replaces_ the current one: contacts see a
+new identity key for this device and their clients flag the change, exactly as
+they would after a purge.
+
+**The phrase is shown once and stored nowhere.** Neither the SDK nor its
+storage keeps a copy, by design — a phrase at rest is the identity at rest — so
+an app that drops it before the user has written it down has lost the backup.
+The password is not stored or checked either: restoring with a different one
+silently derives a different identity.
+
+**What restoring does to a running mesh.** It rotates the account key, so it
+takes the same exclusive path a purge does: signaling is disconnected, every
+room's WebRTC transport is brought to a terminal state, and the cross-signed
+X25519 identity is dropped so the next connection regenerates and re-signs it.
+Rooms, messages, the address book and cached room PINs are all kept — reconnect
+and you are in the same rooms under the restored key. An invalid phrase rejects
+with `InvalidRecoveryPhraseError` before any of that starts.
+
+While a phrase is being typed, `validateMnemonicWords(words)` is synchronous
+and names the first word that is not in the wordlist; `validateMnemonic(phrase)`
+adds the SHA-512 checksum and returns a promise.
+
 ## Cryptography without WebRTC
 
 `p2party/session` is the same protocol-v4 cryptography with no Redux, no
@@ -446,7 +604,8 @@ const decoder = new TextDecoder();
 const sealed = await alice.encrypt(encoder.encode("hello bob"));
 
 // sealed.protocolVersion === 4
-// sealed.root   -> 32-byte Merkle root, authenticated as AEAD additional data
+// sealed.root   -> 64-byte SHA-512 Merkle root, authenticated as AEAD
+//                  additional data (decrypt() rejects any other length)
 // sealed.frames -> [Uint8Array(65490)]  one uniform cell; a 9-byte message and
 //                  a 60 KiB message produce byte-identical frame sizes.
 //                  Each frame is:
@@ -517,8 +676,8 @@ envelope codec and the sparse-PQ healing hooks are in
 `joinRoom()` and `createSession()` are the batteries-included paths. Every step
 they take is also a public call, so you can drive the protocol yourself.
 
-**Identity, signing, and recovery phrases.** Keys are Ed25519; the recovery
-phrase is BIP-39, so a wallet-style backup flow works without a second library:
+**Identity, signing, and recovery phrases.** Keys are Ed25519, and a phrase
+derives one deterministically:
 
 ```ts
 const mnemonic = await p2party.generateMnemonic(256); // 24 words
@@ -530,6 +689,20 @@ const signature = await p2party.sign(bytes, keyPair.secretKey);
 const ok = await p2party.verify(bytes, signature, keyPair.publicKey);
 ```
 
+**This phrase is not BIP-39, and a BIP-39 wallet cannot restore it.** It draws
+its words from the BIP-39 English wordlist and nothing else: the checksum is
+the leading bits of SHA-512 rather than SHA-256, entropy runs from 128 to 512
+bits (12 to 48 words, where BIP-39 stops at 24), and the seed comes from
+argon2id over the normalized phrase — with an optional password used as the
+salt — rather than PBKDF2-HMAC-SHA512. The three canonical BIP-39 English test
+vectors all fail `validateMnemonic()`. Treat it as a p2party-specific format.
+
+These are the primitives. The identity the mesh actually uses is created,
+replaced and restored through
+[`createRecoverableIdentity()` and `restoreIdentityFromMnemonic()`](#back-up-and-restore-your-identity),
+which take care of the storage, the cross-signed X25519 identity and the
+transports authenticated by the outgoing key.
+
 **Room policy as data.** A policy is a value you can encode, hash, compare and
 validate before anything touches the network — useful for showing two peers
 that they really are about to join the same room:
@@ -622,7 +795,16 @@ is what this package compiles.
 
 ## No build step: a script tag and the CDN
 
-Every release publishes its browser bundle, its database worker and its
+> **`0.14.7` is not on the CDN yet.** The release pipeline uploads its objects
+> from the tarball it publishes, and that pipeline has not run for this
+> version: every path under `https://cdn.p2party.com/@0.14.7/` currently
+> answers 404, and npm still resolves `p2party` to an older release. The
+> snippet below is generated from this build and is what the release will
+> serve — until then, either pin the version `npm view p2party version` reports
+> (its objects are live) or self-host the bundle, which works today and is
+> described in the next section.
+
+A release publishes its browser bundle, its database worker and its
 cryptographic module as immutable, versioned CDN objects. The version is in the
 path, so a URL names exactly one build and is safe to cache forever. Drop the
 script in and `window.p2party` is there — no npm, no bundler, no build:
@@ -633,8 +815,8 @@ script in and `window.p2party` is there — no npm, no bundler, no build:
 <title>p2party in one file</title>
 
 <script
-  src="https://cdn.p2party.com/@0.14.2/p2party.min.js"
-  integrity="sha384-KJLIhsZkQzkYg1lyk57oAacQBR3DeWHX92Ksv9QTO9tUJVw1pxUNHI9e2nIcacgZ"
+  src="https://cdn.p2party.com/@0.14.7/p2party.min.js"
+  integrity="sha384-Wh2Pxka9YN2oAZmzYgaoyLmfKQMXsMO4AfUmshluGmYjfS0+ahOZGCTBGHtKTcC9"
   crossorigin="anonymous"
 ></script>
 
@@ -665,15 +847,15 @@ connect directly to each other.
 The three published objects:
 
 ```text
-https://cdn.p2party.com/@0.14.2/p2party.min.js     UMD bundle -> window.p2party
-https://cdn.p2party.com/@0.14.2/db.worker.js       IndexedDB/OPFS worker
-https://cdn.p2party.com/@0.14.2/libcrypto.wasm     the cryptographic module
+https://cdn.p2party.com/@<version>/p2party.min.js  UMD bundle -> window.p2party
+https://cdn.p2party.com/@<version>/db.worker.js    IndexedDB/OPFS worker
+https://cdn.p2party.com/@<version>/libcrypto.wasm  the cryptographic module
 ```
 
 The `integrity` value above is this release's bundle, and the release build
 fails if the README and the built artifact ever disagree — so it is safe to
 copy verbatim. The worker, if you host it yourself, is
-`sha384-qWbMGmyz8mCS/hgbn0jEf4Fo73iXiy6w+H/NfO6ymxKwzldUeHSxolNZtSZfV1nf`.
+`integrity=sha384-BudWf1U+vDU/j4pf2sX+bLogS/7MuPyzKRA9AfLoZqdbduUCwYr42p38rEoQRXa8`.
 
 The WASM is integrity-checked whether or not you pin the script: that hash is
 compiled into the bundle and cannot be turned off.
@@ -688,40 +870,58 @@ same release bytes before calling `connect()`:
 import p2party from "p2party";
 
 p2party.setWasmSourceUrl(
-  new URL("/vendor/p2party-0.14.2/libcrypto.wasm", window.location.href),
+  new URL("/vendor/p2party/libcrypto.wasm", window.location.href),
 );
 ```
 
 The SRI check remains active, so a URL serving different bytes fails closed.
 
-### Download the WASM from the CDN
+### Get the WASM and check it
+
+The npm tarball is the copy that always exists. It carries both files, and the
+package exports them, so no network fetch is needed to obtain either:
+
+```sh
+npm pack p2party && tar -xzf p2party-*.tgz
+ls package/lib/libcrypto.wasm package/lib/libcrypto.provenance.json
+# already installed? the subpaths resolve straight out of node_modules:
+node -p "require.resolve('p2party/libcrypto.wasm')"
+node -p "require.resolve('p2party/libcrypto.provenance.json')"
+```
 
-Every release publishes its cryptographic module as an immutable, versioned
-object. The path carries the version, so a URL always names exactly one build
-and is safe to cache forever:
+A published release also mirrors its cryptographic module to the CDN under an
+immutable, versioned path, so a URL names exactly one build and is safe to
+cache forever:
 
 ```sh
-curl -O https://cdn.p2party.com/@0.14.2/libcrypto.wasm
-curl -O https://cdn.p2party.com/@0.14.2/libcrypto.provenance.json
+curl -O "https://cdn.p2party.com/@$(npm view p2party version)/libcrypto.wasm"
 ```
 
+Two caveats, both current as of this release. The CDN carries only three
+objects — `p2party.min.js`, `db.worker.js` and `libcrypto.wasm` (see the
+`assets` array in `scripts/uploadToCDN.mjs`) — so
+**`libcrypto.provenance.json` is not on the CDN for any version**; take it from
+the tarball. And nothing is uploaded for this release yet, which is why the
+command above asks npm for a version that is actually published instead of
+naming this one.
+
 Check what you downloaded before you serve it. The SHA-256 and the SRI value
-are both recorded in the provenance file that sits next to it:
+are both recorded in the provenance file:
 
 ```sh
 shasum -a 256 libcrypto.wasm
 openssl dgst -sha384 -binary libcrypto.wasm | openssl base64 -A
 ```
 
-For 0.14.2 those are
-`7eea31157e69ac61f3a512b624d5c210296302fd289fc2b65c63ecc31a056267` and
-`sha384-pBMyUqQ3KBztxgeJMgDFZeohfj9QlAFNwt4/gRlqT0vlZ2kbkKxv+q5DwbZOBuUP`.
-They are the same bytes npm ships — the release workflow uploads the CDN object
-from the very tarball it publishes, then re-downloads and compares before
-`npm publish` runs, so the two can never diverge.
+Compare them against `libcrypto.provenance.json`, which records the same
+`sha256` and `sri` for the bytes the same release ships. CDN and npm cannot
+diverge for a release the pipeline actually ran: `.github/workflows/release.yml`
+unpacks the validated tarball, uploads the CDN object from it, and runs
+`npm run verify:cdn` before `npm publish`.
 
 Serve the file yourself and point the browser root at it with
 `setWasmSourceUrl()` above, or hand the bytes straight to `p2party/session`.
+Self-hosting is the path that works today for every version, published or not.
 
 On Node and Bun, `p2party/session` needs none of this: it reads the WASM from
 the installed package and checks it against the same pinned SHA-384, so an
@@ -750,7 +950,7 @@ release rather than surfacing later as a broken offline install.
 ## Development
 
 The reproducible release toolchain is Node 24.11.1, npm 11.6.2, Bun 1.3.14,
-Emscripten 6.0.3, and the repository's pinned libsodium source object. npm and
+Emscripten 6.0.9, and the repository's pinned libsodium source object. npm and
 `package-lock.json` are the dependency authority; Bun is the test runner.
 
 ```sh

package/docs/getting-started.md

@@ -174,6 +174,21 @@ returned. The application limit is 10 GiB. Cancellation is scoped most
 precisely by the handle's transfer ID, so prefer `handle.cancel()` over a
 content-hash lookup for concurrent identical sends.
 
+## Back up and restore an identity
+
+The identity behind every room is an Ed25519 key pair in browser storage, and
+only an identity created from a recovery phrase can be brought back after that
+storage is gone. `getIdentityBackupStatus()` says which kind is in use,
+`createRecoverableIdentity()` replaces the current identity with one a phrase
+reproduces and returns that phrase exactly once, and
+`restoreIdentityFromMnemonic()` adopts the identity a phrase encodes. The
+derivation is one way — an identity generated randomly, which is every identity
+that existed before these calls, cannot be exported to a phrase — and both
+calls replace the account key, so contacts see an identity change and signaling
+is left disconnected until you `connect()` again. The full contract, including
+what survives a restore and what a mistyped phrase costs, is in the
+[README](../README.md#back-up-and-restore-your-identity).
+
 ## Package artifacts and WASM
 
 The 0.14 package exports:

package/docs/protocol-v4-security.md

@@ -126,6 +126,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.7 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.2}
+  note   = {Version 0.14.7}
 }
 ```

package/docs/session-api.md

@@ -450,8 +450,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/lib/api/signalingServerApi.d.ts

@@ -1,15 +1,26 @@
+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;
 }
+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/applyIceConfiguration.d.ts

@@ -0,0 +1,9 @@
+import type { IRTCPeerConnection } from "./interfaces";
+/**
+ * Apply the room's current effective ICE servers to every live transport.
+ *
+ * getConfiguration() preserves construction-time WebRTC options that browsers
+ * do not allow setConfiguration() to change. Only the refreshable ICE list is
+ * replaced.
+ */
+export declare const applyRoomIceConfiguration: (peerConnections: readonly IRTCPeerConnection[], roomId: string, rtcConfig: RTCConfiguration, restartIceAfterApply?: boolean, failurePolicy?: "rollback" | "close") => number;

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

@@ -0,0 +1,10 @@
+import { handleOpenChannel } from "../../handlers/handleOpenChannel";
+import type { IRTCDataChannel, IRTCPeerConnection } from "./interfaces";
+/**
+ * Wires a transport's `ondatachannel` to handleOpenChannel: every inbound
+ * channel goes through the same admission as a locally created one, and an
+ * inbound `main` becomes the transport's main channel. Shared by the fresh
+ * transports built from a roster introduction (connectWithPeer) and from an
+ * inbound offer (setDescription), so the two never drift.
+ */
+export declare const attachDataChannelHandler: (epc: IRTCPeerConnection, dataChannels: IRTCDataChannel[], api: Parameters<typeof handleOpenChannel>[1]) => void;

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

@@ -0,0 +1,13 @@
+import type { MessageData } from "../../db/types";
+export interface DeleteRoomDataDependencies {
+    readonly getMessages: (roomId: string) => Promise<MessageData[]>;
+    readonly deleteRoomRecord: (roomId: string) => Promise<void>;
+    readonly deleteReceive: (merkleRootHex: string) => Promise<void>;
+    readonly deleteOutgoing: (merkleRootHex: string) => Promise<void>;
+}
+/**
+ * Await every durable room-data deletion and report only after all reachable
+ * records were attempted. `removeLocalMessage` is reducer-only; no background
+ * listener owns storage completion after this function returns.
+ */
+export declare const deleteRoomDataTerminal: (roomId: string, removeLocalMessage: (merkleRootHex: string) => void, dependencies?: DeleteRoomDataDependencies) => Promise<void>;

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

@@ -1,8 +1,9 @@
 import type { BaseQueryFn } from "@reduxjs/toolkit/query";
-import type { IRTCDataChannel, IRTCPeerConnection, RTCDisconnectFromAllRoomsParams } from "./interfaces";
+import type { IRTCDataChannel, IRTCPeerConnection, RTCDisconnectFromAllRoomsParams, DisconnectPeerTransport } from "./interfaces";
 export interface RTCDisconnectFromAllRoomsParamsExtension extends RTCDisconnectFromAllRoomsParams {
     peerConnections: IRTCPeerConnection[];
     dataChannels: IRTCDataChannel[];
+    disconnectPeer: DisconnectPeerTransport;
 }
 declare const webrtcDisconnectAllRoomsQuery: BaseQueryFn<RTCDisconnectFromAllRoomsParamsExtension, undefined>;
 export default webrtcDisconnectAllRoomsQuery;

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

@@ -1,8 +1,9 @@
 import type { BaseQueryFn } from "@reduxjs/toolkit/query";
-import type { IRTCDataChannel, IRTCPeerConnection, RTCDisconnectFromRoomParams } from "./interfaces";
+import type { IRTCDataChannel, IRTCPeerConnection, RTCDisconnectFromRoomParams, DisconnectPeerTransport } from "./interfaces";
 export interface RTCDisconnectFromRoomParamsExtension extends RTCDisconnectFromRoomParams {
     peerConnections: IRTCPeerConnection[];
     dataChannels: IRTCDataChannel[];
+    disconnectPeer: DisconnectPeerTransport;
 }
 declare const webrtcDisconnectRoomQuery: BaseQueryFn<RTCDisconnectFromRoomParamsExtension, undefined>;
 export default webrtcDisconnectRoomQuery;

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

@@ -1,8 +1,9 @@
 import type { BaseQueryFn } from "@reduxjs/toolkit/query";
-import type { IRTCDataChannel, IRTCPeerConnection, RTCDisconnectParams } from "./interfaces";
+import type { IRTCDataChannel, IRTCPeerConnection, RTCDisconnectParams, DisconnectPeerTransport } from "./interfaces";
 export interface RTCDisconnectParamsExtension extends RTCDisconnectParams {
     peerConnections: IRTCPeerConnection[];
     dataChannels: IRTCDataChannel[];
+    disconnectPeer: DisconnectPeerTransport;
 }
 declare const webrtcDisconnectQuery: BaseQueryFn<RTCDisconnectParamsExtension, undefined>;
 export default webrtcDisconnectQuery;

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

@@ -1,4 +1,6 @@
-type IceRestartTarget = Pick<RTCPeerConnection, "connectionState" | "signalingState" | "restartIce">;
+type IceRestartTarget = Pick<RTCPeerConnection, "connectionState" | "signalingState" | "restartIce"> & {
+    ensureFreshIceConfiguration?: () => Promise<boolean | void>;
+};
 export type IceCandidateRepairResult = "restarted" | "disconnected";
 /**
  * Repair a candidate-add failure without ever calling restartIce() after