@interop/was-client 0.34.0 → 0.35.1

package/dist/edv/EdvCodec.d.ts

@@ -1,6 +1,7 @@
 import { EdvClientCore } from '@interop/edv-client';
 import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
-import type { EncodedWrite, EncryptionProvider, ResourceCodec, ResponseLike } from '../codec.js';
+import type { CodecIndexing, EncodedWrite, EncryptionProvider, ResourceCodec, ResponseLike } from '../codec.js';
+import type { BlindingKey } from './hmacKey.js';
 import type { Json, ResourceData, ResourceMetadataCustom } from '../types.js';
 /**
  * A {@link ResourceCodec} that encrypts on write and decrypts on read using an
@@ -30,9 +31,16 @@ export declare class EdvCodec implements ResourceCodec {
      *   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.collectionId] {string}   labels decrypt-routing errors
+     * @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 }: {
+    constructor({ edv, keyAgreementKey, readKeys, writeEpoch, contentType, maxBlobBytes, idDerivation, version, collectionId, epochIds, hmac }: {
         edv: EdvClientCore;
         keyAgreementKey: IKeyAgreementKey;
         readKeys: IKeyAgreementKey[];
@@ -41,8 +49,20 @@ export declare class EdvCodec implements ResourceCodec {
         maxBlobBytes: number;
         idDerivation: 'random' | 'content';
         version?: number;
-        collectionId?: string;
+        collectionId: string;
+        epochIds: string[];
+        hmac?: BlindingKey | null;
     });
+    /**
+     * The collection's blinded-index key, or `null` where it declares none.
+     *
+     * @returns {BlindingKey | null}
+     */
+    get blindingKey(): BlindingKey | null;
+    /**
+     * @inheritdoc
+     */
+    get indexing(): CodecIndexing | undefined;
     /**
      * @inheritdoc
      */
@@ -70,6 +90,7 @@ export declare class EdvCodec implements ResourceCodec {
         id?: string;
     }): Promise<{
         custom: object;
+        epoch: string;
     }>;
     /**
      * @inheritdoc
@@ -78,6 +99,11 @@ export declare class EdvCodec implements ResourceCodec {
      * absent `custom` (no metadata written yet, or cleared) decodes to `{}`; a
      * present value must be an EDV envelope (else {@link EncryptionError}, the
      * `_assertEnvelope` guard), so a foreign plaintext `custom` fails closed.
+     *
+     * An omitted `expectedId` means the Collection-level metadata slot (a
+     * Resource metadata read always passes its resource id), so an envelope bound
+     * to a resource is refused there as a server-side swap, and one that does not
+     * bind this Collection's own id is refused as an envelope of some other slot.
      */
     decodeMeta({ custom }: {
         custom?: unknown;
@@ -89,6 +115,14 @@ export declare class EdvCodec implements ResourceCodec {
 export interface EdvKeys {
     keyAgreementKey: IKeyAgreementKey;
     keyResolver: IKeyResolver;
+    /**
+     * The collection's blinded-index key, for a keystore that custodies the HMAC
+     * key directly rather than reading it off the descriptor. An explicitly
+     * supplied key wins over unwrapping the descriptor's `hmac` member; omit it
+     * to let the descriptor decide (and to get `null` when the collection
+     * declares no blinded index at all).
+     */
+    hmac?: BlindingKey;
 }
 /**
  * Builds an {@link EncryptionProvider} for the `edv` scheme: a pure **keystore**

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

@@ -1 +1 @@
-{"version":3,"file":"EdvCodec.d.ts","sourceRoot":"","sources":["../../src/edv/EdvCodec.ts"],"names":[],"mappings":"AA2DA,OAAO,EAAE,aAAa,EAAe,MAAM,qBAAqB,CAAA;AAChE,OAAO,KAAK,EAEV,gBAAgB,EAChB,YAAY,EAEb,MAAM,8BAA8B,CAAA;AACrC,OAAO,KAAK,EACV,YAAY,EACZ,kBAAkB,EAClB,aAAa,EACb,YAAY,EACb,MAAM,aAAa,CAAA;AAkBpB,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AA8H7E;;;;GAIG;AACH,qBAAa,QAAS,YAAW,aAAa;;IAC5C,QAAQ,CAAC,iBAAiB,QAAO;IAiCjC;;;;;;;;;;;;;;;;;;;;;OAqBG;gBACS,EACV,GAAG,EACH,eAAe,EACf,QAAQ,EACR,UAAU,EACV,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,OAAO,EACP,YAAY,EACb,EAAE;QACD,GAAG,EAAE,aAAa,CAAA;QAClB,eAAe,EAAE,gBAAgB,CAAA;QACjC,QAAQ,EAAE,gBAAgB,EAAE,CAAA;QAC5B,UAAU,EAAE,MAAM,CAAA;QAClB,WAAW,EAAE,MAAM,CAAA;QACnB,YAAY,EAAE,MAAM,CAAA;QACpB,YAAY,EAAE,QAAQ,GAAG,SAAS,CAAA;QAClC,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,YAAY,CAAC,EAAE,MAAM,CAAA;KACtB;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,YAAY,EACtB,UAAU,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IAgOvB;;;;;;;;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;IA4B/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;CA4LnC;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,CAyErB"}
+{"version":3,"file":"EdvCodec.d.ts","sourceRoot":"","sources":["../../src/edv/EdvCodec.ts"],"names":[],"mappings":"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"}

package/dist/edv/EdvCodec.js

@@ -54,15 +54,22 @@
  *   encrypted into an EDV Document envelope with the same `documentCipher` used
  *   for content and stored opaquely under `/meta`; the server never sees
  *   plaintext `name`/`tags`. A reader with the keys decrypts it back
- *   transparently via `meta()`.
+ *   transparently via `meta()`. The Collection-level `/meta` surface
+ *   (`Collection.meta()` / `setMeta()`) runs through the same pair, with no
+ *   resource id to bind: its envelope binds the collection id
+ *   (`was.collection`) instead, and the decode side refuses both a
+ *   resource-bound envelope served into that slot and a collection-bound one
+ *   served into a resource's.
  */
 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 { isEncryptedEnvelope } from '../sync/envelope.js';
 import { resolveEpochKeys } from './epochKeys.js';
 import { didKeyResolver } from './epochCrypto.js';
+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';
 /**
@@ -95,21 +102,26 @@ const UTF8_DECODER = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
 const HEADER_DECODER = new TextDecoder();
 /**
  * Builds the AEAD-bound `was` protected-header parameter: the scheme version
- * and key epoch always, and the resource id when it is known at encrypt time
- * (absent for a content-derived id, which does not exist until after
- * encryption). The one shape both the content and the metadata write paths
- * bind.
+ * and key epoch always, and then exactly one slot marker -- the resource id
+ * when it is known at encrypt time (absent for a content-derived id, which
+ * does not exist until after encryption), or the collection id for the
+ * Collection metadata envelope, which belongs to no resource. The one shape
+ * both the content and the metadata write paths bind.
  *
  * @param options {object}
  * @param options.version {number}   the EDV-over-WAS scheme version
  * @param [options.resource] {string}   the resource id the envelope is bound to
+ * @param [options.collection] {string}   the collection id the envelope is
+ *   bound to (the Collection metadata slot only, never alongside `resource`)
  * @param [options.epoch] {string}   the key epoch the write encrypts under
- * @returns {{ v: number, resource?: string, epoch?: string }}
+ * @returns {{ v: number, resource?: string, collection?: string,
+ *   epoch?: string }}
  */
-function wasParam({ version, resource, epoch }) {
+function wasParam({ version, resource, collection, epoch }) {
     return {
         v: version,
         ...(resource !== undefined && { resource }),
+        ...(collection !== undefined && { collection }),
         ...(epoch !== undefined && { epoch })
     };
 }
@@ -201,10 +213,41 @@ export class EdvCodec {
      */
     #version;
     /**
-     * Labels decrypt-routing errors ({@link UnknownEpochError}); the codec is
-     * otherwise collection-agnostic.
+     * 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
+     * match on read, and it labels decrypt-routing errors
+     * ({@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
+     * `indexed` entries an envelope carries) and on query, so equal plaintext
+     * yields equal tokens and the server can match without learning either.
+     */
+    #blindingKey;
+    /**
+     * The collection's persisted index schema, as last applied through
+     * {@link indexing}. Empty until the schema is loaded (at codec resolution) or
+     * a `declareIndex` installs one -- and while it is empty the write seam emits
+     * no `indexed` entries, since there is nothing declared to index.
+     */
+    #schema = EMPTY_INDEX_SCHEMA;
+    /**
+     * The scheme-agnostic search capability handed to the handle layer, present
+     * exactly when this collection declares a blinding key.
+     */
+    #indexing;
     /**
      * @param options {object}
      * @param options.edv {EdvClientCore}             holds the cipher + key resolver
@@ -225,9 +268,16 @@ export class EdvCodec {
      *   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.collectionId] {string}   labels decrypt-routing errors
+     * @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 }) {
+    constructor({ edv, keyAgreementKey, readKeys, writeEpoch, contentType, maxBlobBytes, idDerivation, version, collectionId, epochIds, hmac }) {
         this.#edv = edv;
         this.#recipients =
             edv.documentCipher.createDefaultRecipients(keyAgreementKey);
@@ -237,7 +287,82 @@ export class EdvCodec {
         this.#maxBlobBytes = maxBlobBytes;
         this.#idDerivation = idDerivation;
         this.#version = version ?? EDV_SCHEME_VERSION;
-        this.#collectionId = collectionId ?? '(unknown)';
+        this.#collectionId = collectionId;
+        this.#epochIds = new Set(epochIds);
+        this.#blindingKey = hmac ?? null;
+        if (this.#blindingKey !== null) {
+            this.#indexing = {
+                applySchema: (schema) => this.#applySchema(schema),
+                schema: () => this.#schema,
+                buildQuery: (input) => this.#buildQuery(input)
+            };
+        }
+    }
+    /**
+     * The collection's blinded-index key, or `null` where it declares none.
+     *
+     * @returns {BlindingKey | null}
+     */
+    get blindingKey() {
+        return this.#blindingKey;
+    }
+    /**
+     * @inheritdoc
+     */
+    get indexing() {
+        return this.#indexing;
+    }
+    /**
+     * Installs the persisted schema: records it, then registers each declared
+     * attribute with the EDV core, whose index helper is what actually blinds
+     * attributes on write and builds query terms. Registration is idempotent, so
+     * re-applying the same schema (or a superset of it) is safe.
+     *
+     * @param schema {IndexSchema}
+     * @returns {void}
+     */
+    #applySchema(schema) {
+        this.#schema = schema;
+        for (const entry of schema.indexes) {
+            this.#edv.ensureIndex({
+                attribute: entry.attribute,
+                unique: entry.unique === true
+            });
+        }
+    }
+    /**
+     * Blinds a caller's search terms with the collection's blinding key. Refuses
+     * an attribute the persisted schema does not declare (see
+     * `assertQueryAttributes`), and refuses a query that blinded to no terms at
+     * all -- the residual footgun the name check cannot see, e.g. a compound
+     * index queried by something other than a leading prefix of its members.
+     *
+     * @param input {object}
+     * @param [input.equals] {object | object[]}
+     * @param [input.has] {string | string[]}
+     * @returns {Promise<BlindedQuery>}
+     */
+    async #buildQuery({ equals, has }) {
+        const hmac = this.#blindingKey;
+        if (hmac === null) {
+            throw new EncryptionError(`Collection ${this.#collectionId} declares no blinded-index key, so ` +
+                'its contents cannot be searched.');
+        }
+        assertQueryAttributes({ schema: this.#schema, equals, has });
+        const query = (await this.#edv.indexHelper.buildQuery({
+            hmac,
+            equals,
+            has
+        }));
+        const termless = (query.equals?.every(term => Object.keys(term).length === 0) ?? false) ||
+            query.has?.length === 0;
+        if (termless) {
+            throw new ValidationError('This search blinded to no index terms, so it would match nothing. ' +
+                'A compound index can only be queried by a leading prefix of its ' +
+                "attributes; check the collection's declared indexes with " +
+                'indexes().');
+        }
+        return query;
     }
     /**
      * @inheritdoc
@@ -303,7 +428,11 @@ export class EdvCodec {
             },
             recipients: this.#recipients,
             keyResolver: this.#edv.keyResolver,
-            hmac: undefined,
+            // Blind the declared attributes into the envelope's cleartext `indexed`
+            // entries, so the server can match a search without decrypting anything.
+            // Absent a blinding key or a declared attribute there is nothing to
+            // index, and passing no hmac carries any prior entries through verbatim.
+            hmac: this.#writeBlindingKey(),
             update: priorDoc !== null,
             additionalProtectedParams: { was }
         });
@@ -343,12 +472,26 @@ export class EdvCodec {
             epoch: this.#writeEpoch
         };
     }
+    /**
+     * The blinding key a content write should index with: the collection's key
+     * once the applied schema declares at least one attribute, else `undefined`
+     * (the cipher then computes no `indexed` entries and passes any already
+     * stored on the prior envelope through unchanged).
+     *
+     * @returns {BlindingKey | undefined}
+     */
+    #writeBlindingKey() {
+        if (this.#blindingKey === null || this.#schema.indexes.length === 0) {
+            return undefined;
+        }
+        return this.#blindingKey;
+    }
     /**
      * @inheritdoc
      */
     async decode(response, expectedId) {
         const stored = await readJsonData(response);
-        const decrypted = await this.#openEnvelope(stored, expectedId);
+        const decrypted = await this.#openEnvelope({ doc: stored, expectedId });
         return this.#fromDocument(decrypted.content, decrypted.meta);
     }
     /**
@@ -358,17 +501,24 @@ export class EdvCodec {
      * protected header authentic, so the order is load-bearing). The one opening
      * shared by {@link decode} and {@link decodeMeta}.
      *
-     * @param doc {unknown}   the stored document read from the server
-     * @param [expectedId] {string}   the resource id the read targeted
+     * @param options {object}
+     * @param options.doc {unknown}   the stored document read from the server
+     * @param [options.expectedId] {string}   the resource id the read targeted
+     * @param [options.collectionSlot] {boolean}   the read addressed the
+     *   Collection metadata slot, which belongs to no resource: an envelope bound
+     *   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
      */
-    async #openEnvelope(doc, expectedId) {
+    async #openEnvelope({ doc, expectedId, collectionSlot }) {
         this.#assertEnvelope(doc, 'read');
         const decrypted = await this.#decrypt(doc);
         await this.#verifyBinding({
             jwe: doc.jwe,
             expectedId,
+            collectionSlot,
             keyId: decrypted.keyId
         });
         return decrypted;
@@ -380,12 +530,18 @@ 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`
@@ -400,14 +556,28 @@ export class EdvCodec {
         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));
@@ -457,12 +627,34 @@ export class EdvCodec {
      *   envelope stamps its scheme version) -- {@link EncryptionError}. Greater
      *   than this codec's scheme version: a future-scheme envelope this client
      *   does not implement -- {@link EncryptionError}.
+     * Then the slot markers, which declare positively which of the profile's
+     * slots the envelope was written for -- `was.resource` a resource slot,
+     * `was.collection` the Collection metadata slot, neither a content-derived
+     * content envelope. A read of the Collection metadata slot
+     * (`collectionSlot`) enforces:
+     *
+     * - `was.resource` present: refused outright -- a resource's envelope was
+     *   served in the Collection's metadata slot, which belongs to no resource --
+     *   {@link IntegrityError}.
+     * - `was.collection` missing or not a string: refused -- the envelope belongs
+     *   to some other slot, notably a content-derived content envelope, whose
+     *   member set is otherwise identical -- {@link IntegrityError}.
+     * - `was.collection` not this codec's collection id: one Collection's
+     *   metadata served as another's -- {@link IntegrityError}.
+     *
+     * A read of a resource slot (content or resource metadata) enforces:
+     *
+     * - `was.collection` present: refused before any id comparison -- the
+     *   Collection's metadata envelope was served in a resource slot --
+     *   {@link IntegrityError}.
      * - `was.resource` present and the expected id known: a mismatch is a server-side
      *   swap of two resources' envelopes -- {@link IntegrityError}.
      * - `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}.
+     *
+     * Finally, unconditionally:
      * - `was.epoch` missing or not a string: refused like a missing `was` --
      *   {@link EncryptionError}. Present, it must equal the epoch (the `did:key`
      *   before the `#`) of the key that actually decrypted -- a mismatch is a
@@ -473,11 +665,13 @@ export class EdvCodec {
      * @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.collectionSlot] {boolean}   the read addressed the
+     *   Collection metadata slot
      * @param options.keyId {string}   the id of the key that decrypted, for the
      *   epoch check
      * @returns {Promise<void>}
      */
-    async #verifyBinding({ jwe, expectedId, keyId }) {
+    async #verifyBinding({ jwe, expectedId, collectionSlot, keyId }) {
         const was = parseWasHeader(jwe);
         if (was === undefined) {
             throw new EncryptionError('Cannot decrypt this resource: its envelope carries no `was` binding ' +
@@ -496,24 +690,55 @@ export class EdvCodec {
                 `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.`);
+        if (collectionSlot) {
+            if (typeof was.resource === 'string') {
+                throw new IntegrityError(`Cannot decrypt this Collection's metadata: the stored envelope is ` +
+                    `bound to resource "${was.resource}", but the Collection metadata ` +
+                    "slot belongs to no resource. The server swapped a resource's " +
+                    "metadata envelope into the Collection's metadata slot.");
+            }
+            if (typeof was.collection !== 'string') {
+                throw new IntegrityError(`Cannot decrypt this Collection's metadata: the stored envelope ` +
+                    'binds no `was.collection`, so it was written for some other slot ' +
+                    '(a content envelope, whose binding is otherwise identical). The ' +
+                    "server served a foreign envelope in the Collection's metadata slot.");
+            }
+            if (was.collection !== this.#collectionId) {
+                throw new IntegrityError(`Cannot decrypt this Collection's metadata: the stored envelope is ` +
+                    `bound to collection "${was.collection}", not to the requested ` +
+                    `collection ("${this.#collectionId}"). The server served one ` +
+                    "Collection's metadata as another's.");
             }
         }
-        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.');
+        else {
+            // A resource slot (content or resource metadata). The Collection's own
+            // metadata envelope has no business here, whatever id it names, so it is
+            // refused before any resource-id comparison.
+            if (was.collection !== undefined) {
+                throw new IntegrityError(`Cannot decrypt this resource: the stored envelope is bound to ` +
+                    `collection "${String(was.collection)}", but a resource's slot ` +
+                    'belongs to no collection binding. The server served the ' +
+                    "Collection's own metadata envelope in a resource's slot.");
+            }
+            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 (typeof was.epoch !== 'string') {
@@ -548,23 +773,39 @@ export class EdvCodec {
         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). It seals to the current epoch key like every write,
-        // so it binds `was.epoch` like every write.
+        // AEAD-detected on decode. A Resource-level write always knows that id at
+        // encrypt time (it is never content-derived here); a Collection-level write
+        // has no resource to bind and binds this collection's id instead, so its
+        // slot is declared positively -- a content envelope (which binds neither
+        // marker) served in the Collection metadata slot is then detected too. It
+        // seals to the current epoch key like every write, so it binds `was.epoch`
+        // like every write.
         const was = wasParam({
             version: this.#version,
-            resource: resourceId,
+            ...(resourceId === undefined
+                ? { collection: this.#collectionId }
+                : { resource: resourceId }),
             epoch: this.#writeEpoch
         });
         const encrypted = await documentCipher.encrypt({
             doc: { id, content: custom },
             recipients: this.#recipients,
             keyResolver: this.#edv.keyResolver,
+            // Deliberately un-blinded, even on a searchable collection: this envelope
+            // is the WAS `/meta` value, not part of the resource's content document,
+            // and it is stored in a different slot the search endpoint never reads.
+            // The `meta.*` attribute paths a declared index may name address the
+            // *content document's* own `meta` (the content type and inline-encoding
+            // discriminator), which is a different object entirely -- so blinding
+            // here would emit entries that can never match a query and would leak the
+            // shape of the metadata into a slot with no index at all.
             hmac: undefined,
             additionalProtectedParams: { was }
         });
-        return { custom: encrypted };
+        // Surface the epoch this envelope sealed under: a Collection-level `/meta`
+        // PUT carries it as the body's top-level `epoch` stamp (the server clears
+        // that stamp when it is omitted).
+        return { custom: encrypted, epoch: this.#writeEpoch };
     }
     /**
      * @inheritdoc
@@ -573,12 +814,21 @@ export class EdvCodec {
      * absent `custom` (no metadata written yet, or cleared) decodes to `{}`; a
      * present value must be an EDV envelope (else {@link EncryptionError}, the
      * `_assertEnvelope` guard), so a foreign plaintext `custom` fails closed.
+     *
+     * An omitted `expectedId` means the Collection-level metadata slot (a
+     * Resource metadata read always passes its resource id), so an envelope bound
+     * to a resource is refused there as a server-side swap, and one that does not
+     * bind this Collection's own id is refused as an envelope of some other slot.
      */
     async decodeMeta({ custom }, expectedId) {
         if (custom === undefined || custom === null) {
             return {};
         }
-        const decrypted = await this.#openEnvelope(custom, expectedId);
+        const decrypted = await this.#openEnvelope({
+            doc: custom,
+            expectedId,
+            collectionSlot: expectedId === undefined
+        });
         return (decrypted.content ?? {});
     }
     /**
@@ -865,20 +1115,34 @@ export function createEdvEncryption({ resolveKeys, contentType = DEFAULT_CONTENT
             // resource's recipient (the epoch public key) resolves through the
             // standard did:key resolver, independent of the reader's own keystore.
             const keyAgreementKey = epochKeys.writeKey;
+            // The collection's blinding key: an explicitly supplied one (a keystore
+            // custodying the HMAC key itself) wins over unwrapping the descriptor's
+            // `hmac` member; `null` means the collection declares no blinded index.
+            const hmac = resolved.hmac ??
+                (await resolveHmacKey({
+                    encryption,
+                    keyAgreementKey: resolved.keyAgreementKey
+                }));
             const edv = new EdvClientCore({
                 keyAgreementKey,
-                keyResolver: didKeyResolver
+                keyResolver: didKeyResolver,
+                ...(hmac !== null && { hmac })
             });
             return new EdvCodec({
                 edv,
                 keyAgreementKey,
+                hmac,
                 readKeys: epochKeys.readKeys,
                 writeEpoch: epochKeys.writeEpoch,
                 contentType,
                 maxBlobBytes,
                 idDerivation,
                 version: descriptorVersion ?? EDV_SCHEME_VERSION,
-                collectionId
+                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)
             });
         }
     };