@interop/wallet-core 0.20.0 → 0.22.0

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/cipher.d.ts

@@ -10,7 +10,10 @@
  * Built, the cipher acquires the collection's descriptor (fetch, cache the
  * success, cached fallback on failure -- 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

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;;;;;;;;;;;;;;;;;;GAkBG;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,CA8DrB"}

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

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":"AA0BA,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,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/keyring/record.d.ts

@@ -2,24 +2,74 @@
  * 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 bound to the `keyring` cipher context
+ * (so a keyring envelope can never be mistaken for, or swapped with, any other
+ * wrapped record), 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.
  */
 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 unlock KAK alone, built through `initRecipients` against a
+ * throwaway in-memory store (the descriptor's home is the record itself).
+ *
+ * @param options {object}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the unlock KAK
+ * @returns {Promise<CollectionEncryption>}
+ */
+export declare function mintRecordEncryption({ keyAgreementKey }: {
+    keyAgreementKey: IKeyAgreementKey;
+}): Promise<CollectionEncryption>;
+/**
+ * Builds the record cipher: the keyring-context 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).
+ *
+ * @param options {object}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @param options.encryption {CollectionEncryption}   the record's descriptor
+ * @returns {Promise<DocCipher>}
+ */
+export declare function recordCipher({ keyAgreementKey, keyResolver, encryption }: {
+    keyAgreementKey: IKeyAgreementKey;
+    keyResolver: IKeyResolver;
+    encryption: CollectionEncryption;
+}): Promise<DocCipher>;
+/**
+ * Validates the common `{ version, encryption, wrapped }` frame of a stored
+ * record (keyring or recovery -- `label` names the refusals) and returns its
+ * members.
+ *
+ * @param options {object}
+ * @param options.record {unknown}
+ * @param options.label {string}   `'keyring'` or `'recovery'`
+ * @returns {{ encryption: CollectionEncryption, wrapped: unknown }}
+ */
+export declare function parseRecordFrame({ record, label }: {
+    record: unknown;
+    label: string;
+}): {
+    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 +95,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 +106,7 @@ 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: unknown, wrapped: unknown }>}
  */
 export declare function wrapKeyringRecord({ controller, email, pointer, keyAgreementKey, keyResolver }: {
     controller: string;
@@ -65,12 +116,12 @@ export declare function wrapKeyringRecord({ controller, email, pointer, keyAgree
     keyResolver: IKeyResolver;
 }): Promise<{
     version: number;
+    encryption: unknown;
     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;;;;;;;;;;;;;GAaG;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;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,eAAe,EAChB,EAAE;IACD,eAAe,EAAE,gBAAgB,CAAA;CAClC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAiBhC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,EACjC,eAAe,EACf,WAAW,EACX,UAAU,EACX,EAAE;IACD,eAAe,EAAE,gBAAgB,CAAA;IACjC,WAAW,EAAE,YAAY,CAAA;IACzB,UAAU,EAAE,oBAAoB,CAAA;CACjC,GAAG,OAAO,CAAC,SAAS,CAAC,CAOrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EACN,KAAK,EACN,EAAE;IACD,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;CACd,GAAG;IAAE,UAAU,EAAE,oBAAoB,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAgBzD;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;;;;;;;;;;;;;;GAcG;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,UAAU,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAwBtE;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"}

package/dist/keyring/record.js

@@ -1,16 +1,86 @@
-import { createEdvDocCipher } from '@interop/was-client/edv';
+import { createEdvDocCipher, initRecipients, ownerRecipient } from '@interop/was-client/edv';
 import { KEYRING_COLLECTION } from '../space/collections.js';
 /**
- * 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 const KEYRING_RECORD_VERSION = 2;
+export const KEYRING_RECORD_VERSION = 1;
+/**
+ * Mints the one-epoch descriptor a fresh record is sealed under: epoch[0]
+ * wrapped to the unlock KAK alone, built through `initRecipients` against a
+ * throwaway in-memory store (the descriptor's home is the record itself).
+ *
+ * @param options {object}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the unlock KAK
+ * @returns {Promise<CollectionEncryption>}
+ */
+export async function mintRecordEncryption({ keyAgreementKey }) {
+    let stored = null;
+    const store = {
+        async read() {
+            return stored ? { descriptor: stored } : null;
+        },
+        async replace(next) {
+            stored = next;
+        },
+        async create(next) {
+            stored = next;
+        }
+    };
+    return initRecipients({
+        store,
+        recipients: [ownerRecipient({ keyAgreementKey })]
+    });
+}
+/**
+ * Builds the record cipher: the keyring-context 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).
+ *
+ * @param options {object}
+ * @param options.keyAgreementKey {IKeyAgreementKey}   the unlock KAK
+ * @param options.keyResolver {IKeyResolver}
+ * @param options.encryption {CollectionEncryption}   the record's descriptor
+ * @returns {Promise<DocCipher>}
+ */
+export async function recordCipher({ keyAgreementKey, keyResolver, encryption }) {
+    return createEdvDocCipher({
+        keyAgreementKey,
+        keyResolver,
+        collectionId: KEYRING_COLLECTION.id,
+        encryption
+    });
+}
+/**
+ * Validates the common `{ version, encryption, wrapped }` frame of a stored
+ * record (keyring or recovery -- `label` names the refusals) and returns its
+ * members.
+ *
+ * @param options {object}
+ * @param options.record {unknown}
+ * @param options.label {string}   `'keyring'` or `'recovery'`
+ * @returns {{ encryption: CollectionEncryption, wrapped: unknown }}
+ */
+export function parseRecordFrame({ record, label }) {
+    if (record === null || typeof record !== 'object') {
+        throw new Error(`Malformed ${label} record.`);
+    }
+    const { version, encryption, wrapped } = record;
+    if (version !== KEYRING_RECORD_VERSION) {
+        throw new Error(`Unsupported ${label} record version "${String(version)}".`);
+    }
+    if (encryption === null || typeof encryption !== 'object') {
+        throw new Error(`The ${label} record is missing its encryption descriptor.`);
+    }
+    return { encryption: encryption, wrapped };
+}
 /**
  * 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
@@ -19,13 +89,14 @@ export const KEYRING_RECORD_VERSION = 2;
  *   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: unknown, wrapped: unknown }>}
  */
 export async function wrapKeyringRecord({ controller, email, pointer, keyAgreementKey, keyResolver }) {
-    const cipher = await createEdvDocCipher({
+    const encryption = await mintRecordEncryption({ keyAgreementKey });
+    const cipher = await recordCipher({
         keyAgreementKey,
         keyResolver,
-        collectionId: KEYRING_COLLECTION.id
+        encryption
     });
     const { envelope } = await cipher.encrypt({
         data: {
@@ -43,12 +114,11 @@ export async function wrapKeyringRecord({ controller, email, pointer, keyAgreeme
             createdAt: new Date().toISOString()
         }
     });
-    return { version: KEYRING_RECORD_VERSION, wrapped: envelope };
+    return { version: KEYRING_RECORD_VERSION, encryption, wrapped: envelope };
 }
 /**
  * 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).
  *
@@ -59,17 +129,14 @@ export async function wrapKeyringRecord({ controller, email, pointer, keyAgreeme
  * @returns {Promise<KeyringRecordContents>}
  */
 export async function unwrapKeyringRecord({ record, keyAgreementKey, keyResolver }) {
-    if (record === null || typeof record !== 'object') {
-        throw new Error('Malformed keyring record.');
-    }
-    const { version, wrapped } = record;
-    if (version !== KEYRING_RECORD_VERSION) {
-        throw new Error(`Unsupported keyring record version "${String(version)}".`);
-    }
-    const cipher = await createEdvDocCipher({
+    const { encryption, wrapped } = parseRecordFrame({
+        record,
+        label: 'keyring'
+    });
+    const cipher = await recordCipher({
         keyAgreementKey,
         keyResolver,
-        collectionId: KEYRING_COLLECTION.id
+        encryption
     });
     const plaintext = (await cipher.decrypt({
         envelope: wrapped

package/dist/keyring/record.js.map

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

package/dist/keys/index.d.ts

@@ -36,6 +36,9 @@
  *   re-epoch that brings an encrypted collection onto the roster's current
  *   user key, and the parallel best-effort fan-out over the collections the wallet
  *   names (also the completion sweep's driver).
+ * - `ensureWalletSpaceEpochs` -- the provision-time epoch[0] install for the
+ *   wallet Space's encrypted collections, the EDV-bearing second step of
+ *   `provisionWalletSpace`.
  */
 export { mintUserKey, userKeyVaultKeys } from './userKey.js';
 export type { UserKey } from './userKey.js';
@@ -46,6 +49,7 @@ export { cascadeCollectionsToUserKey, userKeyAsRecipient, rotateCollectionEpochs
 export type { CollectionUserKeyRotationOutcome, UserKeyCascadeResult } from './userKeyCascade.js';
 export type { UserKeyRosterReadResult, RosterRecipientDocument } from './userKeyRoster.js';
 export { userKeyRosterDescriptorStore } from './rosterStore.js';
+export { ensureWalletSpaceEpochs } from './spaceEpochs.js';
 export { readClientLabels, removeClientLabel, setClientLabel } from './clientLabels.js';
 export type { ClientLabelsRecord, ClientLabelsStore } from './clientLabels.js';
 export { wasClientLabelsStore } from './wasLabelsStore.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keys/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC5D,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,mBAAmB,EACnB,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,4BAA4B,EAC7B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,+BAA+B,EAC/B,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,gCAAgC,EAChC,oBAAoB,EACrB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,uBAAuB,EACvB,uBAAuB,EACxB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAE/D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACf,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/keys/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAC5D,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACxB,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,mBAAmB,EACnB,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,4BAA4B,EAC7B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,+BAA+B,EAC/B,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,gCAAgC,EAChC,oBAAoB,EACrB,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,uBAAuB,EACvB,uBAAuB,EACxB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAE/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACf,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAE9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/keys/index.js

@@ -36,12 +36,16 @@
  *   re-epoch that brings an encrypted collection onto the roster's current
  *   user key, and the parallel best-effort fan-out over the collections the wallet
  *   names (also the completion sweep's driver).
+ * - `ensureWalletSpaceEpochs` -- the provision-time epoch[0] install for the
+ *   wallet Space's encrypted collections, the EDV-bearing second step of
+ *   `provisionWalletSpace`.
  */
 export { mintUserKey, userKeyVaultKeys } from './userKey.js';
 export { assertEnrolledClientKeyRecord, decodeClientKeyRecord, encodeClientKeyRecord, parseClientRecordUserKey, parseClientRecordWebvhKeys } from './clientKeyRecord.js';
 export { addUserKeyRosterRecipient, convergeUserKeyRosterToDocument, ensureUserKeyRoster, UserKeyRosterContinuityError, UserKeyRosterIntegrityError, UserKeyRosterUnwrapError, userKeyRosterEpochsSigner, userKeyRosterRecipientResolver, readUserKeyRoster, rosterRecipientKid, rotateUserKeyRoster, verifyUserKeyRosterEpochsSig } from './userKeyRoster.js';
 export { cascadeCollectionsToUserKey, userKeyAsRecipient, rotateCollectionEpochsToUserKey, unwrapUserKeyGenerations } from './userKeyCascade.js';
 export { userKeyRosterDescriptorStore } from './rosterStore.js';
+export { ensureWalletSpaceEpochs } from './spaceEpochs.js';
 export { readClientLabels, removeClientLabel, setClientLabel } from './clientLabels.js';
 export { wasClientLabelsStore } from './wasLabelsStore.js';
 //# sourceMappingURL=index.js.map

package/dist/keys/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/keys/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG5D,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,sBAAsB,CAAA;AAO7B,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,mBAAmB,EACnB,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,4BAA4B,EAC7B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,+BAA+B,EAC/B,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAU5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAE/D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACf,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/keys/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AAG5D,OAAO,EACL,6BAA6B,EAC7B,qBAAqB,EACrB,qBAAqB,EACrB,wBAAwB,EACxB,0BAA0B,EAC3B,MAAM,sBAAsB,CAAA;AAO7B,OAAO,EACL,yBAAyB,EACzB,+BAA+B,EAC/B,mBAAmB,EACnB,4BAA4B,EAC5B,2BAA2B,EAC3B,wBAAwB,EACxB,yBAAyB,EACzB,8BAA8B,EAC9B,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,4BAA4B,EAC7B,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EACL,2BAA2B,EAC3B,kBAAkB,EAClB,+BAA+B,EAC/B,wBAAwB,EACzB,MAAM,qBAAqB,CAAA;AAU5B,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAE/D,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,cAAc,EACf,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/keys/spaceEpochs.d.ts

@@ -0,0 +1,56 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Provision-time key-epoch install for the wallet Space's encrypted
+ * collections: every encrypted collection's descriptor carries an epoch roster
+ * from birth (epoch[0] a fresh random epoch key, never a user-key generation),
+ * and reads/writes are refused fail-closed until it does. `provisionWalletSpace`
+ * (the crypto-free container ensure in `space`) declares the collections; this
+ * EDV-bearing second step installs each one's epoch[0], wrapped to the user key
+ * (recipient zero). It lives in `keys` rather than `space` so the root barrel,
+ * which re-exports `space`, stays free of the EDV crypto graph -- the same
+ * split was-client makes between `ensureSpaceAndCollection` and
+ * `ensureFirstEpoch`.
+ */
+import type { WasClient } from '@interop/was-client';
+import type { UserKey } from './userKey.js';
+/**
+ * Installs key epoch[0] on every encrypted collection of the wallet Space
+ * roster (or on the given `collectionIds`), concurrently, wrapped to the user
+ * key. Each install is `ensureFirstEpoch`: create-if-absent through the
+ * descriptor-store seam, adopting (never overwriting) a roster another
+ * provisioner already landed -- so re-running after a tear converges, and
+ * exactly one epoch[0] ever exists per collection. Run it after
+ * `provisionWalletSpace` has declared the collections; the wallet Space's
+ * provisioning is complete only once both steps have.
+ *
+ * Run both steps from the sync engine's `ensureProvisioned` seam (or, for a
+ * driver of its own, equally before the collection's first content push): the
+ * descriptor-before-first-content-push invariant rests on it. A caller that
+ * minted envelopes eagerly against a locally-minted roster and finds
+ * `installed: false` here (another provisioner's create won) has adopted the
+ * winner's descriptor and must re-mint its pending envelopes under that
+ * descriptor's current epoch before pushing -- `remintPendingEnvelopes`
+ * (`@interop/wallet-core/sync`) is that path.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}
+ * @param options.spaceId {string}
+ * @param options.userKey {UserKey}   the account's user key, epoch[0]'s one
+ *   initial recipient
+ * @param [options.collectionIds] {string[]}   the encrypted collections to
+ *   cover; defaults to the wallet Space roster's encrypted collections. A
+ *   caller naming its own ids (e.g. `contacts`) must name only collections
+ *   declared encrypted
+ * @returns {Promise<Record<string, boolean>>}   per collection id, whether
+ *   this call installed its epoch[0] (`false` means an existing roster was
+ *   adopted)
+ */
+export declare function ensureWalletSpaceEpochs({ was, spaceId, userKey, collectionIds }: {
+    was: WasClient;
+    spaceId: string;
+    userKey: UserKey;
+    collectionIds?: string[];
+}): Promise<Record<string, boolean>>;
+//# sourceMappingURL=spaceEpochs.d.ts.map

package/dist/keys/spaceEpochs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaceEpochs.d.ts","sourceRoot":"","sources":["../../src/keys/spaceEpochs.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAKpD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,uBAAuB,CAAC,EAC5C,GAAG,EACH,OAAO,EACP,OAAO,EACP,aAAa,EACd,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAyBnC"}

package/dist/keys/spaceEpochs.js

@@ -0,0 +1,55 @@
+import { ensureFirstEpoch } from '@interop/was-client/edv';
+import { WALLET_SPACE_PROVISION_ROSTER } from '../space/collections.js';
+import { userKeyAsRecipient } from './userKeyCascade.js';
+/**
+ * Installs key epoch[0] on every encrypted collection of the wallet Space
+ * roster (or on the given `collectionIds`), concurrently, wrapped to the user
+ * key. Each install is `ensureFirstEpoch`: create-if-absent through the
+ * descriptor-store seam, adopting (never overwriting) a roster another
+ * provisioner already landed -- so re-running after a tear converges, and
+ * exactly one epoch[0] ever exists per collection. Run it after
+ * `provisionWalletSpace` has declared the collections; the wallet Space's
+ * provisioning is complete only once both steps have.
+ *
+ * Run both steps from the sync engine's `ensureProvisioned` seam (or, for a
+ * driver of its own, equally before the collection's first content push): the
+ * descriptor-before-first-content-push invariant rests on it. A caller that
+ * minted envelopes eagerly against a locally-minted roster and finds
+ * `installed: false` here (another provisioner's create won) has adopted the
+ * winner's descriptor and must re-mint its pending envelopes under that
+ * descriptor's current epoch before pushing -- `remintPendingEnvelopes`
+ * (`@interop/wallet-core/sync`) is that path.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}
+ * @param options.spaceId {string}
+ * @param options.userKey {UserKey}   the account's user key, epoch[0]'s one
+ *   initial recipient
+ * @param [options.collectionIds] {string[]}   the encrypted collections to
+ *   cover; defaults to the wallet Space roster's encrypted collections. A
+ *   caller naming its own ids (e.g. `contacts`) must name only collections
+ *   declared encrypted
+ * @returns {Promise<Record<string, boolean>>}   per collection id, whether
+ *   this call installed its epoch[0] (`false` means an existing roster was
+ *   adopted)
+ */
+export async function ensureWalletSpaceEpochs({ was, spaceId, userKey, collectionIds }) {
+    const ids = collectionIds ??
+        WALLET_SPACE_PROVISION_ROSTER.filter(spec => spec.encryption === 'edv').map(spec => spec.collectionId);
+    const installed = {};
+    await Promise.all(ids.map(async (collectionId) => {
+        try {
+            const result = await ensureFirstEpoch({
+                collection: was.space(spaceId).collection(collectionId),
+                recipients: [userKeyAsRecipient({ userKey })]
+            });
+            installed[collectionId] = result.installed;
+        }
+        catch (err) {
+            throw new Error(`Error installing the first key epoch for collection ` +
+                `"${collectionId}" in space "${spaceId}".`, { cause: err });
+        }
+    }));
+    return installed;
+}
+//# sourceMappingURL=spaceEpochs.js.map

package/dist/keys/spaceEpochs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spaceEpochs.js","sourceRoot":"","sources":["../../src/keys/spaceEpochs.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAA;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAGxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,EAC5C,GAAG,EACH,OAAO,EACP,OAAO,EACP,aAAa,EAMd;IACC,MAAM,GAAG,GACP,aAAa;QACb,6BAA6B,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,UAAU,KAAK,KAAK,CAAC,CAAC,GAAG,CACzE,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,YAAY,CAC1B,CAAA;IACH,MAAM,SAAS,GAA4B,EAAE,CAAA;IAC7C,MAAM,OAAO,CAAC,GAAG,CACf,GAAG,CAAC,GAAG,CAAC,KAAK,EAAC,YAAY,EAAC,EAAE;QAC3B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC;gBACpC,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC;gBACvD,UAAU,EAAE,CAAC,kBAAkB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC;aAC9C,CAAC,CAAA;YACF,SAAS,CAAC,YAAY,CAAC,GAAG,MAAM,CAAC,SAAS,CAAA;QAC5C,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,sDAAsD;gBACpD,IAAI,YAAY,eAAe,OAAO,IAAI,EAC5C,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAA;QACH,CAAC;IACH,CAAC,CAAC,CACH,CAAA;IACD,OAAO,SAAS,CAAA;AAClB,CAAC"}

package/dist/keys/userKeyCascade.d.ts

@@ -19,12 +19,13 @@
  * unwrapUserKeyGenerations}) -- needed both to recognize a stale epoch and to
  * escrow the fresh user key into a stranded collection's history.
  *
- * One residue, accepted: a collection with NO epochs gets the newest prior
- * generation installed as its first epoch (pre-epoch envelopes are sealed to
- * the era's user key KAK, and the user key IS the epoch construction, so they
- * ARE epoch-of-that-generation envelopes) -- envelopes older than that
- * generation, on a collection every prior cascade missed, stay readable only to
- * sessions that held the older key.
+ * The cascade is rotation-only: every encrypted collection's descriptor
+ * carries an epoch roster from provisioning (`ensureWalletSpaceEpochs`), so a
+ * descriptor met without epochs can only mean a tampering or pre-provisioning
+ * host and is refused fail-closed. No construction anywhere installs a
+ * user-key secret as a collection epoch secret, which is what keeps a
+ * collection-epoch escrow (an App Connect grant, a share) from ever handing a
+ * grantee the user key itself.
  */
 import type { IKeyAgreementKey } from '@interop/data-integrity-core';
 import type { CollectionEncryption } from '@interop/was-client';
@@ -64,21 +65,15 @@ export declare function unwrapUserKeyGenerations({ descriptor, clientKeyAgreemen
 }): Promise<UserKey[]>;
 /**
  * What one collection's cascade step did: `noop` (already on the current user
- * key), `installed` (a pre-epoch collection on a first-generation account
- * gained its first epoch; nothing to retire), `escrowed` (the current user
- * key's wrap was completed into history with no stale epoch to rotate), or
- * `rotated` (a fresh epoch sealed to the current user key, the stale
- * generations retired -- the pre-epoch install falls through to this).
+ * key), `escrowed` (the current user key's wrap was completed into history
+ * with no stale epoch to rotate), or `rotated` (a fresh epoch sealed to the
+ * current user key, the stale generations retired).
  */
-export type CollectionUserKeyRotationOutcome = 'noop' | 'installed' | 'escrowed' | 'rotated';
+export type CollectionUserKeyRotationOutcome = 'noop' | 'escrowed' | 'rotated';
 /**
  * Brings ONE encrypted collection's epoch roster onto the current user key --
  * the per-collection op of the revocation cascade and of the completion sweep:
  *
- * - **No epochs yet**: install the newest PRIOR generation as the first epoch
- *   (see the module doc), wrapped to that generation and the current user key,
- *   then fall through to the rotation. A first-generation account (nothing
- *   prior) installs the current user key alone and is done.
  * - **Stale current epoch** (names a non-current generation): one
  *   `replaceRecipient` write -- the current user key escrowed into every epoch,
  *   a fresh epoch minted without the stale generations. Two requests per
@@ -86,6 +81,9 @@ export type CollectionUserKeyRotationOutcome = 'noop' | 'installed' | 'escrowed'
  *   default did:key resolver re-wraps them).
  * - **Current already** and fully escrowed: no write at all, so a naive
  *   re-run after a mid-cascade crash converges with zero redundant epochs.
+ * - **No epochs**: refused fail-closed (see the module doc) -- provisioning
+ *   installs every encrypted collection's epoch[0], so the cascade never
+ *   mints a first epoch.
  *
  * The pull axis is deliberately a no-op here: a user key rotation follows a
  * document edit (client revocation, code retirement) that already killed the