@interop/was-client 0.17.0 → 0.19.0

package/dist/edv/docCipher.js

@@ -0,0 +1,236 @@
+import { KeyUnwrapError } from '../errors.js';
+import { createEdvEncryption } from './EdvCodec.js';
+import { epochKeyIdFor } from './epochCrypto.js';
+// `isEncryptedEnvelope` and the `DocCipher` interface live in the crypto-free
+// `../sync` module; re-exported here so an encrypted-collection consumer that
+// imports this subpath gets both without a second import.
+export { isEncryptedEnvelope } from '../sync/envelope.js';
+/**
+ * Thrown by a {@link DocCipher.decrypt} when a stored envelope names a JWE
+ * recipient (`kid`) this cipher cannot route: neither the key-agreement key nor
+ * -- on an epoch-aware cipher -- any epoch this cipher knows about. It signals
+ * that the caller's cached Collection Description may be stale and should be
+ * re-read before retrying: an epoch rotation emits no change-feed entry, so a
+ * cipher built from a pre-rotation marker meets envelopes stamped with a newer
+ * epoch it has never seen. It also fires on a single-key cipher that meets an
+ * envelope encrypted to a different key-agreement key entirely.
+ */
+export class UnknownEpochError extends Error {
+    constructor({ collectionId, kids }) {
+        super(`Cannot decrypt a resource in collection "${collectionId}": its ` +
+            `envelope names recipient key id(s) [${kids.join(', ')}] that match ` +
+            'neither the key-agreement key nor any known key epoch. The cached ' +
+            'Collection Description may be stale (an epoch rotation emits no ' +
+            'change-feed entry); re-read it and rebuild the cipher.');
+        this.name = 'UnknownEpochError';
+    }
+}
+/**
+ * A wallet's own key-agreement key as a `RecipientPublicKey` -- the "recipient
+ * zero" entry a caller passes to `initRecipients` when it first makes a
+ * collection multi-recipient (the owner must be a recipient of every epoch, or it
+ * could write envelopes it cannot itself read). An `X25519KeyAgreementKey2020`
+ * carries a did:key-shaped `id` and a `publicKeyMultibase`, so its `kid`'s
+ * fragment resolves through the default did:key recipient resolver.
+ *
+ * @param options {object}
+ * @param options.keyAgreementKey {IKeyAgreementKey}
+ * @returns {RecipientPublicKey}
+ */
+export function ownerRecipient({ keyAgreementKey }) {
+    const { id } = keyAgreementKey;
+    const { publicKeyMultibase, type } = keyAgreementKey;
+    if (typeof id !== 'string' || typeof publicKeyMultibase !== 'string') {
+        throw new Error('Cannot build an owner recipient: the key-agreement key lacks an id or ' +
+            'publicKeyMultibase (a public X25519 key is required to wrap an epoch ' +
+            'key to it).');
+    }
+    return { id, publicKeyMultibase, type };
+}
+/**
+ * Extracts the JWE recipient key ids (`kid`) an EDV envelope names. An epoch
+ * envelope carries one kid (the epoch key id); a single-recipient envelope
+ * carries the key-agreement key id. Returns `[]` for a malformed envelope, so
+ * routing falls through to letting a codec surface its own error.
+ */
+function envelopeRecipientKids(envelope) {
+    if (envelope === null || typeof envelope !== 'object') {
+        return [];
+    }
+    const jwe = envelope.jwe;
+    if (jwe === null || typeof jwe !== 'object') {
+        return [];
+    }
+    const recipients = jwe.recipients;
+    if (!Array.isArray(recipients)) {
+        return [];
+    }
+    const kids = [];
+    for (const recipient of recipients) {
+        const kid = recipient?.header?.kid;
+        if (typeof kid === 'string') {
+            kids.push(kid);
+        }
+    }
+    return kids;
+}
+/**
+ * Builds a {@link DocCipher} for one encrypted collection from a reader's key
+ * material (the key-agreement key + resolver). Keys are supplied directly (no
+ * keystore lookup).
+ *
+ * `idDerivation` selects the id model: `'content'` (default) makes every id a
+ * hash of the JWE ciphertext -- the stable, replica-independent primary key an
+ * immutable content-addressed collection needs; `'random'` mints a stable random
+ * id updated in place via `sequence` (the mutable head-document model, driven by
+ * `encryptUpdate`).
+ *
+ * With no `encryption` marker (or a marker with no epochs) the cipher is single-
+ * recipient: the key-agreement key encrypts and decrypts directly. With epochs on
+ * the marker the cipher becomes multi-recipient: it ALSO builds an epoch codec
+ * that encrypts every write under the marker's `currentEpoch` and decrypts any
+ * epoch this reader still holds a key for. The single-key codec stays built
+ * either way, so a pre-epoch envelope keeps decrypting -- a permanent tolerance,
+ * not a migration shim.
+ *
+ * The reader must be a recipient of every epoch on the marker (the owner is
+ * "recipient zero"). If it is a recipient of none, building the epoch codec
+ * throws {@link KeyUnwrapError}; this surfaces it with a clearer error rather
+ * than silently writing envelopes other recipients cannot read.
+ *
+ * @param options {object}
+ * @param options.keyAgreementKey {IKeyAgreementKey}
+ * @param options.keyResolver {IKeyResolver}
+ * @param options.collectionId {string}   labels errors; the codec is agnostic
+ * @param [options.idDerivation] {'content' | 'random'}   defaults to `'content'`
+ * @param [options.encryption] {CollectionEncryption}   the collection's
+ *   encryption marker; when it carries key epochs, the cipher becomes
+ *   multi-recipient
+ * @returns {Promise<DocCipher>}
+ */
+export async function createEdvDocCipher({ keyAgreementKey, keyResolver, collectionId, idDerivation = 'content', encryption }) {
+    const provider = createEdvEncryption({
+        resolveKeys: async () => null,
+        idDerivation
+    });
+    // The direct (single-key) codec is always built: it decrypts pre-epoch
+    // envelopes and is the whole cipher for a single-recipient collection.
+    const directCodec = await provider.codecFor({
+        spaceId: 'local',
+        collectionId,
+        scheme: 'edv',
+        keys: { keyAgreementKey, keyResolver }
+    });
+    if (!directCodec) {
+        throw new Error(`Could not build the EDV cipher for collection "${collectionId}".`);
+    }
+    // On a multi-recipient collection, ALSO build the epoch codec: same provider
+    // and keys, but with the marker so `codecFor` resolves this reader's per-epoch
+    // keys. Writes go under the marker's `currentEpoch`; reads pick the epoch key
+    // matching the envelope's recipient kid.
+    const hasEpochs = encryption?.epochs !== undefined && encryption.epochs.length > 0;
+    let epochCodec;
+    if (hasEpochs) {
+        try {
+            epochCodec = await provider.codecFor({
+                spaceId: 'local',
+                collectionId,
+                scheme: 'edv',
+                encryption,
+                keys: { keyAgreementKey, keyResolver }
+            });
+        }
+        catch (err) {
+            if (err instanceof KeyUnwrapError) {
+                throw new Error(`Cannot build the multi-recipient EDV cipher for collection ` +
+                    `"${collectionId}": the key-agreement key is not a recipient of any ` +
+                    'key epoch on this collection. The owner must be a recipient of ' +
+                    'every epoch (recipient zero) before writing, or it would encrypt ' +
+                    'envelopes it cannot itself read.', { cause: err });
+            }
+            throw err;
+        }
+        if (!epochCodec) {
+            throw new Error(`Could not build the multi-recipient EDV cipher for collection ` +
+                `"${collectionId}".`);
+        }
+    }
+    const vaultKid = keyAgreementKey.id;
+    const knownEpochKids = new Set((encryption?.epochs ?? []).map(epoch => epochKeyIdFor(epoch.id)));
+    // Parses the codec's `EncodedWrite` (id + envelope body bytes) to the stored
+    // `{ id, envelope, epoch? }` shape. Shared by the create and update paths.
+    const readEncoded = (encoded) => {
+        if (typeof encoded.id !== 'string' ||
+            !(encoded.body instanceof Uint8Array)) {
+            throw new Error(`EDV encrypt for collection "${collectionId}" returned no id/envelope body.`);
+        }
+        const envelope = JSON.parse(new TextDecoder().decode(encoded.body));
+        return {
+            id: encoded.id,
+            envelope,
+            ...(typeof encoded.epoch === 'string' && { epoch: encoded.epoch })
+        };
+    };
+    return {
+        async encrypt({ data }) {
+            // `encode` with no caller id is the add() path: encrypt, then either derive
+            // and stamp the content-hash id (`'content'`) or use the minted random id.
+            // Writes go under the current epoch on a multi-recipient cipher.
+            const codec = epochCodec ?? directCodec;
+            const encoded = await codec.encode({
+                data: data
+            });
+            return readEncoded(encoded);
+        },
+        async encryptUpdate({ id, data, current }) {
+            // The update path (mutable random-id head document): hand the codec the
+            // prior stored envelope so it advances `sequence` from it and re-encrypts
+            // under the same id.
+            const codec = epochCodec ?? directCodec;
+            const priorResponse = {
+                data: current,
+                json: async () => current,
+                headers: { get: () => null }
+            };
+            const encoded = await codec.encode({
+                id,
+                data: data,
+                current: priorResponse
+            });
+            const { id: encodedId, envelope } = readEncoded(encoded);
+            return { id: encodedId, envelope };
+        },
+        async decrypt({ envelope }) {
+            // Route by the envelope's JWE recipient kids:
+            //   1. any kid is the key-agreement key id -- a pre-epoch envelope, so the
+            //      direct codec (permanent tolerance, not a migration shim);
+            //   2. else, on an epoch cipher, any kid names a known epoch -- the epoch
+            //      codec;
+            //   3. else UnknownEpochError: the marker is likely stale, or a single-key
+            //      cipher met an envelope encrypted to a different key entirely.
+            const kids = envelopeRecipientKids(envelope);
+            const codec = selectCodec();
+            const response = {
+                data: envelope,
+                json: async () => envelope
+            };
+            return (await codec.decode(response));
+            function selectCodec() {
+                if (kids.some(kid => kid === vaultKid)) {
+                    return directCodec;
+                }
+                if (epochCodec && kids.some(kid => knownEpochKids.has(kid))) {
+                    return epochCodec;
+                }
+                // A malformed/empty-kid envelope falls through to the direct codec so it
+                // can surface its own decrypt error; a non-empty set of unroutable kids
+                // is the stale-marker signal.
+                if (kids.length === 0) {
+                    return directCodec;
+                }
+                throw new UnknownEpochError({ collectionId, kids });
+            }
+        }
+    };
+}
+//# sourceMappingURL=docCipher.js.map

package/dist/edv/docCipher.js.map

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

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

@@ -1 +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"}
+{"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;AAQpB;;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+FpC"}

package/dist/edv/epochKeys.js

@@ -1,5 +1,6 @@
-import { KeyUnwrapError } from '../errors.js';
+import { IntegrityError, KeyUnwrapError } from '../errors.js';
 import { epochKeyIdFor, reconstructEpochKeyPair, unwrapEpochSecret } from './epochCrypto.js';
+import { verifyEpochsMac } from './epochMac.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
@@ -33,7 +34,7 @@ export async function resolveEpochKeys({ encryption, keyAgreementKey }) {
     // 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
+    // recipient of `currentEpoch` is a removed/archive 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.
@@ -42,23 +43,49 @@ export async function resolveEpochKeys({ encryption, keyAgreementKey }) {
         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({
+    // EDV cipher can name recipients with and encrypt under right away. Its raw
+    // secret is surfaced alongside so the epoch-configuration MAC can be verified.
+    const writeUnwrapped = await unwrapEpochKey({
         epoch: writeEpochEntry,
         keyAgreementKey
     });
-    if (!writeKey) {
+    if (!writeUnwrapped) {
         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.');
     }
+    const writeKey = writeUnwrapped.key;
+    // Authenticate the epoch configuration when this reader holds the marker's
+    // `currentEpoch` (its write epoch IS `currentEpoch`) and the marker carries a
+    // MAC. A reader whose write epoch is an older held epoch cannot key the MAC
+    // (its secret is not the current epoch's), so it skips verification -- its
+    // writes are rejected server-side via its revoked zcap anyway. An absent MAC
+    // is a legacy marker, accepted.
+    if (writeEpochEntry.id === encryption.currentEpoch &&
+        encryption.epochsMac !== undefined) {
+        const { v, alg } = encryption.epochsMac;
+        if (v !== 1 || alg !== 'HS256') {
+            throw new IntegrityError('The epoch configuration failed to authenticate: its MAC declares an ' +
+                `unsupported construction (v=${v}, alg="${alg}"). This is a ` +
+                'server-side rollback or tamper.');
+        }
+        const authentic = await verifyEpochsMac({
+            marker: encryption,
+            epochSecret: writeUnwrapped.secret
+        });
+        if (!authentic) {
+            throw new IntegrityError('The epoch configuration failed to authenticate; a server-side ' +
+                'rollback or tamper of the encryption marker was detected (the ' +
+                'MAC over its epoch configuration does not verify).');
+        }
+    }
     // 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
+    // resources -- never pays the ECDH + KDF + key-unwrap for archive epochs it
     // does not read.
     const readKeys = [writeKey];
     for (const epoch of namedEpochs) {
@@ -71,12 +98,15 @@ export async function resolveEpochKeys({ encryption, keyAgreementKey }) {
 /**
  * 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).
+ * unwrap (a corrupt entry -- never treat `null` as a key). Returns the raw
+ * 32-byte epoch secret alongside the reconstructed key pair, so a caller that
+ * must authenticate the epoch configuration (the `epochsMac`) can key the MAC
+ * without re-unwrapping.
  *
  * @param options {object}
  * @param options.epoch {CollectionEncryptionEpoch}   the epoch to unwrap
  * @param options.keyAgreementKey {IKeyAgreementKey}   the reader's own KAK
- * @returns {Promise<IKeyAgreementKey | null>}
+ * @returns {Promise<{ key: IKeyAgreementKey; secret: Uint8Array } | null>}
  */
 async function unwrapEpochKey({ epoch, keyAgreementKey }) {
     const entry = epoch.recipients.find(recipient => recipient.header.kid === keyAgreementKey.id);
@@ -87,7 +117,7 @@ async function unwrapEpochKey({ epoch, keyAgreementKey }) {
     if (!secret) {
         return null;
     }
-    return reconstructEpochKeyPair({ epochId: epoch.id, secret });
+    return { key: reconstructEpochKeyPair({ epochId: epoch.id, secret }), secret };
 }
 /**
  * Builds a lazily-unwrapping read key for a named epoch: an `IKeyAgreementKey`
@@ -107,16 +137,16 @@ function lazyEpochKey({ epoch, keyAgreementKey }) {
     let pending;
     const resolve = () => {
         if (pending === undefined) {
-            const promise = 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.
+            const promise = unwrapEpochKey({ epoch, keyAgreementKey }).then(unwrapped => {
+                if (!unwrapped) {
+                    // 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 unwrapped.key;
             });
             // Cache only a successful unwrap: drop a rejected promise so the next
             // read re-attempts (the failure may have been transient), rather than

package/dist/edv/epochKeys.js.map

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

package/dist/edv/epochMac.d.ts

@@ -0,0 +1,32 @@
+import type { CollectionEncryption, CollectionEncryptionEpochsMac } from '../types.js';
+/**
+ * Computes the `epochsMac` field for a marker under the current epoch's secret.
+ * Compute this over the exact marker state being written (member fields already
+ * stamped), since a compare-and-swap retry re-reads the marker.
+ *
+ * @param options {object}
+ * @param options.marker {CollectionEncryption}   the marker being written
+ * @param options.epochSecret {Uint8Array}   the 32-byte current epoch secret
+ * @returns {Promise<CollectionEncryptionEpochsMac>}
+ */
+export declare function computeEpochsMac({ marker, epochSecret }: {
+    marker: CollectionEncryption;
+    epochSecret: Uint8Array;
+}): Promise<CollectionEncryptionEpochsMac>;
+/**
+ * Verifies a marker's `epochsMac` against a recomputation from the current
+ * epoch's secret. Returns `false` on any mismatch (or a malformed `mac`); the
+ * caller decides the error semantics. The MAC construction's own version/alg
+ * (`v` / `alg`) is validated by the caller before this is called.
+ *
+ * @param options {object}
+ * @param options.marker {CollectionEncryption}   the marker to verify (its
+ *   `epochsMac.mac` is the tag under test)
+ * @param options.epochSecret {Uint8Array}   the 32-byte current epoch secret
+ * @returns {Promise<boolean>}
+ */
+export declare function verifyEpochsMac({ marker, epochSecret }: {
+    marker: CollectionEncryption;
+    epochSecret: Uint8Array;
+}): Promise<boolean>;
+//# sourceMappingURL=epochMac.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"epochMac.d.ts","sourceRoot":"","sources":["../../src/edv/epochMac.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,oBAAoB,EACpB,6BAA6B,EAC9B,MAAM,aAAa,CAAA;AAwEpB;;;;;;;;;GASG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,MAAM,EACN,WAAW,EACZ,EAAE;IACD,MAAM,EAAE,oBAAoB,CAAA;IAC5B,WAAW,EAAE,UAAU,CAAA;CACxB,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAQzC;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CAAC,EACpC,MAAM,EACN,WAAW,EACZ,EAAE;IACD,MAAM,EAAE,oBAAoB,CAAA;IAC5B,WAAW,EAAE,UAAU,CAAA;CACxB,GAAG,OAAO,CAAC,OAAO,CAAC,CAkBnB"}

package/dist/edv/epochMac.js

@@ -0,0 +1,117 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Authenticated epoch configuration for multi-recipient encrypted Collections:
+ * a MAC over a Collection `encryption` marker's epoch configuration, keyed from
+ * the current epoch's secret (which the server never holds). It lets a reader
+ * detect a server-side rollback of `currentEpoch` or a fabricated epoch list --
+ * a malicious server cannot forge a valid MAC without the epoch secret.
+ *
+ * The MAC covers only `scheme`, `version`, `currentEpoch`, and the ordered list
+ * of epoch ids -- deliberately NOT the recipient entries, so adding a recipient
+ * (which cannot be forged without the epoch secret anyway) does not invalidate
+ * the MAC. Covering `version` makes stripping the marker's scheme version
+ * MAC-detectable.
+ *
+ * Documented limitation (mirrors Cryptomator's versionMac): a server can still
+ * replay an ENTIRE prior consistent configuration (an old epoch list with its
+ * matching old MAC). Detecting that needs client-side monotonic state, which is
+ * out of scope here.
+ */
+import { base64urlnopad } from '@scure/base';
+const TEXT_ENCODER = new TextEncoder();
+/**
+ * The HKDF `info` string binding the derived key to this MAC construction.
+ */
+const MAC_KEY_INFO = TEXT_ENCODER.encode('was-epoch-config-mac/v1');
+/**
+ * The domain-separation prefix prepended to the JSON payload before it is MACed.
+ */
+const MAC_PAYLOAD_PREFIX = 'was-epoch-config/v1.';
+/**
+ * Derives the HMAC-SHA256 key from a 32-byte epoch secret:
+ * HKDF-SHA256(ikm = the epoch secret, salt = empty, info =
+ * "was-epoch-config-mac/v1", length 32 bytes). Uses WebCrypto (`crypto.subtle`)
+ * so it works unchanged in Node 24 and browsers.
+ *
+ * @param epochSecret {Uint8Array}   the 32-byte current epoch secret
+ * @returns {Promise<CryptoKey>}   the derived HMAC key (sign + verify)
+ */
+async function deriveMacKey(epochSecret) {
+    const ikm = await crypto.subtle.importKey('raw', epochSecret, 'HKDF', false, ['deriveKey']);
+    return crypto.subtle.deriveKey({
+        name: 'HKDF',
+        hash: 'SHA-256',
+        salt: new Uint8Array(0),
+        info: MAC_KEY_INFO
+    }, ikm, { name: 'HMAC', hash: 'SHA-256', length: 256 }, false, ['sign', 'verify']);
+}
+/**
+ * Builds the MACed payload bytes for a marker's epoch configuration:
+ * `UTF8("was-epoch-config/v1." + JSON.stringify({ scheme, version,
+ * currentEpoch, epochs }))`, with `version` normalized to `null` when absent
+ * and `epochs` the ordered list of epoch id strings. The object member order is
+ * fixed so both sides serialize identically.
+ *
+ * @param marker {CollectionEncryption}   the marker whose epoch configuration is
+ *   being authenticated
+ * @returns {Uint8Array}
+ */
+function macPayload(marker) {
+    const payload = {
+        scheme: marker.scheme,
+        version: marker.version ?? null,
+        currentEpoch: marker.currentEpoch,
+        epochs: (marker.epochs ?? []).map(epoch => epoch.id)
+    };
+    const bytes = TEXT_ENCODER.encode(MAC_PAYLOAD_PREFIX + JSON.stringify(payload));
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+}
+/**
+ * Computes the `epochsMac` field for a marker under the current epoch's secret.
+ * Compute this over the exact marker state being written (member fields already
+ * stamped), since a compare-and-swap retry re-reads the marker.
+ *
+ * @param options {object}
+ * @param options.marker {CollectionEncryption}   the marker being written
+ * @param options.epochSecret {Uint8Array}   the 32-byte current epoch secret
+ * @returns {Promise<CollectionEncryptionEpochsMac>}
+ */
+export async function computeEpochsMac({ marker, epochSecret }) {
+    const key = await deriveMacKey(epochSecret);
+    const signature = await crypto.subtle.sign('HMAC', key, macPayload(marker));
+    return {
+        v: 1,
+        alg: 'HS256',
+        mac: base64urlnopad.encode(new Uint8Array(signature))
+    };
+}
+/**
+ * Verifies a marker's `epochsMac` against a recomputation from the current
+ * epoch's secret. Returns `false` on any mismatch (or a malformed `mac`); the
+ * caller decides the error semantics. The MAC construction's own version/alg
+ * (`v` / `alg`) is validated by the caller before this is called.
+ *
+ * @param options {object}
+ * @param options.marker {CollectionEncryption}   the marker to verify (its
+ *   `epochsMac.mac` is the tag under test)
+ * @param options.epochSecret {Uint8Array}   the 32-byte current epoch secret
+ * @returns {Promise<boolean>}
+ */
+export async function verifyEpochsMac({ marker, epochSecret }) {
+    const epochsMac = marker.epochsMac;
+    if (!epochsMac) {
+        return false;
+    }
+    let mac;
+    try {
+        mac = base64urlnopad.decode(epochsMac.mac);
+    }
+    catch {
+        return false;
+    }
+    const key = await deriveMacKey(epochSecret);
+    return crypto.subtle.verify('HMAC', key, mac, macPayload(marker));
+}
+//# sourceMappingURL=epochMac.js.map

package/dist/edv/epochMac.js.map

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

package/dist/edv/index.d.ts

@@ -27,4 +27,6 @@ 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';
+export { createEdvDocCipher, ownerRecipient, UnknownEpochError, isEncryptedEnvelope } from './docCipher.js';
+export type { DocCipher } from './docCipher.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;;;;;;;;;;;;;;;;;;;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"}
+{"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;AAC3D,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA"}

package/dist/edv/index.js

@@ -25,4 +25,5 @@ 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';
+export { createEdvDocCipher, ownerRecipient, UnknownEpochError, isEncryptedEnvelope } from './docCipher.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;;;;;;;;;;;;;;;;;;;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"}
+{"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;AAC3D,OAAO,EACL,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,gBAAgB,CAAA"}

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

@@ -1 +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;AAGxC,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,CAuDhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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,CAuFhC"}
+{"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;AAGxC,OAAO,KAAK,EACV,oBAAoB,EAEpB,cAAc,EACf,MAAM,aAAa,CAAA;AAQpB,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,CAyChC;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,CAuDhC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;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,CA+FhC"}