@interop/was-client 0.17.0 → 0.19.0

package/dist/edv/EdvCodec.d.ts

@@ -9,21 +9,8 @@ import type { Json, ResourceData, ResourceMetadataCustom } from '../types.js';
  * collection handle.
  */
 export declare class EdvCodec implements ResourceCodec {
+    #private;
     readonly conditionalWrites = true;
-    private readonly _edv;
-    private readonly _writeKey;
-    /**
-     * The static JWE recipient descriptor every write encrypts to (the write
-     * key's `{ kid, alg }` header; the ephemeral `epk` is minted later inside
-     * `encrypt`). Deterministic per codec, so computed once here instead of per
-     * write.
-     */
-    private readonly _recipients;
-    private readonly _readKeys;
-    private readonly _writeEpoch?;
-    private readonly _contentType;
-    private readonly _maxBlobBytes;
-    private readonly _idDerivation;
     /**
      * @param options {object}
      * @param options.edv {EdvClientCore}             holds the cipher + key resolver
@@ -44,8 +31,13 @@ export declare class EdvCodec implements ResourceCodec {
      * @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 `1`)
+     * @param [options.hasEpochs] {boolean}   whether the collection has key
+     *   epochs, so a decoded envelope's `was.epoch` binding is checked against the
+     *   decrypting key's epoch (defaults to `false`)
      */
-    constructor({ edv, keyAgreementKey, readKeys, writeEpoch, contentType, maxBlobBytes, idDerivation }: {
+    constructor({ edv, keyAgreementKey, readKeys, writeEpoch, contentType, maxBlobBytes, idDerivation, version, hasEpochs }: {
         edv: EdvClientCore;
         keyAgreementKey: IKeyAgreementKey;
         readKeys?: IKeyAgreementKey[];
@@ -53,6 +45,8 @@ export declare class EdvCodec implements ResourceCodec {
         contentType: string;
         maxBlobBytes: number;
         idDerivation: 'random' | 'content';
+        version?: number;
+        hasEpochs?: boolean;
     });
     /**
      * @inheritdoc
@@ -69,23 +63,7 @@ export declare class EdvCodec implements ResourceCodec {
     decode(response: {
         data?: unknown;
         json(): Promise<unknown>;
-    }): Promise<Json | Blob>;
-    /**
-     * Decrypts a stored EDV envelope, selecting which read key to use by matching
-     * the envelope's JWE recipient `kid` against this reader's candidate keys
-     * (one per epoch it can unwrap). On a single-key collection there is exactly
-     * one candidate; on a multi-recipient collection a resource written under an
-     * older epoch selects that epoch's key, so history stays readable.
-     *
-     * A stored envelope naming an epoch this reader holds no key for (it was never
-     * a recipient of that epoch, or was removed and the epoch rotated) fails with
-     * {@link KeyUnwrapError} -- the **read** axis only; it says nothing about
-     * whether the server will still serve (pull) the ciphertext.
-     *
-     * @param encryptedDoc {IEncryptedDocument}
-     * @returns {Promise<{ content?: unknown; meta?: Record<string, unknown> }>}
-     */
-    private _decrypt;
+    }, expectedId?: string): Promise<Json | Blob>;
     /**
      * @inheritdoc
      *
@@ -95,8 +73,9 @@ export declare class EdvCodec implements ResourceCodec {
      * inert (metadata concurrency is the server's plaintext `metaVersion`, not the
      * envelope), so each write re-encrypts fresh with no `update`.
      */
-    encodeMeta({ custom }: {
+    encodeMeta({ custom, id: resourceId }: {
         custom: ResourceMetadataCustom;
+        id?: string;
     }): Promise<{
         custom: object;
     }>;
@@ -110,68 +89,7 @@ export declare class EdvCodec implements ResourceCodec {
      */
     decodeMeta({ custom }: {
         custom?: unknown;
-    }): Promise<ResourceMetadataCustom>;
-    /**
-     * Asserts that a document read from an encrypted collection is an EDV envelope
-     * (`{ jwe, ... }`) before it is handed to the cipher. A plaintext or foreign
-     * resource -- one written without this codec -- carries no `jwe`, which would
-     * otherwise make the EDV core throw a raw `TypeError`. Surfacing a typed
-     * `EncryptionError` keeps the fail-closed contract legible to callers.
-     *
-     * For an `update`, the envelope's `sequence` is also validated: the cipher
-     * requires a non-negative safe integer to advance from, so a foreign envelope
-     * without one (or with a malformed one) must fail here as a typed
-     * `EncryptionError` rather than as the cipher's raw `Error`.
-     *
-     * @param doc {unknown}
-     * @param context {string}   the operation in progress (`read` / `update`),
-     *   for the message
-     * @returns {asserts doc is IEncryptedDocument}
-     */
-    private _assertEnvelope;
-    /**
-     * Splits a caller value into a decrypted EDV document `{ content, meta }`,
-     * carrying the plaintext content type and inline-encoding discriminator in
-     * `meta`. Three cases:
-     *
-     * 1. JSON object/array to `content` verbatim, `meta = { contentType }` (no
-     *   `encoding`); the shape of `content` is never inspected on read, so a
-     *   caller object shaped like `{ text }` / `{ bytes }` round-trips as itself.
-     * 2. Text (`Blob`/`Uint8Array` of a text-family type that is valid UTF-8)
-     *   to `content = { text }`, `meta = { contentType, encoding: 'utf-8' }`;
-     *   stored legibly with no base64 inflation.
-     * 3. Binary (any other `Blob`/`Uint8Array`) to `content = { bytes: base64 }`,
-     *   `meta = { contentType, encoding: 'base64' }`.
-     *
-     * 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
-     * cannot drift.
-     *
-     * @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> }>}
-     */
-    private _toDocument;
-    /**
-     * Reconstructs a caller value from a decrypted EDV document, discriminating
-     * on `meta.encoding`:
-     *
-     * - `'utf-8'` to a `Blob` typed `meta.contentType` from `content.text`.
-     * - `'base64'` to a `Blob` typed `meta.contentType` from `content.bytes`.
-     * - absent (or `meta` absent) to `content` returned verbatim as JSON.
-     *
-     * A malformed inner shape (an encoding that does not match its container key's
-     * type) throws {@link EncryptionError} -- the decrypted-document analogue of
-     * `_assertEnvelope`'s outer guard.
-     *
-     * @param content {unknown}
-     * @param [meta] {Record<string, unknown>}
-     * @returns {Json | Blob}
-     */
-    private _fromDocument;
+    }, expectedId?: string): Promise<ResourceMetadataCustom>;
 }
 /**
  * The per-collection key material an EDV codec is built from.

package/dist/edv/EdvCodec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EdvCodec.d.ts","sourceRoot":"","sources":["../../src/edv/EdvCodec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"EdvCodec.d.ts","sourceRoot":"","sources":["../../src/edv/EdvCodec.ts"],"names":[],"mappings":"AAuDA,OAAO,EAAE,aAAa,EAAe,MAAM,qBAAqB,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AACxD,OAAO,KAAK,EAEV,gBAAgB,EAChB,YAAY,EAEb,MAAM,8BAA8B,CAAA;AACrC,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACd,MAAM,aAAa,CAAA;AAiBpB,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAyD7E;;;;GAIG;AACH,qBAAa,QAAS,YAAW,aAAa;;IAC5C,QAAQ,CAAC,iBAAiB,QAAO;IA4BjC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;gBACS,EACV,GAAG,EACH,eAAe,EACf,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,SAAS,EACV,EAAE;QACD,GAAG,EAAE,aAAa,CAAA;QAClB,eAAe,EAAE,gBAAgB,CAAA;QACjC,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAA;QAC7B,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE,MAAM,CAAA;QACpB,YAAY,EAAE,QAAQ,GAAG,SAAS,CAAA;QAClC,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,SAAS,CAAC,EAAE,OAAO,CAAA;KACpB;IAaD;;OAEG;IACG,MAAM,CAAC,EACX,EAAE,EACF,IAAI,EACJ,WAAW,EACX,OAAO,EACR,EAAE;QACD,EAAE,CAAC,EAAE,MAAM,CAAA;QACX,IAAI,EAAE,YAAY,CAAA;QAClB,WAAW,CAAC,EAAE,MAAM,CAAA;QACpB,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;KAC9B,GAAG,OAAO,CAAC,YAAY,CAAC;IA0GzB;;OAEG;IACG,MAAM,CACV,QAAQ,EAAE;QACR,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;KACzB,EACD,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAwLvB;;;;;;;;OAQG;IACG,UAAU,CAAC,EACf,MAAM,EACN,EAAE,EAAE,UAAU,EACf,EAAE;QACD,MAAM,EAAE,sBAAsB,CAAA;QAC9B,EAAE,CAAC,EAAE,MAAM,CAAA;KACZ,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IA0B/B;;;;;;;OAOG;IACG,UAAU,CACd,EACE,MAAM,EACP,EAAE;QACD,MAAM,CAAC,EAAE,OAAO,CAAA;KACjB,EACD,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,sBAAsB,CAAC;CAkMnC;AAoDD;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,WAAW,EACX,WAAkC,EAClC,YAAqC,EACrC,YAAuB,EACxB,EAAE;IACD,WAAW,EAAE,CAAC,GAAG,EAAE;QACjB,OAAO,EAAE,MAAM,CAAA;QACf,YAAY,EAAE,MAAM,CAAA;KACrB,KAAK,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAAA;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,YAAY,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;CACpC,GAAG,kBAAkB,CA+DrB"}

package/dist/edv/EdvCodec.js

@@ -52,7 +52,7 @@
  *   plaintext `name`/`tags`. A reader with the keys decrypts it back
  *   transparently via `meta()`.
  */
-import { base64 } from '@scure/base';
+import { base64, base64urlnopad } from '@scure/base';
 import { EdvClientCore, assertDocId } from '@interop/edv-client';
 import { EncryptionError, IntegrityError, KeyUnwrapError, ValidationError } from '../errors.js';
 import { readEtag } from '../internal/conditional.js';
@@ -116,20 +116,31 @@ function isKeyMiss(err) {
  */
 export class EdvCodec {
     conditionalWrites = true;
-    _edv;
-    _writeKey;
+    #edv;
     /**
      * The static JWE recipient descriptor every write encrypts to (the write
      * key's `{ kid, alg }` header; the ephemeral `epk` is minted later inside
      * `encrypt`). Deterministic per codec, so computed once here instead of per
      * write.
      */
-    _recipients;
-    _readKeys;
-    _writeEpoch;
-    _contentType;
-    _maxBlobBytes;
-    _idDerivation;
+    #recipients;
+    #readKeys;
+    #writeEpoch;
+    #contentType;
+    #maxBlobBytes;
+    #idDerivation;
+    /**
+     * The EDV-over-WAS scheme version this codec binds into every envelope's
+     * `was.v` protected-header parameter (the marker's `version`, `1` when
+     * absent). Read side rejects an envelope stamped with a greater version.
+     */
+    #version;
+    /**
+     * Whether this codec's collection has key epochs. When it does, an envelope's
+     * `was.epoch` binding is checked on decode against the epoch of the key that
+     * actually decrypted it.
+     */
+    #hasEpochs;
     /**
      * @param options {object}
      * @param options.edv {EdvClientCore}             holds the cipher + key resolver
@@ -150,17 +161,23 @@ export class EdvCodec {
      * @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 `1`)
+     * @param [options.hasEpochs] {boolean}   whether the collection has key
+     *   epochs, so a decoded envelope's `was.epoch` binding is checked against the
+     *   decrypting key's epoch (defaults to `false`)
      */
-    constructor({ edv, keyAgreementKey, readKeys, writeEpoch, contentType, maxBlobBytes, idDerivation }) {
-        this._edv = edv;
-        this._writeKey = keyAgreementKey;
-        this._recipients =
+    constructor({ edv, keyAgreementKey, readKeys, writeEpoch, contentType, maxBlobBytes, idDerivation, version, hasEpochs }) {
+        this.#edv = edv;
+        this.#recipients =
             edv.documentCipher.createDefaultRecipients(keyAgreementKey);
-        this._readKeys = readKeys ?? [keyAgreementKey];
-        this._writeEpoch = writeEpoch;
-        this._contentType = contentType;
-        this._maxBlobBytes = maxBlobBytes;
-        this._idDerivation = idDerivation;
+        this.#readKeys = readKeys ?? [keyAgreementKey];
+        this.#writeEpoch = writeEpoch;
+        this.#contentType = contentType;
+        this.#maxBlobBytes = maxBlobBytes;
+        this.#idDerivation = idDerivation;
+        this.#version = version ?? 1;
+        this.#hasEpochs = hasEpochs ?? false;
     }
     /**
      * @inheritdoc
@@ -184,10 +201,10 @@ export class EdvCodec {
         // mode -- leave it unset and stamp the content-derived id after encryption
         // (the id is a function of the ciphertext, which does not exist yet).
         let docId = id ??
-            (this._idDerivation === 'content'
+            (this.#idDerivation === 'content'
                 ? undefined
-                : (await this._edv.generateId()));
-        const { content, meta } = await this._toDocument(data, contentType, docId);
+                : (await this.#edv.generateId()));
+        const { content, meta } = await this.#toDocument(data, contentType, docId);
         // 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
@@ -196,10 +213,25 @@ export class EdvCodec {
         let priorDoc = null;
         if (current) {
             const read = await readJsonData(current);
-            this._assertEnvelope(read, 'update');
+            this.#assertEnvelope(read, 'update');
             priorDoc = read;
         }
-        const { documentCipher } = this._edv;
+        const { documentCipher } = this.#edv;
+        // Bind an AEAD-authenticated `was` parameter into the JWE protected header:
+        // the scheme version, the resource id when known at encrypt time (omitted
+        // for a content-derived id, which does not exist until after encryption),
+        // and the write epoch on a multi-recipient collection. A server that swaps
+        // two envelopes between ids (or replays one under a rolled-back epoch) is
+        // then detected on decrypt.
+        const was = {
+            v: this.#version
+        };
+        if (docId !== undefined) {
+            was.resource = docId;
+        }
+        if (this.#writeEpoch !== undefined) {
+            was.epoch = this.#writeEpoch;
+        }
         const encrypted = await documentCipher.encrypt({
             doc: {
                 ...(docId !== undefined && { id: docId }),
@@ -210,10 +242,11 @@ export class EdvCodec {
                 meta,
                 ...(priorDoc && { sequence: priorDoc.sequence })
             },
-            recipients: this._recipients,
-            keyResolver: this._edv.keyResolver,
+            recipients: this.#recipients,
+            keyResolver: this.#edv.keyResolver,
             hmac: undefined,
-            update: priorDoc !== null
+            update: priorDoc !== null,
+            additionalProtectedParams: { was }
         });
         if (docId === undefined) {
             // Encrypt-then-stamp: the id lives in the cleartext envelope, outside the
@@ -225,7 +258,7 @@ export class EdvCodec {
         return {
             id: docId,
             body: envelopeBytes(encrypted),
-            contentType: this._contentType,
+            contentType: this.#contentType,
             // Surface the plaintext content type (the server-opaque envelope type stays
             // `contentType`) so `add()` reports the real resource type.
             resourceContentType: meta.contentType,
@@ -245,17 +278,22 @@ export class EdvCodec {
             // Stamp the key epoch this write encrypted under (the `currentEpoch`), so
             // the server records it and a reader can pick the epoch key. Absent on a
             // single-key collection.
-            ...(this._writeEpoch !== undefined && { epoch: this._writeEpoch })
+            ...(this.#writeEpoch !== undefined && { epoch: this.#writeEpoch })
         };
     }
     /**
      * @inheritdoc
      */
-    async decode(response) {
+    async decode(response, expectedId) {
         const encryptedDoc = await readJsonData(response);
-        this._assertEnvelope(encryptedDoc, 'read');
-        const decrypted = await this._decrypt(encryptedDoc);
-        return this._fromDocument(decrypted.content, decrypted.meta);
+        this.#assertEnvelope(encryptedDoc, 'read');
+        const decrypted = await this.#decrypt(encryptedDoc);
+        await this.#verifyBinding({
+            jwe: encryptedDoc.jwe,
+            expectedId,
+            keyId: decrypted.keyId
+        });
+        return this.#fromDocument(decrypted.content, decrypted.meta);
     }
     /**
      * Decrypts a stored EDV envelope, selecting which read key to use by matching
@@ -269,10 +307,15 @@ export class EdvCodec {
      * {@link KeyUnwrapError} -- the **read** axis only; it says nothing about
      * whether the server will still serve (pull) the ciphertext.
      *
+     * 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> }>}
+     * @returns {Promise<{ content?: unknown; meta?: Record<string, unknown>;
+     *   keyId?: string }>}
      */
-    async _decrypt(encryptedDoc) {
+    async #decrypt(encryptedDoc) {
         const recipients = encryptedDoc.jwe.recipients ?? [];
         const kids = new Set(recipients
             .map(recipient => recipient.header?.kid)
@@ -284,14 +327,15 @@ export class EdvCodec {
         // exact-match partition is empty even though a candidate can still unwrap it.
         // For a well-formed epoch envelope the exact match always hits, so `rest` is
         // normally unreached.
-        const preferred = this._readKeys.filter(key => kids.has(key.id));
-        const rest = this._readKeys.filter(key => !kids.has(key.id));
+        const preferred = this.#readKeys.filter(key => kids.has(key.id));
+        const rest = this.#readKeys.filter(key => !kids.has(key.id));
         for (const keyAgreementKey of [...preferred, ...rest]) {
             try {
-                return await this._edv.documentCipher.decrypt({
+                const decrypted = await this.#edv.documentCipher.decrypt({
                     encryptedDoc,
                     keyAgreementKey
                 });
+                return { ...decrypted, keyId: keyAgreementKey.id };
             }
             catch (err) {
                 if (isKeyMiss(err)) {
@@ -318,6 +362,77 @@ export class EdvCodec {
             'collection and the epoch was rotated). This is the read axis only -- ' +
             'the server may still serve the ciphertext (a separate zcap decision).');
     }
+    /**
+     * Verifies the AEAD-authenticated `was` binding on a successfully-decrypted
+     * envelope (spec "Request Body Integrity"'s envelope half). Decrypt success
+     * proves the protected header authentic, so this runs only after a decrypt
+     * succeeds. Enforces, in order:
+     *
+     * - No `was` parameter at all: a legacy envelope, accepted unchanged (this
+     *   client wrote it before the binding existed, or a foreign EDV writer did).
+     * - `was.v` greater than this codec's scheme version: a future-scheme envelope
+     *   this client does not implement -- {@link EncryptionError}.
+     * - `was.resource` present and the expected id known: a mismatch is a server-side
+     *   swap of two resources' envelopes -- {@link IntegrityError}.
+     * - `was` present but `resource` absent (a content-derived write) and the expected
+     *   id known: the envelope's ciphertext must re-derive to the expected id
+     *   ({@link EdvDocumentCipher.deriveId}); a mismatch means the envelope was
+     *   copied under a different id -- {@link IntegrityError}. This check is NEVER
+     *   applied to an envelope with no `was` at all (a legacy random-id envelope
+     *   would fail it wrongly).
+     * - On a collection with epochs, `was.epoch` present: it must equal the epoch
+     *   (the `did:key` before the `#`) of the key that actually decrypted -- a
+     *   mismatch is a replay under a different epoch's key -- {@link IntegrityError}.
+     *
+     * @param options {object}
+     * @param options.jwe {unknown}   the envelope's JWE (its `protected` header is
+     *   parsed for `was`)
+     * @param [options.expectedId] {string}   the resource id the read targeted
+     * @param [options.keyId] {string}   the id of the key that decrypted, for the
+     *   epoch check
+     * @returns {Promise<void>}
+     */
+    async #verifyBinding({ jwe, expectedId, keyId }) {
+        const was = parseWasHeader(jwe);
+        if (was === undefined) {
+            // Legacy envelope (no `was`): accept unchanged for back-compat.
+            return;
+        }
+        if (typeof was.v === 'number' && was.v > this.#version) {
+            throw new EncryptionError(`Cannot decrypt this resource: its envelope is stamped with ` +
+                `EDV-over-WAS scheme version ${was.v}, which this client (version ` +
+                `${this.#version}) does not implement. Upgrade the client.`);
+        }
+        if (typeof was.resource === 'string') {
+            if (expectedId !== undefined && was.resource !== expectedId) {
+                throw new IntegrityError(`Cannot decrypt this resource: the stored envelope is bound to a ` +
+                    `different resource id ("${was.resource}") than the one requested ` +
+                    `("${expectedId}"). The server swapped two resources' envelopes.`);
+            }
+        }
+        else if (expectedId !== undefined) {
+            // Content-derived write (no `resource`): the id is a function of the
+            // ciphertext, so re-derive and compare.
+            const { documentCipher } = this.#edv;
+            const derived = await documentCipher.deriveId({
+                jwe: jwe
+            });
+            if (derived !== expectedId) {
+                throw new IntegrityError(`Cannot decrypt this resource: its content-derived id ("${derived}") ` +
+                    `does not match the requested id ("${expectedId}"). The server ` +
+                    'served this envelope under an id it was not written for.');
+            }
+        }
+        if (this.#hasEpochs && typeof was.epoch === 'string' && keyId) {
+            const decryptedEpoch = keyId.split('#')[0];
+            if (decryptedEpoch !== was.epoch) {
+                throw new IntegrityError(`Cannot decrypt this resource: its envelope is bound to key epoch ` +
+                    `"${was.epoch}" but was decrypted with a key from epoch ` +
+                    `"${decryptedEpoch}". The server replayed it under a different ` +
+                    'epoch.');
+            }
+        }
+    }
     /**
      * @inheritdoc
      *
@@ -327,18 +442,28 @@ export class EdvCodec {
      * inert (metadata concurrency is the server's plaintext `metaVersion`, not the
      * envelope), so each write re-encrypts fresh with no `update`.
      */
-    async encodeMeta({ custom }) {
-        const { documentCipher } = this._edv;
+    async encodeMeta({ custom, id: resourceId }) {
+        const { documentCipher } = this.#edv;
         // The document needs an EDV id (the cipher asserts one on decrypt). It is
         // opaque to the server -- carried inside the un-decryptable envelope -- and
         // minted fresh each write, since the metadata envelope is never updated in
         // place (concurrency is the server's plaintext `metaVersion`, Decision 3).
-        const id = (await this._edv.generateId());
+        const id = (await this.#edv.generateId());
+        // Bind the `was` parameter to the RESOURCE id (not the metadata envelope's
+        // own random EDV id), so a server-side swap of two resources' metadata is
+        // AEAD-detected on decode. The metadata envelope always knows the resource
+        // id at encrypt time, so `resource` is always present here (never content-
+        // derived) and it carries no `epoch`.
+        const was = { v: this.#version };
+        if (resourceId !== undefined) {
+            was.resource = resourceId;
+        }
         const encrypted = await documentCipher.encrypt({
             doc: { id, content: custom },
-            recipients: this._recipients,
-            keyResolver: this._edv.keyResolver,
-            hmac: undefined
+            recipients: this.#recipients,
+            keyResolver: this.#edv.keyResolver,
+            hmac: undefined,
+            additionalProtectedParams: { was }
         });
         return { custom: encrypted };
     }
@@ -350,12 +475,18 @@ export class EdvCodec {
      * present value must be an EDV envelope (else {@link EncryptionError}, the
      * `_assertEnvelope` guard), so a foreign plaintext `custom` fails closed.
      */
-    async decodeMeta({ custom }) {
+    async decodeMeta({ custom }, expectedId) {
         if (custom === undefined || custom === null) {
             return {};
         }
-        this._assertEnvelope(custom, 'read');
-        const decrypted = await this._decrypt(custom);
+        this.#assertEnvelope(custom, 'read');
+        const encryptedDoc = custom;
+        const decrypted = await this.#decrypt(encryptedDoc);
+        await this.#verifyBinding({
+            jwe: encryptedDoc.jwe,
+            expectedId,
+            keyId: decrypted.keyId
+        });
         return (decrypted.content ?? {});
     }
     /**
@@ -375,7 +506,7 @@ export class EdvCodec {
      *   for the message
      * @returns {asserts doc is IEncryptedDocument}
      */
-    _assertEnvelope(doc, context) {
+    #assertEnvelope(doc, context) {
         const jwe = doc !== null && typeof doc === 'object'
             ? doc.jwe
             : undefined;
@@ -422,16 +553,16 @@ export class EdvCodec {
      * @returns {Promise<{ content: Record<string, unknown>; meta:
      *   Record<string, unknown> }>}
      */
-    async _toDocument(data, contentType, id) {
+    async #toDocument(data, contentType, id) {
         const payload = resolvePayload({ data, contentType, id });
         if (payload.kind === 'binary') {
             const bytes = isBlob(payload.data)
                 ? new Uint8Array(await payload.data.arrayBuffer())
                 : payload.data;
             const resolvedType = payload.contentType;
-            if (bytes.length > this._maxBlobBytes) {
+            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 ` +
+                    `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 ' +
@@ -483,7 +614,7 @@ export class EdvCodec {
      * @param [meta] {Record<string, unknown>}
      * @returns {Json | Blob}
      */
-    _fromDocument(content, meta) {
+    #fromDocument(content, meta) {
         const encoding = meta?.encoding;
         const contentType = typeof meta?.contentType === 'string' ? meta.contentType : undefined;
         if (encoding === 'utf-8') {
@@ -522,6 +653,34 @@ function decodeUtf8(bytes) {
         return null;
     }
 }
+/**
+ * Parses the `was` binding out of a JWE's protected header. The header is
+ * base64url (no padding) JSON; a successful decrypt has already proven it
+ * authentic, so this parse is trusted. Returns the `was` object, or `undefined`
+ * when the header is absent/unparseable or carries no `was` member (a legacy
+ * envelope that predates the binding).
+ *
+ * @param jwe {unknown}
+ * @returns {Record<string, unknown> | undefined}
+ */
+function parseWasHeader(jwe) {
+    const protectedHeader = jwe?.protected;
+    if (typeof protectedHeader !== 'string') {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(new TextDecoder().decode(base64urlnopad.decode(protectedHeader)));
+    }
+    catch {
+        return undefined;
+    }
+    const was = parsed?.was;
+    if (was === null || typeof was !== 'object') {
+        return undefined;
+    }
+    return was;
+}
 /**
  * The EDV scheme tag this provider handles (matches the Collection marker).
  */
@@ -569,6 +728,14 @@ export function createEdvEncryption({ resolveKeys, contentType = DEFAULT_CONTENT
             if (scheme !== EDV_SCHEME) {
                 return null;
             }
+            // Refuse a marker from a future scheme version: this client does not
+            // implement it, and silently operating on it could mis-handle the data.
+            const markerVersion = encryption?.version;
+            if (typeof markerVersion === 'number' && markerVersion > 1) {
+                throw new EncryptionError(`Collection ${spaceId}/${collectionId} declares EDV-over-WAS scheme ` +
+                    `version ${markerVersion}, which this client (version 1) does not ` +
+                    'implement. Upgrade the client.');
+            }
             // Prefer override-supplied keys; otherwise consult the keystore.
             const resolved = keys ??
                 (await resolveKeys({ spaceId, collectionId }));
@@ -609,7 +776,9 @@ export function createEdvEncryption({ resolveKeys, contentType = DEFAULT_CONTENT
                 writeEpoch,
                 contentType,
                 maxBlobBytes,
-                idDerivation
+                idDerivation,
+                version: markerVersion ?? 1,
+                hasEpochs: !!(encryption?.epochs && encryption.epochs.length > 0)
             });
         }
     };