@interop/wallet-core 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -21,16 +21,19 @@
  *   entries, and ZCap signing under the did:webvh verification-method id.
  * - `@interop/wallet-core/keys` -- the per-user key (PUK) and its
  *   `key-map/puk.json` wrap-set roster.
+ * - `@interop/wallet-core/markers` -- collection-encryption marker
+ *   acquisition (fetch / cache / offline fallback) and the unknown-epoch
+ *   refresh policy, including a self-refreshing EDV document cipher.
  * - `@interop/wallet-core/keyring` -- the unlock layer: the unlock derivation,
  *   the account-pointer record codec, and the unlock Space.
  * - `@interop/wallet-core/enrollment` -- the client enrollment ceremony
  *   (connect code, approval, completion).
  *
  * This root re-exports `sync` and `space` for convenience. `identity`,
- * `request`, `display`, `webvh`, `keys`, `keyring`, and `enrollment` are
- * deliberately NOT re-exported here, so plaintext consumers of the root never
- * pull the signing / KMS / document-loader dependency graph (the was-client
- * subpath-isolation pattern).
+ * `request`, `display`, `webvh`, `keys`, `markers`, `keyring`, and
+ * `enrollment` are deliberately NOT re-exported here, so plaintext consumers
+ * of the root never pull the signing / KMS / document-loader dependency graph
+ * (the was-client subpath-isolation pattern).
  */
 export * from './sync/index.js';
 export * from './space/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA"}

package/dist/index.js

@@ -21,16 +21,19 @@
  *   entries, and ZCap signing under the did:webvh verification-method id.
  * - `@interop/wallet-core/keys` -- the per-user key (PUK) and its
  *   `key-map/puk.json` wrap-set roster.
+ * - `@interop/wallet-core/markers` -- collection-encryption marker
+ *   acquisition (fetch / cache / offline fallback) and the unknown-epoch
+ *   refresh policy, including a self-refreshing EDV document cipher.
  * - `@interop/wallet-core/keyring` -- the unlock layer: the unlock derivation,
  *   the account-pointer record codec, and the unlock Space.
  * - `@interop/wallet-core/enrollment` -- the client enrollment ceremony
  *   (connect code, approval, completion).
  *
  * This root re-exports `sync` and `space` for convenience. `identity`,
- * `request`, `display`, `webvh`, `keys`, `keyring`, and `enrollment` are
- * deliberately NOT re-exported here, so plaintext consumers of the root never
- * pull the signing / KMS / document-loader dependency graph (the was-client
- * subpath-isolation pattern).
+ * `request`, `display`, `webvh`, `keys`, `markers`, `keyring`, and
+ * `enrollment` are deliberately NOT re-exported here, so plaintext consumers
+ * of the root never pull the signing / KMS / document-loader dependency graph
+ * (the was-client subpath-isolation pattern).
  */
 export * from './sync/index.js';
 export * from './space/index.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA"}

package/dist/markers/acquire.d.ts

@@ -0,0 +1,107 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Collection-encryption marker acquisition: reading a collection's
+ * `CollectionEncryption` marker (its key-epoch roster) from the Collection
+ * Description, caching each success, and falling back to the cached copy when
+ * the description cannot be fetched -- offline, a previously-shared collection
+ * must keep encrypting under its current epoch. A successful fetch that
+ * returns no marker (an unshared collection) yields `undefined`: the
+ * single-key path.
+ *
+ * The two seams are deliberately narrow, so a wallet app's own classes satisfy
+ * them structurally -- no adapter needed. A {@link MarkerSource} is one signed
+ * describe; a {@link MarkerCache} is a durable get/put the host has already
+ * scoped to one account's Space (a web wallet: a localStorage pair keyed by
+ * Space id; a mobile wallet: a per-(profile, collection) table column), so no
+ * scope key appears in the interface.
+ */
+import type { CollectionEncryption, WasClient } from '@interop/was-client';
+/**
+ * Where markers come from: one signed read of the collection's Description.
+ * Resolves `undefined` for a collection that is plaintext or has no marker;
+ * network errors throw through (callers treat the fetch as best-effort and
+ * fall back to a cached copy).
+ */
+export interface MarkerSource {
+    collectionEncryption(options: {
+        collectionId: string;
+    }): Promise<CollectionEncryption | undefined>;
+}
+/**
+ * Where fetched markers survive offline: a durable get/put pre-scoped by the
+ * host to one account's Space. `readMarker` resolves `undefined` when nothing
+ * is cached (never throws for absence).
+ */
+export interface MarkerCache {
+    readMarker(options: {
+        collectionId: string;
+    }): Promise<CollectionEncryption | undefined>;
+    writeMarker(options: {
+        collectionId: string;
+        marker: CollectionEncryption;
+    }): Promise<void>;
+}
+/**
+ * The {@link MarkerSource} over a was-client handle: reads the collection's
+ * Description in the given Space and returns its `encryption` marker.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   a client whose signer can read the Space
+ * @param options.spaceId {string}
+ * @returns {MarkerSource}
+ */
+export declare function wasMarkerSource({ was, spaceId }: {
+    was: WasClient;
+    spaceId: string;
+}): MarkerSource;
+/**
+ * Acquires one collection's marker: fetches it from the source, caching a
+ * success; falls back to the cached copy when the fetch fails; and with no
+ * source at all (a purely local code path) reads the cache alone. A
+ * successful fetch that returns no marker resolves `undefined` -- an unshared
+ * collection stays on the single-key path -- and deliberately leaves any
+ * cached copy in place, mirroring the fetch-failure fallback.
+ *
+ * @param options {object}
+ * @param [options.source] {MarkerSource}   omit for cache-only acquisition
+ * @param options.cache {MarkerCache}
+ * @param options.collectionId {string}
+ * @param [options.onFetchError] {function}   observes a swallowed fetch
+ *   failure (the cached-fallback branch); errors from the cache itself throw
+ *   through
+ * @returns {Promise<CollectionEncryption | undefined>}
+ */
+export declare function acquireMarker({ source, cache, collectionId, onFetchError }: {
+    source?: MarkerSource;
+    cache: MarkerCache;
+    collectionId: string;
+    onFetchError?: (err: unknown, info: {
+        collectionId: string;
+    }) => void;
+}): Promise<CollectionEncryption | undefined>;
+/**
+ * Acquires markers 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 marker are simply absent
+ * from the result.
+ *
+ * @param options {object}
+ * @param [options.source] {MarkerSource}   omit for cache-only acquisition
+ * @param options.cache {MarkerCache}
+ * @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 acquireMarkers({ source, cache, collectionIds, onFetchError }: {
+    source?: MarkerSource;
+    cache: MarkerCache;
+    collectionIds: string[];
+    onFetchError?: (err: unknown, info: {
+        collectionId: string;
+    }) => void;
+}): Promise<Record<string, CollectionEncryption>>;
+//# sourceMappingURL=acquire.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"acquire.d.ts","sourceRoot":"","sources":["../../src/markers/acquire.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAE1E;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,oBAAoB,CAAC,OAAO,EAAE;QAC5B,YAAY,EAAE,MAAM,CAAA;KACrB,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAA;CAC9C;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,OAAO,EAAE;QAClB,YAAY,EAAE,MAAM,CAAA;KACrB,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC,CAAA;IAC7C,WAAW,CAAC,OAAO,EAAE;QACnB,YAAY,EAAE,MAAM,CAAA;QACpB,MAAM,EAAE,oBAAoB,CAAA;KAC7B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,EAC9B,GAAG,EACH,OAAO,EACR,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,YAAY,CAUf;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,aAAa,CAAC,EAClC,MAAM,EACN,KAAK,EACL,YAAY,EACZ,YAAY,EACb,EAAE;IACD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,KAAK,EAAE,WAAW,CAAA;IAClB,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,CAe5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,cAAc,CAAC,EACnC,MAAM,EACN,KAAK,EACL,aAAa,EACb,YAAY,EACb,EAAE;IACD,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,KAAK,EAAE,WAAW,CAAA;IAClB,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/markers/acquire.js

@@ -0,0 +1,83 @@
+/**
+ * The {@link MarkerSource} over a was-client handle: reads the collection's
+ * Description in the given Space and returns its `encryption` marker.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   a client whose signer can read the Space
+ * @param options.spaceId {string}
+ * @returns {MarkerSource}
+ */
+export function wasMarkerSource({ was, spaceId }) {
+    return {
+        async collectionEncryption({ collectionId }) {
+            const description = await was
+                .space(spaceId)
+                .collection(collectionId)
+                .describe();
+            return description?.encryption ?? undefined;
+        }
+    };
+}
+/**
+ * Acquires one collection's marker: fetches it from the source, caching a
+ * success; falls back to the cached copy when the fetch fails; and with no
+ * source at all (a purely local code path) reads the cache alone. A
+ * successful fetch that returns no marker resolves `undefined` -- an unshared
+ * collection stays on the single-key path -- and deliberately leaves any
+ * cached copy in place, mirroring the fetch-failure fallback.
+ *
+ * @param options {object}
+ * @param [options.source] {MarkerSource}   omit for cache-only acquisition
+ * @param options.cache {MarkerCache}
+ * @param options.collectionId {string}
+ * @param [options.onFetchError] {function}   observes a swallowed fetch
+ *   failure (the cached-fallback branch); errors from the cache itself throw
+ *   through
+ * @returns {Promise<CollectionEncryption | undefined>}
+ */
+export async function acquireMarker({ source, cache, collectionId, onFetchError }) {
+    if (!source) {
+        return cache.readMarker({ collectionId });
+    }
+    try {
+        const fetched = await source.collectionEncryption({ collectionId });
+        if (fetched) {
+            await cache.writeMarker({ collectionId, marker: fetched });
+            return fetched;
+        }
+        return undefined;
+    }
+    catch (err) {
+        onFetchError?.(err, { collectionId });
+        return cache.readMarker({ collectionId });
+    }
+}
+/**
+ * Acquires markers 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 marker are simply absent
+ * from the result.
+ *
+ * @param options {object}
+ * @param [options.source] {MarkerSource}   omit for cache-only acquisition
+ * @param options.cache {MarkerCache}
+ * @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 acquireMarkers({ source, cache, collectionIds, onFetchError }) {
+    const resolved = await Promise.all(collectionIds.map(async (collectionId) => [
+        collectionId,
+        await acquireMarker({ source, cache, collectionId, onFetchError })
+    ]));
+    const markers = {};
+    for (const [collectionId, marker] of resolved) {
+        if (marker) {
+            markers[collectionId] = marker;
+        }
+    }
+    return markers;
+}
+//# sourceMappingURL=acquire.js.map

package/dist/markers/acquire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acquire.js","sourceRoot":"","sources":["../../src/markers/acquire.ts"],"names":[],"mappings":"AAgDA;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,EAC9B,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;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAClC,MAAM,EACN,KAAK,EACL,YAAY,EACZ,YAAY,EAMb;IACC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,KAAK,CAAC,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC,CAAA;IAC3C,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,WAAW,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAA;YAC1D,OAAO,OAAO,CAAA;QAChB,CAAC;QACD,OAAO,SAAS,CAAA;IAClB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,YAAY,EAAE,CAAC,GAAG,EAAE,EAAE,YAAY,EAAE,CAAC,CAAA;QACrC,OAAO,KAAK,CAAC,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC,CAAA;IAC3C,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EACnC,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,aAAa,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;KAC1D,CACb,CACF,CAAA;IACD,MAAM,OAAO,GAAyC,EAAE,CAAA;IACxD,KAAK,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC9C,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,CAAC,YAAY,CAAC,GAAG,MAAM,CAAA;QAChC,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC"}

package/dist/markers/cipher.d.ts

@@ -0,0 +1,56 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * A self-refreshing EDV document cipher: `createEdvDocCipher` bound to marker
+ * 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 marker (fetch, cache the
+ * success, cached fallback on failure -- see `acquire.ts`) and constructs the
+ * underlying EDV cipher from it; with no marker, or a marker with no epochs,
+ * that is the single-key path, unchanged. When a decrypt throws
+ * `UnknownEpochError`, the cipher re-acquires the marker, 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.
+ */
+import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
+import { type DocCipher } from '@interop/was-client/edv';
+import { type MarkerCache, type MarkerSource } from './acquire.js';
+/**
+ * Builds a {@link DocCipher} whose marker is acquired through the
+ * source/cache seams and refreshed (once per instance) on an unknown-epoch
+ * decrypt.
+ *
+ * With no `source` the marker 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] {MarkerSource}
+ * @param options.cache {MarkerCache}
+ * @param [options.onFetchError] {function}   observes swallowed marker-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?: MarkerSource;
+    cache: MarkerCache;
+    onFetchError?: (err: unknown, info: {
+        collectionId: string;
+    }) => void;
+}): Promise<DocCipher>;
+//# sourceMappingURL=cipher.d.ts.map

package/dist/markers/cipher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher.d.ts","sourceRoot":"","sources":["../../src/markers/cipher.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,yBAAyB,CAAA;AAChC,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,YAAY,EAClB,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,YAAY,CAAA;IACrB,KAAK,EAAE,WAAW,CAAA;IAClB,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,CAqDrB"}

package/dist/markers/cipher.js

@@ -0,0 +1,73 @@
+import { createEdvDocCipher, UnknownEpochError } from '@interop/was-client/edv';
+import { acquireMarker } from './acquire.js';
+/**
+ * Builds a {@link DocCipher} whose marker is acquired through the
+ * source/cache seams and refreshed (once per instance) on an unknown-epoch
+ * decrypt.
+ *
+ * With no `source` the marker 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] {MarkerSource}
+ * @param options.cache {MarkerCache}
+ * @param [options.onFetchError] {function}   observes swallowed marker-fetch
+ *   failures
+ * @returns {Promise<DocCipher>}
+ */
+export async function createRefreshingEdvDocCipher({ keyAgreementKey, keyResolver, collectionId, idDerivation, source, cache, onFetchError }) {
+    const build = async () => createEdvDocCipher({
+        keyAgreementKey,
+        keyResolver,
+        collectionId,
+        idDerivation,
+        encryption: await acquireMarker({
+            source,
+            cache,
+            collectionId,
+            onFetchError
+        })
+    });
+    let inner = await build();
+    // The one marker refresh this cipher instance (= this collection this
+    // session) may spend, shared so concurrent unknown-epoch decrypts ride a
+    // single re-read instead of each spending one.
+    let refreshed = null;
+    return {
+        encrypt: options => inner.encrypt(options),
+        encryptUpdate: options => {
+            if (!inner.encryptUpdate) {
+                throw new Error(`Collection "${collectionId}" cipher has no in-place update.`);
+            }
+            return inner.encryptUpdate(options);
+        },
+        async decrypt({ envelope }) {
+            try {
+                return await inner.decrypt({ envelope });
+            }
+            catch (err) {
+                if (!(err instanceof UnknownEpochError) || !source) {
+                    throw err;
+                }
+                refreshed ??= build().then(cipher => {
+                    inner = cipher;
+                });
+                await refreshed;
+                // One retry under the swapped cipher. If the refresh was already
+                // spent before this decrypt began, this re-attempt is a local
+                // no-network decrypt that fails the same way -- so a genuinely
+                // foreign envelope still surfaces UnknownEpochError, and never a
+                // second description read.
+                return inner.decrypt({ envelope });
+            }
+        }
+    };
+}
+//# sourceMappingURL=cipher.js.map

package/dist/markers/cipher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cipher.js","sourceRoot":"","sources":["../../src/markers/cipher.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,aAAa,EAGd,MAAM,cAAc,CAAA;AAErB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAAC,EACjD,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,MAAM,EACN,KAAK,EACL,YAAY,EASb;IACC,MAAM,KAAK,GAAG,KAAK,IAAwB,EAAE,CAC3C,kBAAkB,CAAC;QACjB,eAAe;QACf,WAAW;QACX,YAAY;QACZ,YAAY;QACZ,UAAU,EAAE,MAAM,aAAa,CAAC;YAC9B,MAAM;YACN,KAAK;YACL,YAAY;YACZ,YAAY;SACb,CAAC;KACH,CAAC,CAAA;IAEJ,IAAI,KAAK,GAAG,MAAM,KAAK,EAAE,CAAA;IACzB,sEAAsE;IACtE,yEAAyE;IACzE,+CAA+C;IAC/C,IAAI,SAAS,GAAyB,IAAI,CAAA;IAE1C,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAE1C,aAAa,EAAE,OAAO,CAAC,EAAE;YACvB,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CACb,eAAe,YAAY,kCAAkC,CAC9D,CAAA;YACH,CAAC;YACD,OAAO,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAA;QACrC,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE;YACxB,IAAI,CAAC;gBACH,OAAO,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAA;YAC1C,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,CAAC,GAAG,YAAY,iBAAiB,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACnD,MAAM,GAAG,CAAA;gBACX,CAAC;gBACD,SAAS,KAAK,KAAK,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;oBAClC,KAAK,GAAG,MAAM,CAAA;gBAChB,CAAC,CAAC,CAAA;gBACF,MAAM,SAAS,CAAA;gBACf,iEAAiE;gBACjE,8DAA8D;gBAC9D,+DAA+D;gBAC/D,iEAAiE;gBACjE,2BAA2B;gBAC3B,OAAO,KAAK,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAA;YACpC,CAAC;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/markers/index.d.ts

@@ -0,0 +1,30 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/markers` subpath: collection-encryption marker
+ * acquisition and the unknown-epoch refresh policy -- the one implementation
+ * of "which key epoch does this collection encrypt under, and when do we ask
+ * again" that every wallet replica must share (a drift here does not fail
+ * loudly; it fails as a resource one replica cannot decrypt).
+ *
+ * - `MarkerSource` / `MarkerCache` -- the narrow seams a host implements:
+ *   one signed Collection Description read, and a durable get/put pre-scoped
+ *   to one account's Space.
+ * - `wasMarkerSource` -- the `MarkerSource` over a was-client handle.
+ * - `acquireMarker` / `acquireMarkers` -- fetch + cache with the cached
+ *   fallback (offline, a previously-shared collection keeps encrypting under
+ *   its current epoch; no marker at all is the single-key path).
+ * - `MarkerRefreshPolicy` -- 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 marker and, on an unknown-epoch decrypt,
+ *   re-reads the description, swaps itself, and retries exactly once per
+ *   instance.
+ */
+export { acquireMarker, acquireMarkers, wasMarkerSource } from './acquire.js';
+export type { MarkerCache, MarkerSource } from './acquire.js';
+export { MarkerRefreshPolicy } from './refresh.js';
+export { createRefreshingEdvDocCipher } from './cipher.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/markers/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC7E,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAE7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA"}

package/dist/markers/index.js

@@ -0,0 +1,29 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/markers` subpath: collection-encryption marker
+ * acquisition and the unknown-epoch refresh policy -- the one implementation
+ * of "which key epoch does this collection encrypt under, and when do we ask
+ * again" that every wallet replica must share (a drift here does not fail
+ * loudly; it fails as a resource one replica cannot decrypt).
+ *
+ * - `MarkerSource` / `MarkerCache` -- the narrow seams a host implements:
+ *   one signed Collection Description read, and a durable get/put pre-scoped
+ *   to one account's Space.
+ * - `wasMarkerSource` -- the `MarkerSource` over a was-client handle.
+ * - `acquireMarker` / `acquireMarkers` -- fetch + cache with the cached
+ *   fallback (offline, a previously-shared collection keeps encrypting under
+ *   its current epoch; no marker at all is the single-key path).
+ * - `MarkerRefreshPolicy` -- 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 marker and, on an unknown-epoch decrypt,
+ *   re-reads the description, swaps itself, and retries exactly once per
+ *   instance.
+ */
+export { acquireMarker, acquireMarkers, wasMarkerSource } from './acquire.js';
+export { MarkerRefreshPolicy } from './refresh.js';
+export { createRefreshingEdvDocCipher } from './cipher.js';
+//# sourceMappingURL=index.js.map

package/dist/markers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/markers/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAG7E,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAElD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA"}

package/dist/markers/refresh.d.ts

@@ -0,0 +1,60 @@
+/*!
+ * 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 marker 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 marker 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 marker(s), rebuild the cipher(s),
+ * and install them wherever the host keeps them.
+ */
+export declare class MarkerRefreshPolicy {
+    #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 (marker 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 marker 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/markers/refresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.d.ts","sourceRoot":"","sources":["../../src/markers/refresh.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,qBAAa,mBAAmB;;gBAKlB,EACV,OAAO,EACR,EAAE;QACD,OAAO,EAAE,CAAC,OAAO,EAAE;YAAE,YAAY,EAAE,MAAM,CAAA;SAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;KAC9D;IAID,mEAAmE;IACnE,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/markers/refresh.js

@@ -0,0 +1,67 @@
+/*!
+ * 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 marker 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 marker 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 marker(s), rebuild the cipher(s),
+ * and install them wherever the host keeps them.
+ */
+export class MarkerRefreshPolicy {
+    #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 (marker 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 marker 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/markers/refresh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh.js","sourceRoot":"","sources":["../../src/markers/refresh.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;GAQG;AAEH;;;;;;GAMG;AACH,MAAM,OAAO,mBAAmB;IACrB,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,mEAAmE;IACnE,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/recovery/index.d.ts

@@ -0,0 +1,31 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/recovery` subpath: recovery codes on the roster
+ * identity model -- a code as a minimal always-enrolled wallet client.
+ *
+ * - `generateRecoveryCode` / `formatRecoveryCode` / `normalizeRecoveryCode` /
+ *   `decodeRecoveryCode` / `RECOVERY_KDF` -- the format layer and the code's
+ *   own unlock-derivation parameter set (its salt distinct from every other
+ *   unlock method's).
+ * - `recoveryClientFromCode` -- the deterministic client key set:
+ *   unlock identity, client seed (signing + key-agreement pair), and the
+ *   single did:webvh update key whose hash stands pre-committed.
+ * - `wrapRecoveryRecord` / `unwrapRecoveryRecord` -- the keyring-record
+ *   sibling carrying the account pointer plus the pre-minted
+ *   PUT-on-`did.jsonl` delegation (never a seed, never a PUK wrap).
+ * - `publishRecoveryKey` / `removeRecoveryKey` / `recoverWebvhClient` -- the
+ *   document half: issuance's split posture, revocation's removal, and the
+ *   self-enrolling recovery continuation.
+ *
+ * Kept out of the root export: this subpath pulls the webkms-client / ezcap /
+ * was-client dependency graph (the same isolation pattern as `./keyring`).
+ */
+export { decodeRecoveryCode, formatRecoveryCode, generateRecoveryCode, normalizeRecoveryCode, RECOVERY_CODE_BYTES, RECOVERY_KDF, RecoveryCodeInvalidError, recoveryClientFromCode } from './recoveryCode.js';
+export type { RecoveryClient } from './recoveryCode.js';
+export { unwrapRecoveryRecord, wrapRecoveryRecord } from './recoveryRecord.js';
+export type { RecoveryRecordContents } from './recoveryRecord.js';
+export { publishRecoveryKey, recoverWebvhClient, RecoveryKeyNotCommittedError, recoveryVmId, removeRecoveryKey } from './recoveryWebvh.js';
+export type { RecoveryLogStore, RecoveryPublicKeys } from './recoveryWebvh.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/recovery/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,YAAY,EACZ,wBAAwB,EACxB,sBAAsB,EACvB,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAEvD,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAC9E,YAAY,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAA;AAEjE,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,4BAA4B,EAC5B,YAAY,EACZ,iBAAiB,EAClB,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAA"}