@tavrn/e2ee 0.0.0-stage → 0.2.2

package/LICENSE

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in 
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

package/README.md

@@ -1,3 +1,270 @@
-# Temporary Holding Version
+# @tavrn/e2ee
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The client side of tavrn's end-to-end encryption ([`ENCRYPTION.md`](https://github.com/just-tavrn/tavrn-protocol/blob/main/ENCRYPTION.md)),
+shared by the web client and bots (the bot runtime [`@tavrn/bot`](../bot/README.md), [`APPLICATIONS.md`](https://github.com/just-tavrn/tavrn-protocol/blob/main/APPLICATIONS.md)
+§3). It builds on the WebAssembly core [`@tavrn/crypto`](https://github.com/just-tavrn/tavrn-crypto) and the API client
+[`@tavrn/sdk`](../sdk/README.md), and runs unchanged in browsers and in Node.js (24+). Everything that needs the DOM
+(WebAuthn ceremonies, React hooks, UI stores, IndexedDB) stays in the web client
+([tavrn-web](https://github.com/just-tavrn/tavrn-web)).
+
+Like `@tavrn/sdk`, the package ships TypeScript source (the consumer's bundler or test runner compiles it: Vite,
+Vitest, Playwright, `vite-node`); it is not compiled to JavaScript yet. License: MPL-2.0 (file-level copyleft; the
+application that uses it may have any license).
+
+## Entry points
+
+| Import | Environment | Contents |
+|---|---|---|
+| `@tavrn/e2ee` | browser and Node.js | everything below except the file store |
+| `@tavrn/e2ee/node` | Node.js only | `FileKeyStore`, `StateDirInUseError`, `STATE_FILE` |
+
+## API
+
+**WebAssembly** — `ensureCrypto(): Promise<void>` loads `@tavrn/crypto` once: `init()` in browsers (the bundler
+emits `tavrn_crypto_bg.wasm` as an asset), `initSync` with the file read from the installed package in Node.js.
+Every function of this package awaits it itself; call it before using `@tavrn/crypto` directly.
+
+**Key storage** (`keystore.ts`, `storage/`)
+
+- `interface KeyStore`: per account the device id, the master secret and named secrets, encrypted at rest under
+  the local storage key (ENCRYPTION.md §2.1). Methods: `status(account)` → `"none" | "locked" | "unlocked"`,
+  `deviceIdOf`, `resume` (open without user interaction, if the store has a persisted key), `saveMaster(account,
+  deviceId, master)`, `unlockWithMaster(account, master)` (throws `LocalKeyMismatchError`), `isUnlocked`, `lock`,
+  `wipe`, `account`, `deviceId`, `masterSecret` (a copy; zero it), `putSecret` / `getSecret` / `deleteSecret`.
+- `MemoryKeyStore`: in memory (tests, one-shot tools).
+- `FileKeyStore(dir)` (`@tavrn/e2ee/node`): a state directory (mode 0700) with one file `state.json` (mode 0600):
+  a plaintext header `{ v, account, device_id, iv, data }` and AES-256-GCM over all secrets under
+  `MasterSecret.localStorageKey(device_id)`, bound to the account by the additional data. The key is never
+  stored: `resume()` is always false and the process unlocks with the master secret on every start. Every
+  change is written atomically (temporary file, fsync, rename, directory fsync) and writes are serialized;
+  `close()` waits for them. One account per directory (`StateDirInUseError`), one process per directory.
+- The IndexedDB store of the web client (`src/crypto/store.ts` in tavrn-web, `CryptoStore implements KeyStore`) adds
+  "lock on close" (persisted non-extractable WebCrypto key or none).
+- Helpers: `withMasterSecret(store, fn)`, `withBackupKey(store, fn)`, `readJsonSecret` / `writeJsonSecret`,
+  `localStorageKey(master, deviceId)`, `localAad(account, name)`.
+
+**Account flows** (`account.ts`, ENCRYPTION.md §2.4, §3, §8, §9) — all take an `E2eeContext { api, username,
+address, deviceId, store, clientName?, keyPackages? }`, where `api` needs the `keys` and `secretStorage` routes of a
+`TavrnApi`:
+`ensureDevice` (create the MLS client, attest the device together with its share key (§3.1; a device attested
+before share keys existed publishes it once with `keys.putShareKey`), keep ≥ `KEY_PACKAGE_MIN` KeyPackages, uploading
+up to `KEY_PACKAGE_BATCH`; a device key is immutable, so when the node holds another key for the session's device
+than the local one, or a key while the store has none, the device lost its key: `device_key_lost`, nothing new is
+stored and a mismatching stored client is dropped, and the session has to sign in again as a new device), `setupAccount`, `unlockWithRecoveryKey`, `unlockWithPasskeyPrf`, `addPasskeySecret`,
+`regenerateRecoveryKey`, `resetIdentity`, `passkeyEntryIds(api)`; store-only helpers `localStatus(store, address,
+deviceId)`, `loadClient(store)` / `saveClient(store, client)` (secret `CLIENT_STATE = "mls-client"`),
+`localIdentityKey(store)`, `forgetIdentityKeepDevice(store, address)`, `wipeLocal(store, address)`;
+`localDeviceLost(ctx)` (the node lists the session's device with a key this store does not hold: no unlock helps,
+sign in again; false while locked). Errors: `E2eeError` with `code` (`recovery_key_invalid`, `recovery_key_wrong`,
+`passkey_wrong`, `no_recovery_entry`, `no_passkey_entry`, `identity_mismatch`, `rotation_devices`, `locked`,
+`already_set_up`, `device_key_lost`).
+
+**MLS session manager** (`mls.ts`, ENCRYPTION.md §4–§7, FEDERATION.md §3.5, §6, §10) — `MlsManager(deps:
+MlsDeps)` with the node API injected (`MlsApi`: `node(domain)` → `MlsNodeApi` delivery service of the hosting
+node, `keys(address)` from the user's home node, backups on the own home node; `mlsApiOf({ home, node, keys })`
+adapts `@tavrn/sdk` clients) and persistence injected (`persist`, `savePins`, `saveMeta`, `saveVerified`).
+`openMlsManager(store, { api, address, deviceId, homeDomain, onEvent?, onError?, backupDelayMs?, tabs? })` wires it to a
+`KeyStore` (secrets `PINS`, `META`, `VERIFIED`) and returns null when the device has no MLS client yet.
+Conversation ids are qualified (`qualify(domain, ulid)`, `splitQualified`). Methods:
+
+- joining: `ensureJoined(q, { canCreate, priority? })`, `processWelcomes(domain)`, `catchUp(q)`,
+  `addMissingDevices(q, members)`, `removeLeaves(q, identities, keys?)` (with `keys`, exactly the leaves with those
+  signature keys), `selfUpdate(q, { priority? })`, `hasGroup`, `epoch`. Operations that change the client run one at a
+  time; `priority` (a voice join, somebody waits) runs before the waiting background work, not before the running
+  operation. Without a local group `ensureJoined` requests the Welcomes and the GroupInfo at once. `addMissingDevices` adds a claimed KeyPackage only when its leaf carries the identity and the
+  attested key of the device it was claimed for (`keyPackageLeaf`);
+- content: `encrypt(q, content, opts?)`, `decrypt(q, envelope)` → `Decrypted`, `peek`, `encryptEphemeral`,
+  `decryptEphemeral` (replay window), `voiceKey(q)`, `contentHeader(content)`. `opts.ctx` is the message's **signed
+  context** (`{ thread_id, reply_to }`, for answers of applications also `interaction`; ENCRYPTION.md §5.2): it is
+  encrypted and signed with the content, and `decrypt` answers `{ ok: false, reason: "envelope_mismatch" }` when the
+  envelope the node delivers names another thread or reply. Before anything leaves the device (`encrypt`, thread
+  titles, `encryptEphemeral`) the ghost check runs again (`opts.members`, `opts.noBots`; without them the members of
+  the last `ghostCheck`, or every leaf's user) and refuses with `MlsError("ghost")` while a violation is not
+  acknowledged: only `acknowledgeGhosts(q, identities)`, called by the warning's button, lets content out to it
+  (`unacknowledgedGhosts(q)` lists the rest); a ghost check alone acknowledges nothing;
+- plaintext signatures: `signPlaintext(q, fields, content)`, `verifyPlaintext(q, envelope)` → `PlainStatus`;
+- identities: `verifiedDevices(address)`, `ghostCheck(q, members)` (a member whose security key changed stays a
+  ghost with the reason `key_changed` until the user acknowledges the change; no device is added automatically
+  meanwhile), `changedKeys()`, `acknowledgeKeyChange`, `identityChanged`, `forgetDevices`, `safetyNumber`,
+  `comparePayload`, `markVerified`, `removeVerification`, `acceptNewKey`, `verification(address)`,
+  `verificationStates()`;
+- trust record (`trust.ts`, ENCRYPTION.md §7): the pins, the verified contacts and the account's own devices are
+  kept as a backup blob under the backup key on the home node, so they survive a sign-out and reach new devices
+  (`restoreBackups` brings them, `flushBackups` uploads changes, `syncTrust()` merges both ways);
+  `knownOwnDevice(deviceId, key)` tells whether the account attested that device key itself (the cleanup re-attests
+  only such keys as retired);
+- share keys: `verifiedShareKeys(address)` (the share keys of a user's devices whose attestation by the device key
+  checks out), `ownShareKey()`, `encryptHistory(q, json, shareKeys)` (format 2 with sealed boxes per recipient
+  device; format 1 is not sent any more);
+- backups: `flushBackups()`, `hasPendingBackups()`, `restoreBackups()`; `dispose()`;
+- KeyPackages: `createKeyPackages(count)` (in the manager's state; `ensureDevice` tops up through it when its context
+  has `keyPackages`, see below).
+
+Events (`onEvent`): `epoch`, `rejoined`, `removed`, `added`, `key_changed`, `key_rotated`, `verification`.
+Failed background writes of the bookkeeping (`saveMeta`, which nothing waits for) go to `onError({ operation,
+error, consecutive })` (`console.error` without it); a caller that cannot run without its state stops after a few
+in a row (the bot runtime does, with `BotError("state_unwritable")`).
+
+`decrypt` failures (`Decrypted.reason`): `missing_key`, `bad_signature`, `unknown_device` (not attested, or the
+author's leaf in the group carries another key than the attested one), `replay`, `invalid`, `envelope_mismatch`,
+`locked`, and `retry`: the author's devices could not be looked up (network, the author's node, a rate limit). Results
+are cached for the session (the least recently used of at most `DECRYPT_CACHE_LIMIT` go first, keyed by message id,
+author, device and epoch with a fingerprint of the ciphertext: an envelope that names another sender under the same id
+is decrypted and checked again), except `missing_key` and `retry`, which are tried again on the next call;
+message nonces for the replay rule are kept for the last `NONCE_WINDOW` messages. Plaintext signature results are
+cached under the SHA-256 of the signed input; an envelope object passed again is reused only while its fields and
+its content are unchanged (content with nested objects is compared in its canonical form). A keys document with more than
+`KEYS_MAX_DEVICES` devices, `KEYS_MAX_RETIRED` retired devices or `KEYS_MAX_CONTINUITY` continuity statements is
+refused as a whole (`verifiedDevices` rejects with `KeysDocumentError`, kept for the lookup's lifetime).
+
+**Tabs of one browser** (`tabs.ts`, option `tabs` of `openMlsManager`) — the tabs of a browser profile share one
+IndexedDB store and so one MLS state. Without coordination every tab keeps its own copy in memory and writes it:
+the last writer wins, and a tab whose copy is stale commits on an old epoch, joins once more with the same device
+(which throws the other tab out of the group) or rejoins after an invalid commit. With `tabs: { name }`:
+
+- **One owner.** Every tab requests the Web Lock `name` (`navigator.locks`; the web client uses
+  `tavrn-mls|<home node origin>|<address>/<device id>`). The tab that holds it owns the state: it runs every
+  state-changing operation and alone writes the client state and the MLS bookkeeping.
+- **The others forward.** A tab without the lock keeps a read-only copy of the state (loaded from the store) for the
+  synchronous reads (`hasGroup`, `epoch`, `roster`, `voiceKey`, …), decryption, ephemeral events and plaintext
+  signatures: none of them changes the state (content keys are derived per epoch, ENCRYPTION.md §5). Everything that
+  does (`FORWARDED_OPERATIONS`: joins, catch-ups, commits, `encrypt` with its catch-up and rotation, history keys,
+  backups, KeyPackages, inbox keys) goes to the owner over the BroadcastChannel `name`: a request with an id, the
+  response (result or error, rebuilt as `MlsError` / `TavrnApiError`) addressed to the asking tab, 30 s timeout
+  (`MlsError("owner_unavailable")`). A decryption that misses an epoch key asks the owner to catch up or restore
+  the backup, then reads again.
+- **Following the owner.** After every write the owner announces `state`; the other tabs reload their copy before
+  they read it next (after a forwarded call returns, before an event is passed on). The owner also passes on the
+  events the views need (`epoch`, `rejoined`, `removed`); `added` stays with the owner (it shares the history once).
+- **Hand-over.** When the owner tab closes (or signs out: `dispose()`) the browser releases the lock and the next
+  waiting tab gets it. It reloads the state from the store before anything runs there, then announces itself.
+  Operations in flight are retried once on the new owner (the tab that took over runs its own ones itself); losing
+  a second owner fails the call with `owner_unavailable`. Retrying is safe because every forwarded operation can run
+  twice: joins and catch-ups are idempotent, a second commit is one more epoch, and an encryption whose result never
+  arrived was never sent. A new owner serves a request id only once.
+- **Fallback.** Without Web Locks or BroadcastChannel (or when the lock request fails) every tab works alone, as
+  before. The desktop app has one window: its tab always wins the lock, nothing else changes. Bots (one process per
+  state directory) leave `tabs` out.
+- **Not coordinated:** the pins and verified contacts (every tab reads them at start and writes them as before), and
+  the account flows that replace the whole state (identity reset, `forgetIdentityKeepDevice`, `wipeLocal`), after
+  which the web client opens a new manager anyway. Same-origin scripts can talk to the channel; they could read the
+  same store (and the open tab's memory) anyway, and the owner serves only the listed operations with checked
+  arguments.
+
+`ensureDevice` writes the client state when it tops up KeyPackages. While a manager is open, pass
+`keyPackages: (n) => manager.createKeyPackages(n)` in its context: the KeyPackages are then created in the manager's
+state (in the owning tab), and their private keys are not lost when that state is written next.
+
+**Codecs** — `content.ts` (ENCRYPTION.md §6): `encryptAttachment(file)` → ciphertext `Blob` and metadata,
+`decryptAttachment(ciphertext, meta)` (checks the SHA-256 first, `AttachmentIntegrityError`),
+`contentAttachments(content, envelope)` (only entries matching the envelope), `safeFileName`. `plaintext.ts`
+(FEDERATION.md §10.3): `signedAttachments`, `envelopeFields`, `signatureNonce`, `plainMarker`.
+
+**Encrypted files channels** — `files.ts` (FILES.md §8, WebCrypto only): `encryptFileStream(blob)` (1 MiB chunks,
+one in memory at a time) → ciphertext `Blob` and the file key, `decryptFileChunks(key, part, storedSize)` (a
+`TransformStream` for downloads, also for ranges from `ciphertextRange`), `encryptFileBytes`/`decryptFileBytes`
+(thumbnails), `encryptedSize`/`plaintextSize`; entry records: `encryptFileRecord(manager, conversation, record)`
+(under the current epoch, forwarded to the owning tab), `decryptFileRecord` (local; `withheld` when the node serves
+no record), `parseFileRecord` (binds the record to its entry, kind and ciphertext size), `entryName`/`validEntryName`
+(FILES.md §2) and `recordSamples` (records as the samples of history key checks).
+
+**History for new members** — `history.ts` (ENCRYPTION.md §7b): members hand the content keys of past epochs to a
+member who joined later, as far as the channel's policy allows (`parseHistoryPolicy`: `since_join`, `days:<n>`,
+`all`; `historyWindowStart`, `epochsToShare`). Every policy, `since_join` included, covers the epochs between the
+member's room join and its device's first leaf in the group, whose keys reach that device only through a share. `HistorySync` runs the flows of one device: `checkPending(q, policy)`
+(which pending members this device shares with, elected by `sharerDelay` so that one online device does it),
+`shareWith(q, to, joinedAtMs, policy)`, `receive(q)` (fetches the shares addressed to this device, checks every key
+against a stored message of its epoch signed by its author's attested device, keeps accepted keys and acknowledges
+the share), `noteAdded`, `dispose`. With the node capability `history.shares2` a share is **format 2**: a fresh key
+sealed to the verified share key of every device of the recipient (at most `MAX_SHARE_BOXES`), so only those devices
+can read it. Without the capability, or when a device of the recipient has no verified share key, nothing is sent
+(`onLog("share_skipped")`): format 1 (under the current epoch, readable by every leaf) is never sent, only still read.
+The window starts at the node's `since`, but never more than `MAX_JOIN_GAP_MS` (30 days) before this device first saw
+the member waiting (`boundedJoin`). The payload codec is
+`encodeHistoryPayload` / `parseHistoryPayload`, the key check `epochKeyOpens` with `pickSamples`.
+
+**History after a key reset** — also `history.ts` (capability `history.restore`): `restorePlan(q, channel)` lists the
+epochs of a requester's pre-reset range this device can share, `restore(q, to, channel)` sends them after an approved
+request, and `shareSinceReset` / `epochsSinceReset` share the epochs since the reset. The requests themselves (ask,
+approve, deny) are routes of `@tavrn/sdk` (`api.historyRequests`).
+
+**Polls** — `poll.ts` (PROTOCOL.md §7g): `parsePoll` (both kinds, the limits), `pollContent` (a composer's input to
+the content object), `pollHash` (hex SHA-256 of the JCS form without `ctx`), `pollVoteContent` (choices or answers,
+bound to the poll by `ctx.poll` and `ctx.poll_hash`), `encryptPollVote` / `signPlainPollVote` (the body of `PUT
+…/poll/vote`), `checkPollVote` (decrypts with `MlsManager.decryptPollVote` or checks the plaintext signature, then
+binds the vote to the poll: `stale` for an edited poll, `envelope_mismatch` for another poll), `tallyPoll` (one vote
+per member, the newest record; stale, late and unverifiable votes left out; per option counts and voters, date slots
+scored `2 × yes + maybe` with the best ones) and `pollVisibility` (the cooperative `results_visible` and
+`votes_visible`). Vote content is never shown as a message and a message is never a vote.
+
+```ts
+const d = await mls.decrypt(q, message);                          // the poll message
+const poll = d.ok ? parsePoll(d.content) : null;
+const hash = await pollHash(d.content);
+const vote = pollVoteContent(poll, message.id, hash, { choices: ["o2"] });
+await api.polls.vote(conversationId, message.id, await encryptPollVote(mls, q, vote));
+const { items } = await api.polls.votes(conversationId, message.id);
+const checked = await Promise.all(items.map(async (r) => ({ user: r.user, updated_at: r.updated_at, check: await checkPollVote(mls, q, r, poll, hash) })));
+const tally = tallyPoll(poll, checked, { closesAt: message.poll_closes_at });
+```
+
+**Other codecs and helpers**
+
+- `sealed.ts`: the stored form of sealed webhook posts in encrypted channels (`sealedContent`, `webhookPayload`,
+  `validWebhookName`; APPLICATIONS.md §6.1a, ENCRYPTION.md §5b). The box is opened with the epoch's inbox key inside
+  `decrypt`.
+- `commands.ts`: encrypted command arguments (`encryptCommandArgs`, `CommandArgsVerifier`, which refuses payloads for
+  another command, stale or future ones and replays; APPLICATIONS.md §5.8).
+- `components.ts`: encrypted component values and modal input (`encryptComponentValues`, `encryptModalValues`,
+  `ComponentValuesVerifier`, which refuses values made for another message, component or modal, stale or future ones
+  and replays; APPLICATIONS.md §5.10.2, §5.10.4).
+- `embeds.ts`: the embed rules of `text` content (`assertEmbeds` before encrypting, `withValidEmbeds` after
+  decrypting, `readEmbeds` for renderers; APPLICATIONS.md §6.4).
+- `cleanup.ts`: `LeafCleaner` removes ghost leaves the node allows and the client verified (ENCRYPTION.md §4.7), with an
+  election among the devices that may do it; `urgent` (content waits for the removal) skips the election wait and ends
+  the wait of a running cleanup; `noWait` (a voice join: nothing waits for the removal) ends the wait of a running
+  cleanup too, runs at once when this device is elected and otherwise returns `postponed` without committing (the
+  caller repeats the cleanup without `noWait` later); `isRunning(q)` tells whether a cleanup of a conversation runs.
+  The election counts only valid leaves of devices that may commit every removal of the run (own ghost leaves: the
+  same user; departed members: the users in `managers`, when given; deleted or unattested devices: any member) and,
+  when the caller knows it, only online ones (`online`: device identities such as the voice participants;
+  `onlineUsers`: user addresses such as the presence list). Without these lists every valid leaf counts. A cleanup
+  looks the members' devices up again only when the roster (identities and signature keys) changed since the last
+  check without findings, that check is older than `FRESH_REUSE_MS` or the node lists a pending removal of a leaf in
+  the group.
+- `identity.ts`: the current identity key and its rotation with continuity (`rotateIdentity`, `syncIdentity`,
+  `resolveIdentity`; ENCRYPTION.md §9a).
+- `search/`: the local encrypted search index (`SearchIndex` over a `SearchBackend`, `MemorySearchBackend` for tests;
+  keys from `searchKeysFromStore`; SEARCH.md). Every stored value is sealed under the local key and every lookup key
+  is an HMAC token, never an id or a word; the web client provides the IndexedDB backend.
+
+## How a bot uses it
+
+The bot runtime ([`@tavrn/bot`](../bot/README.md), `createBot()`) does, with an app token whose device id is `dev`:
+
+```ts
+import { ensureDevice, mlsApiOf, openMlsManager } from "@tavrn/e2ee";
+import { FileKeyStore } from "@tavrn/e2ee/node";
+
+const store = new FileKeyStore(process.env.TAVRN_BOT_STATE_DIR ?? "./.tavrn-state");
+const master = /* MasterSecret bytes from TAVRN_BOT_KEY or the key file (§3.1) */;
+if ((await store.status(address)) === "none") await store.saveMaster(address, dev, master);
+else await store.unlockWithMaster(address, master); // LocalKeyMismatchError: key file and state differ
+await ensureDevice({ api, username, address, deviceId: dev, store, clientName: "tavrn-bot" });
+const mls = await openMlsManager(store, { api: mlsApiOf({ home: api, node, keys }), address, deviceId: dev, homeDomain });
+await mls!.ensureJoined(conversation, { canCreate: false });
+const reply = await mls!.encrypt(conversation, { type: "text", body: "hello" });
+// on shutdown: mls.dispose(); await store.close();
+```
+
+There is no recovery key and no secret storage for bots; the key file is the backup.
+
+## Tests
+
+`pnpm --filter @tavrn/e2ee test` (part of `just test`; the WebAssembly module comes prebuilt with `@tavrn/crypto`). The suites run in Node.js
+against in-memory nodes (`test/fake-node.ts`): the session manager across several nodes, two parties end to
+end with the in-memory and the file store (setup, join, messages, ephemeral events, plaintext signatures,
+backup restore on a new device, restart from the state directory), the account flows, the `KeyStore` contract
+and the file store's guarantees (encryption at rest, permissions, atomic and serialized writes, tampering), and the
+tab coordination with an in-memory lock manager and BroadcastChannel (`test/fake-tabs.ts`: election, forwarding,
+errors, timeouts, hand-over, fallback; several tabs of one account on one state, with a control case without it).