p2party 0.14.3 → 0.14.10

package/README.md

@@ -9,7 +9,8 @@
 Protocol-v4 end-to-end encryption and reliable file transfer over a WebRTC
 room mesh.
 
-Apache-2.0 · [LICENSE.md](LICENSE.md)
+Apache-2.0 · [License](LICENSE.md) · [Getting started](docs/getting-started.md) ·
+[Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
 
 > Status: protocol v4 is an intentional wire break — v3 peers and persisted v3
 > crypto rows are not resumed. The current code has not completed an
@@ -33,14 +34,23 @@ Apache-2.0 · [LICENSE.md](LICENSE.md)
   decoy slots can hide a message's exact payload length within its transfer.
 - Each outbound message has its own transfer identity and data channel, a
   cancellable handle, authenticated receipts, selective retransmission, and
-  reconnect resume.
+  reconnect and sender-reload recovery from a bounded durable outbox.
 - Text and files up to the enforced 10 GiB application limit are supported.
   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`.
@@ -81,7 +91,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 +202,62 @@ 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`.
+
+Prepared sends now survive sender reloads in the same browser storage and
+identity. Pending state and retry/cancel APIs are described in
+[durable transfer recovery](docs/getting-started.md). A failed `handle.done`
+reports the outcome of that attempt; it does not mean its pending data was
+removed. The outbox retains prepared sends for up to 24 hours and cannot recover
+an upload whose preparation never finished or whose browser storage was erased.
+Current measured recovery results and remaining compatibility limits are in
+[the browser report](docs/e2e/README.md).
+
 ## 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,11 @@ 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.10` is a local release candidate.** This work does not publish npm
+> packages or CDN assets. The snippet names the candidate's intended release
+> path; use the generated local bundle until that version is published.
+
+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 +810,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.3/p2party.min.js"
-  integrity="sha384-dwBCnd3gj0k9HpDetSDOtYhv/CkADQs5h4mz+dI7hdYY1wWQpgvtiOGF4GUrnbqR"
+  src="https://cdn.p2party.com/@0.14.10/p2party.min.js"
+  integrity="sha384-z5PjsRDKjtPcQ9JhEwkPyr/7zthzQgjjh6pSTdjTmhZrwVhhhFS/KhRkGtmJwqJX"
   crossorigin="anonymous"
 ></script>
 
@@ -665,15 +842,15 @@ connect directly to each other.
 The three published objects:
 
 ```text
-https://cdn.p2party.com/@0.14.3/p2party.min.js     UMD bundle -> window.p2party
-https://cdn.p2party.com/@0.14.3/db.worker.js       IndexedDB/OPFS worker
-https://cdn.p2party.com/@0.14.3/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-iZfBJVoMgpK1+s2shZQucC0OUSBaX4eHMTjHj4NqzGApUodsP9T16+EHgyDKTVQP`.
 
 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 +865,66 @@ same release bytes before calling `connect()`:
 import p2party from "p2party";
 
 p2party.setWasmSourceUrl(
-  new URL("/vendor/p2party-0.14.3/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.3/libcrypto.wasm
-curl -O https://cdn.p2party.com/@0.14.3/libcrypto.provenance.json
+curl --compressed -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.
+
+New CDN uploads gzip all three objects; WASM keeps `Content-Type:
+application/wasm` and uses `Content-Encoding: gzip`. Browsers decode it before
+SRI verification, and `curl --compressed` saves those same decoded bytes for
+the checks below. Existing raw WASM objects remain untouched when their decoded
+content matches; enabling compression never overwrites a published version.
+Upload preparation compresses the validated artifacts already in `lib/`; it
+does not replace them from a local development crypto build.
+
 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.3 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 +953,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/THIRD_PARTY_NOTICES.md

@@ -68,7 +68,7 @@ SOFTWARE.
 
 ## Emscripten-generated runtime
 
-The WebAssembly and JavaScript glue are built with Emscripten 6.0.2.
+The WebAssembly and JavaScript glue are built with Emscripten 6.0.9.
 
 Verbatim upstream license:
 
@@ -416,11 +416,6 @@ The browser bundle and/or installed runtime dependency graph includes:
 - `redux-thunk` 3.1.0 — Copyright (c) 2015-present Dan Abramov
 - `reselect` 5.1.1 — Copyright (c) 2015-2018 Reselect Contributors
 - `immer` 11.1.15 — Copyright (c) 2017 Michel Weststrate
-- `class-validator` 0.15.1 — Copyright (c) 2015-2020 TypeStack
-- `validator` 13.15.23 — Copyright (c) 2018 Chris O'Hara
-  `<cohara87@gmail.com>`
-- `libphonenumber-js` 1.12.27 — Copyright (c) 2016 @catamphetamine
-  `<purecatamphetamine@gmail.com>`
 
 Each component above is MIT-licensed. Verbatim grant and disclaimer:
 
@@ -456,3 +451,35 @@ Permission to use, copy, modify, and/or distribute this software for any purpose
 
 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 ```
+
+## Emscripten TypeScript declarations
+
+The module-scoped `EmscriptenModule` and factory types are adapted from
+`@types/emscripten` 1.41.5 in DefinitelyTyped. All inherited LibCrypto members
+are retained; unrelated global declarations are not included.
+
+Verbatim upstream license:
+
+```text
+MIT License
+
+Copyright (c) Microsoft Corporation.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE
+```

package/docs/getting-started.md

@@ -109,6 +109,14 @@ bytes are deliberately absent from the public policy, Redux, persistent room
 records, and logs. PIN mode adds CPace authentication to the identity and
 ML-KEM handshake; it does not replace identity possession.
 
+The SDK retries an unexpectedly closed signaling socket with bounded backoff.
+Let that controller own recovery: do not call `connect()` on every disconnected
+render or browser focus event. Call it for initial admission and a deliberate
+retry, such as entering a corrected PIN. Terminal PIN or policy failures stay
+visible and do not trigger automatic peer discovery or transport retries.
+A fresh connection request from the other peer can retry that peer's failed
+edge; the existing PIN-attempt throttle still applies.
+
 Scheduled timing cover is wired as of 0.14: a policy may pin `coverMode:
 "scheduled"` with 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 data is
@@ -117,8 +125,10 @@ their live transport wiring is not complete.
 
 ## Send, cancel, and read
 
-Wait until the room has peers before sending. Each logical send has a random
-transfer ID and opens a per-message data channel on every eligible peer edge.
+Wait until the room has known recipient identities before sending. Each logical
+send has a random transfer ID. Immediate mode opens a per-message data channel
+on each eligible edge; scheduled mode places its chunks into the existing
+fixed-cadence cover lanes.
 
 ```ts
 const handle = p2party.sendMessage("hello room", "chat", room.id);
@@ -147,8 +157,97 @@ void cancel; // Remove when a UI event uses it.
 
 `sendMessage()` returns a `MessageTransferHandle`, not a promise. `done`
 settles after all started peer sends and cleanup and reports ordered per-peer
-outcomes. A peer may be delivered, failed during setup/transfer, or skipped
-because it is disconnected, unauthenticated, or the transfer was cancelled.
+outcomes for that attempt. A peer may be delivered, failed during setup/transfer,
+or skipped because it is disconnected, unauthenticated, or the transfer was
+cancelled. A rejected attempt can still have a durable pending transfer: do not
+label it delivered, or assume that its resend source was discarded.
+
+The sender publishes its outbox record only after every staged chunk, the
+Merkle tree, and its local message copy have committed. A reload before that
+point cannot resume preparation; select the original file again. After
+publication, a reload or an exhausted reconnect budget retains the original
+transfer ID, Merkle root and staged bytes for retry. Nothing is rehashed or
+randomly repadded on a resumed send.
+
+```ts
+import type { PendingMessage } from "p2party";
+
+const pending: PendingMessage[] = await p2party.listPendingMessages(room.id);
+for (const message of pending) {
+  console.log(message.filename, message.phase, message.remainingRecipients);
+}
+
+// Use a deliberate retry button. It may take the room's scheduled delivery
+// time to settle; leave cancellation available while this promise is pending.
+try {
+  const attempts = await p2party.resumePendingMessages(room.id);
+  for (const attempt of attempts) console.table(attempt.outcomes);
+} catch (error) {
+  // AggregateError.errors contains failed attempts; their pending records stay
+  // available unless explicitly cancelled or expired.
+  console.error(error);
+}
+
+// Exact logical-send cancellation also works after the original handle was
+// lost to a reload. It fences queued writes before removing retained staging.
+if (pending[0])
+  await p2party.cancelPendingMessage(room.id, pending[0].transferId);
+```
+
+Authenticated-peer events trigger a serialized retry pass, including a bounded
+claim after an old tab's lease expires. A failed pass does not start an endless
+retry timer. Explicit retry requires verified signaling and a matching
+currently authenticated recipient; it never calls `connect()`, prompts for a
+passkey, or supplies a PIN. A PIN room must first be admitted with the user's
+current in-memory PIN. PIN and policy failures remain terminal until a deliberate
+authentication retry.
+
+The immutable outbox binds the sender's public key and durable identity
+revision, room capability and canonical policy, channel, and recipient public
+keys. Session peer IDs may change. Only one tab can own a transfer's 30-second
+lease at a time; it renews every 10 seconds. A stale tab cannot publish queued
+writes or renew a replacement owner's lease. Terminal signaling refusal stops
+its current owners, and switching identity invalidates the old outbox.
+
+Confirmed recipients are recorded separately and never retried. A recipient's
+explicit cancellation also ends retries to that recipient without cancelling
+other recipients. Immediate retries rebuild the have-set from authenticated
+receipt replay, so older receivers that discarded a closed channel's partial
+can still recover. Scheduled retries preserve the receipt bitmap and send
+missing chunks plus at most one already-received real chunk as a completion
+probe. The fixed cover cadence and lane count remain unchanged.
+
+Retention and admission have explicit limits:
+
+- Published pending transfers expire 24 hours after publication. Active owners
+  are protected while they run; a completed recipient is never reported as a
+  new delivery merely because staging remains.
+- Interrupted preparation expires after one hour. Its `phase` remains
+  `"staging"`; an expired `retryAfter` means its owner is gone, not that the
+  unfinished file can resume.
+- At most 32 pending transfers and 64 recipients per transfer are admitted.
+  Their aggregate storage reservation is capped at 12 GiB and charges padded
+  cells, metadata, proofs and the sender's local copy. Browser quota can impose
+  a smaller limit than the 10 GiB per-message protocol maximum. Admission
+  refuses excess work rather than evicting another pending send.
+- Incomplete received transfers expire after 24 hours without local receive
+  activity. Cleanup uses the device's activity clock, not the sender's message
+  timestamp. It protects active writes, completed messages and sender copies,
+  checks the room/receive owner, and fences writes queued before cancellation.
+
+Storage sweeps run when pending transfers are listed or an authentication event
+checks for resumable work. Maintenance runs immediately on the first check,
+then at most once every 30 seconds, and defers while receive queues are busy.
+Committed expiry also removes the old room view and retires its mapped receive
+key, preserving newer receives and connection generations.
+Cancelling or deleting a message removes its pending
+outbox; leaving a room discards that room's pending work. Successful completion
+removes resend staging while retaining completed local history.
+
+The outbox reuses the already-staged message bytes in browser storage; it is
+not a new encryption-at-rest guarantee for files or message history. It stores
+no PIN, passkey assertion, plaintext ratchet key or message key. A resumed send
+derives fresh message encryption state from the currently authenticated edge.
 
 For an inbound message, take `merkleRootHex` (and, if needed, `sha512Hex`) from
 the room's exported `messages` state:
@@ -174,6 +273,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: