@interop/wallet-core 0.62.0 → 0.65.0

package/README.md

@@ -75,18 +75,26 @@ The subpaths:
   store they write through, and ZCap signing under the did:webvh
   verification-method id.
 
-- **`@interop/wallet-core/resourceLog`** -- the client side of the Resource Log
-  Profile (the hash-linked log format governing key resources co-managed between
-  a wallet's clients and the storage server): full chain verification against an
-  adversarial host (parse shape, SCID and entry-hash recomputation, entry
-  proofs, the external-authorization rule against the independently verified
-  did:webvh controller document, terminal handover entries), the chain-head pin
-  with its continuity rules, the entry builders, the read/append/create path
-  (compare-and-swap with rebase-and-retry, read-back confirmation), and the
-  sealing sweep -- the idempotent backstop append that re-anchors a log's head
-  past the controller's latest membership change. Transport lives in
-  [`@interop/was-client`](https://npm.im/@interop/was-client)'s `/log` subpath;
-  the hashing and proof kernel in
+- **`@interop/wallet-core/resourceLog`** -- the wallet-domain half of the
+  Resource Log Profile, the hash-linked log format governing key resources
+  co-managed between a wallet's clients and the storage server. Three pieces.
+  The did:webvh controller adapter, which answers which keys could have signed a
+  given entry at a given document version, and supplies the admission hook every
+  verifier consults. The ceremony-tail license that hook carries, which bounds
+  what a standing credential's ladder key may append -- above all refusing a
+  silent rekey against an unchanged document. And `isResourceLogRefusal`, the
+  shared reading of the refusal taxonomy: which refusals a reader must not paper
+  over with a cached copy, and which one it may (a chain-head rollback,
+  reconcilable divergence). The adapter and the license read the account
+  document through one import-free leaf beside them: relation resolution,
+  ladder-VM recognition, and the credential class. They therefore answer exactly
+  as the client listing does. That leaf's public home is the `webvh` subpath.
+  The generic half lives in
+  [`@interop/vh-resource-log`](https://npm.im/@interop/vh-resource-log) -- chain
+  verification against an adversarial host, the chain-head pin, the entry
+  builders, the read/append/create path, and the sealing sweep. Transport is in
+  [`@interop/was-client`](https://npm.im/@interop/was-client)'s `/log` subpath,
+  and the hashing and proof kernel in
   [`@interop/did-method-webvh`](https://npm.im/@interop/did-method-webvh).
 
 - **`@interop/wallet-core/keys`** -- the user key and its wrap-set roster,
@@ -158,6 +166,18 @@ The subpaths:
   delegation builder and the revocation cascade's bridge re-mint core; the
   record codec is the `unlock` subpath's, re-exported here).
 
+- **`@interop/wallet-core/clientAnnex`** -- the client annex, the sibling
+  did:webvh log holding per-visit transient client keys in garbage-collected
+  generations, published in the account's auxiliary annex Space. This is the
+  authoring and maintenance surface of everything anchored on an unlock
+  credential's update-key ladder: the ladder itself (rung and VM derivation, the
+  shared attribution walks), the annex log and its GC, ZCap signing under a
+  ladder VM, the ladder-anchored account-log ceremonies (genesis,
+  self-enrollment, forget, and the last-client transition to a client-less
+  account), the credential-anchored account genesis with its mend and its
+  per-visit readiness ensure, and the transient-recovery continuation. It sits
+  on top of the other subpaths and none of them import from it.
+
 ## Install
 
 - Node.js 24+ is recommended.
@@ -188,10 +208,15 @@ import {
 ```
 
 The `sync` and `space` subpaths are re-exported from the package root as well.
-Every other subpath (`identity`, `request`, `webvh`, `keys`, `clients`,
-`descriptors`, `keyring`, `enrollment`, `recovery`) is import-directly-only, so
-consumers of the root never pull the signing / KMS / document-loader dependency
-graph.
+Every other subpath (`identity`, `request`, `webvh`, `resourceLog`, `keys`,
+`clients`, `descriptors`, `keyring`, `enrollment`, `genesis`, `unlock`,
+`recovery`, `clientAnnex`) is import-directly-only, so consumers of the root
+never pull the signing / KMS / document-loader dependency graph.
+
+Two further exports are leaves of that same isolation, carved out to stay
+dependency-light: `keys/clientKeyRecord` is the client-key record codec alone,
+so a wallet's storage tests load without the crypto graph, and
+`request/matching` is the QueryByExample matchers alone.
 
 ## Contribute
 

package/dist/clientAnnex/credentialAnchoredGenesis.d.ts

@@ -12,13 +12,13 @@
  *    resolution of the orphan-Space tear): re-derivable from the unlock
  *    record's ladder seed, so a tab death here strands nothing a later
  *    login cannot finish or unwind.
- * 2. The optional KMS key map (`provideDidWebKeys`), acquired only once the
- *    Space exists -- the enrolled-client ceremony's stage, verbatim: a
- *    KMS-keeping wallet creates the keystore under the ladder VM's bare
- *    did:key and writes keys.json and did.json into the Space here.
- *    Best-effort: a throw is collected and the genesis proceeds
- *    keystore-less; a later login's heal supplies the missing convenience
- *    key.
+ * 2. The optional KMS authentication binding (`provideKmsAuthentication`),
+ *    started BEFORE stage 1 is awaited and joined before stage 3 -- the
+ *    keystore and the key mint need no Space, so only the thunk's own
+ *    `keys.json` write waits on the `spaceReady` promise this ceremony hands
+ *    it. Best-effort: a throw is collected and the genesis proceeds
+ *    keystore-less, publishing a document with no `authentication` relation,
+ *    which no later entry adds the key to.
  * 3. The ladder-anchored did:webvh genesis
  *    (`ensureLadderAnchoredDidWebvh`): the entry signed by ladder rung 0,
  *    `updateKeys` = [rung 0], `nextKeyHashes` = [hash(rung 0), hash(rung 1)],
@@ -55,7 +55,8 @@
 import { type RecipientPublicKey } from '@interop/was-client/edv';
 import type { WasClient } from '@interop/was-client';
 import type { EncryptionDescriptorStore } from '@interop/was-client/edv';
-import type { DidWebKeyMapV2, WebvhIdStore } from '../webvh/didWebvh.js';
+import type { DIDLog } from '@interop/did-method-webvh';
+import type { KmsAuthenticationBinding, PublishedWebvhLog, WebvhIdStore } from '../webvh/didWebvh.js';
 import type { UnlockKeyAgreementPublication } from '../unlock/standingWebvh.js';
 import { type UserKey } from '../keys/index.js';
 import type { ResourceLogPinStore } from '@interop/vh-resource-log';
@@ -97,17 +98,26 @@ export declare function mintCredentialAnchoredAccountKeySet(): Promise<{
  *   roster and recipient zero of every encrypted collection
  * @param options.idStore {WebvhIdStore}   the account's `id` collection
  *   store, signing as the same bootstrap did:key
- * @param options.rosterStoreFor {Function}   `({ did }) =>
+ * @param options.rosterStoreFor {Function}   `({ did, log }) =>
  *   EncryptionDescriptorStore` -- the user-key roster's store once the DID is
- *   known, with a LADDER-signed `ResourceLogSigner` (the first-entry shape)
- * @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, under the ladder VM's bare did:key); absent or resolving
- *   `undefined`, the genesis is ladder-and-credential-only and no `keys.json`
- *   is ever written. A throw is collected, not fatal: the genesis proceeds
- *   keystore-less and a later login heals the document with the convenience
- *   key
+ *   known, with a LADDER-signed `ResourceLogSigner` (the first-entry shape).
+ *   `log` is the account log the did:webvh stage just adopted or published,
+ *   so a store resolving its controller view can read it out of this run's
+ *   own head instead of fetching `did.jsonl` again
+ * @param [options.provideKmsAuthentication] {Function}   `({ spaceReady }) =>
+ *   Promise<KmsAuthenticationBinding | undefined>` -- the KMS authentication
+ *   binding's acquisition (a wallet that keeps a KMS mints the key under the
+ *   ladder VM's bare did:key and writes `keys.json` here); absent or
+ *   resolving `undefined`, the genesis is ladder-and-credential-only and no
+ *   `keys.json` is ever written. It is STARTED before the Space is awaited
+ *   and joined before the genesis entry, so its `spaceReady` argument is what
+ *   its own `keys.json` write waits on. A throw is collected, not fatal: the
+ *   genesis proceeds keystore-less, and the document it publishes never gains
+ *   the key. The thunk's own obligation, since this ceremony takes
+ *   `authentication.vmId` VERBATIM into the world-readable genesis entry: a
+ *   served `keys.json` may be adopted only after the multibase in its `vmId`
+ *   is checked against the session's own keystore listing; on a mismatch, or
+ *   when the keystore cannot be listed, the thunk mints instead of adopting
  * @param [options.expectedDid] {string}   the account DID, when the caller
  *   holds a pointer that already names one (a heal re-run); a fresh signup
  *   and a fresh-terminal heal legitimately hold none
@@ -119,13 +129,17 @@ export declare function mintCredentialAnchoredAccountKeySet(): Promise<{
  *   account pointer must durably name the DID first (freewallet's record
  *   re-bind) passes `false` and promotes after that write
  * @param [options.onStage] {StageNotifier}   observational: called as each
- *   stage finishes, with `space-provisioning`, `webvh-genesis`,
- *   `roster-genesis`, `collection-epochs`, and (only when this ceremony
- *   promotes) `controller-promotion`. Stage 2's own boundary is the
- *   caller's `provideDidWebKeys` thunk, which is where a caller marks it
- * @returns {Promise<AccountGenesisResult>}
+ *   stage finishes, with the names in `CREDENTIAL_ANCHORED_GENESIS_STAGES`
+ *   (`clientAnnex/stages.ts`) and, only when this ceremony promotes,
+ *   `CONTROLLER_PROMOTION_STAGE`. `kms-authentication` fires at the JOIN
+ *   rather than inside the thunk: stage 2 overlaps stage 1, so a thunk that
+ *   finishes first would otherwise mark out of order
+ * @returns {Promise<AccountGenesisResult>}   with `published` and
+ *   `logMinted` always set: the account log's verified head the did:webvh
+ *   stage adopted or minted, and which of the two it was -- the head is only
+ *   safely reusable downstream when this run minted it
  */
-export declare function ensureCredentialAnchoredAccountGenesis({ was, wasServerUrl, spaceId, ladderSeed, keyAgreement, standingRecipient, userKey, idStore, rosterStoreFor, provideDidWebKeys, expectedDid, accountLogPinStore, onDidPublished, promoteController, onStage }: {
+export declare function ensureCredentialAnchoredAccountGenesis({ was, wasServerUrl, spaceId, ladderSeed, keyAgreement, standingRecipient, userKey, idStore, rosterStoreFor, provideKmsAuthentication, expectedDid, accountLogPinStore, onDidPublished, promoteController, onStage }: {
     was: WasClient;
     wasServerUrl: string;
     spaceId: string;
@@ -136,8 +150,11 @@ export declare function ensureCredentialAnchoredAccountGenesis({ was, wasServerU
     idStore: WebvhIdStore;
     rosterStoreFor: (options: {
         did: string;
+        log: DIDLog;
     }) => EncryptionDescriptorStore;
-    provideDidWebKeys?: () => Promise<DidWebKeyMapV2 | undefined>;
+    provideKmsAuthentication?: (options: {
+        spaceReady: Promise<unknown>;
+    }) => Promise<KmsAuthenticationBinding | undefined>;
     expectedDid?: string;
     accountLogPinStore?: ResourceLogPinStore;
     onDidPublished?: (published: {
@@ -145,5 +162,8 @@ export declare function ensureCredentialAnchoredAccountGenesis({ was, wasServerU
     }) => Promise<void>;
     promoteController?: boolean;
     onStage?: StageNotifier;
-}): Promise<AccountGenesisResult>;
+}): Promise<AccountGenesisResult & {
+    published: PublishedWebvhLog;
+    logMinted: boolean;
+}>;
 //# sourceMappingURL=credentialAnchoredGenesis.d.ts.map

package/dist/clientAnnex/credentialAnchoredGenesis.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentialAnchoredGenesis.d.ts","sourceRoot":"","sources":["../../src/clientAnnex/credentialAnchoredGenesis.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAwB,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC1E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAIxE,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAExE,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAA;AAC/E,OAAO,EAGL,KAAK,OAAO,EAEb,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAE7D;;;;;;;;GAQG;AACH,wBAAsB,mCAAmC,IAAI,OAAO,CAAC;IACnE,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;CAC3B,CAAC,CAED;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAsB,sCAAsC,CAAC,EAC3D,GAAG,EACH,YAAY,EACZ,OAAO,EACP,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,OAAO,EACP,OAAO,EACP,cAAc,EACd,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,iBAAwB,EACxB,OAAO,EACR,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,UAAU,CAAA;IACtB,YAAY,EAAE,6BAA6B,CAAA;IAC3C,iBAAiB,EAAE,kBAAkB,CAAA;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,YAAY,CAAA;IACrB,cAAc,EAAE,CAAC,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,yBAAyB,CAAA;IACvE,iBAAiB,CAAC,EAAE,MAAM,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAA;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,mBAAmB,CAAA;IACxC,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9D,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,OAAO,CAAC,EAAE,aAAa,CAAA;CACxB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAiHhC"}
+{"version":3,"file":"credentialAnchoredGenesis.d.ts","sourceRoot":"","sources":["../../src/clientAnnex/credentialAnchoredGenesis.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAwB,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAC1E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAIxE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAA;AACvD,OAAO,KAAK,EACV,wBAAwB,EACxB,iBAAiB,EACjB,YAAY,EACb,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAA;AAC/E,OAAO,EAGL,KAAK,OAAO,EAEb,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,8BAA8B,CAAA;AACrC,OAAO,EAAiB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAA;AAM7D;;;;;;;;GAQG;AACH,wBAAsB,mCAAmC,IAAI,OAAO,CAAC;IACnE,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAA;CAC3B,CAAC,CAED;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAsB,sCAAsC,CAAC,EAC3D,GAAG,EACH,YAAY,EACZ,OAAO,EACP,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,OAAO,EACP,OAAO,EACP,cAAc,EACd,wBAAwB,EACxB,WAAW,EACX,kBAAkB,EAClB,cAAc,EACd,iBAAwB,EACxB,OAAO,EACR,EAAE;IACD,GAAG,EAAE,SAAS,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,UAAU,CAAA;IACtB,YAAY,EAAE,6BAA6B,CAAA;IAC3C,iBAAiB,EAAE,kBAAkB,CAAA;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,YAAY,CAAA;IACrB,cAAc,EAAE,CAAC,OAAO,EAAE;QACxB,GAAG,EAAE,MAAM,CAAA;QACX,GAAG,EAAE,MAAM,CAAA;KACZ,KAAK,yBAAyB,CAAA;IAC/B,wBAAwB,CAAC,EAAE,CAAC,OAAO,EAAE;QACnC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;KAC7B,KAAK,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC,CAAA;IACnD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kBAAkB,CAAC,EAAE,mBAAmB,CAAA;IACxC,cAAc,CAAC,EAAE,CAAC,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9D,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,OAAO,CAAC,EAAE,aAAa,CAAA;CACxB,GAAG,OAAO,CACT,oBAAoB,GAAG;IAAE,SAAS,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAC5E,CAwJA"}

package/dist/clientAnnex/credentialAnchoredGenesis.js

@@ -12,13 +12,13 @@
  *    resolution of the orphan-Space tear): re-derivable from the unlock
  *    record's ladder seed, so a tab death here strands nothing a later
  *    login cannot finish or unwind.
- * 2. The optional KMS key map (`provideDidWebKeys`), acquired only once the
- *    Space exists -- the enrolled-client ceremony's stage, verbatim: a
- *    KMS-keeping wallet creates the keystore under the ladder VM's bare
- *    did:key and writes keys.json and did.json into the Space here.
- *    Best-effort: a throw is collected and the genesis proceeds
- *    keystore-less; a later login's heal supplies the missing convenience
- *    key.
+ * 2. The optional KMS authentication binding (`provideKmsAuthentication`),
+ *    started BEFORE stage 1 is awaited and joined before stage 3 -- the
+ *    keystore and the key mint need no Space, so only the thunk's own
+ *    `keys.json` write waits on the `spaceReady` promise this ceremony hands
+ *    it. Best-effort: a throw is collected and the genesis proceeds
+ *    keystore-less, publishing a document with no `authentication` relation,
+ *    which no later entry adds the key to.
  * 3. The ladder-anchored did:webvh genesis
  *    (`ensureLadderAnchoredDidWebvh`): the entry signed by ladder rung 0,
  *    `updateKeys` = [rung 0], `nextKeyHashes` = [hash(rung 0), hash(rung 1)],
@@ -59,6 +59,7 @@ import { ensureLadderAnchoredDidWebvh } from './ladderAnchored.js';
 import { ensureWalletSpaceEpochs, mintUserKey } from '../keys/index.js';
 import { AccountGenesisSpaceError, ensurePromotedSpaceController, mintSpaceId } from '../genesis/accountGenesis.js';
 import { stageNotifier } from '../log.js';
+import { CONTROLLER_PROMOTION_STAGE } from './stages.js';
 /**
  * The key set a credential-anchored signup mints locally before anything
  * touches the network: the data Space id and the account's user key -- nothing else.
@@ -94,17 +95,26 @@ export async function mintCredentialAnchoredAccountKeySet() {
  *   roster and recipient zero of every encrypted collection
  * @param options.idStore {WebvhIdStore}   the account's `id` collection
  *   store, signing as the same bootstrap did:key
- * @param options.rosterStoreFor {Function}   `({ did }) =>
+ * @param options.rosterStoreFor {Function}   `({ did, log }) =>
  *   EncryptionDescriptorStore` -- the user-key roster's store once the DID is
- *   known, with a LADDER-signed `ResourceLogSigner` (the first-entry shape)
- * @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, under the ladder VM's bare did:key); absent or resolving
- *   `undefined`, the genesis is ladder-and-credential-only and no `keys.json`
- *   is ever written. A throw is collected, not fatal: the genesis proceeds
- *   keystore-less and a later login heals the document with the convenience
- *   key
+ *   known, with a LADDER-signed `ResourceLogSigner` (the first-entry shape).
+ *   `log` is the account log the did:webvh stage just adopted or published,
+ *   so a store resolving its controller view can read it out of this run's
+ *   own head instead of fetching `did.jsonl` again
+ * @param [options.provideKmsAuthentication] {Function}   `({ spaceReady }) =>
+ *   Promise<KmsAuthenticationBinding | undefined>` -- the KMS authentication
+ *   binding's acquisition (a wallet that keeps a KMS mints the key under the
+ *   ladder VM's bare did:key and writes `keys.json` here); absent or
+ *   resolving `undefined`, the genesis is ladder-and-credential-only and no
+ *   `keys.json` is ever written. It is STARTED before the Space is awaited
+ *   and joined before the genesis entry, so its `spaceReady` argument is what
+ *   its own `keys.json` write waits on. A throw is collected, not fatal: the
+ *   genesis proceeds keystore-less, and the document it publishes never gains
+ *   the key. The thunk's own obligation, since this ceremony takes
+ *   `authentication.vmId` VERBATIM into the world-readable genesis entry: a
+ *   served `keys.json` may be adopted only after the multibase in its `vmId`
+ *   is checked against the session's own keystore listing; on a mismatch, or
+ *   when the keystore cannot be listed, the thunk mints instead of adopting
  * @param [options.expectedDid] {string}   the account DID, when the caller
  *   holds a pointer that already names one (a heal re-run); a fresh signup
  *   and a fresh-terminal heal legitimately hold none
@@ -116,49 +126,89 @@ export async function mintCredentialAnchoredAccountKeySet() {
  *   account pointer must durably name the DID first (freewallet's record
  *   re-bind) passes `false` and promotes after that write
  * @param [options.onStage] {StageNotifier}   observational: called as each
- *   stage finishes, with `space-provisioning`, `webvh-genesis`,
- *   `roster-genesis`, `collection-epochs`, and (only when this ceremony
- *   promotes) `controller-promotion`. Stage 2's own boundary is the
- *   caller's `provideDidWebKeys` thunk, which is where a caller marks it
- * @returns {Promise<AccountGenesisResult>}
+ *   stage finishes, with the names in `CREDENTIAL_ANCHORED_GENESIS_STAGES`
+ *   (`clientAnnex/stages.ts`) and, only when this ceremony promotes,
+ *   `CONTROLLER_PROMOTION_STAGE`. `kms-authentication` fires at the JOIN
+ *   rather than inside the thunk: stage 2 overlaps stage 1, so a thunk that
+ *   finishes first would otherwise mark out of order
+ * @returns {Promise<AccountGenesisResult>}   with `published` and
+ *   `logMinted` always set: the account log's verified head the did:webvh
+ *   stage adopted or minted, and which of the two it was -- the head is only
+ *   safely reusable downstream when this run minted it
  */
-export async function ensureCredentialAnchoredAccountGenesis({ was, wasServerUrl, spaceId, ladderSeed, keyAgreement, standingRecipient, userKey, idStore, rosterStoreFor, provideDidWebKeys, expectedDid, accountLogPinStore, onDidPublished, promoteController = true, onStage }) {
+export async function ensureCredentialAnchoredAccountGenesis({ was, wasServerUrl, spaceId, ladderSeed, keyAgreement, standingRecipient, userKey, idStore, rosterStoreFor, provideKmsAuthentication, expectedDid, accountLogPinStore, onDidPublished, promoteController = true, onStage }) {
     const failed = [];
     const stage = stageNotifier(onStage);
     const bootstrap = await ladderVmAgent({ ladderSeed });
     // 1. The Space and its collection roster, create-if-absent under the
-    // ladder VM's bare did:key. The typed refusal, exactly as on the
-    // enrolled-client flow: nothing downstream can proceed without a Space.
+    // ladder VM's bare did:key. Started here and awaited below, so stage 2 --
+    // which needs no Space until its own write -- runs alongside it. The typed
+    // refusal, exactly as on the enrolled-client flow: nothing downstream can
+    // proceed without a Space.
+    const spaceReady = provisionWalletSpace({
+        was,
+        spaceId,
+        controllerDid: bootstrap.id
+    });
+    // 2. The optional KMS authentication binding, started before the Space is
+    // awaited: the keystore and the key mint touch no Space, and the thunk
+    // orders its own `keys.json` write behind `spaceReady`. A throw degrades to
+    // the ladder-and-credential-only genesis rather than aborting: every later
+    // ceremony anchors in the ladder, and the document simply publishes no
+    // `authentication` relation.
+    // Started inside the same guard the join uses, so a thunk that throws
+    // synchronously is collected like one that rejects.
+    let kmsRun;
+    // The flag rather than the value decides whether the stage is reported, so
+    // a thunk rejecting with `undefined` is still a collected failure.
+    let kmsFailed = false;
+    let kmsFailure;
     try {
-        await provisionWalletSpace({ was, spaceId, controllerDid: bootstrap.id });
+        kmsRun = provideKmsAuthentication?.({ spaceReady });
+    }
+    catch (err) {
+        kmsFailed = true;
+        kmsFailure = err;
+    }
+    // A Space that never came up returns below while the thunk is still in
+    // flight, so its rejection is claimed here rather than surfacing as an
+    // unhandled one.
+    kmsRun?.catch(() => { });
+    try {
+        await spaceReady;
     }
     catch (err) {
         throw new AccountGenesisSpaceError({ spaceId, cause: err });
     }
     stage('space-provisioning');
-    // 2. The optional KMS key map, acquired only once the Space exists (a
-    // KMS-keeping wallet creates the keystore under the ladder VM's bare
-    // did:key and writes keys.json and did.json into the Space here). A throw
-    // degrades to the ladder-and-credential-only genesis rather than aborting:
-    // every later ceremony anchors in the ladder, and a later login heals the
-    // document with the convenience key.
-    let didWebKeys;
-    if (provideDidWebKeys) {
+    // The join: the genesis entry carries the KMS binding, so it waits on the
+    // whole stage even though the Space no longer does.
+    let kmsAuthentication;
+    if (kmsRun) {
         try {
-            didWebKeys = await provideDidWebKeys();
+            kmsAuthentication = await kmsRun;
         }
         catch (err) {
-            failed.push({ stage: 'didWebKeys', error: err });
+            kmsFailed = true;
+            kmsFailure = err;
         }
     }
+    if (kmsFailed) {
+        failed.push({ stage: 'kmsAuthentication', error: kmsFailure });
+    }
+    stage('kms-authentication');
+    const didWebKeys = kmsAuthentication?.keys;
     // 3. The ladder-anchored did:webvh genesis -- probe, adopt
     // (ladder-attributed), or create-and-publish. Fatal on failure, like the
     // enrolled-client stage.
-    const { did } = await ensureLadderAnchoredDidWebvh({
+    const { did, published, logMinted } = await ensureLadderAnchoredDidWebvh({
         idStore,
         wasServerUrl,
         spaceId,
         ...(didWebKeys ? { didWebKeys } : {}),
+        ...(kmsAuthentication?.etag !== undefined && {
+            keysJsonEtag: kmsAuthentication.etag
+        }),
         ladderSeed,
         keyAgreement,
         ...(expectedDid !== undefined ? { expectedDid } : {}),
@@ -171,7 +221,7 @@ export async function ensureCredentialAnchoredAccountGenesis({ was, wasServerUrl
     // genesis append is the ceremony-tail license's first-entry shape.
     let rosterDescriptor;
     try {
-        const store = rosterStoreFor({ did });
+        const store = rosterStoreFor({ did, log: published.log });
         const current = await store.read();
         rosterDescriptor =
             current !== null
@@ -224,10 +274,12 @@ export async function ensureCredentialAnchoredAccountGenesis({ was, wasServerUrl
         catch (err) {
             failed.push({ stage: 'promotion', error: err });
         }
-        stage('controller-promotion');
+        stage(CONTROLLER_PROMOTION_STAGE);
     }
     return {
         did,
+        published,
+        logMinted,
         ...(rosterDescriptor ? { rosterDescriptor } : {}),
         ...(epochs ? { epochs } : {}),
         ...(epochsSkipped ? { epochsSkipped } : {}),

package/dist/clientAnnex/credentialAnchoredGenesis.js.map

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

package/dist/clientAnnex/establish.d.ts

@@ -26,8 +26,9 @@
  *    moments before dying on the promoted Space, a permanent lockout.
  * 2. `ensureCredentialAnchoredAccountGenesis` under the ladder VM's bare
  *    did:key as bootstrap controller, promotion deferred
- *    (`promoteController: false`): Space + collections, the optional KMS key
- *    map (`provideDidWebKeys`, an opaque best-effort thunk the caller owns),
+ *    (`promoteController: false`): Space + collections, the optional KMS
+ *    authentication binding (`provideKmsAuthentication`, an opaque
+ *    best-effort thunk the caller owns, started alongside the Space),
  *    the one-entry ladder-anchored did:webvh genesis with the credential's
  *    `keyAgreement` publication folded in, the roster's epoch[0] wrapped to
  *    the credential's standing key-agreement key with a ladder-signed entry
@@ -86,13 +87,14 @@
  * bare did:key -- outside the current-key-set rule -- with no mender here;
  * an open gap owned by the did:web-stage collapse.
  */
+import type { DIDLog } from '@interop/did-method-webvh';
 import type { IKeyAgreementKey, IZcap } from '@interop/data-integrity-core';
 import type { WasClient } from '@interop/was-client';
 import type { EncryptionDescriptorStore } from '@interop/was-client/edv';
 import type { ResourceLogPinStore } from '@interop/vh-resource-log';
 import type { ZcapClient } from '@interop/ezcap';
 import { type AccountGenesisResult } from '../genesis/accountGenesis.js';
-import type { ClientWebvhUpdateKeys, DidWebKeyMapV2, PublishedWebvhLog, WebvhIdStore } from '../webvh/didWebvh.js';
+import type { ClientWebvhUpdateKeys, KmsAuthenticationBinding, PublishedWebvhLog, WebvhIdStore } from '../webvh/didWebvh.js';
 import type { ICapabilityAgent } from '../webvh/zcap.js';
 import type { AccountPointer } from '../keyring/record.js';
 import { type UserKey } from '../keys/index.js';
@@ -122,16 +124,25 @@ export interface CredentialAnchoredStandingFields {
  * DID, the record's unlock Space id and management zcap, the standing fields
  * a registry entry records, and the report members -- the genesis's
  * `epochsSkipped` marker and the best-effort stages' collected failures
- * (`didWebKeys`, `keystorePromotion`).
+ * (`kmsAuthentication`, `keystorePromotion`).
  */
 export interface CredentialAnchoredEstablishment {
     did: string;
+    /**
+     * The account log's verified head this run ends standing on -- the pointer
+     * entry's own post-publish head when stage 3 wrote one, otherwise the head
+     * stage 3 stood on. The caller enters the account straight after this
+     * returns, so it seeds its session's verified-log memo from here rather
+     * than fetching `did.jsonl` again (`verifiedAccountLogOf`); reuse is within
+     * this one run alone.
+     */
+    accountLog: PublishedWebvhLog;
     unlockSpaceId: string;
     manageCapability?: IZcap;
     standingFields: CredentialAnchoredStandingFields;
     epochsSkipped?: AccountGenesisResult['epochsSkipped'];
     failed: Array<{
-        stage: 'didWebKeys' | 'keystorePromotion';
+        stage: 'kmsAuthentication' | 'keystorePromotion';
         error: unknown;
     }>;
 }
@@ -230,11 +241,19 @@ export type CredentialAnchoredBindRecordHook = (options: {
  *   establishment's root window omits it
  * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins; slot
  *   keys are derived here per log
+ * @param [options.published] {PublishedWebvhLog}   the same account head as
+ *   `account`, complete with the ETag its read carried, when the caller holds
+ *   one. The pointer entry's first attempt then builds on it -- one saved
+ *   read of the log the caller just read or published -- and a lost
+ *   compare-and-swap falls through to a fresh pinned read
  * @param [options.now] {number}   epoch milliseconds, for tests
  * @returns {Promise<object>}   the pointed (or freshly minted) annex DID,
- *   the generation delegation when one was installed here, and what ran
+ *   the generation delegation when one was installed here, what ran, and --
+ *   on `accountLog` -- the account head this block leaves standing: the
+ *   post-pointer-entry one when it wrote, the supplied `published` verbatim
+ *   when the document already pointed at a generation
  */
-export declare function ensurePointedClientAnnexGeneration({ account, wasServerUrl, accountSpaceId, ladderSeed, was, mintController, mintGenerationDelegation, idStore, updateKeys, delegatedClients, invocation, logOnly, pinStore, now }: {
+export declare function ensurePointedClientAnnexGeneration({ account, wasServerUrl, accountSpaceId, ladderSeed, was, mintController, mintGenerationDelegation, idStore, updateKeys, delegatedClients, invocation, logOnly, pinStore, published, now }: {
     account: Pick<PublishedWebvhLog, 'did' | 'doc' | 'log'>;
     wasServerUrl: string;
     accountSpaceId: string;
@@ -253,12 +272,14 @@ export declare function ensurePointedClientAnnexGeneration({ account, wasServerU
     };
     logOnly?: boolean;
     pinStore?: ResourceLogPinStore;
+    published?: PublishedWebvhLog;
     now?: number;
 }): Promise<{
     clientAnnexDid: string;
     generationDelegation?: IZcap;
     generationMinted: boolean;
     spaceMinted: boolean;
+    accountLog?: PublishedWebvhLog;
 }>;
 /**
  * Runs the whole credential-anchored establishment for one unlock credential
@@ -279,10 +300,12 @@ export declare function ensurePointedClientAnnexGeneration({ account, wasServerU
  * @param options.bindRecord {CredentialAnchoredBindRecordHook}   REQUIRED:
  *   the unlock-record codec closure (see its type doc for the hook's
  *   standing-layout and freshness-floor obligations)
- * @param options.rosterStoreFor {Function}   REQUIRED: `({ did }) =>
+ * @param options.rosterStoreFor {Function}   REQUIRED: `({ did, log }) =>
  *   EncryptionDescriptorStore` -- the user-key roster's store, with a
  *   LADDER-signed log signer (the ceremony-tail license's first-entry
- *   shape), invoked as the bootstrap did:key
+ *   shape), invoked as the bootstrap did:key. `log` is the account log this
+ *   run adopted or published, so a store resolving its controller view reads
+ *   it out of this run's own head instead of fetching `did.jsonl` again
  * @param options.bootstrapWasFor {Function}   REQUIRED:
  *   `({ keyAgent }) => WasClient` -- the storage client wiring, signing as
  *   the ladder VM's bare did:key (the agent is derived here from the seed)
@@ -308,10 +331,15 @@ export declare function ensurePointedClientAnnexGeneration({ account, wasServerU
  *   delegation, when the caller holds one -- threaded into stage 3's Space
  *   resolution; under this ceremony's bootstrap-only authority a
  *   sibling-named Space it can no longer write falls back to a fresh mint
- * @param [options.provideDidWebKeys] {Function}   `() =>
- *   Promise<DidWebKeyMapV2 | undefined>` -- the caller's opaque best-effort
- *   KMS/did:web thunk, run inside stage 2 (the caller owns its body and its
- *   timeout); a throw is the collected non-fatal `didWebKeys` failure
+ * @param [options.provideKmsAuthentication] {Function}   `({ spaceReady }) =>
+ *   Promise<KmsAuthenticationBinding | undefined>` -- the caller's opaque
+ *   best-effort KMS thunk, started in stage 2 alongside the Space
+ *   provisioning it reports through `spaceReady` (the caller owns its body
+ *   and its timeout); a throw is the collected non-fatal `kmsAuthentication`
+ *   failure. The thunk's obligation, since the genesis takes
+ *   `authentication.vmId` verbatim into the world-readable entry: it adopts a
+ *   served `keys.json` only after checking that `vmId`'s multibase against
+ *   its own keystore listing, and mints otherwise
  * @param [options.promoteKeystore] {Function}   `({ did }) => Promise<void>`
  *   -- the best-effort keystore-controller promotion, called after the
  *   Space's own promotion; the caller's closure no-ops when its KMS stage
@@ -326,15 +354,16 @@ export declare function ensurePointedClientAnnexGeneration({ account, wasServerU
  *   client-local one when a remembered caller seeds its own pin)
  * @param [options.now] {number}   epoch milliseconds, for tests
  * @param [options.onStage] {StageNotifier}   observational: called as each
- *   stage finishes, so a caller can time them. In order:
- *   `interim-bind` (skipped with `priorCreatedAt`), `space-provisioning`,
- *   `webvh-genesis`, `roster-genesis`, `collection-epochs`,
- *   `roster-delivered-epochs` (only on the adopted-roster arm),
- *   `account-log-read`, `annex-generation`, `record-rebind`,
- *   `controller-promotion`. The three stages whose body is the caller's own
- *   closure -- the KMS thunk, `beforePromotion`, `promoteKeystore` -- are
- *   left for the caller to mark inside them, since only the caller can name
- *   what its closure does
+ *   stage finishes, so a caller can time them, in the order of
+ *   `CREDENTIAL_ANCHORED_ESTABLISHMENT_STAGES` (`clientAnnex/stages.ts`).
+ *   `interim-bind` is skipped with `priorCreatedAt`; `account-log-read` is
+ *   kept as the stage-3 preamble's name, its span near-zero whenever the
+ *   genesis's own head is reused instead of read; and the adopted-roster arm
+ *   reports `roster-delivered-epochs` in place of `collection-epochs` (see
+ *   `CREDENTIAL_ANCHORED_ESTABLISHMENT_STAGE_ALIASES` beside it). The two
+ *   stages whose body is the caller's own closure -- `beforePromotion` and
+ *   `promoteKeystore` -- are left for the caller to mark inside them, since
+ *   only the caller can name what its closure does
  * @returns {Promise<CredentialAnchoredEstablishment>}
  * @throws {TypeError}   synchronously, when a required hook is missing
  * @throws {Error}   when the genesis's roster or epoch stage did not land
@@ -354,6 +383,7 @@ export declare function establishCredentialAnchoredAccount(options: {
     bindRecord: CredentialAnchoredBindRecordHook;
     rosterStoreFor: (options: {
         did: string;
+        log: DIDLog;
     }) => EncryptionDescriptorStore;
     bootstrapWasFor: (options: {
         keyAgent: ICapabilityAgent;
@@ -363,7 +393,9 @@ export declare function establishCredentialAnchoredAccount(options: {
     lowEntropy: boolean;
     priorCreatedAt?: string;
     delegatedClients?: IZcap;
-    provideDidWebKeys?: () => Promise<DidWebKeyMapV2 | undefined>;
+    provideKmsAuthentication?: (options: {
+        spaceReady: Promise<unknown>;
+    }) => Promise<KmsAuthenticationBinding | undefined>;
     promoteKeystore?: (options: {
         did: string;
     }) => Promise<void>;
@@ -378,17 +410,6 @@ export declare function establishCredentialAnchoredAccount(options: {
     now?: number;
     onStage?: StageNotifier;
 }): Promise<CredentialAnchoredEstablishment>;
-/**
- * The current `updateKeys` / `nextKeyHashes` view of a published log, for
- * the bind-time rung attribution.
- *
- * @param published {PublishedWebvhLog}
- * @returns {object}
- */
-export declare function currentLogParameters(published: Pick<PublishedWebvhLog, 'log'>): {
-    updateKeys: string[];
-    nextKeyHashes: string[];
-};
 /**
  * A delegation's `expires` caveat, when it carries one.
  *