@interop/was-client 0.14.0 → 0.14.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"epochCrypto.d.ts","sourceRoot":"","sources":["../../src/edv/epochCrypto.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAA;AAEhE;;GAEG;AACH,eAAO,MAAM,YAAY,mBAAmB,CAAA;AAS5C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAA;IACV,kBAAkB,EAAE,MAAM,CAAA;IAC1B,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,EACpC,WAAW,EACX,SAAS,EACV,EAAE;IACD,WAAW,EAAE,UAAU,CAAA;IACvB,SAAS,EAAE,kBAAkB,CAAA;CAC9B,GAAG,OAAO,CAAC,6BAA6B,CAAC,CA4BzC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,KAAK,EACL,eAAe,EAChB,EAAE;IACD,KAAK,EAAE,6BAA6B,CAAA;IACpC,eAAe,EAAE,gBAAgB,CAAA;CAClC,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAyB7B;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,UAAU,CAAA;CACnB,CAAC,CAQD;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,EACtC,OAAO,EACP,MAAM,EACP,EAAE;IACD,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,UAAU,CAAA;CACnB,GAAG,gBAAgB,CASnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAErD;AAkBD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,EACnC,EAAE,EACH,EAAE;IACD,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,CAAC,CAoBpE"}

package/dist/edv/epochCrypto.js

@@ -0,0 +1,211 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The key-epoch cryptography for multi-recipient encrypted Collections: wrapping
+ * and unwrapping a per-epoch collection key to each reader's X25519
+ * key-agreement key, and minting / reconstructing the epoch key pair the EDV
+ * codec encrypts resources under.
+ *
+ * A collection key epoch is a fresh 32-byte X25519 private key. Resources are
+ * encrypted with the ordinary EDV `documentCipher`, naming the epoch's public
+ * key as the sole recipient (each document gets a fresh content-encryption key
+ * wrapped `ECDH-ES+A256KW` to the epoch key) -- so the read/write machinery is
+ * unchanged and only key resolution is epoch-aware. The epoch's public key IS
+ * its `did:key`, and the epoch id is that `did:key` string, so the standard
+ * `did:key` resolver resolves the recipient named in a resource's JWE.
+ *
+ * The epoch key itself is shared with a reader by wrapping the 32-byte epoch
+ * secret to the reader's own X25519 key-agreement key, `ECDH-ES+A256KW`, and
+ * storing the result as a JWE `recipients` entry verbatim on the Collection's
+ * `encryption` marker. The wrap is derive-then-wrap per recipient: an ephemeral
+ * ECDH against the reader's public key, the RFC 7518 Concat KDF, then A256KW --
+ * `@interop/minimal-cipher`'s own `ECDH-ES+A256KW` building blocks (via its
+ * `algorithms` subpath), so the wrapped bytes are interchangeable with what its
+ * `Cipher` would produce.
+ *
+ * The two axes stay separate here: this module governs **read** (who can
+ * decrypt), which is prospective -- rotating the epoch only protects resources
+ * written afterwards. **Pull** (who the server will serve ciphertext to) is the
+ * zcap layer, enforced immediately at request time. Neither alone removes a
+ * reader; see `removeRecipient`.
+ */
+import { base64urlnopad } from '@scure/base';
+import { createKek, deriveKey } from '@interop/minimal-cipher/algorithms';
+import { X25519KeyAgreementKey2020, multibaseDecode, multibaseEncode, MULTICODEC_X25519_PUB_HEADER } from '@interop/x25519-key-agreement-key';
+/**
+ * The JOSE key-management algorithm for every epoch/recipient wrap.
+ */
+export const KEY_WRAP_ALG = 'ECDH-ES+A256KW';
+/**
+ * The X25519 suite tag used for the ephemeral and reconstructed key pairs.
+ */
+const X25519_TYPE = 'X25519KeyAgreementKey2020';
+const TEXT_ENCODER = new TextEncoder();
+/**
+ * Wraps a 32-byte epoch secret to one recipient's X25519 key-agreement key,
+ * producing the JWE `recipients` entry stored on the marker. Generates a fresh
+ * ephemeral key per call (ECDH-ES), so each wrap carries its own `epk`.
+ *
+ * @param options {object}
+ * @param options.epochSecret {Uint8Array}       the 32-byte epoch key to wrap
+ * @param options.recipient {RecipientPublicKey}   the reader's public KAK
+ * @returns {Promise<CollectionEncryptionRecipient>}
+ */
+export async function wrapEpochSecret({ epochSecret, recipient }) {
+    const ephemeral = await X25519KeyAgreementKey2020.generate();
+    const ephemeralPublicKey = multibaseDecode(MULTICODEC_X25519_PUB_HEADER, ephemeral.publicKeyMultibase);
+    const secret = await ephemeral.deriveSecret({
+        publicKey: { publicKeyMultibase: recipient.publicKeyMultibase }
+    });
+    const producerInfo = ephemeralPublicKey;
+    const consumerInfo = TEXT_ENCODER.encode(recipient.id);
+    const keyData = await deriveKey({ secret, producerInfo, consumerInfo });
+    const kek = await createKek({ keyData });
+    const encryptedKey = await kek.wrapKey({ unwrappedKey: epochSecret });
+    return {
+        header: {
+            kid: recipient.id,
+            alg: KEY_WRAP_ALG,
+            epk: {
+                kty: 'OKP',
+                crv: 'X25519',
+                x: base64urlnopad.encode(ephemeralPublicKey)
+            },
+            apu: base64urlnopad.encode(producerInfo),
+            apv: base64urlnopad.encode(consumerInfo)
+        },
+        encrypted_key: encryptedKey
+    };
+}
+/**
+ * Unwraps an epoch secret from a marker `recipients` entry using the reader's
+ * own key-agreement key. Returns `null` when this key does not match the entry
+ * (the wrong recipient, or a corrupt entry) -- never treat `null` as a key; try
+ * the next candidate entry or epoch, and fail with a typed error when nothing
+ * unwraps.
+ *
+ * @param options {object}
+ * @param options.entry {CollectionEncryptionRecipient}   the marker entry
+ * @param options.keyAgreementKey {IKeyAgreementKey}      the reader's own KAK
+ *   (its `id` must equal `entry.header.kid` for the derivation to match)
+ * @returns {Promise<Uint8Array | null>}
+ */
+export async function unwrapEpochSecret({ entry, keyAgreementKey }) {
+    const epk = entry.header.epk;
+    if (!epk || typeof epk.x !== 'string') {
+        return null;
+    }
+    const ephemeralPublicKey = base64urlnopad.decode(epk.x);
+    let secret;
+    try {
+        secret = await keyAgreementKey.deriveSecret({
+            publicKey: {
+                type: X25519_TYPE,
+                publicKeyMultibase: multibaseEncode(MULTICODEC_X25519_PUB_HEADER, ephemeralPublicKey)
+            }
+        });
+    }
+    catch {
+        return null;
+    }
+    const producerInfo = ephemeralPublicKey;
+    const consumerInfo = TEXT_ENCODER.encode(keyAgreementKey.id);
+    const keyData = await deriveKey({ secret, producerInfo, consumerInfo });
+    const kek = await createKek({ keyData });
+    return kek.unwrapKey({ wrappedKey: entry.encrypted_key });
+}
+/**
+ * Mints a fresh key epoch: a new random X25519 key pair whose `did:key` is the
+ * epoch id. Returns the id and the raw 32-byte secret (to wrap to recipients);
+ * `resolveEpochKeys` reconstructs the epoch key pair from the id and secret when
+ * a resource must be encrypted or decrypted under the epoch.
+ *
+ * @returns {Promise<{ epochId: string, secret: Uint8Array }>}
+ */
+export async function mintEpoch() {
+    const generated = await X25519KeyAgreementKey2020.generate();
+    if (generated.privateKeyMultibase === undefined) {
+        throw new Error('Generated epoch key is missing its private key.');
+    }
+    const secret = generated.rawSecret;
+    const epochId = `did:key:${generated.publicKeyMultibase}`;
+    return { epochId, secret };
+}
+/**
+ * Reconstructs an epoch key pair from its id (a `did:key`, which carries the
+ * public key) and the unwrapped 32-byte secret, ready to hand to the EDV
+ * `documentCipher` as its `keyAgreementKey`.
+ *
+ * @param options {object}
+ * @param options.epochId {string}      the epoch's `did:key`
+ * @param options.secret {Uint8Array}   the unwrapped 32-byte epoch secret
+ * @returns {X25519KeyAgreementKey2020}
+ */
+export function reconstructEpochKeyPair({ epochId, secret }) {
+    // The concrete instance always carries a defined `id` (set here), so it
+    // satisfies `IKeyAgreementKey` (whose `id` is required); the suite's type
+    // declares `id` optional, hence the assertion.
+    return X25519KeyAgreementKey2020.fromRawSecret({
+        secret,
+        controller: epochId,
+        id: epochKeyIdFor(epochId)
+    });
+}
+/**
+ * The verification-method id of an epoch key: `<did:key>#<fingerprint>`. This is
+ * the `kid` the EDV `documentCipher` stamps on a resource encrypted under the
+ * epoch; a reader maps it back to the epoch by taking the `did:key` portion
+ * before the `#` fragment.
+ *
+ * @param epochId {string}   the epoch's `did:key`
+ * @returns {string}
+ */
+export function epochKeyIdFor(epochId) {
+    return `${epochId}#${publicKeyMultibaseFromEpochId(epochId)}`;
+}
+/**
+ * Extracts the `publicKeyMultibase` fingerprint from an epoch id (`did:key:z...`).
+ *
+ * @param epochId {string}
+ * @returns {string}
+ */
+function publicKeyMultibaseFromEpochId(epochId) {
+    const prefix = 'did:key:';
+    if (!epochId.startsWith(prefix)) {
+        throw new Error(`Epoch id "${epochId}" is not a did:key (expected a "${prefix}z..." id).`);
+    }
+    return epochId.slice(prefix.length);
+}
+/**
+ * A `did:key` key resolver for X25519 key-agreement keys: resolves a
+ * `did:key:z...#z...` id (an epoch key, or any self-describing X25519 key) to
+ * its public verification method. The public key is the fragment, so no network
+ * or registry lookup is needed.
+ *
+ * @param options {object}
+ * @param options.id {string}   the key id to resolve
+ * @returns {Promise<{ id: string, type: string, publicKeyMultibase: string }>}
+ */
+export async function didKeyResolver({ id }) {
+    if (!id) {
+        throw new Error('A key id is required to resolve.');
+    }
+    const hash = id.indexOf('#');
+    const fragment = hash === -1 ? '' : id.slice(hash + 1);
+    if (!fragment.startsWith('z')) {
+        throw new Error(`Cannot resolve non-did:key key id "${id}".`);
+    }
+    // Validate the fragment is a well-formed X25519 public key fingerprint; the
+    // suite throws on invalid header bytes.
+    const keyPair = X25519KeyAgreementKey2020.fromFingerprint({
+        fingerprint: fragment
+    });
+    keyPair.verifyFingerprint({ fingerprint: fragment });
+    return {
+        id,
+        type: X25519_TYPE,
+        publicKeyMultibase: keyPair.publicKeyMultibase
+    };
+}
+//# sourceMappingURL=epochCrypto.js.map

package/dist/edv/epochCrypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epochCrypto.js","sourceRoot":"","sources":["../../src/edv/epochCrypto.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAA;AACzE,OAAO,EACL,yBAAyB,EACzB,eAAe,EACf,eAAe,EACf,4BAA4B,EAC7B,MAAM,mCAAmC,CAAA;AAI1C;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAA;AAE5C;;GAEG;AACH,MAAM,WAAW,GAAG,2BAA2B,CAAA;AAE/C,MAAM,YAAY,GAAG,IAAI,WAAW,EAAE,CAAA;AAatC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,EACpC,WAAW,EACX,SAAS,EAIV;IACC,MAAM,SAAS,GAAG,MAAM,yBAAyB,CAAC,QAAQ,EAAE,CAAA;IAC5D,MAAM,kBAAkB,GAAG,eAAe,CACxC,4BAA4B,EAC5B,SAAS,CAAC,kBAAkB,CAC7B,CAAA;IACD,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,YAAY,CAAC;QAC1C,SAAS,EAAE,EAAE,kBAAkB,EAAE,SAAS,CAAC,kBAAkB,EAAE;KAChE,CAAC,CAAA;IACF,MAAM,YAAY,GAAG,kBAAkB,CAAA;IACvC,MAAM,YAAY,GAAG,YAAY,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAA;IACtD,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC,CAAA;IACvE,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;IACxC,MAAM,YAAY,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,CAAA;IACrE,OAAO;QACL,MAAM,EAAE;YACN,GAAG,EAAE,SAAS,CAAC,EAAE;YACjB,GAAG,EAAE,YAAY;YACjB,GAAG,EAAE;gBACH,GAAG,EAAE,KAAK;gBACV,GAAG,EAAE,QAAQ;gBACb,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,kBAAkB,CAAC;aAC7C;YACD,GAAG,EAAE,cAAc,CAAC,MAAM,CAAC,YAAY,CAAC;YACxC,GAAG,EAAE,cAAc,CAAC,MAAM,CAAC,YAAY,CAAC;SACzC;QACD,aAAa,EAAE,YAAY;KAC5B,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EACtC,KAAK,EACL,eAAe,EAIhB;IACC,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC,GAAkC,CAAA;IAC3D,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;QACtC,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,kBAAkB,GAAG,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;IACvD,IAAI,MAAkB,CAAA;IACtB,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,eAAe,CAAC,YAAY,CAAC;YAC1C,SAAS,EAAE;gBACT,IAAI,EAAE,WAAW;gBACjB,kBAAkB,EAAE,eAAe,CACjC,4BAA4B,EAC5B,kBAAkB,CACnB;aACF;SACF,CAAC,CAAA;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,YAAY,GAAG,kBAAkB,CAAA;IACvC,MAAM,YAAY,GAAG,YAAY,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC,CAAA;IAC5D,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC,CAAA;IACvE,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,CAAA;IACxC,OAAO,GAAG,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE,CAAC,CAAA;AAC3D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS;IAI7B,MAAM,SAAS,GAAG,MAAM,yBAAyB,CAAC,QAAQ,EAAE,CAAA;IAC5D,IAAI,SAAS,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;IACpE,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,SAAS,CAAA;IAClC,MAAM,OAAO,GAAG,WAAW,SAAS,CAAC,kBAAkB,EAAE,CAAA;IACzD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AAC5B,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CAAC,EACtC,OAAO,EACP,MAAM,EAIP;IACC,wEAAwE;IACxE,0EAA0E;IAC1E,+CAA+C;IAC/C,OAAO,yBAAyB,CAAC,aAAa,CAAC;QAC7C,MAAM;QACN,UAAU,EAAE,OAAO;QACnB,EAAE,EAAE,aAAa,CAAC,OAAO,CAAC;KAC3B,CAAqB,CAAA;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,OAAO,GAAG,OAAO,IAAI,6BAA6B,CAAC,OAAO,CAAC,EAAE,CAAA;AAC/D,CAAC;AAED;;;;;GAKG;AACH,SAAS,6BAA6B,CAAC,OAAe;IACpD,MAAM,MAAM,GAAG,UAAU,CAAA;IACzB,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CACb,aAAa,OAAO,mCAAmC,MAAM,YAAY,CAC1E,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;AACrC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EACnC,EAAE,EAGH;IACC,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;IACrD,CAAC;IACD,MAAM,IAAI,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;IAC5B,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAA;IACtD,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,sCAAsC,EAAE,IAAI,CAAC,CAAA;IAC/D,CAAC;IACD,4EAA4E;IAC5E,wCAAwC;IACxC,MAAM,OAAO,GAAG,yBAAyB,CAAC,eAAe,CAAC;QACxD,WAAW,EAAE,QAAQ;KACtB,CAAC,CAAA;IACF,OAAO,CAAC,iBAAiB,CAAC,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAA;IACpD,OAAO;QACL,EAAE;QACF,IAAI,EAAE,WAAW;QACjB,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;KAC/C,CAAA;AACH,CAAC"}

package/dist/edv/epochKeys.d.ts

@@ -0,0 +1,57 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Resolves a reader's per-epoch keys from a Collection's `encryption` marker.
+ * Given the marker (its `epochs` and `currentEpoch`) and the reader's own
+ * key-agreement key, it reconstructs each epoch the reader is a recipient of as
+ * an X25519 key pair the EDV `documentCipher` can use -- the write epoch's key
+ * for writes, and one read key per epoch the reader holds (so a resource written
+ * under an older epoch stays readable). The write epoch is unwrapped eagerly;
+ * the other epochs' keys unwrap lazily on first decrypt naming them, so a
+ * write-only handle does not pay to unwrap history it never reads.
+ *
+ * This is the read axis: holding an epoch key lets a reader decrypt resources
+ * written under it. A reader removed from a later epoch keeps the earlier epoch
+ * keys and so keeps reading pre-rotation resources -- rotation is prospective,
+ * never retroactive.
+ */
+import type { IKeyAgreementKey } from '@interop/data-integrity-core';
+import type { CollectionEncryption } from '../types.js';
+/**
+ * The reader's resolved key-epoch material for a Collection.
+ */
+export interface ResolvedEpochKeys {
+    /**
+     * the epoch id writes encrypt under and stamp (the marker's `currentEpoch`)
+     */
+    writeEpoch: string;
+    /**
+     * the key writes encrypt under
+     */
+    writeKey: IKeyAgreementKey;
+    /**
+     * every epoch key this reader can unwrap, for decrypting any epoch (the
+     * `writeKey`, unwrapped eagerly, plus a lazily-unwrapped key per other epoch
+     * this reader is a recipient of)
+     */
+    readKeys: IKeyAgreementKey[];
+}
+/**
+ * Resolves the reader's epoch keys from a marker. Returns `null` when the marker
+ * declares no epochs (a single-key collection -- the caller keeps its existing
+ * single-key path). Throws {@link KeyUnwrapError} when the marker HAS epochs but
+ * this reader can unwrap none of them (it is not a recipient), so an encrypted
+ * collection is never silently read/written with the wrong key.
+ *
+ * @param options {object}
+ * @param options.encryption {CollectionEncryption}   the Collection's marker
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the reader's own KAK; its
+ *   `id` must match a recipient `kid` in an epoch for that epoch to unwrap
+ * @returns {Promise<ResolvedEpochKeys | null>}
+ */
+export declare function resolveEpochKeys({ encryption, keyAgreementKey }: {
+    encryption: CollectionEncryption;
+    keyAgreementKey: IKeyAgreementKey;
+}): Promise<ResolvedEpochKeys | null>;
+//# sourceMappingURL=epochKeys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"epochKeys.d.ts","sourceRoot":"","sources":["../../src/edv/epochKeys.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AAEpE,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,aAAa,CAAA;AAOpB;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB;;OAEG;IACH,QAAQ,EAAE,gBAAgB,CAAA;IAC1B;;;;OAIG;IACH,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,UAAU,EACV,eAAe,EAChB,EAAE;IACD,UAAU,EAAE,oBAAoB,CAAA;IAChC,eAAe,EAAE,gBAAgB,CAAA;CAClC,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA+DpC"}

package/dist/edv/epochKeys.js

@@ -0,0 +1,132 @@
+import { KeyUnwrapError } from '../errors.js';
+import { epochKeyIdFor, reconstructEpochKeyPair, unwrapEpochSecret } from './epochCrypto.js';
+/**
+ * Resolves the reader's epoch keys from a marker. Returns `null` when the marker
+ * declares no epochs (a single-key collection -- the caller keeps its existing
+ * single-key path). Throws {@link KeyUnwrapError} when the marker HAS epochs but
+ * this reader can unwrap none of them (it is not a recipient), so an encrypted
+ * collection is never silently read/written with the wrong key.
+ *
+ * @param options {object}
+ * @param options.encryption {CollectionEncryption}   the Collection's marker
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the reader's own KAK; its
+ *   `id` must match a recipient `kid` in an epoch for that epoch to unwrap
+ * @returns {Promise<ResolvedEpochKeys | null>}
+ */
+export async function resolveEpochKeys({ encryption, keyAgreementKey }) {
+    const epochs = encryption.epochs;
+    if (!epochs || epochs.length === 0) {
+        return null;
+    }
+    // The epochs this reader is named in (has a recipient entry keyed to its
+    // `kid`), in the marker's canonical order. Being named IS being a recipient;
+    // whether a named entry actually unwraps is confirmed eagerly for the write
+    // epoch and lazily (on first decrypt) for the rest.
+    const namedEpochs = epochs.filter(epoch => epoch.recipients.some(recipient => recipient.header.kid === keyAgreementKey.id));
+    if (namedEpochs.length === 0) {
+        throw new KeyUnwrapError('This reader is not a recipient of any key epoch on this encrypted ' +
+            "collection (none of the marker's recipient entries name this " +
+            "reader's key-agreement key). Add this reader with addRecipient, or " +
+            'supply the correct key-agreement key.');
+    }
+    // Choose the write epoch: `currentEpoch` when this reader holds it, otherwise
+    // the newest epoch it holds -- defined deterministically as the LAST epoch in
+    // the marker's canonical `epochs` order that names this reader, never the
+    // incidental order in which secrets happened to unwrap. A reader that is not a
+    // recipient of `currentEpoch` is a removed/historical reader whose writes the
+    // server rejects via its revoked zcap anyway; selecting a deterministic
+    // fallback here only keeps the local `writeEpoch`/`writeKey` well-defined
+    // instead of assuming the `epochs` array is append-ordered newest-last.
+    const currentEpoch = encryption.currentEpoch;
+    const writeEpochEntry = (currentEpoch !== undefined &&
+        namedEpochs.find(epoch => epoch.id === currentEpoch)) ||
+        namedEpochs[namedEpochs.length - 1];
+    // The write epoch is unwrapped eagerly: `writeKey` must be a full key pair the
+    // EDV cipher can name recipients with and encrypt under right away.
+    const writeKey = await unwrapEpochKey({
+        epoch: writeEpochEntry,
+        keyAgreementKey
+    });
+    if (!writeKey) {
+        throw new KeyUnwrapError(`This reader's recipient entry for the write epoch ` +
+            `"${writeEpochEntry.id}" did not unwrap (a corrupt entry). Re-add ` +
+            'this reader with addRecipient, or supply the correct key-agreement ' +
+            'key.');
+    }
+    // Read keys: the eagerly-unwrapped write key, plus a LAZY key per other named
+    // epoch. Each lazy key knows its `id` up front (derived from the epoch id, so
+    // the codec's kid-match filter needs no secret) and unwraps + reconstructs its
+    // epoch secret only on first decrypt naming it, caching the result. So a
+    // write-only handle -- or a reader that only ever touches current-epoch
+    // resources -- never pays the ECDH + KDF + key-unwrap for historical epochs it
+    // does not read.
+    const readKeys = [writeKey];
+    for (const epoch of namedEpochs) {
+        if (epoch.id !== writeEpochEntry.id) {
+            readKeys.push(lazyEpochKey({ epoch, keyAgreementKey }));
+        }
+    }
+    return { writeEpoch: writeEpochEntry.id, writeKey, readKeys };
+}
+/**
+ * Unwraps and reconstructs a single epoch's key pair for this reader, or returns
+ * `null` when the reader is not a recipient of the epoch or its entry does not
+ * unwrap (a corrupt entry -- never treat `null` as a key).
+ *
+ * @param options {object}
+ * @param options.epoch {CollectionEncryptionEpoch}   the epoch to unwrap
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the reader's own KAK
+ * @returns {Promise<IKeyAgreementKey | null>}
+ */
+async function unwrapEpochKey({ epoch, keyAgreementKey }) {
+    const entry = epoch.recipients.find(recipient => recipient.header.kid === keyAgreementKey.id);
+    if (!entry) {
+        return null;
+    }
+    const secret = await unwrapEpochSecret({ entry, keyAgreementKey });
+    if (!secret) {
+        return null;
+    }
+    return reconstructEpochKeyPair({ epochId: epoch.id, secret });
+}
+/**
+ * Builds a lazily-unwrapping read key for a named epoch: an `IKeyAgreementKey`
+ * whose `id` is known up front (the epoch key's verification-method id, derived
+ * from the epoch id -- the `kid` a resource written under this epoch stamps), so
+ * the codec can kid-match it before any secret is derived, and whose
+ * `deriveSecret` unwraps + reconstructs the real epoch key pair on first call
+ * and caches it. This defers the ECDH + KDF + key-unwrap cost until (and unless)
+ * a resource named for this epoch is actually decrypted.
+ *
+ * @param options {object}
+ * @param options.epoch {CollectionEncryptionEpoch}   the epoch this key reads
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the reader's own KAK
+ * @returns {IKeyAgreementKey}
+ */
+function lazyEpochKey({ epoch, keyAgreementKey }) {
+    let pending;
+    const resolve = () => {
+        if (pending === undefined) {
+            pending = unwrapEpochKey({ epoch, keyAgreementKey }).then(key => {
+                if (!key) {
+                    // The reader was named in this epoch (else no lazy key was built) but
+                    // its entry did not unwrap: a corrupt entry. The codec's `_decrypt`
+                    // catches this and tries the next candidate before surfacing its own
+                    // typed failure.
+                    throw new KeyUnwrapError(`This reader's recipient entry for epoch "${epoch.id}" did not ` +
+                        'unwrap (a corrupt entry).');
+                }
+                return key;
+            });
+        }
+        return pending;
+    };
+    return {
+        id: epochKeyIdFor(epoch.id),
+        async deriveSecret(options) {
+            const key = await resolve();
+            return key.deriveSecret(options);
+        }
+    };
+}
+//# sourceMappingURL=epochKeys.js.map

package/dist/edv/epochKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"epochKeys.js","sourceRoot":"","sources":["../../src/edv/epochKeys.ts"],"names":[],"mappings":"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"}

package/dist/edv/index.d.ts

@@ -15,8 +15,16 @@
  *   override), so `collection.put`/`get` transparently encrypt/decrypt.
  * - `WasTransport` -- the standalone `@interop/edv-client`
  *   transport, for driving an `EdvClient` directly against WAS.
+ *
+ * Multi-recipient (key-epoch) collections layer on top: `initRecipients` /
+ * `addRecipient` / `removeRecipient` manage the readers and rotate the epoch
+ * key, so the same `createEdvEncryption` provider transparently encrypts each
+ * write under the current epoch and decrypts any epoch a reader still holds.
  */
 export { createEdvEncryption, EdvCodec } from './EdvCodec.js';
 export type { EdvKeys } from './EdvCodec.js';
 export { WasTransport, JOSE_CONTENT_TYPE } from './WasTransport.js';
+export { initRecipients, addRecipient, removeRecipient } from './recipients.js';
+export type { OwnerKey, RecipientPublicKey } from './recipients.js';
+export { mintEpoch, epochKeyIdFor } from './epochCrypto.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7D,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAC7D,YAAY,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC/E,YAAY,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACnE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/edv/index.js

@@ -15,7 +15,14 @@
  *   override), so `collection.put`/`get` transparently encrypt/decrypt.
  * - `WasTransport` -- the standalone `@interop/edv-client`
  *   transport, for driving an `EdvClient` directly against WAS.
+ *
+ * Multi-recipient (key-epoch) collections layer on top: `initRecipients` /
+ * `addRecipient` / `removeRecipient` manage the readers and rotate the epoch
+ * key, so the same `createEdvEncryption` provider transparently encrypts each
+ * write under the current epoch and decrypts any epoch a reader still holds.
  */
 export { createEdvEncryption, EdvCodec } from './EdvCodec.js';
 export { WasTransport, JOSE_CONTENT_TYPE } from './WasTransport.js';
+export { initRecipients, addRecipient, removeRecipient } from './recipients.js';
+export { mintEpoch, epochKeyIdFor } from './epochCrypto.js';
 //# sourceMappingURL=index.js.map

package/dist/edv/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAE7D,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAE/E,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/edv/recipients.d.ts

@@ -0,0 +1,122 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Recipient and key-epoch management for multi-recipient encrypted Collections:
+ * initializing the first epoch, adding a reader (escrow -- history included),
+ * and removing a reader (the full revoke-and-rotate procedure). Each operation
+ * mutates the Collection's `encryption` marker and writes it back with a
+ * compare-and-swap (`If-Match`), retrying on a concurrent change so two racing
+ * recipient edits cannot clobber one another.
+ *
+ * The two axes stay separate and are both required to actually remove a reader:
+ *
+ * - **pull** -- the zcap the server checks at request time. Revoking it stops
+ *   the server serving that reader ciphertext. Immediate and total.
+ * - **read** -- possession of an epoch key. Rotating the epoch means resources
+ *   written afterward are encrypted under a key the removed reader does not
+ *   hold. Prospective only.
+ *
+ * Important: Rotation protects post-rotation writes only. It never claws
+ * back data a reader already downloaded, and a removed reader keeps every
+ * earlier epoch's key, so any pre-rotation resource whose ciphertext it obtains
+ * stays readable to it. {@link removeRecipient} does both halves so a caller
+ * cannot accidentally do one; callers who truly want half can call
+ * `space.revoke()` or nothing, respectively, themselves.
+ */
+import type { IKeyAgreementKey } from '@interop/data-integrity-core';
+import type { Collection } from '../Collection.js';
+import type { Space } from '../Space.js';
+import type { CollectionEncryption, IDelegatedZcap } from '../types.js';
+import type { RecipientPublicKey } from './epochCrypto.js';
+export type { RecipientPublicKey } from './epochCrypto.js';
+/**
+ * The caller's own key material, used to unwrap existing epoch keys so they can
+ * be re-wrapped to a newly added reader (escrow).
+ */
+export interface OwnerKey {
+    keyAgreementKey: IKeyAgreementKey;
+}
+/**
+ * Initializes the first key epoch on a Collection that is declared encrypted
+ * but has no epochs yet: mints a fresh epoch key, wraps it to each initial
+ * recipient, and writes `epochs: [epoch]` / `currentEpoch` back with a
+ * compare-and-swap. After this, resources written by any recipient are encrypted
+ * under the epoch, and readers unwrap it with their own key-agreement key.
+ *
+ * @param options {object}
+ * @param options.collection {Collection}   the (already encrypted) collection
+ * @param options.recipients {RecipientPublicKey[]}   the initial readers' public
+ *   key-agreement keys (each `id` is the reader's `kid`)
+ * @returns {Promise<CollectionEncryption>}   the new marker
+ */
+export declare function initRecipients({ collection, recipients }: {
+    collection: Collection;
+    recipients: RecipientPublicKey[];
+}): Promise<CollectionEncryption>;
+/**
+ * Adds a reader to a multi-recipient encrypted Collection. Escrow semantics: the
+ * new reader receives EVERY epoch's key (the current one and all prior), because
+ * "add a reader to a collection" means it can read the Collection, history
+ * included. No rotation happens -- **adds are cheap, removals rotate.**
+ *
+ * The caller must itself be a recipient of every epoch (its `owner` key unwraps
+ * each epoch key, which is then re-wrapped to the new reader). Written back with
+ * a compare-and-swap, retried on a concurrent change.
+ *
+ * @param options {object}
+ * @param options.collection {Collection}   the collection
+ * @param options.recipient {RecipientPublicKey}   the new reader's public KAK
+ * @param options.owner {OwnerKey}   the caller's own key-agreement key, to
+ *   unwrap each epoch key for re-wrapping to the new reader
+ * @returns {Promise<CollectionEncryption>}   the new marker
+ */
+export declare function addRecipient({ collection, recipient, owner }: {
+    collection: Collection;
+    recipient: RecipientPublicKey;
+    owner: OwnerKey;
+}): Promise<CollectionEncryption>;
+/**
+ * Removes a reader from a multi-recipient encrypted Collection -- one
+ * indivisible operation doing BOTH halves of a removal:
+ *
+ * 1. **Rotate the epoch**: mint a fresh epoch key, wrap it to each REMAINING
+ *    recipient (the current epoch's roster minus the removed reader), append it
+ *    as a new epoch, and repoint `currentEpoch`, with a compare-and-swap.
+ *    Resources written afterward are unreadable to the removed reader (the read
+ *    axis; prospective).
+ * 2. **Revoke the reader's zcap(s)** via `space.revoke()`, so the server stops
+ *    serving it ciphertext (the pull axis; immediate).
+ *
+ * The rotation runs first so it is durable before the irreversible revocation:
+ * a rotation that keeps losing the compare-and-swap throws with nothing revoked,
+ * leaving the operation safely retryable rather than half-applied. The revoke
+ * step tolerates an already-revoked capability (a retry re-revokes) so the
+ * operation converges.
+ *
+ * Important: this does not re-encrypt existing resources, so the removed
+ * reader keeps every earlier epoch's key and can still decrypt any pre-rotation
+ * resource whose ciphertext it gets. Neither half alone removes a reader.
+ *
+ * @param options {object}
+ * @param options.collection {Collection}   the collection
+ * @param options.space {Space}   the collection's Space, for the zcap revocation
+ * @param options.recipientId {string}   the removed reader's key-agreement key
+ *   id (`kid`), dropped from the new epoch's recipients
+ * @param options.revoke {IDelegatedZcap | IDelegatedZcap[]}   the reader's
+ *   delegated capability/capabilities to revoke (the pull axis)
+ * @param [options.resolveRecipientKey] {function}   resolves a remaining
+ *   recipient's `kid` to its public key-agreement key, so the fresh epoch key
+ *   can be wrapped to it. Defaults to a `did:key` resolver (the `kid` fragment
+ *   is the X25519 public key); override for recipients whose `kid` is not a
+ *   self-describing `did:key`.
+ * @returns {Promise<CollectionEncryption>}   the new marker
+ */
+export declare function removeRecipient({ collection, space, recipientId, revoke, resolveRecipientKey }: {
+    collection: Collection;
+    space: Space;
+    recipientId: string;
+    revoke: IDelegatedZcap | IDelegatedZcap[];
+    resolveRecipientKey?: (kid: string) => Promise<RecipientPublicKey>;
+}): Promise<CollectionEncryption>;
+//# sourceMappingURL=recipients.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recipients.d.ts","sourceRoot":"","sources":["../../src/edv/recipients.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAA;AAExC,OAAO,KAAK,EACV,oBAAoB,EAEpB,cAAc,EACf,MAAM,aAAa,CAAA;AAOpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE1D;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,eAAe,EAAE,gBAAgB,CAAA;CAClC;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAAC,EACnC,UAAU,EACV,UAAU,EACX,EAAE;IACD,UAAU,EAAE,UAAU,CAAA;IACtB,UAAU,EAAE,kBAAkB,EAAE,CAAA;CACjC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA2BhC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAAC,EACjC,UAAU,EACV,SAAS,EACT,KAAK,EACN,EAAE;IACD,UAAU,EAAE,UAAU,CAAA;IACtB,SAAS,EAAE,kBAAkB,CAAA;IAC7B,KAAK,EAAE,QAAQ,CAAA;CAChB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkDhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,eAAe,CAAC,EACpC,UAAU,EACV,KAAK,EACL,WAAW,EACX,MAAM,EACN,mBAAgD,EACjD,EAAE;IACD,UAAU,EAAE,UAAU,CAAA;IACtB,KAAK,EAAE,KAAK,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,cAAc,GAAG,cAAc,EAAE,CAAA;IACzC,mBAAmB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAA;CACnE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA6EhC"}