@interop/was-client 0.53.0 → 0.55.0

package/README.md

@@ -12,6 +12,7 @@
 - [Install](#install)
 - [Usage](#usage)
   - [Creating a client (signer + zcapClient)](#creating-a-client-signer--zcapclient)
+    - [Deriving a client from a secret or seed (`./identity`)](#deriving-a-client-from-a-secret-or-seed-identity)
   - [The handle model](#the-handle-model)
   - [Spaces](#spaces)
   - [Collections](#collections)
@@ -131,14 +132,44 @@ const was = WasClient.fromSigner({
 
 The `seed` is where a passphrase-, stored-secret-, or KMS-derived key plugs in:
 deriving the same 32-byte seed yields the same DID, and therefore access to the
-same spaces. (Apps with user accounts often derive the signer from a passphrase
-via `CapabilityAgent.fromSecret()` from `@digitalbazaar/webkms-client` -- not
-required, just a common alternative.)
+same spaces.
 
 `serverUrl` is the base for both URL building and zcap `invocationTarget`s, so
 the "server URL must equal the invocation target host:port" constraint holds by
 construction.
 
+#### Deriving a client from a secret or seed (`./identity`)
+
+Apps with user accounts usually do not hold a `did:key` signer directly -- they
+hold a passphrase, or a stored secret, and need to derive the same client from
+it every time. The `./identity` subpath does that derivation:
+
+```ts
+import { agentsFromSecret } from '@interop/was-client/identity'
+import { WasClient } from '@interop/was-client'
+
+const agents = await agentsFromSecret({ secret: 'the account secret' })
+
+const was = WasClient.fromSigner({
+  serverUrl: 'https://was.example',
+  signer: agents.keyAgent.getSigner()
+})
+```
+
+`agents.zcapClient` is the same client `fromSigner` builds, for callers that
+need it directly.
+
+The derivation is type-sensitive, so the secret is always a string: a
+passphrase, or the base64url text of random bytes, not the decoded bytes. To
+derive from an already-derived 32-byte seed instead, use
+`agentsFromSeed({ seed })`.
+
+The derivation is deterministic and permanent: the same secret, on any client,
+derives the same `did:key` and joins the same account. `agents.keyAgreementKey`
+and `agents.keyResolver` are the key-agreement key and resolver the `./edv`
+cipher takes, so a caller building an encrypted collection has both halves from
+one call.
+
 ### The delegation-proof suite
 
 Delegation proofs are signed with `eddsa-jcs-2022`. That cryptosuite
@@ -147,6 +178,10 @@ JSON-LD canonicalization and needs no document loader to serve the suite's
 context at signing time. Invocations are unaffected -- those ride HTTP
 signatures, not proofs.
 
+`zcapClientForSigner({ signer })`, exported from the package root, is the one
+`ZcapClient` construction site that hard-codes this suite; `fromSigner()` above
+builds its client through it, and so does every `./identity` derivation.
+
 The server has to verify `eddsa-jcs-2022` for grants from this client to be
 accepted. A server that verifies both it and the older `Ed25519Signature2020`
 accepts chains whose links mix the two, which is what a fleet upgrading at its
@@ -905,17 +940,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 +971,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 +994,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/WasClient.d.ts

@@ -9,7 +9,7 @@
  * (`grant`), capability-rebuilding (`fromCapability`), and the signed
  * escape-hatch (`request`).
  */
-import { ZcapClient } from '@interop/ezcap';
+import type { ZcapClient } from '@interop/ezcap';
 import type { HttpResponse } from '@interop/http-client';
 import type { EncryptionProvider } from './codec.js';
 import { Space } from './Space.js';

package/dist/WasClient.d.ts.map

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

package/dist/WasClient.js

@@ -1,16 +1,3 @@
-/*!
- * Copyright (c) 2026 Interop Alliance. All rights reserved.
- */
-/**
- * The top-level WAS client. Wraps an ezcap `ZcapClient` (which holds the active
- * signer) and exposes the WAS containment model
- * (`SpacesRepository > Space > Collection > Resource`) through lazy
- * navigational handles. Also hosts the general delegation primitive
- * (`grant`), capability-rebuilding (`fromCapability`), and the signed
- * escape-hatch (`request`).
- */
-import { ZcapClient } from '@interop/ezcap';
-import { EddsaJcs2022 } from '@interop/ed25519-signature/eddsa-jcs-2022';
 import { collectionItemsUrl, parseSpaceTarget, spacesRoot, toUrl } from './internal/paths.js';
 import { send, rawRequest, unsignedRequest } from './internal/request.js';
 import { createdId, parseResource, readJsonData } from './internal/content.js';
@@ -18,6 +5,7 @@ import { buildPageWalk, collectPages, collectWalk, signedPageWalk, walkItems, wa
 import { delegateGrant } from './internal/grant.js';
 import { spaceIdOf, submitRevocation } from './internal/revoke.js';
 import { ValidationError } from './errors.js';
+import { zcapClientForSigner } from './zcapClient.js';
 import { Space } from './Space.js';
 import { Collection } from './Collection.js';
 import { Resource } from './Resource.js';
@@ -59,12 +47,11 @@ export class WasClient {
      * @returns {WasClient}
      */
     static fromSigner({ serverUrl, signer, encryption }) {
-        const zcapClient = new ZcapClient({
-            SuiteClass: EddsaJcs2022,
-            invocationSigner: signer,
-            delegationSigner: signer
+        return new WasClient({
+            serverUrl,
+            zcapClient: zcapClientForSigner({ signer }),
+            encryption
         });
-        return new WasClient({ serverUrl, zcapClient, encryption });
     }
     /**
      * The DID controlling the wrapped signer (`signer.id` without the key

package/dist/WasClient.js.map

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

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