@loro-dev/streams-crdt 0.14.0 → 0.15.0

package/README.md

@@ -180,17 +180,13 @@ Only adjust if any of these apply:
 ```ts
 import { LoroDoc } from "loro-crdt";
 import {
-  createStreamUrl,
   createLoroDocAdapter,
   StreamsCrdt,
 } from "@loro-dev/streams-crdt/loro";
 
 const doc = new LoroDoc();
 const transport = new StreamsCrdt({
-  streamUrl: createStreamUrl({
-    bucketId: "my-bucket",
-    streamId: "doc-1",
-  }),
+  streamUrl: "https://streams-api.loro.dev/ds/my-bucket/doc-1",
   auth: async () => "<gateway-jwt>",
   adapter: createLoroDocAdapter(doc),
   // Optional TTL applied when the stream is created.
@@ -305,14 +301,10 @@ import { EphemeralStore } from "loro-crdt";
 import {
   EphemeralStreamCrdt,
   EphemeralStoreAdaptor,
-  createStreamUrl,
 } from "@loro-dev/streams-crdt/loro";
 
 const store = new EphemeralStore();
-const docStreamUrl = createStreamUrl({
-  bucketId: "my-bucket",
-  streamId: "doc-1",
-});
+const docStreamUrl = "https://streams-api.loro.dev/ds/my-bucket/doc-1";
 
 const presence = new EphemeralStreamCrdt({
   streamUrl: `${docStreamUrl}?ephemeral=presence`,
@@ -357,10 +349,10 @@ sync derive from that same id:
 
 ```ts
 const roomId = "design-review-42";
-const durableStreamUrl = createStreamUrl({
-  bucketId: "my-bucket",
-  streamId: `flock-${roomId}`,
-});
+const durableStreamUrl = new URL(
+  `ds/my-bucket/${encodeURIComponent(`flock-${roomId}`)}`,
+  "https://streams-api.loro.dev/proxy/",
+).toString();
 
 const presenceStreamUrl = new URL(durableStreamUrl);
 presenceStreamUrl.searchParams.set("ephemeral", "presence");
@@ -378,6 +370,10 @@ const presenceTransport = new EphemeralStreamCrdt({
 });
 ```
 
+The `ds/...` path is relative so a gateway path prefix such as `/proxy/` is
+preserved. Validate dynamic bucket and stream segments with `isValidRillId()`
+before constructing the URL; this rejects `.`/`..` before URL normalization.
+
 `EphemeralStreamCrdt` does not create or delete the durable stream. It posts
 updates to the ephemeral URL and opens SSE on the same URL with `live=sse`.
 Ephemeral state is not persisted with the Flock document stream; it is scoped by
@@ -388,17 +384,13 @@ the URL path plus channel and is meant for current live state only.
 ```ts
 import { Flock } from "@loro-dev/flock-wasm";
 import {
-  createStreamUrl,
   createFlockAdapter,
   StreamsCrdt,
 } from "@loro-dev/streams-crdt/flock";
 
 const flock = new Flock();
 const transport = new StreamsCrdt({
-  streamUrl: createStreamUrl({
-    bucketId: "my-bucket",
-    streamId: "room-1",
-  }),
+  streamUrl: "https://streams-api.loro.dev/ds/my-bucket/room-1",
   auth: async () => "<gateway-jwt>",
   adapter: createFlockAdapter(flock),
 });
@@ -538,114 +530,432 @@ before their bytes are appended to Durable Streams. Auth stays separate:
 gateway tokens authorize HTTP requests, while document keys protect document
 bytes from the server and unauthorized readers.
 
-`payloadProtection` remains available as a deprecated alias for compatibility.
-Do not pass both `e2ee` and `payloadProtection` on the same `StreamsCrdt`
-instance.
+### E2EE at a Glance
+
+#### 1. What the application provides
+
+The application injects a `PayloadProtectionProvider`, not a raw key. At the
+streams-crdt API boundary, the provider supplies three things:
+
+- `seal()` encrypts with the current write key and a fresh nonce, then returns
+  an opaque authenticated `header` plus provider-defined `sealed` bytes.
+- `open()` parses that header, resolves the corresponding historical read key,
+  authenticates the ciphertext, and returns plaintext.
+- `maxSealOverheadBytes` declares the maximum provider-added size so
+  streams-crdt can batch updates without speculatively sealing or consuming a
+  nonce.
+
+The provider owns the audited AEAD implementation, nonce generation, sealed
+layout, opaque header schema, logical-room AAD, current write key/epoch, and
+historical key lookup. streams-crdt never receives a key directly and does not
+implement MLS, device identity, epoch state, key storage, or product policy.
+
+#### 2. What streams-crdt does
+
+streams-crdt places that provider at the common durable payload boundary:
+
+```text
+local CRDT payload
+  -> batch and freeze
+  -> provider.seal()
+  -> streams-crdt envelope and transport framing
+  -> Durable Streams
+
+Durable Streams payload
+  -> remove transport framing and parse the envelope
+  -> provider.open()
+  -> clear CRDT payload
+  -> apply to Loro or Flock
+```
+
+The same boundary covers updates, snapshots, bootstrap, catch-up, live
+SSE/long-poll, 410 recovery, and write-only appends. Frozen update retries reuse
+the same ciphertext instead of calling `seal()` and generating a second nonce.
+Protected reads authenticate before adapter apply or cursor persistence and
+fail closed on any envelope or provider error.
+
+`streamUrl` remains an opaque transport URL and is not cryptographic identity.
+The provider must bind a stable logical room identity itself when cross-room
+replay protection is required. This boundary covers only durable `StreamsCrdt`
+payloads: `EphemeralStreamCrdt` presence, awareness, cursor, selection, and
+display-name payloads are outside it.
+
+#### 3. What gets encoded
+
+Every protected update batch and snapshot uses the same envelope:
+
+```text
+protectedEnvelope =
+  "LSCE"[4]
+  || version[1]
+  || payloadKind[1]
+  || providerHeaderLength[2]
+  || reserved[2]
+  || providerHeader[H]
+  || sealed[provider-defined]
+```
+
+The fixed envelope header is 10 bytes. `providerHeader` is 1–512 bytes, so the
+prefix before `sealed` is `10 + H`, or 11–522 bytes. The provider header is
+visible but authenticated; streams-crdt does not parse it.
+
+For example, a provider using XChaCha20-Poly1305 commonly chooses this sealed
+layout:
 
-When `e2ee` is omitted, streams-crdt keeps the current plaintext
-wire format. When it is present, the transport still uses
-`application/octet-stream`, but update batches and snapshots may carry an
-encrypted envelope inside the existing length-prefixed framing.
+```text
+sealed = nonce[24] || ciphertext[plaintext.length] || authenticationTag[16]
+```
+
+The 24-byte nonce is the random 192-bit XChaCha nonce. The 16-byte tag is the
+128-bit Poly1305 authentication tag. XChaCha ciphertext has the same length as
+its plaintext, so this provider layout adds `24 + 16 = 40` bytes. This layout
+is an example, not a format imposed by streams-crdt.
+
+The two durable payload classes then differ only in their surrounding framing:
+
+```text
+update append body = u32be(protectedEnvelope.length) || protectedEnvelope
+snapshot PUT body  = protectedEnvelope
+```
+
+If `H` is the provider-header length, a direct XChaCha layout adds the following
+bytes relative to the plaintext passed to `seal()`:
+
+| Payload | Size calculation | Added bytes |
+| --- | --- | ---: |
+| Update batch | outer length `4` + envelope `10` + header `H` + nonce/tag `40` | `54 + H` |
+| Snapshot | envelope `10` + header `H` + nonce/tag `40` | `50 + H` |
+
+For a 16-byte provider header, that is 70 bytes per encrypted update append and
+66 bytes per encrypted snapshot. That provider's declared
+`maxSealOverheadBytes` must cover `H + 40`; the fixed 10-byte envelope and the
+update-only 4-byte outer length are accounted for separately by streams-crdt.
+Compression may independently change the snapshot plaintext size before
+sealing. The 40-byte streams-crdt AAD domain tag is reconstructed locally and
+authenticated, not serialized as another 40 bytes on the wire.
+
+The server can still observe the stream URL, provider header, offsets, total
+payload sizes, timing, and auth metadata. It cannot read the CRDT payload or,
+within one encrypted update batch, its update count and individual update
+sizes.
+
+### Minimal Provider Setup
 
-For the design rationale and wire format, see
-[`docs/plans/2026-04-09-streams-crdt-payload-protection-design.md`](../../docs/plans/2026-04-09-streams-crdt-payload-protection-design.md).
+The cryptographic and header helpers in this example are application
+pseudocode, not exports from `@loro-dev/streams-crdt`. An application should
+implement them with an audited AEAD library and an unambiguous binary encoding.
+The only streams-crdt API being implemented here is
+`PayloadProtectionProvider`.
 
 ```ts
-const roomKey = new Uint8Array(32); // Load this from your own key store.
-crypto.getRandomValues(roomKey);
+import {
+  PayloadProtectionError,
+  type PayloadProtectionProvider,
+} from "@loro-dev/streams-crdt/loro";
+
+// This provider belongs to one application room session and captures that
+// session's finalized write epoch and stable room AAD. Header parsing remains
+// provider-owned. frameAad() must encode its inputs unambiguously.
+const roomAad = encodeApplicationRoomIdentity(roomId);
+const provider: PayloadProtectionProvider = {
+  // header + random 24-byte nonce + 16-byte tag, conservatively bounded.
+  maxSealOverheadBytes: 256,
+
+  async seal({ plaintext, additionalData }) {
+    const header = encodeLodyHeader({
+      epoch: roomSession.writeEpoch,
+      keyId: roomSession.writeKeyId,
+    });
+    const nonce = crypto.getRandomValues(new Uint8Array(24));
+    const ciphertextAndTag = await xchacha20poly1305Seal({
+      key: roomSession.writeKey,
+      nonce,
+      plaintext,
+      aad: frameAad(roomAad, additionalData(header)),
+    });
+    return { header, sealed: concatBytes(nonce, ciphertextAndTag) };
+  },
+  async open({ sealed, header, additionalData }) {
+    const historical = decodeLodyHeader(header);
+    // Resolve from logical room + provider-owned epoch/key id.
+    const key = await roomKeys.readKey(roomId, historical);
+    if (key == null) {
+      throw new PayloadProtectionError("missing_read_key");
+    }
+    return await xchacha20poly1305Open({
+      key,
+      nonce: sealed.slice(0, 24),
+      ciphertextAndTag: sealed.slice(24),
+      aad: frameAad(roomAad, additionalData),
+    });
+  },
+};
 
 const transport = new StreamsCrdt({
-  streamUrl,
+  streamUrl: "https://streams-api.loro.dev/ds/my-bucket/doc-1",
   adapter: createLoroDocAdapter(doc),
   e2ee: {
-    // Defaults when e2ee is present:
+    provider,
+    // Defaults shown explicitly:
     readPolicy: "encrypted-only",
     writePolicy: "encrypt",
-    encryption: {
-      // Stable application identity. Prefer bucket/stream identity over a full
-      // gateway URL so proxy/host changes do not break decryption.
-      scope: { bucketId: "my-bucket", streamId: "doc-1" },
-      writeKey: { id: "room-key-v1", key: roomKey },
-      // Optional. When omitted, writeKey is also the only read key.
-      readKeys: async () => [{ id: "room-key-v1", key: roomKey }],
-    },
   },
 });
 ```
 
-Encrypted streams still use `application/octet-stream`. The transport keeps a
-plaintext length-prefix frame around each encrypted envelope, so catch-up reads
-can concatenate several appends and clients can still recover payload
-boundaries.
+### Provider Contract
 
-### E2EE Protocol Summary
+The package's exported TypeScript declarations are the source of truth. The
+relevant contract, defined in [`src/types.ts`](./src/types.ts), is equivalent
+to this abbreviated definition:
 
-E2EE wraps the existing transport framing; it does not replace it.
+```ts
+type MaybePromise<T> = T | Promise<T>;
+type PayloadProtectionKind = "update_batch" | "snapshot";
 
-Encrypted update appends use this pipeline:
+interface PayloadProtectionContext {
+  readonly protocol: "loro-streams-crdt-payload-protection";
+  readonly version: 2;
+  readonly kind: PayloadProtectionKind;
+}
+
+interface PayloadProtectionProvider {
+  readonly maxSealOverheadBytes: number;
+
+  seal(input: {
+    readonly plaintext: Uint8Array;
+    readonly context: PayloadProtectionContext;
+    readonly additionalData: (header: Uint8Array) => Uint8Array;
+  }): MaybePromise<{
+    readonly header: Uint8Array;
+    readonly sealed: Uint8Array;
+  }>;
+
+  open(input: {
+    readonly sealed: Uint8Array;
+    readonly header: Uint8Array;
+    readonly context: PayloadProtectionContext;
+    readonly additionalData: Uint8Array;
+  }): MaybePromise<Uint8Array>;
+}
+
+interface E2eeOptions {
+  readonly provider?: PayloadProtectionProvider;
+  readonly readPolicy?: "encrypted-only" | "allow-plaintext";
+  readonly writePolicy?: "encrypt" | "plaintext";
+}
+```
+
+The provider is optional only when `writePolicy` is `"plaintext"`; protected
+reads still need one to open encrypted history.
+
+The inputs have these exact meanings:
+
+| Field | Meaning |
+| --- | --- |
+| `plaintext` in `seal()` | For `update_batch`, an inner length-prefixed batch containing one or more CRDT update blobs. For `snapshot`, the adapter snapshot after optional `snapshotCodec.compress`. |
+| `context` | Stable streams-crdt protocol/version/payload-kind context. It contains no URL, bucket, stream, room, epoch, or key id. |
+| `additionalData(header)` in `seal()` | Builds the exact streams-crdt-owned AAD for the final provider header. It must be called exactly once. |
+| `header` | Provider-owned, plaintext metadata used to select an algorithm or historical key. It must be 1–512 bytes and must be authenticated. |
+| `sealed` | Provider-owned non-empty bytes, normally nonce plus ciphertext and authentication tag. |
+| `additionalData` in `open()` | The same streams-crdt-owned AAD bytes produced for that envelope at write time. |
+
+For cross-room replay protection, use keys isolated per logical room or combine
+application room AAD and streams-crdt AAD without ambiguity. For example, use
+domain tags plus length-prefixed fields; do not use plain string concatenation
+where two input pairs can produce the same bytes. `seal()` must return the exact
+header passed to `additionalData(header)`.
+
+The `sealed` layout stays provider-owned. For example, it may be a random
+192-bit XChaCha20-Poly1305 nonce followed by ciphertext and tag; streams-crdt
+does not parse the nonce or enforce an algorithm suite.
+
+`seal()` runs exactly once after a logical append is frozen for retry, so a
+retry reuses the same ciphertext. It does not define an epoch transition
+barrier. For a Lody write-epoch change, drain pending appends with
+`waitUntilSynced()`, close the old room transport, finalize the epoch change,
+then create a replacement room transport/provider. Only that room session must
+be rebuilt, not the whole repo. The replacement provider may still resolve old
+headers dynamically in `open()`.
+
+Encrypted streams still use `application/octet-stream`. The server stores
+opaque bodies and never parses the protected envelope. Update appends retain
+their outer item-length framing. Snapshot PUT bodies contain the snapshot
+envelope directly; they do not use the update append's outer item frame.
+
+### Payload Lifecycle and Framing
+
+E2EE wraps the existing transport payloads; it does not replace Durable
+Streams HTTP, CAS, offset, multipart, or live-event framing.
+
+#### Update write path
+
+One `seal()` call protects one **frozen append batch**, not one individual CRDT
+update. Before freezing an append, the transport may merge FIFO queued batches
+while the estimated encoded body remains within its 256 KiB append budget. It
+then performs this pipeline:
 
 ```text
-adapter.exportUpdates()
-  -> encodeItems(clearUpdates)
-  -> encrypt(kind = "update_batch")
-  -> encodeItems([encryptedEnvelope])
-  -> POST body
+adapter export/subscription
+  -> clearUpdates[]                         one or more opaque CRDT update blobs
+  -> encodeItems(clearUpdates)              inner update-batch plaintext
+  -> provider.seal(kind = "update_batch")  exactly once for this frozen append
+  -> protectedEnvelope
+  -> encodeItems([protectedEnvelope])       outer Durable Streams append frame
+  -> POST/CAS body
 ```
 
-Encrypted snapshots use:
+`encodeItems()` is a sequence of unsigned 32-bit big-endian length prefixes:
 
 ```text
-exportSnapshot -> snapshotCodec.compress -> encrypt(kind = "snapshot")
-decrypt(kind = "snapshot") -> snapshotCodec.decompress -> applySnapshot
+innerUpdateBatch =
+  u32be(update_1.length) || update_1
+  || u32be(update_2.length) || update_2
+  || ...
+
+protectedEnvelope =
+  fixedEnvelopeHeader || providerHeader || providerSealedBytes
+
+encryptedAppendBody =
+  u32be(protectedEnvelope.length) || protectedEnvelope
 ```
 
-Envelope v1 is:
+The provider receives `innerUpdateBatch` as `seal().plaintext`. The outer
+length prefix is added only after sealing so streams-crdt readers can recover
+the protected item from the stored append. The server still treats the whole
+append body as opaque and does not learn the number or individual sizes of the
+CRDT updates inside the batch. Once the protected append and producer sequence
+are frozen, retries reuse the same bytes and do not call `seal()` or generate
+another nonce.
+
+With `writePolicy: "plaintext"`, there is no inner encrypted batch or protected
+envelope: the append body is simply `encodeItems(clearUpdates)`.
+
+#### Update read path
+
+Bootstrap tails, catch-up responses, long-poll responses, and SSE events all
+reuse the same reverse path:
+
+```text
+Durable Streams append bytes
+  -> decodeItems(outer append frame)
+  -> detect and parse protectedEnvelope
+  -> provider.open(kind = "update_batch")
+  -> innerUpdateBatch plaintext
+  -> decodeItems(innerUpdateBatch)
+  -> clearUpdates[]
+  -> adapter.applyRemoteUpdates(clearUpdates, remoteVersion)
+```
+
+An encrypted outer item must open to one valid inner `encodeItems()` payload.
+It may expand to several CRDT update blobs before the adapter is called. Under
+`allow-plaintext`, a non-envelope outer item is passed to the adapter as one
+clear update. Under `encrypted-only`, that same item fails before adapter apply
+or cursor persistence.
+
+#### Snapshot write and read paths
+
+Snapshots use the same provider envelope but not the update batch's inner or
+outer item framing:
+
+```text
+adapter.exportSnapshot()
+  -> snapshotCodec.compress?()
+  -> provider.seal(kind = "snapshot")
+  -> protectedEnvelope
+  -> PUT snapshot body directly
+
+bootstrap snapshot part
+  -> parse protectedEnvelope
+  -> provider.open(kind = "snapshot")
+  -> snapshotCodec.decompress?()
+  -> adapter.applySnapshot()
+```
+
+The provider therefore sees the optionally compressed snapshot bytes as
+`seal().plaintext`. A selected snapshot is exported, compressed, and sealed
+once before its PUT; an HTTP-level resend of that prepared request reuses the
+same body. A later scheduled snapshot may export and seal newer state again.
+Snapshot offset headers and bootstrap multipart boundaries remain outside the
+envelope because the service must read them.
+
+#### Bootstrap, catch-up, live, and recovery
+
+All durable paths converge on the two update hooks and two snapshot hooks
+described above:
+
+| Path | Processing order |
+| --- | --- |
+| Initial bootstrap | Open/decompress/apply the snapshot when present, then open and apply the retained update tail. |
+| `sync()` / `catchup()` | Deframe and open every returned update batch before adapter apply. |
+| `join()` live SSE or long-poll | Use the same update read path for every event; there is no live-specific plaintext bypass. |
+| 410 recovery | Re-bootstrap through the same snapshot and update hooks before resuming live reads. |
+| Local join/sync writes | Merge, freeze, seal, and append through the same update write path. |
+| `appendWriteOnly()` | Uses the same frozen update write path but performs no remote read or snapshot upload. |
+| Snapshot upload | Compress, seal, and PUT through the same snapshot write path. |
+
+Protected reads complete authentication and decoding before `applySnapshot()`,
+`applyRemoteUpdates()`, local durability hooks, or remote cursor persistence.
+Any failure therefore leaves the corresponding remote cursor unadvanced.
+
+### Provider Envelope and AAD
+
+Provider envelope v2 is:
 
 ```text
 magic               4 bytes   "LSCE"
-version             1 byte    0x01
+version             1 byte    0x02
 kind                1 byte    0x01 update_batch, 0x02 snapshot
-suite               1 byte    0x01 aes_256_gcm
-key_id_len          1 byte
-nonce_len           1 byte    expected 12
-reserved            1 byte    0
-key_id              key_id_len bytes, UTF-8
-nonce               nonce_len bytes
-ciphertext_and_tag  remaining bytes
+provider_header_len 2 bytes   unsigned big-endian; 1..512
+reserved            2 bytes   both 0
+provider_header     provider_header_len bytes, opaque
+sealed              remaining bytes, provider-defined and non-empty
 ```
 
-AEAD additional authenticated data (AAD) is constructed from stable local
-context:
-
-```json
-{
-  "protocol": "loro-streams-crdt-payload-protection",
-  "version": 1,
-  "kind": "update_batch",
-  "suite": "aes_256_gcm",
-  "keyId": "room-key-v1",
-  "scope": { "bucketId": "my-bucket", "streamId": "doc-1" }
-}
+The common AAD is an unambiguous byte sequence:
+
+```text
+UTF8("loro-streams-crdt-payload-protection/v2\0")
+|| exact envelope bytes from magic through provider_header
 ```
 
-AAD is not stored as a separate field on the wire. Parts of it live in the
-envelope header; `scope` comes from the local `e2ee.encryption.scope`
-config. Keep `scope` stable and avoid full gateway URLs, otherwise old encrypted
-history may become unreadable after host or proxy changes.
+This streams-crdt-owned AAD binds protocol/version, payload kind, and the
+provider's entire opaque header. Algorithm, epoch, key-id, application room,
+and stream identity schemas are not part of the streams-crdt protocol. A
+provider that needs cross-room replay protection must capture a stable logical
+room identity and combine it unambiguously with `additionalData`, as in the
+example above. Do not use a gateway origin as room identity unless moving that
+origin is intentionally a cryptographic migration.
+
+The service does not parse the v2 envelope. It remains inside the
+application payload: append/CAS headers, offsets, multipart boundaries, and
+snapshot offsets stay outside so Durable Streams can route and retain bytes.
+
+`maxSealOverheadBytes` must be a safe integer from 0 through 4096 and must bound
+`header.length + sealed.length - plaintext.length`. The transport uses that
+bound to merge queued CRDT batches without speculative sealing or nonce use;
+actual output above the declaration fails closed.
+
+### Draft Compatibility
+
+Provider v2 is still unreleased. Ciphertext produced by earlier revisions of
+this draft branch used URL-derived AAD and is not compatible with the final
+caller-owned AAD contract; discard or recreate that draft data rather than
+adding a production dual-reader for an unpublished format.
 
 ### Mode Matrix
 
 `e2ee` supports a few distinct shapes. Choose one explicitly:
 
-| Use case | `readPolicy` | `writePolicy` | Required encryption config | Remote plaintext accepted? | Local writes sent as |
+| Use case | `readPolicy` | `writePolicy` | Required protection config | Remote plaintext accepted? | Local writes sent as |
 | --- | --- | --- | --- | --- | --- |
 | Existing plaintext stream | omitted | omitted | none | Yes | plaintext |
-| Private reader/writer | `encrypted-only` (default) | `encrypt` (default) | `scope` + `writeKey` | No | encrypted |
-| Mixed private reader/writer | `allow-plaintext` | `encrypt` | `scope` + `writeKey` | Yes | encrypted |
+| Provider private reader/writer | `encrypted-only` (default) | `encrypt` (default) | `streamUrl` + `provider` | No | provider v2 |
+| Mixed provider reader/writer | `allow-plaintext` | `encrypt` | `streamUrl` + `provider` | Yes | provider v2 |
 | Public write-only writer | `allow-plaintext` | `plaintext` | none | Yes | plaintext via `appendWriteOnly()` |
-| Encrypted reader without a write key | `encrypted-only` | `plaintext` | `scope` + `readKeys` | No | plaintext if local writes are exported |
+| Provider reader without writes | `encrypted-only` | `plaintext` | `streamUrl` + `provider` | No | plaintext if local writes are exported |
 
-There is no separate transport-level "read-only mode" in v1. The last row is
+There is no separate transport-level read-only mode. The last row is
 only appropriate when the local CRDT is treated as read-only or the caller's
 auth rejects writes. `writePolicy: "plaintext"` avoids requiring a write key; it
 does not suppress local export attempts by itself.
@@ -664,6 +974,15 @@ That also means one stream must use exactly one CRDT family:
   protection is enabled or not. The decrypted inner update bytes and snapshots
   are CRDT-specific and are not cross-compatible.
 
+The examples below use separate stream URLs and room-bound providers:
+
+```ts
+const streamUrl = "https://streams-api.loro.dev/ds/my-bucket/doc-1";
+const flockStreamUrl = "https://streams-api.loro.dev/ds/my-bucket/flock-1";
+const loroProvider = createRoomProvider("doc-1");
+const flockProvider = createRoomProvider("flock-1");
+```
+
 Protected Loro room:
 
 ```ts
@@ -678,10 +997,7 @@ const loroTransport = new StreamsCrdt({
   streamUrl,
   adapter: createLoroDocAdapter(doc),
   e2ee: {
-    encryption: {
-      scope: { bucketId: "my-bucket", streamId: "doc-1" },
-      writeKey: { id: "room-key-v1", key: roomKey },
-    },
+    provider: loroProvider,
   },
 });
 ```
@@ -697,13 +1013,10 @@ import {
 
 const flock = new Flock();
 const flockTransport = new StreamsCrdt({
-  streamUrl,
+  streamUrl: flockStreamUrl,
   adapter: createFlockAdapter(flock),
   e2ee: {
-    encryption: {
-      scope: { bucketId: "my-bucket", streamId: "room-1" },
-      writeKey: { id: "room-key-v1", key: roomKey },
-    },
+    provider: flockProvider,
   },
 });
 ```
@@ -722,12 +1035,7 @@ const privateReaderWriter = new StreamsCrdt({
   streamUrl,
   adapter: createLoroDocAdapter(doc),
   e2ee: {
-    encryption: {
-      scope: { bucketId: "my-bucket", streamId: "doc-1" },
-      writeKey: { id: "private-v1", key: roomKey },
-      // Optional. Keep old keys here during rotation.
-      readKeys: async () => [{ id: "private-v1", key: roomKey }],
-    },
+    provider,
   },
 });
 ```
@@ -745,10 +1053,7 @@ const privateReaderWriter = new StreamsCrdt({
   e2ee: {
     readPolicy: "allow-plaintext",
     writePolicy: "encrypt",
-    encryption: {
-      scope: { bucketId: "my-bucket", streamId: "doc-1" },
-      writeKey: { id: "private-v1", key: roomKey },
-    },
+    provider,
   },
 });
 ```
@@ -774,14 +1079,20 @@ const appended = await publicWriter.appendWriteOnly();
 
 - If `e2ee` is present and no policies are specified, the defaults
   are `readPolicy: "encrypted-only"` and `writePolicy: "encrypt"`.
-- `writePolicy: "encrypt"` requires `e2ee.encryption.scope` and
-  `e2ee.encryption.writeKey`.
-- Any client that needs to decrypt encrypted payloads must provide
-  `e2ee.encryption.scope` plus at least one read key. If
-  `readKeys` is omitted, the current `writeKey` is also used as the only read
-  key.
-- `payloadProtection` is a deprecated alias for `e2ee`. Passing both is an
-  error.
+- `streamUrl` is required, remains opaque, and is never parsed to invent a
+  security identity.
+- streams-crdt does not bind ciphertext to `streamUrl`. The provider/application
+  must authenticate a stable logical room identity or use keys isolated per
+  room. A provider configured for the wrong room must fail authentication.
+- `PayloadProtectionProviderConfig` (alias `E2eeProviderConfig`) is a scope-free
+  `{ provider, readPolicy?, writePolicy? }` shape suitable for a repo to forward
+  directly. Set `payloadProtectionRequired: true` once protection is enabled at
+  repo level so a missing room config throws instead of becoming plaintext.
+  This flag checks config presence only; it does not override an explicit
+  `allow-plaintext` / `plaintext` policy such as public write-only mode.
+- Lody rekey is an application-owned room-session barrier: drain, close, switch
+  the finalized write epoch, and create a new room transport. Historical reads
+  may resolve provider headers dynamically.
 - `appendWriteOnly()` is the write-only path. It only posts local CRDT batches
   that this transport observed after construction. It does not bootstrap, catch
   up, join SSE, upload snapshots, apply remote updates, or persist a remote
@@ -796,12 +1107,15 @@ const appended = await publicWriter.appendWriteOnly();
   cannot read private state should not publish full-document snapshots.
 - Protected read failures stop before `applySnapshot()`,
   `applyRemoteUpdates()`, local durability hooks, or remote cursor persistence.
-- Writers always encrypt with the current `writeKey`. Keep old keys in
-  `readKeys` until retained encrypted history and encrypted snapshots no longer
+- A recognized protected envelope never falls back to plaintext after an
+  authentication failure, unknown version/key/epoch, wrong scope/kind, or
+  tamper. Under `encrypted-only`, bytes without the envelope magic are also
+  rejected as `plaintext_forbidden`. `allow-plaintext` intentionally accepts
+  non-envelope bytes and is therefore not an encrypted-only room policy.
+- Keep historical keys until retained protected updates and snapshots no longer
   reference them.
-- Encryption adds envelope overhead. The transport enforces the 256 KB batch
-  cap against the encoded on-wire bytes, so a batch near the limit may split
-  earlier under encryption than it would in plaintext mode.
+- Provider batching uses only declared bounded overhead. It never calls
+  `seal()` while estimating a merge and validates the actual frozen output.
 
 If `e2ee` is configured and `readPolicy` is left at the default
 `"encrypted-only"`, remote plaintext updates fail with
@@ -815,18 +1129,24 @@ E2EE-related transport failures surface as
 | Reason | Meaning |
 | --- | --- |
 | `plaintext_forbidden` | A reader configured as `encrypted-only` saw plaintext data in the stream. |
-| `missing_read_key` | The envelope `keyId` does not exist in the configured `readKeys`. |
-| `decrypt_failed` | AES-GCM authentication failed. This usually means the wrong key, wrong scope, or tampered/corrupted bytes. |
-| `invalid_envelope` | The payload was not a supported streams-crdt encrypted envelope. |
+| `missing_read_key` | The provider cannot resolve its opaque header to a historical read key. |
+| `decrypt_failed` | The provider AEAD open failed. Common causes are a wrong key, wrong scope, or tampered bytes. |
+| `invalid_envelope` | The payload was not a supported streams-crdt protected envelope/version. |
 | `wrong_payload_kind` | An encrypted snapshot was used where an update batch was expected, or the reverse. |
 | `encrypt_failed` | Local write-side encryption could not proceed because the key/config/input was invalid. |
 
 Callers usually treat these as operator or configuration errors, not transient
-network failures. They are always returned as `retryable: false`.
-
-E2EE does **not** hide stream URLs, offsets, payload sizes, timing
-or auth metadata, and it does not detect a malicious server rolling back or
-forking history.
+network failures. They are always returned as `retryable: false`. The public
+`TransportError` carries only the stable `reason` and a stable redacted message;
+it never copies provider causes, key ids, or epochs into the default error path.
+
+E2EE does **not** hide stream URLs, the opaque provider header, offsets, total
+append/snapshot sizes, timing, or auth metadata. It hides the count and
+individual sizes of updates within one encrypted append batch, but it is not a
+traffic-analysis defense. It also does not by itself detect a malicious server
+rolling back or forking history. In mixed `allow-plaintext` mode, no format can
+distinguish deliberate plaintext from ciphertext whose magic was stripped; use
+`encrypted-only` for a no-downgrade room.
 
 ## Remote Cursor Store
 
@@ -870,10 +1190,7 @@ cursor advancement. The transport advances the cursor only after:
 
 ```ts
 const transport = new StreamsCrdt({
-  streamUrl: createStreamUrl({
-    bucketId: "my-bucket",
-    streamId: "doc-1",
-  }),
+  streamUrl: "https://streams-api.loro.dev/ds/my-bucket/doc-1",
   adapter: createLoroDocAdapter(doc),
   beforeRemoteCursorSave: async ({ cursor, source }) => {
     // Persist local CRDT state before cursor advances.
@@ -896,7 +1213,6 @@ when you also persist **and restore** the local CRDT state for the same stream.
 ```ts
 import { LoroDoc } from "loro-crdt";
 import {
-  createStreamUrl,
   createLoroDocAdapter,
   IndexedDbRemoteCursorStore,
   StreamsCrdt,
@@ -906,10 +1222,7 @@ import {
 const doc = (await restorePersistedDoc("doc-1")) ?? new LoroDoc();
 
 const transport = new StreamsCrdt({
-  streamUrl: createStreamUrl({
-    bucketId: "my-bucket",
-    streamId: "doc-1",
-  }),
+  streamUrl: "https://streams-api.loro.dev/ds/my-bucket/doc-1",
   auth: async () => "<gateway-jwt>",
   adapter: createLoroDocAdapter(doc),
   // Step 2: use a persistent cursor store.
@@ -991,7 +1304,6 @@ Then wire the exported hooks directly into `snapshotCodec`:
 import { LoroDoc } from "loro-crdt";
 import {
   createLoroDocAdapter,
-  createStreamUrl,
   StreamsCrdt,
 } from "@loro-dev/streams-crdt/loro";
 import {
@@ -1001,10 +1313,7 @@ import {
 
 const doc = new LoroDoc();
 const transport = new StreamsCrdt({
-  streamUrl: createStreamUrl({
-    bucketId: "my-bucket",
-    streamId: "doc-1",
-  }),
+  streamUrl: "https://streams-api.loro.dev/ds/my-bucket/doc-1",
   adapter: createLoroDocAdapter(doc),
   snapshotCodec: { compress, decompress },
 });
@@ -1099,12 +1408,18 @@ const transport = new StreamsCrdt({
 - `TransportRoomStatus` — `"joined" | "reconnecting" | "disconnected" | "error"`
 - `SnapshotCodec`, `SnapshotTransformHook` — full snapshot encode/decode hooks
 - `WriteOnlyAppendResult` — result returned by `appendWriteOnly()`
-- `E2eeError` — local error class thrown by low-level E2EE helpers before
-  conversion into `TransportError`
-- `E2eeOptions`, `E2eeKey`, `E2eeScope`, `E2eeEncryptionOptions`
-  — E2EE configuration types
-- `PayloadProtectionError`, `PayloadProtectionOptions`, `PayloadProtectionKey`,
-  `PayloadProtectionScope` — deprecated compatibility aliases
+- `E2eeError` — alias for `PayloadProtectionError`
+- `E2eeOptions`, `E2eeProvider`, `E2eeProviderConfig`, `E2eeReadPolicy`,
+  `E2eeWritePolicy` — E2EE configuration types
+- `PayloadProtectionProvider`, `PayloadProtectionProviderConfig`,
+  `PayloadProtectionOptions` — provider implementation and room configuration
+- `PayloadProtectionSealInput`, `PayloadProtectionSealResult`,
+  `PayloadProtectionOpenInput` — exact `seal()` / `open()` byte contracts
+- `PayloadProtectionContext`, `PayloadProtectionKind`,
+  `PayloadProtectionReadPolicy`, `PayloadProtectionWritePolicy` — stable
+  protocol context and policy types
+- `PayloadProtectionError`, `PayloadProtectionFailureReason` — provider and
+  transport failure classification
 - `SnapshotUploadOptions` — snapshot upload configuration
 - `RemoteCursor` — replay progress metadata
 - `RemoteCursorStore` — abstract cursor storage interface
@@ -1114,8 +1429,7 @@ const transport = new StreamsCrdt({
 - `IndexedDbRemoteCursorStore` — persistent cursor store (requires local CRDT persistence)
 - `IndexedDbRemoteCursorStoreOptions` — IndexedDB store config
 - `createInitialRemoteCursor(...)` — seed a cursor store
-- `createStreamUrl(...)` — build stream URL from bucket/stream IDs
-- `isValidBucketId(...)`, `isValidRillId(...)` — ID validation helpers
+- `isValidRillId(...)` — stream ID validation helper
 
 ### Loro Entry Point