@interop/wallet-core 0.34.0 → 0.36.0

package/README.md

@@ -127,6 +127,17 @@ The subpaths:
   (connect code, approval, completion) plus the onboarding-response envelope
   that carries a connect code back over an exchange.
 
+- **`@interop/wallet-core/genesis`** -- the account-genesis ceremony: the local
+  mint of a brand-new account's complete key set (`mintAccountKeySet`: Space id,
+  client identity seed, user key, did:webvh update keys) and the staged
+  provisioning both apps must encode identically (`ensureAccountGenesis`: Space
+  provisioning, the optional KMS key-map acquisition, did:webvh genesis,
+  user-key roster genesis after DID publication, epoch[0] on every encrypted
+  roster collection, and the Space-controller promotion, also exported standing
+  alone as `ensurePromotedSpaceController`). Idempotent end to end: a torn run
+  heals by re-running. The keyring bind is deliberately not a stage, so a wallet
+  with no unlock method bound at creation drives the same ceremony.
+
 - **`@interop/wallet-core/recovery`** -- recovery codes on the roster identity
   model: a code as a minimal always-enrolled wallet client (format and
   derivation, the recovery record, the document half of issuance / revocation /

package/dist/descriptors/cipher.d.ts

@@ -22,6 +22,15 @@
  * epoch after the one refresh is spent) propagates. A refresh that itself
  * fails does not count as spent -- the original `UnknownEpochError` is
  * rethrown and a later decrypt may try again.
+ *
+ * Only `UnknownEpochError` drives that refresh, and by design. The client
+ * splits the two ways a decrypt can find no key: an epoch the descriptor does
+ * not list at all raises `UnknownEpochError`, because a fresher descriptor may
+ * well list it; an epoch the descriptor does list but this reader holds no key
+ * for raises `KeyUnwrapError` (never a recipient, or removed and the epoch
+ * rotated). The second is rethrown immediately, with the refresh left
+ * untouched, since re-reading the same descriptor cannot produce a key the
+ * reader was not given.
  */
 import type { IKeyAgreementKey, IKeyResolver } from '@interop/data-integrity-core';
 import { type DocCipher } from '@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;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"cipher.d.ts","sourceRoot":"","sources":["../../src/descriptors/cipher.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;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.map

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

@@ -0,0 +1,206 @@
+import type { CollectionEncryption, WasClient } from '@interop/was-client';
+import type { EncryptionDescriptorStore } from '@interop/was-client/edv';
+import type { IKeyAgreementKey } from '@interop/data-integrity-core';
+import { type ClientWebvhUpdateKeys, type DidWebKeyMapV2, type ICapabilityAgent, type WebvhIdStore } from '../webvh/index.js';
+import { type UserKey, type WalletSpaceEpochsResult } from '../keys/index.js';
+import type { ResourceLogPinStore } from '../resourceLog/index.js';
+/**
+ * The complete key set a brand-new account mints locally before anything
+ * touches the network: the data Space id, this founding client's identity
+ * seed, the account's user key, and the client-held did:webvh update-key
+ * seeds. Persisting the set durably (under the app's unlock layer) is the
+ * caller's job, and for the update keys it must happen BEFORE
+ * {@link ensureAccountGenesis} publishes anything -- the seeds are the only
+ * update authority the log will ever accept.
+ */
+export interface AccountKeySet {
+    spaceId: string;
+    clientSeed: Uint8Array;
+    userKey: Required<UserKey>;
+    updateKeys: ClientWebvhUpdateKeys;
+}
+/**
+ * Mints a fresh data-Space id: 32 random bytes, base64url without padding.
+ * Random rather than controller-derived on purpose: the Space's controller is
+ * promoted to a did:webvh whose id embeds this Space id, so a
+ * controller-derived id would be circular.
+ *
+ * @returns {string}
+ */
+export declare function mintSpaceId(): string;
+/**
+ * Mints the complete key set of a brand-new account: a fresh Space id, a
+ * 32-byte client identity seed (expanded to the founding client's agents via
+ * `agentsFromSeed`), the account's user key, and the did:webvh update-key
+ * pair. Pure minting -- nothing here touches the network or any store.
+ *
+ * @returns {Promise<AccountKeySet>}
+ */
+export declare function mintAccountKeySet(): Promise<AccountKeySet>;
+/**
+ * What the promotion stage found and did: `promoted` (the Space Description
+ * named another controller -- on a fresh signup, this founding client's
+ * did:key -- and the ceremony moved it to the account DID), `confirmed` (the
+ * Space already names the account DID; nothing written), or `healed` (the
+ * Description was unreadable under the session's signing identity -- the torn
+ * state where the controller PUT never landed -- and the re-PUT signed as the
+ * stored did:key controller landed it).
+ */
+export type SpaceControllerPromotion = 'promoted' | 'confirmed' | 'healed';
+/**
+ * Promotes the data Space's controller to the account's did:webvh, as a state
+ * machine over the Space Description so every state a torn earlier run can
+ * leave behind converges:
+ *
+ * - The Description reads and already names `did`: nothing to do.
+ * - The Description reads and names another controller (a fresh signup: this
+ *   founding client's did:key, which `was` is then signing as): one configure
+ *   PUT moves it to `did`.
+ * - The Description is unreadable (`null` covers both absent and
+ *   unauthorized): the torn case, where the session already signs under the
+ *   did:webvh but the controller PUT never landed, so the server still
+ *   authorizes only the stored did:key controller. The re-PUT goes through
+ *   `wasAsClient`, the handle signing under this client's plain did:key.
+ *
+ * The PUT always carries the full `{ name, controller }` description, so the
+ * unreadable-Description merge guard in was-client's `configure` never
+ * defaults anything from a state this ceremony cannot see.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   signing as the session currently signs
+ *   (this client's did:key on a fresh signup; the promoted did:webvh keyId on
+ *   a heal re-run)
+ * @param [options.wasAsClient] {WasClient}   signing under this client's
+ *   plain did:key, for the torn-promotion heal; omitted, that branch refuses
+ *   instead of healing
+ * @param options.spaceId {string}
+ * @param options.did {string}   the account's did:webvh DID
+ * @returns {Promise<SpaceControllerPromotion>}
+ */
+export declare function ensurePromotedSpaceController({ was, wasAsClient, spaceId, did }: {
+    was: WasClient;
+    wasAsClient?: WasClient;
+    spaceId: string;
+    did: string;
+}): Promise<SpaceControllerPromotion>;
+/**
+ * The Space-provisioning stage of {@link ensureAccountGenesis} failed: the
+ * Space (or part of its collection roster) could not be ensured, so nothing
+ * downstream ran. Raised as its own class with a stable `name`, so a caller
+ * that treats the later stages as non-fatal can still let a missing Space
+ * propagate -- match it on `err.name === 'AccountGenesisSpaceError'`, never
+ * `instanceof` (the error can be raised by a linked or duplicated copy of
+ * this package).
+ */
+export declare class AccountGenesisSpaceError extends Error {
+    constructor(options: {
+        spaceId: string;
+        cause: unknown;
+    });
+}
+/**
+ * The stages whose failures the ceremony collects instead of throwing (see
+ * the module doc for the split).
+ */
+export type AccountGenesisStage = 'didWebKeys' | 'roster' | 'epochs' | 'promotion';
+/**
+ * What a completed ceremony reports: the account DID, each collected stage's
+ * outcome where it ran (the roster descriptor, the per-collection epoch
+ * install -- whose own `failed` list stays inside it -- and what the
+ * promotion found), and the stages that failed on this run. A result with
+ * `failed` entries is a resumable success: the account exists and is
+ * identified, and a naive re-run of the whole ceremony finishes the rest.
+ */
+export interface AccountGenesisResult {
+    did: string;
+    rosterDescriptor?: CollectionEncryption;
+    epochs?: WalletSpaceEpochsResult;
+    promotion?: SpaceControllerPromotion;
+    failed: Array<{
+        stage: AccountGenesisStage;
+        error: unknown;
+    }>;
+}
+/**
+ * Runs the account-genesis ceremony against an already-minted
+ * {@link AccountKeySet} (whose update-key seeds the caller has already
+ * persisted durably). Idempotent end to end: every stage adopts what an
+ * earlier run landed, so a torn run -- and a lost create race against a
+ * concurrent provisioner -- heals by re-running.
+ *
+ * Stage order (the module doc has the why): Space provisioning, the optional
+ * KMS key-map acquisition, did:webvh genesis, user-key roster genesis, the
+ * encrypted collections' epoch[0] install, Space-controller promotion.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   signing as the session currently signs:
+ *   this client's did:key on a fresh signup, the promoted did:webvh keyId on
+ *   a heal re-run over an already-promoted account
+ * @param [options.wasAsClient] {WasClient}   signing under this client's
+ *   plain did:key, for the torn-promotion heal (see
+ *   {@link ensurePromotedSpaceController})
+ * @param options.wasServerUrl {string}   the storage server the account
+ *   lives on; the did:webvh id embeds its host
+ * @param options.spaceId {string}
+ * @param options.keyAgent {ICapabilityAgent}   this founding client's signing
+ *   key agent (`agentsFromSeed` over the key set's `clientSeed`); its did:key
+ *   id is the Space's controller at creation
+ * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
+ *   (identity) key-agreement key -- its published `keyAgreement` verification
+ *   method, and the roster's first recipient
+ * @param options.userKey {UserKey}   the account's user key, recipient zero
+ *   of every encrypted collection and the roster's first epoch
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   the client-held
+ *   did:webvh update-key seeds, already durably persisted
+ * @param options.idStore {WebvhIdStore}   the account's `id` collection
+ *   store the did:webvh ceremony reads and publishes through
+ * @param options.rosterStoreFor {Function}   `({ did }) =>
+ *   EncryptionDescriptorStore` -- builds the user-key roster's descriptor
+ *   store once the account DID is known (the log-governed store's controller
+ *   view and chain-head pin are the app's wiring)
+ * @param [options.provideDidWebKeys] {Function}   `() =>
+ *   Promise<DidWebKeyMapV2 | undefined>` -- the KMS key-map acquisition (a
+ *   wallet that keeps a KMS runs its did:web provisioning here, after the
+ *   Space exists); absent or resolving `undefined`, the genesis is
+ *   client-keys-only and no `keys.json` is ever written. A throw is
+ *   collected, not fatal: the genesis proceeds client-keys-only and a later
+ *   run heals the document with the convenience key
+ * @param [options.expectedDid] {string}   the account's did:webvh from the
+ *   caller's stored account pointer, when it already names one; the genesis
+ *   read then refuses a published log resolving to any other account
+ * @param [options.accountLogPinStore] {ResourceLogPinStore}   this client's
+ *   chain-head pin for the account log
+ * @param [options.onDidPublished] {Function}   `({ did }) => Promise<void>`
+ *   -- runs between the DID publication and the roster genesis, so the app
+ *   can adopt the DID (and drop any verified-log memo) before the roster
+ *   store's controller view resolves against the published document
+ * @param [options.promoteController] {boolean}   whether to run the
+ *   promotion stage (default `true`). An app whose account pointer must
+ *   durably name the DID BEFORE the controller PUT lands -- and whose
+ *   pointer write lives outside this call (freewallet's keyring re-bind) --
+ *   passes `false` and runs {@link ensurePromotedSpaceController} itself
+ *   after that write
+ * @returns {Promise<AccountGenesisResult>}
+ */
+export declare function ensureAccountGenesis({ was, wasAsClient, wasServerUrl, spaceId, keyAgent, clientKeyAgreementKey, userKey, updateKeys, idStore, rosterStoreFor, provideDidWebKeys, expectedDid, accountLogPinStore, onDidPublished, promoteController }: {
+    was: WasClient;
+    wasAsClient?: WasClient;
+    wasServerUrl: string;
+    spaceId: string;
+    keyAgent: ICapabilityAgent;
+    clientKeyAgreementKey: IKeyAgreementKey;
+    userKey: UserKey;
+    updateKeys: ClientWebvhUpdateKeys;
+    idStore: WebvhIdStore;
+    rosterStoreFor: (options: {
+        did: string;
+    }) => EncryptionDescriptorStore;
+    provideDidWebKeys?: () => Promise<DidWebKeyMapV2 | undefined>;
+    expectedDid?: string;
+    accountLogPinStore?: ResourceLogPinStore;
+    onDidPublished?: (published: {
+        did: string;
+    }) => Promise<void>;
+    promoteController?: boolean;
+}): Promise<AccountGenesisResult>;
+//# sourceMappingURL=accountGenesis.d.ts.map

package/dist/genesis/accountGenesis.d.ts.map

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

package/dist/genesis/accountGenesis.js

@@ -0,0 +1,294 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The account-genesis ceremony: minting a brand-new wallet account's key set
+ * and provisioning its data Space, in the one stage order every wallet app
+ * must encode identically -- Space provisioning, did:webvh genesis, user-key
+ * roster genesis (after DID publication, so the roster log's entry proofs
+ * anchor in the published document), epoch[0] on every encrypted roster
+ * collection, and Space-controller promotion.
+ *
+ * Two callers, one ceremony. A wallet that keeps a KMS (freewallet) supplies
+ * `provideDidWebKeys` and gets the KMS-backed did:webvh genesis; a wallet
+ * with no KMS anywhere in the path (dcw) supplies nothing and gets the
+ * client-keys-only genesis. The keyring bind is deliberately NOT a stage:
+ * where an app binds an unlock method (and whether it binds one at all)
+ * stays app-side, as does the `userExists` probe -- that probe exists only
+ * because a passphrase signup can collide with an existing account, which is
+ * an unlock-layer concern, not an account-genesis one.
+ *
+ * Every stage detects its own completion from durable state alone (the
+ * cascade/sweep posture): the Space provisioning and the epoch install are
+ * create-if-absent and adopt what an earlier provisioner landed, the
+ * did:webvh genesis probes `did.jsonl` and adopts a log its seeds still
+ * authorize, the roster genesis returns an existing roster untouched, and
+ * the promotion is a state machine over the Space Description. So a torn run
+ * heals by naively re-running the whole ceremony, backstopped by the
+ * login-time sweeps.
+ *
+ * The essential identity chain -- Space provisioning and the did:webvh
+ * genesis -- throws on failure (nothing downstream can proceed without it);
+ * the stages after it are collected in `failed` instead, so a transient
+ * failure on one never costs the caller the others' outcomes -- a completed
+ * call with `failed` entries is a resumable success, finished by a re-run.
+ */
+import { base64urlnopad } from '@scure/base';
+import { provisionWalletSpace, WALLET_SPACE_NAME } from '../space/index.js';
+import { clientSigningKeyMultibase, ensureDidWebvh, mintClientWebvhUpdateKeys } from '../webvh/index.js';
+import { ensureUserKeyRoster, ensureWalletSpaceEpochs, mintUserKey } from '../keys/index.js';
+/**
+ * The byte length of a freshly minted data-Space id.
+ */
+const SPACE_ID_BYTES = 32;
+/**
+ * Mints a fresh data-Space id: 32 random bytes, base64url without padding.
+ * Random rather than controller-derived on purpose: the Space's controller is
+ * promoted to a did:webvh whose id embeds this Space id, so a
+ * controller-derived id would be circular.
+ *
+ * @returns {string}
+ */
+export function mintSpaceId() {
+    return base64urlnopad.encode(crypto.getRandomValues(new Uint8Array(SPACE_ID_BYTES)));
+}
+/**
+ * Mints the complete key set of a brand-new account: a fresh Space id, a
+ * 32-byte client identity seed (expanded to the founding client's agents via
+ * `agentsFromSeed`), the account's user key, and the did:webvh update-key
+ * pair. Pure minting -- nothing here touches the network or any store.
+ *
+ * @returns {Promise<AccountKeySet>}
+ */
+export async function mintAccountKeySet() {
+    const clientSeed = crypto.getRandomValues(new Uint8Array(32));
+    return {
+        spaceId: mintSpaceId(),
+        clientSeed,
+        userKey: await mintUserKey(),
+        updateKeys: await mintClientWebvhUpdateKeys()
+    };
+}
+/**
+ * Promotes the data Space's controller to the account's did:webvh, as a state
+ * machine over the Space Description so every state a torn earlier run can
+ * leave behind converges:
+ *
+ * - The Description reads and already names `did`: nothing to do.
+ * - The Description reads and names another controller (a fresh signup: this
+ *   founding client's did:key, which `was` is then signing as): one configure
+ *   PUT moves it to `did`.
+ * - The Description is unreadable (`null` covers both absent and
+ *   unauthorized): the torn case, where the session already signs under the
+ *   did:webvh but the controller PUT never landed, so the server still
+ *   authorizes only the stored did:key controller. The re-PUT goes through
+ *   `wasAsClient`, the handle signing under this client's plain did:key.
+ *
+ * The PUT always carries the full `{ name, controller }` description, so the
+ * unreadable-Description merge guard in was-client's `configure` never
+ * defaults anything from a state this ceremony cannot see.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   signing as the session currently signs
+ *   (this client's did:key on a fresh signup; the promoted did:webvh keyId on
+ *   a heal re-run)
+ * @param [options.wasAsClient] {WasClient}   signing under this client's
+ *   plain did:key, for the torn-promotion heal; omitted, that branch refuses
+ *   instead of healing
+ * @param options.spaceId {string}
+ * @param options.did {string}   the account's did:webvh DID
+ * @returns {Promise<SpaceControllerPromotion>}
+ */
+export async function ensurePromotedSpaceController({ was, wasAsClient, spaceId, did }) {
+    const space = was.space(spaceId);
+    const description = await space.describe();
+    if (description !== null) {
+        if (description.controller === did) {
+            return 'confirmed';
+        }
+        await space.configure({ name: WALLET_SPACE_NAME, controller: did });
+        return 'promoted';
+    }
+    if (!wasAsClient) {
+        throw new Error('The Space Description is unreadable under the current signing ' +
+            'identity and no did:key-signed client was supplied to heal a torn ' +
+            'controller promotion.');
+    }
+    await wasAsClient
+        .space(spaceId)
+        .configure({ name: WALLET_SPACE_NAME, controller: did });
+    return 'healed';
+}
+/**
+ * The Space-provisioning stage of {@link ensureAccountGenesis} failed: the
+ * Space (or part of its collection roster) could not be ensured, so nothing
+ * downstream ran. Raised as its own class with a stable `name`, so a caller
+ * that treats the later stages as non-fatal can still let a missing Space
+ * propagate -- match it on `err.name === 'AccountGenesisSpaceError'`, never
+ * `instanceof` (the error can be raised by a linked or duplicated copy of
+ * this package).
+ */
+export class AccountGenesisSpaceError extends Error {
+    constructor(options) {
+        super(`Provisioning the wallet Space "${options.spaceId}" failed; ` +
+            'the account-genesis ceremony did not proceed.', { cause: options.cause });
+        this.name = 'AccountGenesisSpaceError';
+    }
+}
+/**
+ * Runs the account-genesis ceremony against an already-minted
+ * {@link AccountKeySet} (whose update-key seeds the caller has already
+ * persisted durably). Idempotent end to end: every stage adopts what an
+ * earlier run landed, so a torn run -- and a lost create race against a
+ * concurrent provisioner -- heals by re-running.
+ *
+ * Stage order (the module doc has the why): Space provisioning, the optional
+ * KMS key-map acquisition, did:webvh genesis, user-key roster genesis, the
+ * encrypted collections' epoch[0] install, Space-controller promotion.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   signing as the session currently signs:
+ *   this client's did:key on a fresh signup, the promoted did:webvh keyId on
+ *   a heal re-run over an already-promoted account
+ * @param [options.wasAsClient] {WasClient}   signing under this client's
+ *   plain did:key, for the torn-promotion heal (see
+ *   {@link ensurePromotedSpaceController})
+ * @param options.wasServerUrl {string}   the storage server the account
+ *   lives on; the did:webvh id embeds its host
+ * @param options.spaceId {string}
+ * @param options.keyAgent {ICapabilityAgent}   this founding client's signing
+ *   key agent (`agentsFromSeed` over the key set's `clientSeed`); its did:key
+ *   id is the Space's controller at creation
+ * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
+ *   (identity) key-agreement key -- its published `keyAgreement` verification
+ *   method, and the roster's first recipient
+ * @param options.userKey {UserKey}   the account's user key, recipient zero
+ *   of every encrypted collection and the roster's first epoch
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   the client-held
+ *   did:webvh update-key seeds, already durably persisted
+ * @param options.idStore {WebvhIdStore}   the account's `id` collection
+ *   store the did:webvh ceremony reads and publishes through
+ * @param options.rosterStoreFor {Function}   `({ did }) =>
+ *   EncryptionDescriptorStore` -- builds the user-key roster's descriptor
+ *   store once the account DID is known (the log-governed store's controller
+ *   view and chain-head pin are the app's wiring)
+ * @param [options.provideDidWebKeys] {Function}   `() =>
+ *   Promise<DidWebKeyMapV2 | undefined>` -- the KMS key-map acquisition (a
+ *   wallet that keeps a KMS runs its did:web provisioning here, after the
+ *   Space exists); absent or resolving `undefined`, the genesis is
+ *   client-keys-only and no `keys.json` is ever written. A throw is
+ *   collected, not fatal: the genesis proceeds client-keys-only and a later
+ *   run heals the document with the convenience key
+ * @param [options.expectedDid] {string}   the account's did:webvh from the
+ *   caller's stored account pointer, when it already names one; the genesis
+ *   read then refuses a published log resolving to any other account
+ * @param [options.accountLogPinStore] {ResourceLogPinStore}   this client's
+ *   chain-head pin for the account log
+ * @param [options.onDidPublished] {Function}   `({ did }) => Promise<void>`
+ *   -- runs between the DID publication and the roster genesis, so the app
+ *   can adopt the DID (and drop any verified-log memo) before the roster
+ *   store's controller view resolves against the published document
+ * @param [options.promoteController] {boolean}   whether to run the
+ *   promotion stage (default `true`). An app whose account pointer must
+ *   durably name the DID BEFORE the controller PUT lands -- and whose
+ *   pointer write lives outside this call (freewallet's keyring re-bind) --
+ *   passes `false` and runs {@link ensurePromotedSpaceController} itself
+ *   after that write
+ * @returns {Promise<AccountGenesisResult>}
+ */
+export async function ensureAccountGenesis({ was, wasAsClient, wasServerUrl, spaceId, keyAgent, clientKeyAgreementKey, userKey, updateKeys, idStore, rosterStoreFor, provideDidWebKeys, expectedDid, accountLogPinStore, onDidPublished, promoteController = true }) {
+    const failed = [];
+    // 1. The Space and its collection roster, create-if-absent under this
+    // founding client's did:key controller (adopted untouched when it exists).
+    // Raised as the typed refusal so a caller that treats the later stages as
+    // non-fatal can still propagate a Space that never came up.
+    try {
+        await provisionWalletSpace({ was, spaceId, controllerDid: keyAgent.id });
+    }
+    catch (err) {
+        throw new AccountGenesisSpaceError({ spaceId, cause: err });
+    }
+    // 2. The optional KMS key map, acquired only once the Space exists (a
+    // KMS-keeping wallet writes keys.json and did.json into it here). A throw
+    // degrades to the client-keys-only genesis rather than aborting: every
+    // later ceremony anchors in client keys, and the first KMS-capable re-run
+    // heals the document with the convenience key.
+    let didWebKeys;
+    if (provideDidWebKeys) {
+        try {
+            didWebKeys = await provideDidWebKeys();
+        }
+        catch (err) {
+            failed.push({ stage: 'didWebKeys', error: err });
+        }
+    }
+    // 3. The did:webvh genesis -- probe, adopt, or create-and-publish. Fatal on
+    // failure: the account DID is what every remaining stage anchors in.
+    const { publicKeyMultibase: keyAgreementKeyMultibase } = clientKeyAgreementKey;
+    if (!keyAgreementKeyMultibase) {
+        throw new Error('The client key-agreement key has no public multibase.');
+    }
+    const { did } = await ensureDidWebvh({
+        idStore,
+        wasServerUrl,
+        spaceId,
+        ...(didWebKeys ? { didWebKeys } : {}),
+        clientKeys: {
+            signingKeyMultibase: clientSigningKeyMultibase({ keyAgent }),
+            keyAgreementKeyMultibase
+        },
+        updateKeys,
+        ...(expectedDid !== undefined ? { expectedDid } : {}),
+        ...(accountLogPinStore ? { pinStore: accountLogPinStore } : {})
+    });
+    await onDidPublished?.({ did });
+    // 4. The user-key roster genesis, strictly after the DID publication: the
+    // roster log's entry proofs anchor in the published document, so a roster
+    // created first could never verify.
+    let rosterDescriptor;
+    try {
+        rosterDescriptor = await ensureUserKeyRoster({
+            store: rosterStoreFor({ did }),
+            userKey,
+            clientKeyAgreementKey
+        });
+    }
+    catch (err) {
+        failed.push({ stage: 'roster', error: err });
+    }
+    // 5. Epoch[0] on every encrypted roster collection, wrapped to the user
+    // key. Its own per-collection failures stay inside the result (`epochs
+    // .failed`); only a fan-out that could not run at all lands here.
+    let epochs;
+    try {
+        epochs = await ensureWalletSpaceEpochs({ was, spaceId, userKey });
+    }
+    catch (err) {
+        failed.push({ stage: 'epochs', error: err });
+    }
+    // 6. The controller promotion, last: every earlier stage ran under the
+    // signing identity the Space's stored controller authorizes. Skipped when
+    // the caller's account-pointer write must land first (see the JSDoc).
+    let promotion;
+    if (promoteController) {
+        try {
+            promotion = await ensurePromotedSpaceController({
+                was,
+                ...(wasAsClient ? { wasAsClient } : {}),
+                spaceId,
+                did
+            });
+        }
+        catch (err) {
+            failed.push({ stage: 'promotion', error: err });
+        }
+    }
+    return {
+        did,
+        ...(rosterDescriptor ? { rosterDescriptor } : {}),
+        ...(epochs ? { epochs } : {}),
+        ...(promotion ? { promotion } : {}),
+        failed
+    };
+}
+//# sourceMappingURL=accountGenesis.js.map

package/dist/genesis/accountGenesis.js.map

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

package/dist/genesis/index.d.ts

@@ -0,0 +1,22 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/genesis` subpath: the account-genesis ceremony --
+ * minting a brand-new account's key set and provisioning its data Space in
+ * the one stage order both wallet apps must encode identically.
+ *
+ * - `mintAccountKeySet` / `mintSpaceId` -- the local mint of a new account's
+ *   complete key set (Space id, client identity seed, user key, did:webvh
+ *   update keys), before anything touches the network.
+ * - `ensureAccountGenesis` -- the ceremony itself: Space provisioning, the
+ *   optional KMS key-map acquisition, did:webvh genesis, user-key roster
+ *   genesis, epoch[0] on every encrypted roster collection, and
+ *   Space-controller promotion; idempotent end to end, so a torn run heals
+ *   by re-running.
+ * - `ensurePromotedSpaceController` -- the promotion stage standing alone,
+ *   the state machine a login-time heal drives directly.
+ */
+export { AccountGenesisSpaceError, ensureAccountGenesis, ensurePromotedSpaceController, mintAccountKeySet, mintSpaceId } from './accountGenesis.js';
+export type { AccountGenesisResult, AccountGenesisStage, AccountKeySet, SpaceControllerPromotion } from './accountGenesis.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/genesis/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,6BAA6B,EAC7B,iBAAiB,EACjB,WAAW,EACZ,MAAM,qBAAqB,CAAA;AAC5B,YAAY,EACV,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,wBAAwB,EACzB,MAAM,qBAAqB,CAAA"}

package/dist/genesis/index.js

@@ -0,0 +1,21 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/genesis` subpath: the account-genesis ceremony --
+ * minting a brand-new account's key set and provisioning its data Space in
+ * the one stage order both wallet apps must encode identically.
+ *
+ * - `mintAccountKeySet` / `mintSpaceId` -- the local mint of a new account's
+ *   complete key set (Space id, client identity seed, user key, did:webvh
+ *   update keys), before anything touches the network.
+ * - `ensureAccountGenesis` -- the ceremony itself: Space provisioning, the
+ *   optional KMS key-map acquisition, did:webvh genesis, user-key roster
+ *   genesis, epoch[0] on every encrypted roster collection, and
+ *   Space-controller promotion; idempotent end to end, so a torn run heals
+ *   by re-running.
+ * - `ensurePromotedSpaceController` -- the promotion stage standing alone,
+ *   the state machine a login-time heal drives directly.
+ */
+export { AccountGenesisSpaceError, ensureAccountGenesis, ensurePromotedSpaceController, mintAccountKeySet, mintSpaceId } from './accountGenesis.js';
+//# sourceMappingURL=index.js.map

package/dist/genesis/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/genesis/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,6BAA6B,EAC7B,iBAAiB,EACjB,WAAW,EACZ,MAAM,qBAAqB,CAAA"}

package/dist/keys/index.d.ts

@@ -44,6 +44,8 @@
  * - `ensureWalletSpaceEpochs` -- the provision-time epoch[0] install for the
  *   wallet Space's encrypted collections, the EDV-bearing second step of
  *   `provisionWalletSpace`.
+ * - `ensureIndexedFirstEpoch` -- one collection's epoch[0] plus its
+ *   blinded-index HMAC key, adopting a pre-blind-index roster as-is.
  */
 export { mintUserKey, userKeyVaultKeys } from './userKey.js';
 export type { UserKey } from './userKey.js';
@@ -56,7 +58,7 @@ export type { UserKeyRosterReadResult, RosterRecipientDocument } from './userKey
 export { userKeyRosterDescriptorStore } from './rosterStore.js';
 export { EPOCH_CONFIGURATION_STATE_TYPE, isSealableDescriptorStore, logGovernedDescriptorStore } from './rosterLogStore.js';
 export type { SealableEncryptionDescriptorStore } from './rosterLogStore.js';
-export { ensureWalletSpaceEpochs } from './spaceEpochs.js';
+export { ensureIndexedFirstEpoch, ensureWalletSpaceEpochs } from './spaceEpochs.js';
 export type { WalletSpaceEpochsResult } from './spaceEpochs.js';
 export { readClientLabels, removeClientLabel, setClientLabel } from './clientLabels.js';
 export type { ClientLabelsRecord, ClientLabelsStore } from './clientLabels.js';