@interop/was-client 0.35.0 → 0.36.0

package/dist/edv/EdvCodec.js

@@ -36,9 +36,13 @@
  * - **Inline non-JSON as a single JWE.** A `Blob`/`Uint8Array` under the size cap
  *   is encrypted as one document -- stored as a legible UTF-8 string for a
  *   text-family type (else base64) -- with the plaintext content type and the
- *   encoding carried in the document `meta`. An oversized one is
- *   rejected (large chunked encrypted blobs need the server's `chunked-streams`
- *   affordance).
+ *   encoding carried in the document `meta`. A blob over `maxBlobBytes` is
+ *   auto-routed by `add()` to the chunked-stream path instead: `encode` returns
+ *   a multi-request plan the write path executes, storing one document plus its
+ *   chunk resources over a `WasTransport` of the codec's own. That needs the
+ *   backend's `chunked-streams` affordance, checked before the first write.
+ *   Reads reassemble transparently, so `get()` returns the same `Blob` either
+ *   way.
  * - **Enforced sequence (conditional writes).** The codec sets
  *   `conditionalWrites`, so the write path pre-reads the current envelope and
  *   hands it to `encode`: an update advances `sequence` from its prior value and
@@ -64,8 +68,9 @@
 import { base64, base64urlnopad } from '@scure/base';
 import { EdvClientCore, assertDocId } from '@interop/edv-client';
 import { EMPTY_INDEX_SCHEMA, assertQueryAttributes } from '../internal/indexSchema.js';
-import { EncryptionError, IntegrityError, KeyUnwrapError, UnknownEpochError, ValidationError } from '../errors.js';
-import { readEtag } from '../internal/conditional.js';
+import { EncryptionError, IntegrityError, KeyUnwrapError, NotSupportedError, UnknownEpochError, ValidationError } from '../errors.js';
+import { readEtag, writeHeaders } from '../internal/conditional.js';
+import { WasTransport } from './WasTransport.js';
 import { isEncryptedEnvelope } from '../sync/envelope.js';
 import { resolveEpochKeys } from './epochKeys.js';
 import { didKeyResolver } from './epochCrypto.js';
@@ -73,16 +78,26 @@ import { resolveHmacKey } from './hmacKey.js';
 import { isBlob, isTextContentType, readJsonData, resolvePayload } from '../internal/content.js';
 import { DEFAULT_CONTENT_TYPE, EDV_SCHEME_VERSION, envelopeBytes } from './constants.js';
 /**
- * Default ceiling for a single-document (unchunked) encrypted binary or text
- * write, measured in raw (pre-base64) bytes. Past this a `Blob`/`Uint8Array`
- * is rejected with guidance toward the chunked-stream path. 512 KiB: the
- * envelope is stored as a JSON-family content type routed through the server's
- * in-memory JSON body parser (a ~1 MiB cap), and a binary payload inflates
- * ~33% inside the document (base64) and again ~33% in the JWE ciphertext
- * (base64url) -- ~1.78x total, so 512 KiB raw stays safely under the cap.
- * Raise `maxBlobBytes` against a server with a larger JSON body limit.
+ * Default threshold above which an encrypted binary write is routed to the
+ * chunked-stream path instead of being sealed into one document, measured in
+ * raw (pre-base64) bytes. It is a routing threshold, not a hard cap: `add()`
+ * carries a larger blob as a document plus chunk resources, which needs the
+ * backend's `chunked-streams` feature. 512 KiB: a single-document envelope is
+ * stored as a JSON-family content type routed through the server's in-memory
+ * JSON body parser (a ~1 MiB cap), and a binary payload inflates ~33% inside
+ * the document (base64) and again ~33% in the JWE ciphertext (base64url) --
+ * ~1.78x total, so 512 KiB raw stays safely under the cap. Raise
+ * `maxBlobBytes` against a server with a larger JSON body limit.
  */
 const DEFAULT_MAX_BLOB_BYTES = 512 * 1024;
+/**
+ * The `meta.encoding` discriminator a chunked binary document carries: its
+ * bytes live in the document's chunk resources, not in `content`. It is sealed
+ * inside the JWE payload (the cipher encrypts `meta` alongside `content`), so
+ * it is the AEAD-authenticated signal the read side routes on, and it keeps the
+ * decrypted document self-describing alongside `'utf-8'` and `'base64'`.
+ */
+const CHUNKED_ENCODING = 'chunked';
 /**
  * A shared strict UTF-8 decoder used to test whether a non-JSON payload is
  * valid UTF-8 (so it can be stored legibly as text rather than base64).
@@ -203,7 +218,20 @@ export class EdvCodec {
      */
     #writeEpoch;
     #contentType;
+    /**
+     * The size, in raw bytes, above which a binary write is routed to the
+     * chunked-stream path instead of being sealed into one document. A routing
+     * threshold, not a hard cap.
+     */
     #maxBlobBytes;
+    /**
+     * The size of each encrypted chunk a routed write emits, or `undefined` to
+     * take the EDV core's default (1 MiB). One chunk is one upload, so it has to
+     * stay under the backend's `maxUploadBytes`; nothing here can check that (the
+     * feature probe answers affordance tokens, not the backend's constraints), so
+     * a chunk over the limit surfaces as the server's 413.
+     */
+    #chunkSize;
     #idDerivation;
     /**
      * The EDV-over-WAS scheme version this codec binds into every envelope's
@@ -212,6 +240,12 @@ export class EdvCodec {
      * stamped with a greater version.
      */
     #version;
+    /**
+     * The id of the Space holding this codec's Collection. Needed only by the
+     * chunked-stream path, which addresses the document and its chunks through a
+     * `WasTransport` of its own.
+     */
+    #spaceId;
     /**
      * The id of the Collection this codec was built for. It is bound into the
      * Collection metadata envelope's `was.collection` on write and required to
@@ -219,6 +253,16 @@ export class EdvCodec {
      * ({@link UnknownEpochError}).
      */
     #collectionId;
+    /**
+     * The id of every epoch the descriptor lists -- held by this reader or not.
+     * Decrypt routing uses it to tell the two unroutable-envelope cases apart:
+     * an envelope kid whose epoch is listed here but matches no candidate key
+     * means this reader is not a recipient of that epoch
+     * ({@link KeyUnwrapError}); a kid whose epoch is not listed at all means the
+     * descriptor this codec was built from has never seen the epoch
+     * ({@link UnknownEpochError} -- the stale-descriptor signal).
+     */
+    #epochIds;
     /**
      * The collection's blinded-index key, or `null` where the collection
      * declares none. It blinds attribute names and values both on write (the
@@ -252,19 +296,30 @@ export class EdvCodec {
      *   into every envelope's `was.epoch`, which the decode side checks against
      *   the decrypting key's epoch unconditionally.
      * @param options.contentType {string}            stored envelope content type
-     * @param options.maxBlobBytes {number}           single-document binary cap
+     * @param options.maxBlobBytes {number}   the size above which a binary write
+     *   is routed to the chunked-stream path instead of one document
+     * @param [options.chunkSize] {number}   the size of each encrypted chunk a
+     *   routed write emits (defaults to the EDV core's 1 MiB). One chunk is one
+     *   upload, so it must stay under the backend's `maxUploadBytes`; that
+     *   constraint is not advertised through the feature probe, so it is the
+     *   caller's to respect (see `createEdvEncryption`)
      * @param options.idDerivation {string}           how `add()` mints a document
      *   id: `'random'` (classic `generateId()`) or `'content'` (derived from the
      *   JWE ciphertext, content-addressed)
      * @param [options.version] {number}   the EDV-over-WAS scheme version to bind
      *   into each envelope's `was.v` (defaults to {@link EDV_SCHEME_VERSION})
+     * @param options.spaceId {string}   the Space holding the Collection, for the
+     *   chunked-stream path's own transport
      * @param options.collectionId {string}   the Collection this codec reads and
      *   writes: bound into the Collection metadata envelope's `was.collection`
      *   (and checked on read), and it labels decrypt-routing errors
+     * @param options.epochIds {string[]}   the id of every epoch the descriptor
+     *   lists (held by this reader or not); decrypt routing checks it to tell a
+     *   not-a-recipient envelope apart from a stale-descriptor one
      * @param [options.hmac] {BlindingKey}   the collection's blinded-index key,
      *   where it declares one
      */
-    constructor({ edv, keyAgreementKey, readKeys, writeEpoch, contentType, maxBlobBytes, idDerivation, version, collectionId, hmac }) {
+    constructor({ edv, keyAgreementKey, readKeys, writeEpoch, contentType, maxBlobBytes, chunkSize, idDerivation, version, spaceId, collectionId, epochIds, hmac }) {
         this.#edv = edv;
         this.#recipients =
             edv.documentCipher.createDefaultRecipients(keyAgreementKey);
@@ -272,9 +327,12 @@ export class EdvCodec {
         this.#writeEpoch = writeEpoch;
         this.#contentType = contentType;
         this.#maxBlobBytes = maxBlobBytes;
+        this.#chunkSize = chunkSize;
         this.#idDerivation = idDerivation;
         this.#version = version ?? EDV_SCHEME_VERSION;
+        this.#spaceId = spaceId;
         this.#collectionId = collectionId;
+        this.#epochIds = new Set(epochIds);
         this.#blindingKey = hmac ?? null;
         if (this.#blindingKey !== null) {
             this.#indexing = {
@@ -379,7 +437,25 @@ export class EdvCodec {
             (this.#idDerivation === 'content'
                 ? undefined
                 : (await this.#edv.generateId()));
-        const { content, meta } = await this.#toDocument(data, contentType, docId);
+        const parts = await this.#toDocument(data, contentType, docId);
+        if (parts.kind === 'chunked') {
+            if (docId === undefined) {
+                throw new ValidationError(`Encrypted binary write of ${parts.size} bytes exceeds the ` +
+                    `single-document threshold of ${this.#maxBlobBytes} bytes, so it ` +
+                    'must be stored as a document plus chunk resources -- which a ' +
+                    "content-addressed collection (idDerivation: 'content') cannot " +
+                    'do: the document is written twice (once to reserve it, once to ' +
+                    'record the chunk count), so no single ciphertext derives its id. ' +
+                    'Store large blobs in a random-id collection, or keep the payload ' +
+                    'under the threshold.');
+            }
+            return this.#chunkedWrite({
+                id: docId,
+                stream: parts.stream,
+                meta: parts.meta
+            });
+        }
+        const { content, meta } = parts;
         // When the write path pre-read a current envelope, advance `sequence` from
         // its prior value (`encrypt({ update: true })` increments it) and pin the
         // write to the server's current ETag with `If-Match`. With no prior envelope
@@ -458,6 +534,171 @@ export class EdvCodec {
             epoch: this.#writeEpoch
         };
     }
+    /**
+     * Builds the `WasTransport` the chunked-stream paths drive, over the signed
+     * requester core supplied and this codec's own Space/Collection. The
+     * handle's memoized feature probe is passed straight through, so the
+     * transport's own affordance gates cost no extra descriptor read.
+     *
+     * @param context {CodecRequestContext}
+     * @param [documentHeaders] {Record<string, string>}   extra headers for
+     *   document writes (the `Key-Epoch` stamp the codec seam applies)
+     * @returns {WasTransport}
+     */
+    #transportFor(context, documentHeaders) {
+        return new WasTransport({
+            was: { request: input => context.request(input) },
+            spaceId: this.#spaceId,
+            collectionId: this.#collectionId,
+            contentType: this.#contentType,
+            features: context.features,
+            ...(documentHeaders !== undefined && { documentHeaders })
+        });
+    }
+    /**
+     * Refuses the operation unless the collection's backend advertises the
+     * `chunked-streams` affordance. Checked before the first write, so an
+     * unsupported server never ends up holding a document stub with no chunks.
+     *
+     * @param context {CodecRequestContext}
+     * @param what {string}   the operation, for the message
+     * @returns {Promise<void>}
+     */
+    async #assertChunkedStreams(context, what) {
+        if (await context.features.has('chunked-streams')) {
+            return;
+        }
+        // "No features" has two causes, and only one of them is about the server's
+        // capabilities: a descriptor that was read and lists no `chunked-streams`,
+        // versus a descriptor that could not be read at all (no backend descriptor
+        // endpoint, a deleted collection, or a capability that cannot read it --
+        // WAS masks unauthorized reads as 404). Name the one that applies, so a
+        // capable server whose collection is gone does not look incapable.
+        if (await context.features.descriptorAbsent()) {
+            throw new NotSupportedError(`${what} needs the collection's backend to advertise the ` +
+                `'chunked-streams' feature, but the backend descriptor could not be ` +
+                'read at all: the collection may not exist, or this capability may ' +
+                'not be able to read its descriptor. Confirm the collection and the ' +
+                'capability, then retry.');
+        }
+        throw new NotSupportedError(`${what} needs the collection's backend to advertise the ` +
+            `'chunked-streams' feature, which it does not. Store the blob in a ` +
+            'collection on a backend that supports chunked streams, or keep the ' +
+            `payload under the ${this.#maxBlobBytes}-byte single-document ` +
+            "threshold (raise it with the provider's `maxBlobBytes` where the " +
+            'server accepts a larger body).');
+    }
+    /**
+     * The plan for a binary payload over the single-document threshold: one EDV
+     * document plus its chunk resources, written by `EdvClientCore.insert({ doc,
+     * stream, transport })` over a transport built from the write context. The
+     * document id is minted before the plan is returned, so the caller can report
+     * it without waiting for the write.
+     *
+     * The `was` binding, the recipients and the write epoch are exactly the
+     * single-document path's, and `additionalProtectedParams` carries the binding
+     * into both the document envelope and every chunk's AAD. `content` stays
+     * empty: the bytes are the chunks, and `meta` records the plaintext content
+     * type plus the chunked encoding discriminator so a read reconstructs the
+     * same `Blob` a small binary read returns. `meta` is sealed inside the JWE
+     * payload, so that discriminator is what the read side routes on: a server
+     * cannot mint it, and cannot suppress it to hide the chunks either.
+     *
+     * The write is two-phase (`EdvClientCore.insert` writes the document, then
+     * streams the chunks), so a failure partway leaves a document stub whose
+     * sealed stream state is still `{ pending: true }` -- undecryptable, listed,
+     * and never re-used, since a retry mints a fresh id. The plan therefore
+     * compensates: if the document was written and the write then failed, it
+     * best-effort deletes the stub before rethrowing.
+     *
+     * @param options {object}
+     * @param options.id {string}                        the minted document id
+     * @param options.stream {ReadableStream<Uint8Array>}   the payload, as the
+     *   stream the EDV core re-chunks (never buffered whole by this codec)
+     * @param options.meta {Record<string, unknown>}     the document meta to seal
+     * @returns {ChunkedWrite}
+     */
+    #chunkedWrite({ id, stream, meta }) {
+        const was = wasParam({
+            version: this.#version,
+            resource: id,
+            epoch: this.#writeEpoch
+        });
+        return {
+            chunked: true,
+            id,
+            resourceContentType: meta.contentType,
+            // What the scheme-agnostic write path appends when it refuses this plan
+            // for a write by id: only this codec knows why the payload needs several
+            // requests, and which low-level API writes one directly.
+            guidance: 'This payload is too large for a single encrypted document, so it is ' +
+                'stored as a document plus chunk resources. Drive the write yourself ' +
+                'with `EdvClientCore.update({ doc, stream, transport })` over a ' +
+                '`WasTransport`, against a server whose backend advertises the ' +
+                "'chunked-streams' feature.",
+            execute: async (context) => {
+                await this.#assertChunkedStreams(context, 'Writing a large blob');
+                // The EDV core owns the write and swallows the responses, so the
+                // transport reports the document write it made: whether one landed at
+                // all (the cleanup decision below) and the validator the server acked
+                // it with.
+                const transport = this.#transportFor(context, writeHeaders({ epoch: this.#writeEpoch }));
+                try {
+                    await this.#edv.insert({
+                        doc: { id, content: {}, meta },
+                        stream,
+                        ...(this.#chunkSize !== undefined && {
+                            chunkSize: this.#chunkSize
+                        }),
+                        recipients: this.#recipients,
+                        keyResolver: this.#edv.keyResolver,
+                        hmac: this.#writeBlindingKey(),
+                        additionalProtectedParams: { was },
+                        transport
+                    });
+                }
+                catch (err) {
+                    throw await this.#chunkedWriteFailed({ err, id, transport });
+                }
+                const etag = transport.lastDocumentWrite?.etag;
+                return { id, ...(etag !== undefined && { etag }) };
+            }
+        };
+    }
+    /**
+     * Compensates a failed chunked write and builds the error to rethrow. The
+     * document stub is deleted only when the transport reports it actually wrote
+     * one: a write that failed before that (the id is freshly minted, so this is
+     * a server or network failure, not a collision) must not delete a resource
+     * this write never created. The delete is best effort -- it is a cleanup, and
+     * its own failure must not mask the failure that caused it -- so its outcome
+     * only shapes the message.
+     *
+     * @param options {object}
+     * @param options.err {unknown}   the failure from the chunked write
+     * @param options.id {string}     the document id the write minted
+     * @param options.transport {WasTransport}   the transport the write ran on
+     * @returns {Promise<Error>}   the error to throw, carrying `err` as its cause
+     */
+    async #chunkedWriteFailed({ err, id, transport }) {
+        if (transport.lastDocumentWrite === undefined) {
+            return err instanceof Error ? err : new Error(String(err));
+        }
+        let removed = true;
+        try {
+            await transport.deleteDocument({ id });
+        }
+        catch {
+            removed = false;
+        }
+        return new EncryptionError(`The chunked encrypted write of resource "${id}" failed partway: its ` +
+            'document was written but its chunks were not, so the stored ' +
+            'document cannot be read. ' +
+            (removed
+                ? 'The incomplete document was deleted; retry the write.'
+                : 'The incomplete document could NOT be deleted and is still ' +
+                    'stored; delete it and retry the write.'), { cause: err });
+    }
     /**
      * The blinding key a content write should index with: the collection's key
      * once the applied schema declares at least one attribute, else `undefined`
@@ -475,11 +716,89 @@ export class EdvCodec {
     /**
      * @inheritdoc
      */
-    async decode(response, expectedId) {
+    async decode(response, expectedId, context) {
         const stored = await readJsonData(response);
         const decrypted = await this.#openEnvelope({ doc: stored, expectedId });
+        // A chunked document's bytes live in its chunk resources. Both routing
+        // inputs are AEAD-authenticated, never the cleartext copies on the
+        // envelope: the `meta.encoding` discriminator sealed in the JWE payload
+        // decides that this IS a chunked document (a server cannot bolt a
+        // cleartext `stream` onto an ordinary document to mask its sealed
+        // content), and the sealed `stream.chunks` count then says how many chunks
+        // to fetch (a server cannot lower it to truncate the read). A sealed
+        // discriminator with no sealed count is an interrupted write, whose state
+        // is still `{ pending: true }`: it fails loudly rather than decoding to an
+        // empty document.
+        if (decrypted.meta?.encoding === CHUNKED_ENCODING) {
+            return this.#readChunked({
+                // Address the chunk resources by the AEAD-bound `was.resource` id, not
+                // by the envelope's cleartext `id`: a server that serves document A's
+                // authentic envelope with the cleartext id swapped to B would
+                // otherwise have the read fetch (and cleanly decrypt) B's chunks,
+                // exactly the envelope swap the `was.resource` binding exists to
+                // detect.
+                id: decrypted.resourceId,
+                chunks: decrypted.stream?.chunks,
+                meta: decrypted.meta,
+                keyId: decrypted.keyId,
+                context
+            });
+        }
         return this.#fromDocument(decrypted.content, decrypted.meta);
     }
+    /**
+     * Reassembles a chunked binary document: drives `EdvClientCore.getStream`
+     * over a transport built from the read context, buffers the decrypt stream,
+     * and returns the same `Blob` a small binary read returns.
+     *
+     * Only AEAD-authenticated inputs are trusted -- the sealed chunk count and
+     * the `was.resource` id the envelope is bound to, never the envelope's
+     * cleartext `id` -- and the decrypt uses the very key that opened the
+     * document envelope, so a chunk sealed to some other epoch fails to
+     * authenticate rather than being accepted.
+     *
+     * @param options {object}
+     * @param [options.id] {string}   the AEAD-bound resource id (= WAS resource
+     *   id, the parent of the chunk resources)
+     * @param options.chunks {unknown}   the sealed chunk count
+     * @param [options.meta] {Record<string, unknown>}   the decrypted meta
+     * @param options.keyId {string}   the id of the key that decrypted the
+     *   document envelope
+     * @param [options.context] {CodecRequestContext}   the signed-request context
+     * @returns {Promise<Blob>}
+     */
+    async #readChunked({ id, chunks, meta, keyId, context }) {
+        if (typeof chunks !== 'number') {
+            throw new EncryptionError('Cannot read this resource: it is a chunked encrypted blob whose ' +
+                'sealed stream state records no chunk count, so the write that ' +
+                'created it never completed. Re-upload the blob.');
+        }
+        if (context === undefined) {
+            throw new EncryptionError('Cannot read this resource: it is a chunked encrypted blob, whose ' +
+                'bytes live in separate chunk resources, and this caller supplied no ' +
+                'request context to fetch them with. Read it through a Resource or ' +
+                'Collection handle (`resource.get()`), which supplies one.');
+        }
+        if (id === undefined) {
+            throw new EncryptionError('Cannot read this resource: the stored chunked document binds no ' +
+                '`was.resource` id, so its chunk resources cannot be addressed. ' +
+                "Only the envelope's AEAD-bound id may address them -- the cleartext " +
+                'id on the envelope is server-controlled and could point the read at ' +
+                "another document's chunks.");
+        }
+        await this.#assertChunkedStreams(context, 'Reading a large blob');
+        const keyAgreementKey = this.#readKeys.find(key => key.id === keyId);
+        const stream = (await this.#edv.getStream({
+            doc: { id, stream: { chunks } },
+            keyAgreementKey,
+            transport: this.#transportFor(context)
+        }));
+        const contentType = typeof meta?.contentType === 'string' ? meta.contentType : undefined;
+        return streamToBlob({
+            stream,
+            ...(contentType !== undefined && { type: contentType })
+        });
+    }
     /**
      * Opens a stored envelope: asserts it IS an EDV envelope, decrypts it with
      * whichever read key its JWE recipient names, and only then verifies the
@@ -495,19 +814,20 @@ export class EdvCodec {
      *   to a resource id is refused there, and one bound to this Collection's id
      *   is required (see {@link _verifyBinding}). Set only by the
      *   Collection-level metadata read
-     * @returns {Promise<{ content?: unknown; meta?: Record<string, unknown>;
-     *   keyId: string }>}   the decrypted document
+     * @returns {Promise<object>}   the decrypted document (`content`, `meta`, the
+     *   AEAD-authenticated `stream` state where one was sealed, `keyId`, and the
+     *   AEAD-bound `resourceId` the envelope declares, where it binds one)
      */
     async #openEnvelope({ doc, expectedId, collectionSlot }) {
         this.#assertEnvelope(doc, 'read');
         const decrypted = await this.#decrypt(doc);
-        await this.#verifyBinding({
+        const resourceId = await this.#verifyBinding({
             jwe: doc.jwe,
             expectedId,
             collectionSlot,
             keyId: decrypted.keyId
         });
-        return decrypted;
+        return { ...decrypted, ...(resourceId !== undefined && { resourceId }) };
     }
     /**
      * Decrypts a stored EDV envelope, selecting which read key to use by matching
@@ -516,34 +836,53 @@ export class EdvCodec {
      * selects that epoch's key, so history stays readable.
      *
      * A stored envelope naming only recipients this reader holds no candidate
-     * key for fails fast with {@link UnknownEpochError} -- the signal that the
-     * cached Collection Description may be stale (an epoch rotation emits no
+     * key for fails fast, and which error it raises depends on whether the
+     * descriptor lists the named epoch. An epoch the descriptor lists but wraps
+     * only to other recipients raises {@link KeyUnwrapError}: this reader is
+     * not a recipient of that epoch (it never was, or it was removed and the
+     * epoch rotated), so re-reading the descriptor cannot help. That is the
+     * read axis only; it says nothing about whether the server will still
+     * serve (pull) the ciphertext. An epoch the descriptor does not list at
+     * all raises {@link UnknownEpochError} -- the signal that the cached
+     * Collection Description may be stale (an epoch rotation emits no
      * change-feed entry) and the codec must be rebuilt from a re-read
-     * descriptor. A candidate whose entry then fails to unwrap surfaces
-     * {@link KeyUnwrapError} -- the **read** axis only; it says nothing about
-     * whether the server will still serve (pull) the ciphertext.
+     * descriptor. A candidate whose entry then fails to unwrap also surfaces
+     * {@link KeyUnwrapError}.
      *
      * Also returns the `id` of the key that actually decrypted the envelope (its
      * JWE recipient `kid`), so {@link _verifyBinding} can check a `was.epoch`
      * binding against the epoch of the decrypting key.
      *
      * @param encryptedDoc {IEncryptedDocument}
-     * @returns {Promise<{ content?: unknown; meta?: Record<string, unknown>;
-     *   keyId: string }>}
+     * @returns {Promise<object>}   the decrypted document plus `keyId`
      */
     async #decrypt(encryptedDoc) {
         const kids = envelopeRecipientKids(encryptedDoc);
         const kidSet = new Set(kids);
         // Prefer the read key whose id names a recipient of this envelope; for a
         // well-formed envelope the exact match always hits. A non-empty recipient
-        // set that matches NO candidate is unroutable: the envelope was encrypted
-        // under an epoch (or key) this codec's descriptor knows nothing about, so
-        // fail fast with the stale-descriptor signal rather than burning ECDH
-        // attempts that cannot succeed. The `rest` fallback below is then reached
-        // only for a malformed envelope naming no recipient kid at all, letting a
-        // candidate surface the cipher's own typed decrypt error.
+        // set that matches NO candidate is unroutable, so fail fast rather than
+        // burning ECDH attempts that cannot succeed. Which failure it is depends
+        // on whether the descriptor lists the named epoch: an epoch key's kid is
+        // `<epoch did:key>#<fingerprint>`, so the portion before the fragment
+        // names the epoch. Listed but wrapped only to others: this reader is not
+        // a recipient of that epoch (the membership signal, KeyUnwrapError). Not
+        // listed at all: the descriptor has never seen the epoch (the
+        // stale-descriptor signal, UnknownEpochError). The `rest` fallback below
+        // is then reached only for a malformed envelope naming no recipient kid
+        // at all, letting a candidate surface the cipher's own typed decrypt
+        // error.
         const preferred = this.#readKeys.filter(key => kidSet.has(key.id));
         if (preferred.length === 0 && kids.length > 0) {
+            const listed = kids.some(kid => this.#epochIds.has(kid.split('#')[0] ?? kid));
+            if (listed) {
+                throw new KeyUnwrapError('Cannot decrypt this resource: it was encrypted under a key epoch ' +
+                    'this reader holds no key for. The epoch is on the Collection ' +
+                    'Description, but none of its recipient entries name this reader ' +
+                    '(it was never a recipient of that epoch, or it was removed and ' +
+                    'the epoch rotated). This is the read axis only -- the server ' +
+                    'may still serve the ciphertext (a separate zcap decision).');
+            }
             throw new UnknownEpochError({ collectionId: this.#collectionId, kids });
         }
         const rest = this.#readKeys.filter(key => !kidSet.has(key.id));
@@ -635,7 +974,13 @@ export class EdvCodec {
      *   Collection metadata slot
      * @param options.keyId {string}   the id of the key that decrypted, for the
      *   epoch check
-     * @returns {Promise<void>}
+     * @returns {Promise<string | undefined>}   the verified `was.resource` id the
+     *   envelope binds, or `undefined` where it binds none (a content-derived
+     *   content envelope, or the Collection metadata slot). It is the only
+     *   trustworthy resource id on a stored document -- the envelope's top-level
+     *   `id` is cleartext and server-controlled -- so a read that addresses
+     *   anything under the document's path (the chunked-stream path) must use
+     *   this one.
      */
     async #verifyBinding({ jwe, expectedId, collectionSlot, keyId }) {
         const was = parseWasHeader(jwe);
@@ -720,6 +1065,7 @@ export class EdvCodec {
                 `"${decryptedEpoch}". The server replayed it under a different ` +
                 'epoch.');
         }
+        return typeof was.resource === 'string' ? was.resource : undefined;
     }
     /**
      * @inheritdoc
@@ -850,6 +1196,13 @@ export class EdvCodec {
      * 3. Binary (any other `Blob`/`Uint8Array`) to `content = { bytes: base64 }`,
      *   `meta = { contentType, encoding: 'base64' }`.
      *
+     * A binary payload over {@link #maxBlobBytes} is not an inline document at
+     * all: it answers `kind: 'chunked'`, carrying a byte stream (plus its size,
+     * for messages) and the `meta` the chunked-stream path seals, and the caller
+     * routes the write there. The routing decision is made on the payload's size
+     * alone, so a `Blob` over the threshold is never buffered here: it is handed
+     * on as `blob.stream()`, and the EDV core re-chunks it as it reads.
+     *
      * A bare primitive is rejected (mirroring the plaintext `prepareBody`
      * contract). The binary/text detection and content-type precedence are the
      * shared `resolvePayload` rules, so the plaintext and encrypted write paths
@@ -858,25 +1211,36 @@ export class EdvCodec {
      * @param data {ResourceData}
      * @param [contentType] {string}   caller-supplied content type
      * @param [id] {string}            resource id, for the extension guess
-     * @returns {Promise<{ content: Record<string, unknown>; meta:
-     *   Record<string, unknown> }>}
+     * @returns {Promise<object>}   the inline document `{ content, meta }`, or
+     *   the `{ stream, size, meta }` of a payload to route to the chunked-stream
+     *   path
      */
     async #toDocument(data, contentType, id) {
         const payload = resolvePayload({ data, contentType, id });
         if (payload.kind === 'binary') {
+            const resolvedType = payload.contentType;
+            // Route on the size alone (`Blob.size` is synchronous), so an
+            // over-threshold blob is never read into memory here just to measure it.
+            const size = isBlob(payload.data)
+                ? payload.data.size
+                : payload.data.length;
+            if (size > this.#maxBlobBytes) {
+                // Too large for one document: route it to the chunked-stream path,
+                // where the bytes live in the document's own chunk resources. Hand it
+                // over as a stream -- a `Blob` streams itself, and bytes already in
+                // hand become a one-value stream the same way -- so the payload is not
+                // held twice while the EDV core re-chunks it.
+                return {
+                    kind: 'chunked',
+                    stream: bytesToStream(payload.data),
+                    size,
+                    meta: { contentType: resolvedType, encoding: CHUNKED_ENCODING }
+                };
+            }
+            // Under the threshold the bytes are sealed inline, so buffer them now.
             const bytes = isBlob(payload.data)
                 ? new Uint8Array(await payload.data.arrayBuffer())
                 : payload.data;
-            const resolvedType = payload.contentType;
-            if (bytes.length > this.#maxBlobBytes) {
-                throw new ValidationError(`Encrypted binary write of ${bytes.length} bytes exceeds the ` +
-                    `single-document limit of ${this.#maxBlobBytes} bytes. The codec ` +
-                    'seam is a single-request transform and cannot chunk. To store a ' +
-                    'blob this large, write it through the chunked-stream path -- ' +
-                    '`EdvClientCore.insert({ doc, stream, transport })` with a ' +
-                    '`WasTransport`, read back with `getStream` -- against a server ' +
-                    "whose backend advertises the 'chunked-streams' feature.");
-            }
             // Text-family AND valid UTF-8 to store as a legible string. The UTF-8 gate
             // guarantees the bytes survive the string round-trip exactly; anything
             // else falls through to base64, which is always byte-safe.
@@ -884,12 +1248,14 @@ export class EdvCodec {
                 const text = decodeUtf8(bytes);
                 if (text !== null) {
                     return {
+                        kind: 'inline',
                         content: { text },
                         meta: { contentType: resolvedType, encoding: 'utf-8' }
                     };
                 }
             }
             return {
+                kind: 'inline',
                 content: { bytes: base64.encode(bytes) },
                 meta: { contentType: resolvedType, encoding: 'base64' }
             };
@@ -899,6 +1265,7 @@ export class EdvCodec {
             // an absent `meta.encoding` as JSON). EDV models `content` as an object
             // record; a JSON array is also a valid encrypted value here, so widen it.
             return {
+                kind: 'inline',
                 content: data,
                 meta: { contentType: contentType ?? 'application/json' }
             };
@@ -948,6 +1315,43 @@ export class EdvCodec {
         return content;
     }
 }
+/**
+ * Presents a binary payload as the `ReadableStream`
+ * `EdvClientCore.insert({ stream })` consumes. A `Blob` streams itself; bytes
+ * already in hand are wrapped in a `Blob` and stream the same way. The encrypt
+ * stream re-chunks whatever it is fed at its own `chunkSize`, so the shape of
+ * the source stream does not affect the stored chunks.
+ *
+ * @param data {Blob | Uint8Array}
+ * @returns {ReadableStream<Uint8Array>}
+ */
+function bytesToStream(data) {
+    const blob = isBlob(data) ? data : new Blob([data]);
+    return blob.stream();
+}
+/**
+ * Drains a byte stream into one `Blob` of the given type. `Blob` does the
+ * concatenation: its parts are the chunks the stream yielded, in order.
+ *
+ * @param options {object}
+ * @param options.stream {ReadableStream<Uint8Array>}
+ * @param [options.type] {string}   the blob's content type
+ * @returns {Promise<Blob>}
+ */
+async function streamToBlob({ stream, type }) {
+    const reader = stream.getReader();
+    const parts = [];
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done) {
+            break;
+        }
+        if (value !== undefined) {
+            parts.push(value);
+        }
+    }
+    return new Blob(parts, type !== undefined ? { type } : undefined);
+}
 /**
  * Decodes bytes as strict UTF-8, returning `null` when they are not valid UTF-8
  * (so the caller can fall back to base64). Uses the shared fatal decoder.
@@ -1017,10 +1421,19 @@ const EDV_SCHEME = 'edv';
  *   defaults to `application/json`. Pass `JOSE_CONTENT_TYPE`
  *   (`application/jose+json`) against a server that registers an
  *   `application/*+json` parser.
- * @param [options.maxBlobBytes] {number}   single-document binary cap in raw
- *   bytes (default 512 KiB, sized so the encrypted envelope stays under a
+ * @param [options.maxBlobBytes] {number}   the size in raw bytes above which a
+ *   binary `add()` is routed to the chunked-stream path instead of one document
+ *   (default 512 KiB, sized so a single-document envelope stays under a
  *   server's ~1 MiB JSON body cap; raise it against a server with a larger
- *   limit)
+ *   limit). A routing threshold, not a hard cap.
+ * @param [options.chunkSize] {number}   the size of each encrypted chunk a
+ *   routed write emits, in bytes (default 1 MiB). Each chunk is one upload, so
+ *   it must stay under the backend's `maxUploadBytes` constraint (the
+ *   encrypted chunk is somewhat larger than `chunkSize`, so leave headroom).
+ *   This is not checked client-side: the shared backend probe reads the
+ *   descriptor's affordance tokens, not its `constraints`, so a chunk over the
+ *   limit is rejected by the server with a `PayloadTooLargeError` (413) and
+ *   the failed write's document stub is then cleaned up.
  * @param [options.idDerivation] {string}   how `add()` mints a document id.
  *   `'random'` (default) is the classic mutable-document model: a random
  *   `generateId()` id, updated in place via `sequence`. `'content'` derives the
@@ -1032,7 +1445,7 @@ const EDV_SCHEME = 'edv';
  *   `put(id, ...)` path is unaffected either way.
  * @returns {EncryptionProvider}
  */
-export function createEdvEncryption({ resolveKeys, contentType = DEFAULT_CONTENT_TYPE, maxBlobBytes = DEFAULT_MAX_BLOB_BYTES, idDerivation = 'random' }) {
+export function createEdvEncryption({ resolveKeys, contentType = DEFAULT_CONTENT_TYPE, maxBlobBytes = DEFAULT_MAX_BLOB_BYTES, chunkSize, idDerivation = 'random' }) {
     return {
         async codecFor({ spaceId, collectionId, scheme, encryption, keys }) {
             if (scheme !== EDV_SCHEME) {
@@ -1102,9 +1515,15 @@ export function createEdvEncryption({ resolveKeys, contentType = DEFAULT_CONTENT
                 writeEpoch: epochKeys.writeEpoch,
                 contentType,
                 maxBlobBytes,
+                ...(chunkSize !== undefined && { chunkSize }),
                 idDerivation,
                 version: descriptorVersion ?? EDV_SCHEME_VERSION,
-                collectionId
+                spaceId,
+                collectionId,
+                // Every epoch the descriptor lists, recipient of it or not, so
+                // decrypt routing can tell "not a recipient of this epoch" apart
+                // from "descriptor has never seen this epoch".
+                epochIds: encryption.epochs.map(epoch => epoch.id)
             });
         }
     };