@interop/wallet-core 0.21.0 → 0.22.1

package/README.md

@@ -81,8 +81,11 @@ The subpaths:
   staleness detected from durable state alone, history escrowed -- also the
   completion sweep's building block), plus the detector that converges a roster
   left wrapping the current key to a recipient the account document no longer
-  keys. Also the enrolled-client display labels (`key-map/client-labels.json`)
-  and their WAS-backed store. Also the client-key record codec: the contents and
+  keys. Also `ensureWalletSpaceEpochs`, the provision-time install of each
+  encrypted wallet collection's key epoch[0] (a fresh random epoch key wrapped
+  to the user key) -- the EDV-bearing second step of `provisionWalletSpace`.
+  Also the enrolled-client display labels (`key-map/client-labels.json`) and
+  their WAS-backed store. Also the client-key record codec: the contents and
   strict validation of the local record each wallet client keeps its own key
   material in (storage and wrapping stay app-side).
 

package/dist/descriptors/acquire.d.ts

@@ -4,11 +4,16 @@
 /**
  * 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 when
- * the description cannot be fetched -- offline, a previously-shared collection
- * must keep encrypting under its current epoch. A successful fetch that
- * returns no descriptor (an unshared collection) yields `undefined`: the
- * single-key path.
+ * 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 wallet app's own classes satisfy
  * them structurally -- no adapter needed. An {@link EncryptionDescriptorSource}
@@ -20,9 +25,11 @@
 import type { CollectionEncryption, WasClient } from '@interop/was-client';
 /**
  * Where descriptors come from: one signed read of the collection's
- * Description. Resolves `undefined` for a collection that is plaintext or has
- * no descriptor; network errors throw through (callers treat the fetch as
- * best-effort and fall back to a cached copy).
+ * 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: {
@@ -59,11 +66,12 @@ export declare function wasDescriptorSource({ was, spaceId }: {
 }): EncryptionDescriptorSource;
 /**
  * Acquires one collection's descriptor: 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 descriptor resolves `undefined` -- an unshared
- * collection stays on the single-key path -- and deliberately leaves any
- * cached copy in place, mirroring the fetch-failure fallback.
+ * 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
@@ -71,8 +79,8 @@ export declare function wasDescriptorSource({ was, spaceId }: {
  * @param options.cache {EncryptionDescriptorCache}
  * @param options.collectionId {string}
  * @param [options.onFetchError] {function}   observes a swallowed fetch
- *   failure (the cached-fallback branch); errors from the cache itself throw
- *   through
+ *   failure (the thrown-fetch branch only; an empty description is not an
+ *   error). Errors from the cache itself throw through
  * @returns {Promise<CollectionEncryption | undefined>}
  */
 export declare function acquireDescriptor({ source, cache, collectionId, onFetchError }: {

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

@@ -1 +1 @@
-{"version":3,"file":"acquire.d.ts","sourceRoot":"","sources":["../../src/descriptors/acquire.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAE1E;;;;;GAKG;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;;;;;;;;;;;;;;;;;GAiBG;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,CAe5C;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"}
+{"version":3,"file":"acquire.d.ts","sourceRoot":"","sources":["../../src/descriptors/acquire.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAE1E;;;;;;;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;;;;;;;;;;;;;;;;;;GAkBG;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,CAiB5C;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/descriptors/acquire.js

@@ -21,11 +21,12 @@ export function wasDescriptorSource({ was, spaceId }) {
 }
 /**
  * Acquires one collection's descriptor: 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 descriptor resolves `undefined` -- an unshared
- * collection stays on the single-key path -- and deliberately leaves any
- * cached copy in place, mirroring the fetch-failure fallback.
+ * 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
@@ -33,8 +34,8 @@ export function wasDescriptorSource({ was, spaceId }) {
  * @param options.cache {EncryptionDescriptorCache}
  * @param options.collectionId {string}
  * @param [options.onFetchError] {function}   observes a swallowed fetch
- *   failure (the cached-fallback branch); errors from the cache itself throw
- *   through
+ *   failure (the thrown-fetch branch only; an empty description is not an
+ *   error). Errors from the cache itself throw through
  * @returns {Promise<CollectionEncryption | undefined>}
  */
 export async function acquireDescriptor({ source, cache, collectionId, onFetchError }) {
@@ -47,7 +48,9 @@ export async function acquireDescriptor({ source, cache, collectionId, onFetchEr
             await cache.writeDescriptor({ collectionId, descriptor: fetched });
             return fetched;
         }
-        return undefined;
+        // 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) {
         onFetchError?.(err, { collectionId });

package/dist/descriptors/acquire.js.map

@@ -1 +1 @@
-{"version":3,"file":"acquire.js","sourceRoot":"","sources":["../../src/descriptors/acquire.ts"],"names":[],"mappings":"AAgDA;;;;;;;;;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;;;;;;;;;;;;;;;;;GAiBG;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,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,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"}
+{"version":3,"file":"acquire.js","sourceRoot":"","sources":["../../src/descriptors/acquire.ts"],"names":[],"mappings":"AAuDA;;;;;;;;;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;;;;;;;;;;;;;;;;;;GAkBG;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,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/descriptors/cipher.d.ts

@@ -8,14 +8,20 @@
  * conflict resolver) rather than a row-scanning store.
  *
  * Built, the cipher acquires the collection's descriptor (fetch, cache the
- * success, cached fallback on failure -- see `acquire.ts`) and constructs 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, that is the single-key path, unchanged. When a decrypt throws
+ * 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.
+ * 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.
  */
 import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
 import { type DocCipher } from '@interop/was-client/edv';

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

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

package/dist/descriptors/cipher.js

@@ -23,18 +23,26 @@ import { acquireDescriptor } from './acquire.js';
  * @returns {Promise<DocCipher>}
  */
 export async function createRefreshingEdvDocCipher({ keyAgreementKey, keyResolver, collectionId, idDerivation, source, cache, onFetchError }) {
-    const build = async () => createEdvDocCipher({
-        keyAgreementKey,
-        keyResolver,
-        collectionId,
-        idDerivation,
-        encryption: await acquireDescriptor({
+    const build = async () => {
+        const encryption = await acquireDescriptor({
             source,
             cache,
             collectionId,
             onFetchError
-        })
-    });
+        });
+        if (!encryption) {
+            throw new Error(`Collection "${collectionId}" has no encryption descriptor available ` +
+                '(fetched or cached). Every encrypted collection carries its key ' +
+                'epochs from provisioning; refusing to build a cipher without them.');
+        }
+        return createEdvDocCipher({
+            keyAgreementKey,
+            keyResolver,
+            collectionId,
+            idDerivation,
+            encryption
+        });
+    };
     let inner = await build();
     // The one descriptor refresh this cipher instance (= this collection this
     // session) may spend, shared so concurrent unknown-epoch decrypts ride a
@@ -56,10 +64,33 @@ export async function createRefreshingEdvDocCipher({ keyAgreementKey, keyResolve
                 if (!(err instanceof UnknownEpochError) || !source) {
                     throw err;
                 }
-                refreshed ??= build().then(cipher => {
-                    inner = cipher;
-                });
-                await refreshed;
+                if (!refreshed) {
+                    const attempt = build().then(cipher => {
+                        inner = cipher;
+                    });
+                    refreshed = attempt;
+                    // Only a COMPLETED refresh is spent. A rejected one (the description
+                    // could not be read and no cached copy answered either) un-arms the
+                    // guard so a later unknown-epoch decrypt may try again; a successful
+                    // refresh that still cannot route the envelope stays spent for the
+                    // session, which is what keeps a genuinely foreign envelope from
+                    // driving a refetch loop.
+                    attempt.catch(() => {
+                        if (refreshed === attempt) {
+                            refreshed = null;
+                        }
+                    });
+                }
+                try {
+                    await refreshed;
+                }
+                catch {
+                    // The refresh failed, so nothing was learned about this envelope's
+                    // epoch: surface the original UnknownEpochError rather than the
+                    // build failure, so callers classifying on it (the create-loss
+                    // re-mint) still see the row they exist to repair.
+                    throw err;
+                }
                 // 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

package/dist/descriptors/cipher.js.map

@@ -1 +1 @@
-{"version":3,"file":"cipher.js","sourceRoot":"","sources":["../../src/descriptors/cipher.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,iBAAiB,EAGlB,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,iBAAiB,CAAC;YAClC,MAAM;YACN,KAAK;YACL,YAAY;YACZ,YAAY;SACb,CAAC;KACH,CAAC,CAAA;IAEJ,IAAI,KAAK,GAAG,MAAM,KAAK,EAAE,CAAA;IACzB,0EAA0E;IAC1E,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"}
+{"version":3,"file":"cipher.js","sourceRoot":"","sources":["../../src/descriptors/cipher.ts"],"names":[],"mappings":"AA6BA,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EAElB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,iBAAiB,EAGlB,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;QAC3C,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC;YACzC,MAAM;YACN,KAAK;YACL,YAAY;YACZ,YAAY;SACb,CAAC,CAAA;QACF,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACb,eAAe,YAAY,2CAA2C;gBACpE,kEAAkE;gBAClE,oEAAoE,CACvE,CAAA;QACH,CAAC;QACD,OAAO,kBAAkB,CAAC;YACxB,eAAe;YACf,WAAW;YACX,YAAY;YACZ,YAAY;YACZ,UAAU;SACX,CAAC,CAAA;IACJ,CAAC,CAAA;IAED,IAAI,KAAK,GAAG,MAAM,KAAK,EAAE,CAAA;IACzB,0EAA0E;IAC1E,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,IAAI,CAAC,SAAS,EAAE,CAAC;oBACf,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE;wBACpC,KAAK,GAAG,MAAM,CAAA;oBAChB,CAAC,CAAC,CAAA;oBACF,SAAS,GAAG,OAAO,CAAA;oBACnB,qEAAqE;oBACrE,oEAAoE;oBACpE,qEAAqE;oBACrE,mEAAmE;oBACnE,iEAAiE;oBACjE,0BAA0B;oBAC1B,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE;wBACjB,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;4BAC1B,SAAS,GAAG,IAAI,CAAA;wBAClB,CAAC;oBACH,CAAC,CAAC,CAAA;gBACJ,CAAC;gBACD,IAAI,CAAC;oBACH,MAAM,SAAS,CAAA;gBACjB,CAAC;gBAAC,MAAM,CAAC;oBACP,mEAAmE;oBACnE,gEAAgE;oBAChE,+DAA+D;oBAC/D,mDAAmD;oBACnD,MAAM,GAAG,CAAA;gBACX,CAAC;gBACD,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/descriptors/index.d.ts

@@ -15,8 +15,12 @@
  * - `wasDescriptorSource` -- the `EncryptionDescriptorSource` over a
  *   was-client handle.
  * - `acquireDescriptor` / `acquireDescriptors` -- fetch + cache with the
- *   cached fallback (offline, a previously-shared collection keeps encrypting
- *   under its current epoch; no descriptor at all is the single-key path).
+ *   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.
  * - `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.

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/descriptors/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC3B,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/descriptors/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AACrB,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC3B,MAAM,cAAc,CAAA;AAErB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA"}

package/dist/descriptors/index.js

@@ -15,8 +15,12 @@
  * - `wasDescriptorSource` -- the `EncryptionDescriptorSource` over a
  *   was-client handle.
  * - `acquireDescriptor` / `acquireDescriptors` -- fetch + cache with the
- *   cached fallback (offline, a previously-shared collection keeps encrypting
- *   under its current epoch; no descriptor at all is the single-key path).
+ *   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.
  * - `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.

package/dist/descriptors/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/descriptors/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AAMrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/descriptors/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EACL,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,cAAc,CAAA;AAMrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAA;AAEtD,OAAO,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAA"}

package/dist/keyring/index.d.ts

@@ -10,8 +10,13 @@
  *   wire-level unlock derivation (implemented over `@noble/hashes`, so it runs
  *   unchanged where WebCrypto's `deriveBits` is unavailable) and the unlock
  *   Space addressing convention.
- * - `wrapKeyringRecord` / `unwrapKeyringRecord` -- the `{ version, wrapped }`
- *   account-pointer record codec.
+ * - `wrapKeyringRecord` / `unwrapKeyringRecord` -- the
+ *   `{ version, encryption, wrapped }` account-pointer record codec.
+ * - `mintRecordEncryption` / `recordCipher` / `parseRecordFrame` -- the
+ *   record-own-epoch envelope construction the codec seals with plus the frame
+ *   validation it opens with, exported so an app's own locally stored records
+ *   seal and unseal the same way (under their own cipher context) rather than
+ *   re-deriving the construction.
  * - `ensureUnlockSpace` / `getUnlockKeyring` / `putUnlockKeyring` /
  *   `deleteUnlockSpace` / `deleteUnlockSpaceWithCapability` -- the unlock
  *   Space's lifecycle and its one resource.
@@ -23,7 +28,7 @@
  */
 export { deriveUnlockIdentity, KEYRING_KDF, UNLOCK_HANDLE, UNLOCK_KEY_NAME, unlockSpaceIdFor } from './kdf.js';
 export type { UnlockIdentity, UnlockKdf } from './kdf.js';
-export { KEYRING_RECORD_VERSION, parseRecordPointer, unwrapKeyringRecord, wrapKeyringRecord } from './record.js';
+export { KEYRING_RECORD_VERSION, mintRecordEncryption, parseRecordFrame, parseRecordPointer, recordCipher, unwrapKeyringRecord, wrapKeyringRecord } from './record.js';
 export type { AccountPointer, KeyringRecordContents } from './record.js';
 export { deleteUnlockSpace, deleteUnlockSpaceWithCapability, ensureUnlockSpace, getUnlockKeyring, putUnlockKeyring, putUnlockKeyringWithCapability, UNLOCK_SPACE_NAME } from './unlockSpace.js';
 export { fetchKeyringRecord } from './fetch.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keyring/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EACjB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEzD,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExE,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,8BAA8B,EAC9B,iBAAiB,EAClB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keyring/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EACjB,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAEzD,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExE,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,8BAA8B,EAC9B,iBAAiB,EAClB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA"}

package/dist/keyring/index.js

@@ -10,8 +10,13 @@
  *   wire-level unlock derivation (implemented over `@noble/hashes`, so it runs
  *   unchanged where WebCrypto's `deriveBits` is unavailable) and the unlock
  *   Space addressing convention.
- * - `wrapKeyringRecord` / `unwrapKeyringRecord` -- the `{ version, wrapped }`
- *   account-pointer record codec.
+ * - `wrapKeyringRecord` / `unwrapKeyringRecord` -- the
+ *   `{ version, encryption, wrapped }` account-pointer record codec.
+ * - `mintRecordEncryption` / `recordCipher` / `parseRecordFrame` -- the
+ *   record-own-epoch envelope construction the codec seals with plus the frame
+ *   validation it opens with, exported so an app's own locally stored records
+ *   seal and unseal the same way (under their own cipher context) rather than
+ *   re-deriving the construction.
  * - `ensureUnlockSpace` / `getUnlockKeyring` / `putUnlockKeyring` /
  *   `deleteUnlockSpace` / `deleteUnlockSpaceWithCapability` -- the unlock
  *   Space's lifecycle and its one resource.
@@ -22,7 +27,7 @@
  * was-client dependency graph (the same isolation pattern as `./identity`).
  */
 export { deriveUnlockIdentity, KEYRING_KDF, UNLOCK_HANDLE, UNLOCK_KEY_NAME, unlockSpaceIdFor } from './kdf.js';
-export { KEYRING_RECORD_VERSION, parseRecordPointer, unwrapKeyringRecord, wrapKeyringRecord } from './record.js';
+export { KEYRING_RECORD_VERSION, mintRecordEncryption, parseRecordFrame, parseRecordPointer, recordCipher, unwrapKeyringRecord, wrapKeyringRecord } from './record.js';
 export { deleteUnlockSpace, deleteUnlockSpaceWithCapability, ensureUnlockSpace, getUnlockKeyring, putUnlockKeyring, putUnlockKeyringWithCapability, UNLOCK_SPACE_NAME } from './unlockSpace.js';
 export { fetchKeyringRecord } from './fetch.js';
 //# sourceMappingURL=index.js.map

package/dist/keyring/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/keyring/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EACjB,MAAM,UAAU,CAAA;AAGjB,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,8BAA8B,EAC9B,iBAAiB,EAClB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/keyring/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACL,oBAAoB,EACpB,WAAW,EACX,aAAa,EACb,eAAe,EACf,gBAAgB,EACjB,MAAM,UAAU,CAAA;AAGjB,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,aAAa,CAAA;AAGpB,OAAO,EACL,iBAAiB,EACjB,+BAA+B,EAC/B,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,8BAA8B,EAC9B,iBAAiB,EAClB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA"}

package/dist/keyring/record.d.ts

@@ -2,24 +2,93 @@
  * Copyright (c) 2026 Interop Alliance. All rights reserved.
  */
 /**
- * The keyring record codec: the `{ version, wrapped }` envelope stored as the
- * one resource of an account's unlock Space. Its plaintext carries the account
- * controller, the email captured at bind time, and the account pointer -- and
- * deliberately no key material of any kind, so the record locates an account
- * without authorizing anything against it.
+ * The keyring record codec: the `{ version, encryption, wrapped }` envelope
+ * stored as the one resource of an account's unlock Space. Its plaintext
+ * carries the account controller, the email captured at bind time, and the
+ * account pointer -- and deliberately no key material of any kind, so the
+ * record locates an account without authorizing anything against it.
  *
- * The wrap is an EDV document envelope under the unlock key-agreement key,
- * bound to the `keyring` cipher context, so a keyring envelope can never be
- * mistaken for (or swapped with) any other wrapped record.
+ * The wrap is an EDV document envelope sealed under the record's own key
+ * epoch: every EDV envelope seals to an epoch key, so the record carries its
+ * one-epoch descriptor in its `encryption` member, epoch[0] wrapped to the
+ * unlock key-agreement key. The record stays self-contained -- unlock KAK in,
+ * contents out. The cipher's `keyring` collection context labels errors only
+ * (the codec is agnostic to it); what keeps a swapped-in foreign record from
+ * being accepted is the contents validation on unwrap, not the cipher.
  */
 import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
+import type { CollectionEncryption } from '@interop/was-client';
+import { type DocCipher } from '@interop/was-client/edv';
 /**
- * The version stamped on the stored `{ version, wrapped }` keyring envelope.
- * Version 2 is the account-pointer record; version-1 records (which carried a
- * wrapped account-wide data seed) are refused as unusable -- such accounts are
- * re-provisioned, not migrated.
+ * The version stamped on the stored `{ version, encryption, wrapped }` keyring
+ * envelope: the record whose envelope seals under the record's own key epoch
+ * (the `encryption` member). Any other version is refused as unusable -- such
+ * accounts are re-provisioned, not migrated.
  */
-export declare const KEYRING_RECORD_VERSION = 2;
+export declare const KEYRING_RECORD_VERSION = 1;
+/**
+ * Mints the one-epoch descriptor a fresh record is sealed under: epoch[0]
+ * wrapped to the given KAK alone, built through `initRecipients` against a
+ * throwaway in-memory store (the descriptor's home is the record itself).
+ * Exported for any consumer sealing a self-contained
+ * `{ version, encryption, wrapped }` record -- the keyring and recovery
+ * records here, and a wallet app's own locally stored records (e.g.
+ * freewallet's client-key record and unlock-methods registry).
+ *
+ * @param options {object}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the wrapping KAK (for
+ *   the keyring record, the unlock KAK)
+ * @returns {Promise<CollectionEncryption>}
+ */
+export declare function mintRecordEncryption({ keyAgreementKey }: {
+    keyAgreementKey: IKeyAgreementKey;
+}): Promise<CollectionEncryption>;
+/**
+ * Builds the record cipher: an EDV cipher over the record's own descriptor.
+ * Shared by the wrap and unwrap paths (and by the recovery record, which
+ * reuses the keyring cipher context verbatim); an app's own record kind
+ * passes its own `collectionId` so its failures name the record kind. The
+ * context labels errors only -- the codec is agnostic to it, so a record
+ * kind's real swap protection is its contents validation on unwrap.
+ *
+ * @param options {object}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the wrapping KAK (for
+ *   the keyring record, the unlock KAK)
+ * @param options.keyResolver {IKeyResolver}
+ * @param options.encryption {CollectionEncryption}   the record's descriptor
+ * @param [options.collectionId] {string}   the cipher context failures are
+ *   labeled with; defaults to the keyring context
+ * @returns {Promise<DocCipher>}
+ */
+export declare function recordCipher({ keyAgreementKey, keyResolver, encryption, collectionId }: {
+    keyAgreementKey: IKeyAgreementKey;
+    keyResolver: IKeyResolver;
+    encryption: CollectionEncryption;
+    collectionId?: string;
+}): Promise<DocCipher>;
+/**
+ * Validates the common `{ version, encryption, wrapped }` frame of a stored
+ * record (keyring or recovery -- `label` names the refusals) and returns its
+ * members. Exported so an app's own record kinds open their records through
+ * the same frame validation the codec here seals with, rather than re-deriving
+ * the version and shape checks.
+ *
+ * @param options {object}
+ * @param options.record {unknown}
+ * @param options.label {string}   `'keyring'`, `'recovery'`, or an app record
+ *   kind's own label
+ * @param [options.version] {number}   the version the frame must carry;
+ *   defaults to the keyring record version
+ * @returns {{ encryption: CollectionEncryption, wrapped: unknown }}
+ */
+export declare function parseRecordFrame({ record, label, version }: {
+    record: unknown;
+    label: string;
+    version?: number;
+}): {
+    encryption: CollectionEncryption;
+    wrapped: unknown;
+};
 /**
  * The account pointer a keyring record carries in place of the retired data
  * seed: where the account lives (`spaceId` + `host`, the WAS server origin)
@@ -45,8 +114,9 @@ export interface KeyringRecordContents {
 }
 /**
  * Wraps the account-pointer contents into a keyring record: the controller,
- * email, and pointer (+ timestamp) encrypted under the unlock KAK via the EDV
- * cipher. Deliberately carries no key material of any kind.
+ * email, and pointer (+ timestamp) sealed under a freshly minted record epoch
+ * whose key is wrapped to the unlock KAK. Deliberately carries no key material
+ * of any kind.
  *
  * @param options {object}
  * @param options.controller {string}   the account did:key
@@ -55,7 +125,8 @@ export interface KeyringRecordContents {
  *   no-WAS deployments)
  * @param options.keyAgreementKey {IKeyAgreementKey}   the unlock KAK
  * @param options.keyResolver {IKeyResolver}
- * @returns {Promise<{ version: number, wrapped: unknown }>}
+ * @returns {Promise<{ version: number, encryption: CollectionEncryption,
+ *   wrapped: unknown }>}
  */
 export declare function wrapKeyringRecord({ controller, email, pointer, keyAgreementKey, keyResolver }: {
     controller: string;
@@ -65,12 +136,12 @@ export declare function wrapKeyringRecord({ controller, email, pointer, keyAgree
     keyResolver: IKeyResolver;
 }): Promise<{
     version: number;
+    encryption: CollectionEncryption;
     wrapped: unknown;
 }>;
 /**
  * Unwraps and validates a keyring record. Rejects a record whose `version` is
- * not the current one (version-1 records carried the retired wrapped data
- * seed and are refused -- accounts are re-provisioned, not migrated), and
+ * not the current one (accounts are re-provisioned, not migrated), and
  * sanity-checks the decrypted plaintext (non-empty controller, well-formed
  * pointer when present).
  *

package/dist/keyring/record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/keyring/record.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAA;AAIrC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,UAAU,EACV,KAAK,EACL,OAAO,EACP,eAAe,EACf,WAAW,EACZ,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAuBjD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,MAAM,EACN,eAAe,EACf,WAAW,EACZ,EAAE;IACD,MAAM,EAAE,OAAO,CAAA;IACf,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAsCjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAsB7E"}
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/keyring/record.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;GAcG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,YAAY,EACb,MAAM,8BAA8B,CAAA;AACrC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,EAIL,KAAK,SAAS,EAEf,MAAM,yBAAyB,CAAA;AAGhC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAA;AAEvC;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,eAAe,EAChB,EAAE;IACD,eAAe,EAAE,gBAAgB,CAAA;CAClC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAiBhC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,YAAY,CAAC,EACjC,eAAe,EACf,WAAW,EACX,UAAU,EACV,YAAoC,EACrC,EAAE;IACD,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;IACzB,UAAU,EAAE,oBAAoB,CAAA;IAChC,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,GAAG,OAAO,CAAC,SAAS,CAAC,CAOrB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,KAAK,EACL,OAAgC,EACjC,EAAE;IACD,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,GAAG;IAAE,UAAU,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAoCzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CAAC,EACtC,UAAU,EACV,KAAK,EACL,OAAO,EACP,eAAe,EACf,WAAW,EACZ,EAAE;IACD,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,cAAc,CAAA;IACxB,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B,GAAG,OAAO,CAAC;IACV,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,oBAAoB,CAAA;IAChC,OAAO,EAAE,OAAO,CAAA;CACjB,CAAC,CAwBD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,MAAM,EACN,eAAe,EACf,WAAW,EACZ,EAAE;IACD,MAAM,EAAE,OAAO,CAAA;IACf,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;CAC1B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAgCjC;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,SAAS,CAsB7E"}