@interop/was-client 0.53.0 → 0.54.0

package/README.md

@@ -905,17 +905,21 @@ plugs into:
   `ETag`. The port moves stored bodies **verbatim** -- for an encrypted
   collection that means the opaque EDV envelope, never plaintext, and the port
   itself never touches keys. A rejected precondition throws
-  `WasSyncConflictError` (412); a delete of an already-gone resource throws
-  `WasSyncNotFoundError` (404) -- both catchable subtypes of the core
-  `PreconditionFailedError` / `NotFoundError`. Every other failure arrives as
-  the typed `WasError` subclass for its status, carrying the server's
-  `problem+json` fields.
+  `WasSyncConflictError` (412); a delete of an already-gone resource or a
+  `putMeta` against one throws `WasSyncNotFoundError` (404) -- both catchable
+  subtypes of the core `PreconditionFailedError` / `NotFoundError`. Every other
+  failure arrives as the typed `WasError` subclass for its status, carrying the
+  server's `problem+json` fields.
 - **`isSyncConflictError` / `isSyncNotFoundError` / `isSyncAuthError` /
-  `isUnknownEpochError`** classify those signals by `err.name`. Use them rather
-  than `instanceof`: the port and the `DocCipher` are seams your app injects,
-  and a tree that resolves two copies of this package makes an `instanceof`
-  check quietly false. Read what you need off the matched value, such as
-  `err.status` on an auth error to tell a 401 from the masked 404.
+  `isUnknownEpochError` / `isKeyUnwrapError`** classify those signals by
+  `err.name`. Use them rather than `instanceof`: the port and the `DocCipher`
+  are seams your app injects, and a tree that resolves two copies of this
+  package makes an `instanceof` check quietly false. Read what you need off the
+  matched value, such as `err.status` on an auth error to tell a 401 from the
+  masked 404. The last two tell a decrypt's two no-key outcomes apart: an epoch
+  the reader's descriptor does not list (a re-read may fix it) and an epoch it
+  lists but this reader holds no key for (real data, permanently unreadable
+  here, never garbage).
 - **`SyncStatus`** (`'idle' | 'syncing' | 'synced' | 'error'`) is the closed
   vocabulary a replication driver reports one feed's state through.
 - **`DocCipher`** is the per-collection encrypt/decrypt seam sitting above the
@@ -932,6 +936,21 @@ plugs into:
   counterpart, built from the descriptor alone with no key-agreement secret
   (writes seal to the current epoch's public key, reconstructed from the epoch
   id); `decrypt` on it refuses with the typed `EncryptOnlyCipherError`.
+- **`createRefreshingEdvDocCipher(...)`** (from `@interop/was-client/edv`) is
+  `createEdvDocCipher` bound to descriptor acquisition and the unknown-epoch
+  refresh rule: it acquires the collection's descriptor through the
+  `EncryptionDescriptorSource` / `EncryptionDescriptorCache` seams
+  (`wasDescriptorSource` is the source over a `WasClient`; the cache is a
+  client-local get/put your app scopes to one Space), refuses fail-closed to
+  build without one, and on an `UnknownEpochError` decrypt re-reads the
+  descriptor, swaps itself, and retries exactly once per instance. An epoch
+  rotation emits no change-feed entry, so this is how a replica meets an
+  envelope sealed under an epoch it has never seen without a refetch per
+  resource. `acquireDescriptor` / `acquireDescriptors` are the acquisition alone
+  (fetch, cache the success, fall back to the cache whenever the fetch yields no
+  descriptor), and `DescriptorRefreshPolicy` is the
+  once-per-collection-per-session guard for a host whose reads scan rows instead
+  of going through a cipher.
 - **`contentCid(doc)`** and **`deriveSpaceId(controllerDid)`** derive
   content-addressed ids -- `base64url(SHA-256(utf8(JCS-canonicalized JSON)))`,
   unpadded -- so the same logical document (and the same controller) lands on
@@ -940,7 +959,9 @@ plugs into:
   Space, configure the collection (`edv`, `plaintext`, or `governed`, optionally
   world-readable). Safe to re-run on every connect. A `governed` collection is
   created with no `encryption` member, the caller declaring governance
-  afterwards through the history log's guarded create.
+  afterwards through the history log's guarded create. An optional `capability`
+  is the invocation capability every request rides, for a client holding a
+  delegated zcap rather than the Space's root authority.
 
 ```ts
 import {

package/dist/edv/acquire.d.ts

@@ -0,0 +1,98 @@
+import type { CollectionEncryption } from '../types.js';
+import type { WasClient } from '../WasClient.js';
+/**
+ * Where descriptors come from: one signed read of the collection's
+ * Description. Resolves `undefined` when the description carries no encryption
+ * member -- which a WAS host also serves for a read this client is not
+ * authorized to make, so the absence is ambiguous and callers fall back to a
+ * cached copy just as they do for a thrown fetch. Network errors throw through
+ * (callers treat the fetch as best-effort).
+ */
+export interface EncryptionDescriptorSource {
+    collectionEncryption(options: {
+        collectionId: string;
+    }): Promise<CollectionEncryption | undefined>;
+}
+/**
+ * Where fetched descriptors survive offline: a client-local get/put
+ * pre-scoped by the host to one Space. `readDescriptor` resolves `undefined`
+ * when nothing is cached (never throws for absence).
+ */
+export interface EncryptionDescriptorCache {
+    readDescriptor(options: {
+        collectionId: string;
+    }): Promise<CollectionEncryption | undefined>;
+    writeDescriptor(options: {
+        collectionId: string;
+        descriptor: CollectionEncryption;
+    }): Promise<void>;
+}
+/**
+ * The {@link EncryptionDescriptorSource} over a was-client handle: reads the
+ * collection's Description in the given Space and returns its `encryption`
+ * descriptor.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   a client whose signer can read the Space
+ * @param options.spaceId {string}
+ * @returns {EncryptionDescriptorSource}
+ */
+export declare function wasDescriptorSource({ was, spaceId }: {
+    was: WasClient;
+    spaceId: string;
+}): EncryptionDescriptorSource;
+/**
+ * Acquires one collection's descriptor: fetches it from the source, caching a
+ * success; falls back to the cached copy whenever the fetch yields no
+ * descriptor (it threw, or it came back empty -- a masked 404 for an
+ * unauthorized read looks exactly like an unencrypted collection); and with no
+ * source at all (a purely local code path) reads the cache alone. Any cached
+ * copy is deliberately left in place, never cleared by an empty fetch.
+ * `undefined` means no descriptor exists anywhere for this collection.
+ *
+ * @param options {object}
+ * @param [options.source] {EncryptionDescriptorSource}   omit for cache-only
+ *   acquisition
+ * @param options.cache {EncryptionDescriptorCache}
+ * @param options.collectionId {string}
+ * @param [options.onFetchError] {function}   observes a swallowed fetch
+ *   failure (the thrown-fetch branch only; an empty description is not an
+ *   error). Errors from the cache itself throw through, as do a log-governed
+ *   source's refusal classes (a fabricated or discontinuous log is a security
+ *   signal, not an outage the cache should paper over) -- except a continuity
+ *   `rollback`, which falls back to the cache like any transport hiccup
+ * @returns {Promise<CollectionEncryption | undefined>}
+ */
+export declare function acquireDescriptor({ source, cache, collectionId, onFetchError }: {
+    source?: EncryptionDescriptorSource;
+    cache: EncryptionDescriptorCache;
+    collectionId: string;
+    onFetchError?: (err: unknown, info: {
+        collectionId: string;
+    }) => void;
+}): Promise<CollectionEncryption | undefined>;
+/**
+ * Acquires descriptors for a set of collections concurrently (each fetch is an
+ * independent signed round trip, so a session start is not gated on a serial
+ * chain of describes). Collections that resolve no descriptor are simply
+ * absent from the result.
+ *
+ * @param options {object}
+ * @param [options.source] {EncryptionDescriptorSource}   omit for cache-only
+ *   acquisition
+ * @param options.cache {EncryptionDescriptorCache}
+ * @param options.collectionIds {string[]}
+ * @param [options.onFetchError] {function}   observes each swallowed fetch
+ *   failure
+ * @returns {Promise<Record<string, CollectionEncryption>>}   keyed by
+ *   collection id
+ */
+export declare function acquireDescriptors({ source, cache, collectionIds, onFetchError }: {
+    source?: EncryptionDescriptorSource;
+    cache: EncryptionDescriptorCache;
+    collectionIds: string[];
+    onFetchError?: (err: unknown, info: {
+        collectionId: string;
+    }) => void;
+}): Promise<Record<string, CollectionEncryption>>;
+//# sourceMappingURL=acquire.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"acquire.d.ts","sourceRoot":"","sources":["../../src/edv/acquire.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD;;;;;;;GAOG;AACH,MAAM,WAAW,0BAA0B;IACzC,oBAAoB,CAAC,OAAO,EAAE;QAC5B,YAAY,EAAE,MAAM,CAAA;KACrB,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAA;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACxC,cAAc,CAAC,OAAO,EAAE;QACtB,YAAY,EAAE,MAAM,CAAA;KACrB,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAA;IAC7C,eAAe,CAAC,OAAO,EAAE;QACvB,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,oBAAoB,CAAA;KACjC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,OAAO,EACR,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,0BAA0B,CAU7B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,MAAM,EACN,KAAK,EACL,YAAY,EACZ,YAAY,EACb,EAAE;IACD,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,KAAK,EAAE,yBAAyB,CAAA;IAChC,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACtE,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAwB5C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,MAAM,EACN,KAAK,EACL,aAAa,EACb,YAAY,EACb,EAAE;IACD,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,KAAK,EAAE,yBAAyB,CAAA;IAChC,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACtE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC,CAiBhD"}

package/dist/edv/acquire.js

@@ -0,0 +1,130 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Collection encryption-descriptor acquisition: reading a collection's
+ * `CollectionEncryption` descriptor (its key-epoch roster) from the Collection
+ * Description, caching each success, and falling back to the cached copy
+ * whenever the description yields no descriptor -- whether it could not be
+ * fetched at all (offline, a collection must keep encrypting under its current
+ * epoch) or came back empty (WAS masks an unauthorized read as an absent one,
+ * so an empty description is ambiguous, never an authoritative "no
+ * encryption"). `undefined` therefore means only this: nothing, fetched or
+ * cached, describes this collection's encryption -- a plaintext collection, or
+ * an encrypted one whose epoch[0] install has not landed. A caller that has
+ * declared the collection encrypted must refuse fail-closed rather than
+ * encrypt without a roster.
+ *
+ * The two seams are deliberately narrow, so a consumer's own classes satisfy
+ * them structurally -- no adapter needed. An {@link EncryptionDescriptorSource}
+ * is one signed describe; an {@link EncryptionDescriptorCache} is a
+ * client-local get/put the host has already scoped to one Space (a web app: a
+ * localStorage pair keyed by Space id; a mobile app: a per-(profile,
+ * collection) table column), so no scope key appears in the interface.
+ *
+ * A source over a log-governed descriptor throws the resource-log refusal
+ * classes, and those are security signals rather than outages: the read path
+ * rethrows them past a warm cache, matched by `@interop/vh-resource-log`'s
+ * `isResourceLogRefusal` (a continuity `rollback` is the one carve-out, and
+ * falls back to the cache like a transport failure).
+ */
+import { isResourceLogRefusal } from '@interop/vh-resource-log';
+/**
+ * The {@link EncryptionDescriptorSource} over a was-client handle: reads the
+ * collection's Description in the given Space and returns its `encryption`
+ * descriptor.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   a client whose signer can read the Space
+ * @param options.spaceId {string}
+ * @returns {EncryptionDescriptorSource}
+ */
+export function wasDescriptorSource({ was, spaceId }) {
+    return {
+        async collectionEncryption({ collectionId }) {
+            const description = await was
+                .space(spaceId)
+                .collection(collectionId)
+                .describe();
+            return description?.encryption ?? undefined;
+        }
+    };
+}
+/**
+ * Acquires one collection's descriptor: fetches it from the source, caching a
+ * success; falls back to the cached copy whenever the fetch yields no
+ * descriptor (it threw, or it came back empty -- a masked 404 for an
+ * unauthorized read looks exactly like an unencrypted collection); and with no
+ * source at all (a purely local code path) reads the cache alone. Any cached
+ * copy is deliberately left in place, never cleared by an empty fetch.
+ * `undefined` means no descriptor exists anywhere for this collection.
+ *
+ * @param options {object}
+ * @param [options.source] {EncryptionDescriptorSource}   omit for cache-only
+ *   acquisition
+ * @param options.cache {EncryptionDescriptorCache}
+ * @param options.collectionId {string}
+ * @param [options.onFetchError] {function}   observes a swallowed fetch
+ *   failure (the thrown-fetch branch only; an empty description is not an
+ *   error). Errors from the cache itself throw through, as do a log-governed
+ *   source's refusal classes (a fabricated or discontinuous log is a security
+ *   signal, not an outage the cache should paper over) -- except a continuity
+ *   `rollback`, which falls back to the cache like any transport hiccup
+ * @returns {Promise<CollectionEncryption | undefined>}
+ */
+export async function acquireDescriptor({ source, cache, collectionId, onFetchError }) {
+    if (!source) {
+        return cache.readDescriptor({ collectionId });
+    }
+    try {
+        const fetched = await source.collectionEncryption({ collectionId });
+        if (fetched) {
+            await cache.writeDescriptor({ collectionId, descriptor: fetched });
+            return fetched;
+        }
+        // Empty description: not authoritative (an unauthorized read is masked as
+        // an absent one), so a warm cache still serves the collection.
+        return cache.readDescriptor({ collectionId });
+    }
+    catch (err) {
+        // A resource-log refusal the cache must not paper over -- a fabricated
+        // log, or one that is not the continuation of the pinned history. A
+        // rollback is not one of them and falls through to the cache, as any
+        // transport failure does.
+        if (isResourceLogRefusal(err)) {
+            throw err;
+        }
+        onFetchError?.(err, { collectionId });
+        return cache.readDescriptor({ collectionId });
+    }
+}
+/**
+ * Acquires descriptors for a set of collections concurrently (each fetch is an
+ * independent signed round trip, so a session start is not gated on a serial
+ * chain of describes). Collections that resolve no descriptor are simply
+ * absent from the result.
+ *
+ * @param options {object}
+ * @param [options.source] {EncryptionDescriptorSource}   omit for cache-only
+ *   acquisition
+ * @param options.cache {EncryptionDescriptorCache}
+ * @param options.collectionIds {string[]}
+ * @param [options.onFetchError] {function}   observes each swallowed fetch
+ *   failure
+ * @returns {Promise<Record<string, CollectionEncryption>>}   keyed by
+ *   collection id
+ */
+export async function acquireDescriptors({ source, cache, collectionIds, onFetchError }) {
+    const resolved = await Promise.all(collectionIds.map(async (collectionId) => [
+        collectionId,
+        await acquireDescriptor({ source, cache, collectionId, onFetchError })
+    ]));
+    const descriptors = {};
+    for (const [collectionId, descriptor] of resolved) {
+        if (descriptor) {
+            descriptors[collectionId] = descriptor;
+        }
+    }
+    return descriptors;
+}
+//# sourceMappingURL=acquire.js.map

package/dist/edv/acquire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acquire.js","sourceRoot":"","sources":["../../src/edv/acquire.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAiC/D;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAClC,GAAG,EACH,OAAO,EAIR;IACC,OAAO;QACL,KAAK,CAAC,oBAAoB,CAAC,EAAE,YAAY,EAAE;YACzC,MAAM,WAAW,GAAG,MAAM,GAAG;iBAC1B,KAAK,CAAC,OAAO,CAAC;iBACd,UAAU,CAAC,YAAY,CAAC;iBACxB,QAAQ,EAAE,CAAA;YACb,OAAO,WAAW,EAAE,UAAU,IAAI,SAAS,CAAA;QAC7C,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,EACtC,MAAM,EACN,KAAK,EACL,YAAY,EACZ,YAAY,EAMb;IACC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,KAAK,CAAC,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC,CAAA;IAC/C,CAAC;IACD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,oBAAoB,CAAC,EAAE,YAAY,EAAE,CAAC,CAAA;QACnE,IAAI,OAAO,EAAE,CAAC;YACZ,MAAM,KAAK,CAAC,eAAe,CAAC,EAAE,YAAY,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAA;YAClE,OAAO,OAAO,CAAA;QAChB,CAAC;QACD,0EAA0E;QAC1E,+DAA+D;QAC/D,OAAO,KAAK,CAAC,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC,CAAA;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,uEAAuE;QACvE,oEAAoE;QACpE,qEAAqE;QACrE,0BAA0B;QAC1B,IAAI,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,GAAG,CAAA;QACX,CAAC;QACD,YAAY,EAAE,CAAC,GAAG,EAAE,EAAE,YAAY,EAAE,CAAC,CAAA;QACrC,OAAO,KAAK,CAAC,cAAc,CAAC,EAAE,YAAY,EAAE,CAAC,CAAA;IAC/C,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,MAAM,EACN,KAAK,EACL,aAAa,EACb,YAAY,EAMb;IACC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAChC,aAAa,CAAC,GAAG,CACf,KAAK,EAAC,YAAY,EAAC,EAAE,CACnB;QACE,YAAY;QACZ,MAAM,iBAAiB,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;KAC9D,CACb,CACF,CAAA;IACD,MAAM,WAAW,GAAyC,EAAE,CAAA;IAC5D,KAAK,MAAM,CAAC,YAAY,EAAE,UAAU,CAAC,IAAI,QAAQ,EAAE,CAAC;QAClD,IAAI,UAAU,EAAE,CAAC;YACf,WAAW,CAAC,YAAY,CAAC,GAAG,UAAU,CAAA;QACxC,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAA;AACpB,CAAC"}

package/dist/edv/index.d.ts

@@ -50,8 +50,36 @@
  * cannot help). Both ship from this subpath beside the cipher that raises
  * them, so a consumer classifying what a cipher threw need not reach for the
  * package root. Both assign their `name` explicitly, and a consumer whose
- * cipher arrives through an injected seam should match on that name rather
- * than `instanceof`: the seam may resolve to a second copy of this package.
+ * cipher arrives through an injected seam matches on that name rather than
+ * `instanceof`, since the seam may resolve to a second copy of this package:
+ * `isKeyUnwrapError` here, and `isUnknownEpochError` on `./sync`, are those
+ * matchers.
+ *
+ * Which epoch a collection encrypts under, and when to ask again, is the
+ * descriptor acquisition and refresh policy every consumer running an
+ * encrypted collection must share (a drift between two replicas does not fail
+ * loudly; it fails as a resource one of them cannot decrypt):
+ *
+ * - `EncryptionDescriptorSource` / `EncryptionDescriptorCache` -- the narrow
+ *   seams a host implements: one signed Collection Description read, and a
+ *   client-local get/put pre-scoped to one Space. `wasDescriptorSource` is the
+ *   source over a `WasClient` handle.
+ * - `acquireDescriptor` / `acquireDescriptors` -- fetch + cache with the
+ *   cached fallback whenever the fetch yields no descriptor, thrown or empty
+ *   (offline, a collection keeps encrypting under its current epoch; an empty
+ *   description is ambiguous, since WAS masks an unauthorized read as an
+ *   absent one). No descriptor anywhere means a plaintext collection, or an
+ *   encrypted one whose epoch[0] install has not landed -- which a caller that
+ *   has declared the collection encrypted must refuse fail-closed. A
+ *   log-governed source's refusal classes rethrow instead of falling back
+ *   (except a continuity rollback, which is reconcilable divergence).
+ * - `DescriptorRefreshPolicy` -- the once-per-collection-per-session
+ *   unknown-epoch refresh guard, plus the refresh-and-re-read-once wrapper
+ *   for hosts whose reads scan rows and count unknown-epoch skips.
+ * - `createRefreshingEdvDocCipher` -- `createEdvDocCipher` bound to both: a
+ *   cipher that acquires its own descriptor and, on an unknown-epoch decrypt,
+ *   re-reads the description, swaps itself, and retries exactly once per
+ *   instance.
  */
 export { createEdvEncryption, EdvCodec, wasTransportFactory } from './EdvCodec.js';
 export type { CodecTransportFactory, EdvKeys } from './EdvCodec.js';
@@ -72,4 +100,9 @@ export { HMAC_KEY_TYPE, mintHmacKey, hmacKeyFromSecret, resolveHmacKey } from '.
 export type { BlindingKey } from './hmacKey.js';
 export { createEdvDocCipher, createEdvEncryptOnlyDocCipher, ownerRecipient, EncryptOnlyCipherError, KeyUnwrapError, UnknownEpochError, isEncryptedEnvelope } from './docCipher.js';
 export type { DocCipher, EdvDocCipher } from './docCipher.js';
+export { acquireDescriptor, acquireDescriptors, wasDescriptorSource } from './acquire.js';
+export type { EncryptionDescriptorCache, EncryptionDescriptorSource } from './acquire.js';
+export { DescriptorRefreshPolicy } from './refresh.js';
+export { createRefreshingEdvDocCipher } from './refreshingDocCipher.js';
+export { isKeyUnwrapError } from '../sync/predicates.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,mBAAmB,EACpB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACtE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,gBAAgB,EACjB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EACL,eAAe,EACf,yBAAyB,EAC1B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAA;AACrE,OAAO,EACL,8BAA8B,EAC9B,oCAAoC,EACpC,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EAC1B,MAAM,iCAAiC,CAAA;AACxC,YAAY,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AACjF,OAAO,EACL,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACvD,OAAO,EACL,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,EACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EACL,kBAAkB,EAClB,6BAA6B,EAC7B,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,mBAAmB,EACpB,MAAM,eAAe,CAAA;AACtB,YAAY,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACnE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACtE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,gBAAgB,EACjB,MAAM,iBAAiB,CAAA;AACxB,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,EACL,eAAe,EACf,yBAAyB,EAC1B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,yBAAyB,EAAE,MAAM,sBAAsB,CAAA;AACrE,OAAO,EACL,8BAA8B,EAC9B,oCAAoC,EACpC,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EAC1B,MAAM,iCAAiC,CAAA;AACxC,YAAY,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAA;AACjF,OAAO,EACL,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AACjD,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACvD,OAAO,EACL,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,EACf,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,EACL,kBAAkB,EAClB,6BAA6B,EAC7B,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAC7D,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC3B,MAAM,cAAc,CAAA;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAA;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/edv/index.js

@@ -50,8 +50,36 @@
  * cannot help). Both ship from this subpath beside the cipher that raises
  * them, so a consumer classifying what a cipher threw need not reach for the
  * package root. Both assign their `name` explicitly, and a consumer whose
- * cipher arrives through an injected seam should match on that name rather
- * than `instanceof`: the seam may resolve to a second copy of this package.
+ * cipher arrives through an injected seam matches on that name rather than
+ * `instanceof`, since the seam may resolve to a second copy of this package:
+ * `isKeyUnwrapError` here, and `isUnknownEpochError` on `./sync`, are those
+ * matchers.
+ *
+ * Which epoch a collection encrypts under, and when to ask again, is the
+ * descriptor acquisition and refresh policy every consumer running an
+ * encrypted collection must share (a drift between two replicas does not fail
+ * loudly; it fails as a resource one of them cannot decrypt):
+ *
+ * - `EncryptionDescriptorSource` / `EncryptionDescriptorCache` -- the narrow
+ *   seams a host implements: one signed Collection Description read, and a
+ *   client-local get/put pre-scoped to one Space. `wasDescriptorSource` is the
+ *   source over a `WasClient` handle.
+ * - `acquireDescriptor` / `acquireDescriptors` -- fetch + cache with the
+ *   cached fallback whenever the fetch yields no descriptor, thrown or empty
+ *   (offline, a collection keeps encrypting under its current epoch; an empty
+ *   description is ambiguous, since WAS masks an unauthorized read as an
+ *   absent one). No descriptor anywhere means a plaintext collection, or an
+ *   encrypted one whose epoch[0] install has not landed -- which a caller that
+ *   has declared the collection encrypted must refuse fail-closed. A
+ *   log-governed source's refusal classes rethrow instead of falling back
+ *   (except a continuity rollback, which is reconcilable divergence).
+ * - `DescriptorRefreshPolicy` -- the once-per-collection-per-session
+ *   unknown-epoch refresh guard, plus the refresh-and-re-read-once wrapper
+ *   for hosts whose reads scan rows and count unknown-epoch skips.
+ * - `createRefreshingEdvDocCipher` -- `createEdvDocCipher` bound to both: a
+ *   cipher that acquires its own descriptor and, on an unknown-epoch decrypt,
+ *   re-reads the description, swaps itself, and retries exactly once per
+ *   instance.
  */
 export { createEdvEncryption, EdvCodec, wasTransportFactory } from './EdvCodec.js';
 export { WasTransport } from './WasTransport.js';
@@ -65,4 +93,8 @@ export { hasKeyEpochs, epochRostersEqual } from './epochRoster.js';
 export { resolveEpochKeys } from './epochKeys.js';
 export { HMAC_KEY_TYPE, mintHmacKey, hmacKeyFromSecret, resolveHmacKey } from './hmacKey.js';
 export { createEdvDocCipher, createEdvEncryptOnlyDocCipher, ownerRecipient, EncryptOnlyCipherError, KeyUnwrapError, UnknownEpochError, isEncryptedEnvelope } from './docCipher.js';
+export { acquireDescriptor, acquireDescriptors, wasDescriptorSource } from './acquire.js';
+export { DescriptorRefreshPolicy } from './refresh.js';
+export { createRefreshingEdvDocCipher } from './refreshingDocCipher.js';
+export { isKeyUnwrapError } from '../sync/predicates.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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,mBAAmB,EACpB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACtE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,gBAAgB,EACjB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,eAAe,EACf,yBAAyB,EAC1B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,8BAA8B,EAC9B,oCAAoC,EACpC,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EAC1B,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEjD,OAAO,EACL,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,EACf,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,kBAAkB,EAClB,6BAA6B,EAC7B,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/edv/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,OAAO,EACL,mBAAmB,EACnB,QAAQ,EACR,mBAAmB,EACpB,MAAM,eAAe,CAAA;AAEtB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACtE,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,eAAe,EACf,gBAAgB,EACjB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,eAAe,EACf,yBAAyB,EAC1B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACxB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,8BAA8B,EAC9B,oCAAoC,EACpC,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EAC1B,MAAM,iCAAiC,CAAA;AAExC,OAAO,EACL,SAAS,EACT,aAAa,EACb,iBAAiB,EACjB,eAAe,EAChB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAEjD,OAAO,EACL,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,cAAc,EACf,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,kBAAkB,EAClB,6BAA6B,EAC7B,cAAc,EACd,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AAKrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AACtD,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAA;AACvE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/edv/refresh.d.ts

@@ -0,0 +1,62 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The unknown-epoch refresh policy: an epoch rotation emits no change-feed
+ * entry, so a cipher built from a cached descriptor can meet envelopes stamped
+ * with an epoch it has never seen. The remedy is one re-read of the
+ * Collection Description plus a cipher rebuild and a single retry -- and the
+ * policy guards that remedy to ONCE per collection per session, so a
+ * genuinely foreign envelope (one no descriptor will ever route) cannot drive
+ * a refetch loop, let alone a refetch per resource.
+ */
+/**
+ * Tracks which collections have already spent their one refresh this session,
+ * and runs reads under the refresh-and-retry-once rule. One instance per
+ * session (it IS the session scope of the guard); the injected `refresh` does
+ * the host's whole swap -- re-acquire the descriptor(s), rebuild the
+ * cipher(s), and install them wherever the host keeps them.
+ */
+export declare class DescriptorRefreshPolicy {
+    #private;
+    constructor({ refresh }: {
+        refresh: (options: {
+            collectionId: string;
+        }) => Promise<void>;
+    });
+    /**
+     * Whether a collection still has its one refresh this session.
+     */
+    shouldRefresh({ collectionId }: {
+        collectionId: string;
+    }): boolean;
+    /**
+     * Runs a read that reports whether it skipped unknown-epoch rows; on the
+     * first such report for a collection this session, spends the collection's
+     * refresh (descriptor re-read + cipher swap, via the injected `refresh`) and
+     * re-reads once. A later unknown-epoch report for the same collection
+     * returns the read's value as-is.
+     *
+     * @param options {object}
+     * @param options.collectionId {string}
+     * @param options.read {function}   the read, reporting `unknownEpoch`
+     * @returns {Promise<T>}   the (possibly re-read) value
+     */
+    readWithRefresh<T>({ collectionId, read }: {
+        collectionId: string;
+        read: () => Promise<{
+            value: T;
+            unknownEpoch: boolean;
+        }>;
+    }): Promise<T>;
+    /**
+     * Re-arms the guard -- for one collection, or (with no argument) for all.
+     * Call when a fresh descriptor is installed by some other path (a share,
+     * unshare, or recipient rotation this session performed itself), since the
+     * next unknown-epoch read is then evidence of a NEW rotation elsewhere.
+     */
+    reset(options?: {
+        collectionId?: string;
+    }): void;
+}
+//# sourceMappingURL=refresh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../src/edv/refresh.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,qBAAa,uBAAuB;;gBAKtB,EACV,OAAO,EACR,EAAE;QACD,OAAO,EAAE,CAAC,OAAO,EAAE;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KAC9D;IAID;;OAEG;IACH,aAAa,CAAC,EAAE,YAAY,EAAE,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO;IAIlE;;;;;;;;;;;OAWG;IACG,eAAe,CAAC,CAAC,EAAE,EACvB,YAAY,EACZ,IAAI,EACL,EAAE;QACD,YAAY,EAAE,MAAM,CAAA;QACpB,IAAI,EAAE,MAAM,OAAO,CAAC;YAAE,KAAK,EAAE,CAAC,CAAC;YAAC,YAAY,EAAE,OAAO,CAAA;SAAE,CAAC,CAAA;KACzD,GAAG,OAAO,CAAC,CAAC,CAAC;IAUd;;;;;OAKG;IACH,KAAK,CAAC,OAAO,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;CAOjD"}

package/dist/edv/refresh.js

@@ -0,0 +1,69 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The unknown-epoch refresh policy: an epoch rotation emits no change-feed
+ * entry, so a cipher built from a cached descriptor can meet envelopes stamped
+ * with an epoch it has never seen. The remedy is one re-read of the
+ * Collection Description plus a cipher rebuild and a single retry -- and the
+ * policy guards that remedy to ONCE per collection per session, so a
+ * genuinely foreign envelope (one no descriptor will ever route) cannot drive
+ * a refetch loop, let alone a refetch per resource.
+ */
+/**
+ * Tracks which collections have already spent their one refresh this session,
+ * and runs reads under the refresh-and-retry-once rule. One instance per
+ * session (it IS the session scope of the guard); the injected `refresh` does
+ * the host's whole swap -- re-acquire the descriptor(s), rebuild the
+ * cipher(s), and install them wherever the host keeps them.
+ */
+export class DescriptorRefreshPolicy {
+    #refresh;
+    // Collection ids whose one refresh this session is already spent.
+    #refreshed = new Set();
+    constructor({ refresh }) {
+        this.#refresh = refresh;
+    }
+    /**
+     * Whether a collection still has its one refresh this session.
+     */
+    shouldRefresh({ collectionId }) {
+        return !this.#refreshed.has(collectionId);
+    }
+    /**
+     * Runs a read that reports whether it skipped unknown-epoch rows; on the
+     * first such report for a collection this session, spends the collection's
+     * refresh (descriptor re-read + cipher swap, via the injected `refresh`) and
+     * re-reads once. A later unknown-epoch report for the same collection
+     * returns the read's value as-is.
+     *
+     * @param options {object}
+     * @param options.collectionId {string}
+     * @param options.read {function}   the read, reporting `unknownEpoch`
+     * @returns {Promise<T>}   the (possibly re-read) value
+     */
+    async readWithRefresh({ collectionId, read }) {
+        const first = await read();
+        if (first.unknownEpoch && this.shouldRefresh({ collectionId })) {
+            this.#refreshed.add(collectionId);
+            await this.#refresh({ collectionId });
+            return (await read()).value;
+        }
+        return first.value;
+    }
+    /**
+     * Re-arms the guard -- for one collection, or (with no argument) for all.
+     * Call when a fresh descriptor is installed by some other path (a share,
+     * unshare, or recipient rotation this session performed itself), since the
+     * next unknown-epoch read is then evidence of a NEW rotation elsewhere.
+     */
+    reset(options) {
+        if (options?.collectionId === undefined) {
+            this.#refreshed.clear();
+        }
+        else {
+            this.#refreshed.delete(options.collectionId);
+        }
+    }
+}
+//# sourceMappingURL=refresh.js.map

package/dist/edv/refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.js","sourceRoot":"","sources":["../../src/edv/refresh.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,MAAM,OAAO,uBAAuB;IACzB,QAAQ,CAAsD;IACvE,kEAAkE;IACzD,UAAU,GAAG,IAAI,GAAG,EAAU,CAAA;IAEvC,YAAY,EACV,OAAO,EAGR;QACC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAA;IACzB,CAAC;IAED;;OAEG;IACH,aAAa,CAAC,EAAE,YAAY,EAA4B;QACtD,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;IAC3C,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,eAAe,CAAI,EACvB,YAAY,EACZ,IAAI,EAIL;QACC,MAAM,KAAK,GAAG,MAAM,IAAI,EAAE,CAAA;QAC1B,IAAI,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;YAC/D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;YACjC,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,YAAY,EAAE,CAAC,CAAA;YACrC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,KAAK,CAAA;QAC7B,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAA;IACpB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAmC;QACvC,IAAI,OAAO,EAAE,YAAY,KAAK,SAAS,EAAE,CAAC;YACxC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAA;QACzB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAA;QAC9C,CAAC;IACH,CAAC;CACF"}

package/dist/edv/refreshingDocCipher.d.ts

@@ -0,0 +1,70 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * A self-refreshing EDV document cipher: `createEdvDocCipher` bound to
+ * descriptor acquisition and the once-per-session refresh rule, for a host
+ * whose decrypt seam is the cipher itself (a sync engine's `decryptDoc`, a
+ * conflict resolver) rather than a row-scanning store.
+ *
+ * Built, the cipher acquires the collection's descriptor (fetch, cache the
+ * success, cached fallback whenever the fetch yields none -- see
+ * `acquire.ts`) and constructs the underlying EDV cipher from it; with no
+ * descriptor, or a descriptor with no epochs, the build refuses fail-closed
+ * (every encrypted collection's descriptor carries an epoch roster from
+ * provisioning, so the absence can only mean the install has not landed or
+ * the host is lying). When a decrypt throws
+ * `UnknownEpochError`, the cipher re-acquires the descriptor, rebuilds itself,
+ * and retries that decrypt exactly once -- and only once per cipher instance,
+ * which the host scopes to one `(profile, collection)` session by dropping
+ * its cipher cache when the session ends. A second failure (or any unknown
+ * epoch after the one refresh is spent) propagates. A refresh that itself
+ * fails does not count as spent -- the original `UnknownEpochError` is
+ * rethrown and a later decrypt may try again.
+ *
+ * Only `UnknownEpochError` drives that refresh, and by design. The client
+ * splits the two ways a decrypt can find no key: an epoch the descriptor does
+ * not list at all raises `UnknownEpochError`, because a fresher descriptor may
+ * well list it; an epoch the descriptor does list but this reader holds no key
+ * for raises `KeyUnwrapError` (never a recipient, or removed and the epoch
+ * rotated). The second is rethrown immediately, with the refresh left
+ * untouched, since re-reading the same descriptor cannot produce a key the
+ * reader was not given.
+ */
+import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
+import { type DocCipher } from './docCipher.js';
+import { type EncryptionDescriptorCache, type EncryptionDescriptorSource } from './acquire.js';
+/**
+ * Builds a {@link DocCipher} whose descriptor is acquired through the
+ * source/cache seams and refreshed (once per instance) on an unknown-epoch
+ * decrypt.
+ *
+ * With no `source` the descriptor is served from the cache alone and the
+ * refresh path is inert (an unknown-epoch decrypt propagates immediately) --
+ * the shape for a purely local code path that must never touch the network.
+ *
+ * @param options {object}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the vault key pair this
+ *   collection's envelopes are sealed to
+ * @param options.keyResolver {IKeyResolver}
+ * @param options.collectionId {string}
+ * @param [options.idDerivation] {'content' | 'random'}   defaults to
+ *   `'content'`
+ * @param [options.source] {EncryptionDescriptorSource}
+ * @param options.cache {EncryptionDescriptorCache}
+ * @param [options.onFetchError] {function}   observes swallowed
+ *   descriptor-fetch failures
+ * @returns {Promise<DocCipher>}
+ */
+export declare function createRefreshingEdvDocCipher({ keyAgreementKey, keyResolver, collectionId, idDerivation, source, cache, onFetchError }: {
+    keyAgreementKey: IKeyAgreementKey;
+    keyResolver: IKeyResolver;
+    collectionId: string;
+    idDerivation?: 'content' | 'random';
+    source?: EncryptionDescriptorSource;
+    cache: EncryptionDescriptorCache;
+    onFetchError?: (err: unknown, info: {
+        collectionId: string;
+    }) => void;
+}): Promise<DocCipher>;
+//# sourceMappingURL=refreshingDocCipher.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refreshingDocCipher.d.ts","sourceRoot":"","sources":["../../src/edv/refreshingDocCipher.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAA;AAErC,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAChC,MAAM,cAAc,CAAA;AAErB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,4BAA4B,CAAC,EACjD,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,MAAM,EACN,KAAK,EACL,YAAY,EACb,EAAE;IACD,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;IACzB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAA;IACnC,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,KAAK,EAAE,yBAAyB,CAAA;IAChC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;CACtE,GAAG,OAAO,CAAC,SAAS,CAAC,CAyFrB"}