@interop/wallet-core 0.61.0 → 0.65.0

package/dist/webvh/didWebvh.js

@@ -21,10 +21,10 @@
  * key-agreement key (under `keyAgreement`, the source of record for
  * user-key-wrap recipient keys). The genesis comes in two flavors: a wallet
  * that keeps a KMS supplies its `didWebKeys` map and the document gains one
- * server-held key, the KMS `authentication` key (a convenience for DIDAuth);
- * a wallet with no KMS supplies no map and the document holds client keys
- * only (a later log entry can still add the KMS authentication key when the
- * first KMS-capable client appears). In either flavor every other relation
+ * server-held key, the KMS `authentication` key (a DIDAuth signing key the
+ * document publishes); a wallet with no KMS supplies no map and the document
+ * holds client keys only, permanently -- no later entry adds the KMS key to a
+ * document that published without it. In either flavor every other relation
  * lists client keys only. In particular no server-held key may appear under
  * `keyAgreement` (no server key is a wrap target) or under `assertionMethod`
  * (membership there is what entitles a key to issue assertions as the account
@@ -35,8 +35,7 @@
  * glue: a `Signer` bridge over a client-held update-key seed, the idempotent,
  * crash-resumable provisioning flow (`ensureDidWebvh`), the per-client
  * update-key rotation ceremony (`rotateWebvhUpdateKey`), the two-entry client
- * enrollment ceremony (`enrollWebvhClient`), and the lost-`keys.json` recovery
- * path for the did:web relationship bindings (`repairKeyBindings`). Update-key
+ * enrollment ceremony (`enrollWebvhClient`). Update-key
  * seeds are minted here but persisted by the caller -- with client-held keys a
  * lost seed is lost update authority, so every publish is preceded by a
  * caller-persisted write.
@@ -71,10 +70,11 @@ import { equalBytes } from '@noble/ciphers/utils.js';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { base58, base64urlnopad } from '@scure/base';
 import { VOCAB_CONTEXT_URL } from 'byoe-context';
-import { DID_DOCUMENT_RESOURCE, DID_LOG_RESOURCE, ID_COLLECTION } from '../space/collections.js';
+import { DID_LOG_RESOURCE, ID_COLLECTION } from '../space/collections.js';
 import { ResourceLogContinuityError } from '@interop/vh-resource-log';
+import { putDidWebProjection } from './didWebProjection.js';
 import { multibaseOf } from './didWeb.js';
-import { accountLogPinId, checkAccountLogContinuity } from './verifyLog.js';
+import { accountLogPinId, checkAccountLogContinuity, checkAndAdvanceAccountLogPin } from './verifyLog.js';
 /**
  * The Multikey verification-method type the did:webvh data model uses for both
  * the Ed25519 (authentication/assertionMethod/capability*) and X25519
@@ -326,8 +326,9 @@ export function assertCanonicalClientKeys({ signingKeyMultibase, keyAgreementKey
 /**
  * The one builder of the ladder VM's published verification method -- the
  * STABLE SIBLING key a standing credential derives from its ladder seed
- * (`@interop/wallet-core/unlock`, `ladderVmKeyMultibase`), published while
- * the account has no enrolled client. The shape is forced, not
+ * (`@interop/wallet-core/unlock`, `ladderVmKeyMultibase`), published for as
+ * long as that credential stands and co-resident with whatever clients the
+ * account has enrolled. The shape is forced, not
  * preferred: @interop/zcap's `isController` flat-compares the delegating VM's
  * `controller` string against the parent capability's controller (which the
  * server synthesizes as the account did:webvh), and only an
@@ -338,9 +339,9 @@ export function assertCanonicalClientKeys({ signingKeyMultibase, keyAgreementKey
  * The method is listed under `assertionMethod` and `capabilityDelegation`
  * ONLY -- no `authentication`, no `capabilityInvocation`, no `keyAgreement`
  * twin, and no marker property. Recognition is by that relation asymmetry
- * (`ladderVmIds` in the listings module): a `capabilityDelegation` member
- * absent from `capabilityInvocation` is the ladder VM, which also keeps it
- * structurally out of every client listing.
+ * (`ladderVmIds`, in the shared account-document readers): a
+ * `capabilityDelegation` member absent from `capabilityInvocation` is the
+ * ladder VM, which also keeps it structurally out of every client listing.
  *
  * Because the key is derived, a reinstall republishes the SAME key under the
  * SAME id, and a still-unexpired delegation it signed resumes verifying the
@@ -543,9 +544,10 @@ function assembleWebvhVerificationMethods({ controllerTemplate, didWebKeys, clie
         };
     }
     if (ladderVm) {
-        throw new Error('did:webvh: a genesis document lists a founding client or a ladder VM, ' +
-            'never both -- the ladder VM exists only while the account has no ' +
-            'enrolled client.');
+        throw new Error('did:webvh: a genesis document lists either a founding client or a ' +
+            'ladder VM, and this one supplies both. The constraint is ' +
+            'genesis-only: a later entry may publish clients and ladder VMs ' +
+            'side by side.');
     }
     const { signingKeyMultibase, keyAgreementKeyMultibase } = clientKeys;
     const method = (publicKeyMultibase) => ({
@@ -598,7 +600,7 @@ function assembleWebvhVerificationMethods({ controllerTemplate, didWebKeys, clie
  * @param options.updateKeyPublicKeyMultibase {string}
  * @param options.nextKeyHashes {string[]}
  * @param options.signer {Signer}
- * @returns {Promise<{ log: DIDLog; webDoc: object; did: string }>}
+ * @returns {Promise<CreatedWebvhLog>}
  */
 async function createWebvhLog({ wasServerUrl, spaceId, didWebKeys, clientKeys, ladderVm, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
     const { host } = new URL(wasServerUrl);
@@ -631,7 +633,19 @@ async function createWebvhLog({ wasServerUrl, spaceId, didWebKeys, clientKeys, l
     if (!result.webDoc) {
         throw new Error('createDID did not return a webDoc despite alsoKnownAsWeb.');
     }
-    return { log: result.log, webDoc: result.webDoc, did: result.did };
+    return {
+        log: result.log,
+        webDoc: result.webDoc,
+        did: result.did,
+        // Detached: `createDID` hands back the very object the genesis entry
+        // carries as its `state`, and a read-side head's document is a copy of
+        // the entry's state. Cloning here makes both producers of a
+        // {@link PublishedWebvhLog} alias the same way, so a caller that mutates
+        // a document it was handed can never edit a log entry through it.
+        doc: structuredClone(result.doc),
+        updateKeys: result.meta.updateKeys ?? [],
+        nextKeyHashes: result.meta.nextKeyHashes ?? []
+    };
 }
 /**
  * Builds a genesis entry's `nextKeyHashes`: the active update key's own
@@ -688,7 +702,7 @@ export async function genesisNextKeyHashes({ activeKeyMultibase, stagedKeyMultib
  * @param options.updateKeyPublicKeyMultibase {string}   ladder rung 0's key
  * @param options.nextKeyHashes {string[]}   [hash(rung 0), hash(rung 1)]
  * @param options.signer {Signer}   ladder rung 0's signer
- * @returns {Promise<{ log: DIDLog; webDoc: object; did: string }>}
+ * @returns {Promise<CreatedWebvhLog>}
  */
 export async function createLadderAnchoredWebvhLog({ wasServerUrl, spaceId, didWebKeys, ladderVmKeyMultibase, credentialKeyAgreementMethod, updateKeyPublicKeyMultibase, nextKeyHashes, signer }) {
     return createWebvhLog({
@@ -758,17 +772,20 @@ export async function withLogConflictRetry(run) {
  * @param options.log {DIDLog}
  * @param [options.ifMatch] {string}   publish only if the log is unchanged
  * @param [options.ifNoneMatch] {boolean}   publish only if the log is absent
- * @returns {Promise<void>}
+ * @returns {Promise<{ etag?: string }>}   the new validator of the log just
+ *   written, for a stage building its entry on this head; absent against a
+ *   backend that serves no ETags
  */
 export async function putLogResource({ store, log, ifMatch, ifNoneMatch }) {
     try {
-        await store.putIdResource({
+        const written = await store.putIdResource({
             resourceId: DID_LOG_RESOURCE,
             content: logToJsonlString(log),
             contentType: 'text/jsonl',
             ifMatch,
             ifNoneMatch
         });
+        return written?.etag !== undefined ? { etag: written.etag } : {};
     }
     catch (err) {
         if (err?.name === 'PreconditionFailedError') {
@@ -777,6 +794,45 @@ export async function putLogResource({ store, log, ifMatch, ifNoneMatch }) {
         throw err;
     }
 }
+/**
+ * THE POSTAMBLE: publishes `did.jsonl` -- the log only, never `did.json` (a
+ * caller writing through a bridge delegation is authorized for nothing else)
+ * -- and advances the caller's chain-head pin to what it just published, so a
+ * host rolling the log back straight afterwards is refused on the next read.
+ *
+ * So an entry published here leaves the `did:web` projection standing at
+ * whatever it said before: a ceremony whose entry REMOVES inventory (a
+ * removal, a retirement) must republish the projection itself before the
+ * entry lands, and a projection left behind by one that did not is mended by
+ * `ensureDidWebProjection` at the next visit holding a writer for the `id`
+ * collection (a controller-invoking client, or a transient visit under its
+ * generation delegation).
+ * The publish is conditional on the read the entry was built on; a lost race
+ * surfaces as a {@link WebvhLogConflictError} (the mapping lives in
+ * {@link putLogResource}).
+ *
+ * The two halves are one function on purpose. Separating them is what leaves
+ * a pin standing behind an entry this client itself published, the gap that
+ * already forced `BuiltOnHeadNotReachedError` into existence as a
+ * compensating class.
+ *
+ * @param options {object}
+ * @param options.store {object}   anything with the seam's `putIdResource`
+ * @param options.log {DIDLog}   the log this entry produced
+ * @param [options.ifMatch] {string}   publish only if `did.jsonl` is unchanged
+ * @param [options.pinStore] {ResourceLogPinStore}   the caller's chain-head
+ *   pins; the pin advances only when a `logId` names its slot
+ * @param [options.logId] {string}   the log's pin slot
+ * @returns {Promise<{ etag?: string }>}   the new validator of the log this
+ *   entry just published, for a stage building on the post-entry head
+ */
+export async function publishEntryPinned({ store, log, ifMatch, pinStore, logId }) {
+    const written = await putLogResource({ store, log, ifMatch });
+    if (pinStore && logId !== undefined) {
+        await pinStore.write({ logId, pin: pinOfLog(log) });
+    }
+    return written;
+}
 /**
  * Publishes an already-created log: PUT `did.jsonl` (`text/jsonl`) then PUT
  * `did.json` from `webDoc` (`application/did+json`, adopting the webvh
@@ -793,8 +849,11 @@ export async function putLogResource({ store, log, ifMatch, ifNoneMatch }) {
  * after the log's compare-and-swap was WON, so it is already serialized behind
  * that win; the log is the source of truth and the projection a derived cache;
  * and {@link concludeWithPublishedLog} re-derives and republishes the
- * projection from the resolved log on every ceremony's no-op path, healing any
- * lag a race or a torn publish leaves behind.
+ * projection from the resolved log on the no-op path of every ceremony that
+ * reaches this function, so a torn publish on one of those paths is healed by
+ * the next run of the same ceremony. That reach is the controller-invoking
+ * paths alone; `ensureDidWebProjection` is what mends a projection a
+ * ladder-signed entry ({@link publishEntryPinned}) left behind.
  *
  * @param options {object}
  * @param options.idStore {WebvhIdStore}
@@ -802,15 +861,19 @@ export async function putLogResource({ store, log, ifMatch, ifNoneMatch }) {
  * @param options.webDoc {object}
  * @param [options.ifMatch] {string}   publish only if `did.jsonl` is unchanged
  * @param [options.ifNoneMatch] {boolean}   publish only if `did.jsonl` is absent
- * @returns {Promise<void>}
+ * @returns {Promise<{ etag?: string }>}   the LOG's new validator, never the
+ *   projection's: the projection is a derived cache, and only the log's ETag
+ *   is a precondition anything is built on
  */
 export async function publishWebvhLog({ idStore, log, webDoc, ifMatch, ifNoneMatch }) {
-    await putLogResource({ store: idStore, log, ifMatch, ifNoneMatch });
-    await idStore.putIdResource({
-        resourceId: DID_DOCUMENT_RESOURCE,
-        content: webDoc,
-        contentType: 'application/did+json'
+    const written = await putLogResource({
+        store: idStore,
+        log,
+        ifMatch,
+        ifNoneMatch
     });
+    await putDidWebProjection({ store: idStore, webDoc });
+    return written;
 }
 /**
  * The shared guard-and-publish tail of every ceremony that extends the log
@@ -825,13 +888,13 @@ export async function publishWebvhLog({ idStore, log, webDoc, ifMatch, ifNoneMat
  * @param [options.updated.webDoc] {object}
  * @param [options.ifMatch] {string}   the ETag of the read this entry was built
  *   on
- * @returns {Promise<void>}
+ * @returns {Promise<{ etag?: string }>}   the log's new validator
  */
 export async function publishUpdatedLog({ idStore, updated, ifMatch }) {
     if (!updated.webDoc) {
         throw new Error('did:webvh: updateDID returned no webDoc despite the did:web alsoKnownAs.');
     }
-    await publishWebvhLog({
+    return publishWebvhLog({
         idStore,
         log: updated.log,
         webDoc: updated.webDoc,
@@ -839,20 +902,116 @@ export async function publishUpdatedLog({ idStore, updated, ifMatch }) {
     });
 }
 /**
- * Writes `keys.json` v2: the did:web relationship map plus the `webvh` block,
- * preserving the three did:web relationships. Exported for the ladder-anchored
- * ensure, whose create path records the account DID the same way the
- * enrolled-client one does.
+ * The served `keys.json`, read for the two members this module acts on. A body
+ * of any other shape reads as an empty map rather than throwing: the resource
+ * is host-held bookkeeping, and the caller's next step is a rewrite either
+ * way.
+ *
+ * @param content {unknown}
+ * @returns {object}   the members present, as a partial key map
+ */
+function servedKeyMap(content) {
+    const map = content;
+    const { vmId, kmsKeyId } = map?.authentication ?? {};
+    const did = map?.webvh?.did;
+    return {
+        ...(typeof vmId === 'string' && typeof kmsKeyId === 'string'
+            ? { authentication: { vmId, kmsKeyId } }
+            : {}),
+        ...(typeof did === 'string' ? { webvh: { did } } : {})
+    };
+}
+/**
+ * Writes `keys.json` v2: the KMS binding plus the `webvh` block. Exported for
+ * the ladder-anchored ensure, whose create path records the account DID the
+ * same way the enrolled-client one does.
+ *
+ * The body is CONSTRUCTED from the two members the map carries rather than
+ * spread from the caller's, so a legacy `keyAgreement` binding a stored map
+ * still holds is dropped by this rewrite.
+ *
+ * This is the genesis' rewrite of the map the KMS stage created one stage
+ * earlier, so it carries that write's ETag as its `ifMatch`. A caller holding
+ * no ETag (a backend that versions nothing) writes unconditionally.
+ *
+ * A lost precondition CONVERGES rather than propagating, since the genesis
+ * entry has already published by the time this runs and a bookkeeping resource
+ * must not fail a ceremony standing behind it: the served map is re-read, a
+ * map already naming this DID under this binding is left alone, and anything
+ * else is rewritten once under the served ETag. A second lost precondition
+ * propagates. Without the store's optional read there is nothing to converge
+ * on, and the first failure propagates.
  *
  * @param options {object}
  * @param options.idStore {WebvhIdStore}
- * @param options.didWebKeys {DidWebKeyMap}
+ * @param options.didWebKeys {DidWebKeyMap}   the binding to record, which on
+ *   the create path is the one this run published in the genesis entry
  * @param options.webvh {DidWebvhBlock}
+ * @param [options.ifMatch] {string}   the ETag the KMS stage's own write
+ *   returned
+ * @returns {Promise<void>}
+ */
+export async function writeKeysJson({ idStore, didWebKeys, webvh, ifMatch }) {
+    const content = {
+        authentication: didWebKeys.authentication,
+        webvh
+    };
+    try {
+        await idStore.putKeyMap({
+            content,
+            ...(ifMatch !== undefined && { ifMatch })
+        });
+        return;
+    }
+    catch (err) {
+        const lostRace = err?.name === 'PreconditionFailedError';
+        if (!lostRace || !idStore.getKeyMapRaw) {
+            throw err;
+        }
+        const served = await idStore.getKeyMapRaw();
+        const servedMap = servedKeyMap(served?.content);
+        if (servedMap.webvh?.did === webvh.did &&
+            servedMap.authentication?.vmId === content.authentication.vmId) {
+            // The winner recorded this DID under this binding already: done.
+            return;
+        }
+        await idStore.putKeyMap({
+            content,
+            ...(served?.etag !== undefined && { ifMatch: served.etag })
+        });
+    }
+}
+/**
+ * Records the account DID into a `keys.json` carrying a KMS binding and no (or
+ * a stale) `webvh` block -- the state a run torn between its genesis entry and
+ * its rewrite leaves behind. It is the adoption path's half of that rewrite,
+ * and the binding comes from the SERVED map: the run that published the log
+ * recorded it, while this run's own map may name a key that log never
+ * published.
+ *
+ * A no-op when the store offers no read, when the served map carries no
+ * binding, and when it already names this DID.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}
+ * @param options.did {string}   the DID the adopted log resolves to
  * @returns {Promise<void>}
  */
-export async function writeKeysJson({ idStore, didWebKeys, webvh }) {
-    const content = { ...didWebKeys, webvh };
-    await idStore.putKeyMap({ content });
+export async function backfillKeyMapWebvhBlock({ idStore, did }) {
+    if (!idStore.getKeyMapRaw) {
+        return;
+    }
+    const served = await idStore.getKeyMapRaw();
+    const servedMap = servedKeyMap(served?.content);
+    if (!servedMap.authentication || servedMap.webvh?.did === did) {
+        return;
+    }
+    await writeKeysJson({
+        idStore,
+        didWebKeys: { authentication: servedMap.authentication },
+        webvh: { did },
+        ...(served?.etag !== undefined && { ifMatch: served.etag })
+    });
 }
 /**
  * Reads and resolves the published `did.jsonl`, or returns `undefined` when
@@ -881,7 +1040,9 @@ export async function writeKeysJson({ idStore, didWebKeys, webvh }) {
  * refused as a `rollback` instead of read as `undefined`.
  *
  * @param options {object}
- * @param options.idStore {WebvhIdStore}
+ * @param options.idStore {Pick<WebvhIdStore, 'getIdResourceRaw'>}   the read
+ *   half of the seam alone, so a caller holding a narrower store (a bridge
+ *   delegation's read + PUT pair) passes it directly
  * @param [options.expectedDid] {string}   the DID the log must resolve to
  * @param [options.pinStore] {ResourceLogPinStore}   this client's chain-head
  *   pins for the account log
@@ -915,20 +1076,7 @@ export async function readPublishedLog({ idStore, expectedDid, pinStore, logId }
     if (resolved.meta.error || !resolved.did || !resolved.doc) {
         throw new Error(`did:webvh: existing did.jsonl failed to resolve (${resolved.meta.error}).`);
     }
-    if (expectedDid !== undefined && resolved.did !== expectedDid) {
-        throw new Error('did:webvh: the published did.jsonl resolves to a different DID ' +
-            `(${resolved.did}) than expected (${expectedDid}).`);
-    }
-    if (pinned) {
-        const pin = await pinned.store.read({ logId: pinned.logId });
-        const served = checkAccountLogContinuity({ log, pin });
-        // Advanced only when the served head is genuinely ahead of the pin: the
-        // check above has already refused everything that is not.
-        if (!pin || pin.head !== served.head) {
-            await pinned.store.write({ logId: pinned.logId, pin: served });
-        }
-    }
-    return {
+    const published = {
         log,
         did: resolved.did,
         doc: resolved.doc,
@@ -936,6 +1084,77 @@ export async function readPublishedLog({ idStore, expectedDid, pinStore, logId }
         nextKeyHashes: resolved.meta.nextKeyHashes ?? [],
         etag: read.etag
     };
+    assertPublishedLogDid({ published, expectedDid });
+    if (pinned) {
+        await checkAndAdvanceAccountLogPin({
+            pinStore: pinned.store,
+            logId: pinned.logId,
+            log
+        });
+    }
+    return published;
+}
+/**
+ * The substituted-account refusal on its own: a resolved head that is not the
+ * DID the caller expected is refused rather than built on. Stated once so a
+ * fresh read and a caller-threaded head refuse identically.
+ *
+ * A ceremony that takes an already-read head from its caller (the transient
+ * visit's one-read composition, where the readiness stage hands its verified
+ * head to the enrollment) runs this explicitly: the read that would otherwise
+ * have run it never happened, and a head resolving to another DID must not
+ * become the entry's basis just because it arrived by parameter.
+ *
+ * @param options {object}
+ * @param options.published {PublishedWebvhLog}   the resolved head
+ * @param [options.expectedDid] {string}   the DID it must resolve to; absent,
+ *   the head is accepted (the caller discovering the DID from the log itself)
+ * @returns {PublishedWebvhLog}   the head verbatim
+ */
+export function assertPublishedLogDid({ published, expectedDid }) {
+    if (expectedDid !== undefined && published.did !== expectedDid) {
+        throw new Error('did:webvh: the published did.jsonl resolves to a different DID ' +
+            `(${published.did}) than expected (${expectedDid}).`);
+    }
+    return published;
+}
+/**
+ * {@link readPublishedLog} for the ceremonies whose premise is a log that
+ * already exists: an absent `did.jsonl` is a refusal rather than a state to
+ * branch on, so the caller gets a `PublishedWebvhLog` or an error. The
+ * `missingMessage` is the caller's own phrasing of what there is nothing to do
+ * against ("nothing to enroll into", "nothing to recover"), since the read
+ * itself cannot know which ceremony is standing on it.
+ *
+ * Every other option, and every check behind them -- the `expectedDid`
+ * refusal and the chain-head pin's rollback / fork / identity-switch
+ * refusals -- is {@link readPublishedLog}'s verbatim. Each attempt of a
+ * conflict-retried ceremony reads for itself, so the continuity check runs on
+ * the read the compare-and-swap publish is conditioned on rather than only on
+ * an orchestrator's pre-read.
+ *
+ * @param options {object}
+ * @param options.idStore {Pick<WebvhIdStore, 'getIdResourceRaw'>}
+ * @param [options.expectedDid] {string}   the DID the log must resolve to
+ * @param [options.pinStore] {ResourceLogPinStore}   this client's chain-head
+ *   pins for the log being read
+ * @param [options.logId] {string}   the log's pin-slot key; required whenever
+ *   a `pinStore` is supplied
+ * @param [options.missingMessage] {string}   the thrown `Error`'s message when
+ *   the log is absent
+ * @returns {Promise<PublishedWebvhLog>}
+ */
+export async function readPublishedLogOrThrow({ idStore, expectedDid, pinStore, logId, missingMessage = 'did:webvh: did.jsonl is missing.' }) {
+    const published = await readPublishedLog({
+        idStore,
+        ...(expectedDid !== undefined ? { expectedDid } : {}),
+        ...(pinStore ? { pinStore } : {}),
+        ...(logId !== undefined ? { logId } : {})
+    });
+    if (!published) {
+        throw new Error(missingMessage);
+    }
+    return published;
 }
 /**
  * The chain-head pin a log establishes: the genesis entry's method and SCID
@@ -967,16 +1186,22 @@ export function servedHead(log) {
  * already-revoked no-op. All of them used to infer completion from `did.jsonl`
  * alone, which is a half of the state: {@link publishWebvhLog} writes the log
  * and its `did:web` projection in two non-atomic PUTs, so a crash between them
- * leaves a `did.jsonl` that is complete beside a `did.json` that lags it
- * forever (nothing else republishes the projection).
+ * leaves a `did.jsonl` that is complete beside a `did.json` that lags it.
  *
  * So the projection is re-derived from the resolved log and re-PUT
  * unconditionally rather than compared first: the write is idempotent and one
  * request either way, and the resolved log is the source of truth for what the
  * projection must say. A ceremony that no-ops on the log therefore still heals
- * a torn earlier publish. The projection PUT is deliberately unconditional
- * here too: healing it is the whole point, and the log it was derived from is
- * the state this call just read and resolved.
+ * a torn earlier publish OF THAT CEREMONY. The projection PUT is deliberately
+ * unconditional here too: healing it is the whole point, and the log it was
+ * derived from is the state this call just read and resolved.
+ *
+ * The reach is what to hold on to: every caller here invokes as the account's
+ * controller, so this heals nothing for the ladder-signed entries that publish
+ * through {@link publishEntryPinned} and write the log alone. Those are mended
+ * by their own ceremony's pre-entry projection PUT and, failing that, by
+ * `ensureDidWebProjection` at the next visit that holds an `id`-collection
+ * writer.
  *
  * @param options {object}
  * @param options.idStore {WebvhIdStore}
@@ -985,10 +1210,9 @@ export function servedHead(log) {
  *   resolved document
  */
 export async function concludeWithPublishedLog({ idStore, published }) {
-    await idStore.putIdResource({
-        resourceId: DID_DOCUMENT_RESOURCE,
-        content: generateParallelDidWeb(published.did, published.doc),
-        contentType: 'application/did+json'
+    await putDidWebProjection({
+        store: idStore,
+        webDoc: generateParallelDidWeb(published.did, published.doc)
     });
     return { did: published.did, doc: published.doc };
 }
@@ -1017,6 +1241,22 @@ export function effectiveParameters(log) {
     }
     return out;
 }
+/**
+ * The log's current `updateKeys` / `nextKeyHashes` view: the last entry's
+ * effective parameters, or the empty pair for a log with no entries.
+ *
+ * The empty default is a policy choice, not a convenience: it is what makes
+ * an unresolvable log attribute as "no rung standing" rather than throw, so
+ * it is stated here once rather than at each attribution site.
+ *
+ * @param published {object}
+ * @param published.log {DIDLog}
+ * @returns {object}
+ */
+export function currentLogParameters(published) {
+    const params = effectiveParameters(published.log);
+    return params[params.length - 1] ?? { updateKeys: [], nextKeyHashes: [] };
+}
 /**
  * The `publicKeyMultibase` of every update-key seed this client holds, in
  * role order (active, staged, pending).
@@ -1103,8 +1343,10 @@ function advancedSeeds({ published, multibases, updateKeys }) {
  * @param options.wasServerUrl {string}
  * @param options.spaceId {string}
  * @param [options.didWebKeys] {DidWebKeyMapV2}   the parsed keys.json (with any
- *   webvh block) returned by the did:web provisioning; absent on a
+ *   webvh block) returned by the KMS-authentication stage; absent on a
  *   client-keys-only genesis (no KMS anywhere in the path)
+ * @param [options.keysJsonEtag] {string}   the ETag that stage's own write
+ *   returned, carried as the `ifMatch` of the rewrite that records the DID
  * @param options.clientKeys {WebvhClientKeys}   this client's published keys
  * @param options.updateKeys {ClientWebvhUpdateKeys}   already persisted
  *   client-local
@@ -1124,7 +1366,7 @@ export async function ensureDidWebvh(options) {
  * @param options {object}   see {@link ensureDidWebvh}
  * @returns {Promise<{ did: string }>}
  */
-async function ensureDidWebvhOnce({ idStore, wasServerUrl, spaceId, didWebKeys, clientKeys, updateKeys, expectedDid, pinStore }) {
+async function ensureDidWebvhOnce({ idStore, wasServerUrl, spaceId, didWebKeys, keysJsonEtag, clientKeys, updateKeys, expectedDid, pinStore }) {
     // The DID this run expects the published log to resolve to: the caller's,
     // else the one keys.json already records. Undefined only on the documented
     // first-contact adoption, which discovers the DID from the log itself.
@@ -1156,10 +1398,13 @@ async function ensureDidWebvhOnce({ idStore, wasServerUrl, spaceId, didWebKeys,
             await writeKeysJson({
                 idStore,
                 didWebKeys,
-                webvh: { did: published.did }
+                webvh: { did: published.did },
+                ...(keysJsonEtag !== undefined && { ifMatch: keysJsonEtag })
             });
         }
-        // Heals a did.json left lagging by a torn earlier publish.
+        // Heals a did.json left lagging by a torn earlier publish of this
+        // controller-invoking path (a ladder-signed entry's lag is not reached
+        // here; `ensureDidWebProjection` is that mender).
         const { did } = await concludeWithPublishedLog({ idStore, published });
         return { did };
     }
@@ -1194,7 +1439,8 @@ async function ensureDidWebvhOnce({ idStore, wasServerUrl, spaceId, didWebKeys,
         await writeKeysJson({
             idStore,
             didWebKeys,
-            webvh: { did: created.did }
+            webvh: { did: created.did },
+            ...(keysJsonEtag !== undefined && { ifMatch: keysJsonEtag })
         });
     }
     return { did: created.did };
@@ -1378,281 +1624,4 @@ export async function assertCarryOverCommitments({ published }) {
         }
     }
 }
-/**
- * The relationship references of a resolved document as verification-method
- * ids, tolerating embedded objects beside string references.
- *
- * @param relation {Array}   the relationship array, when present
- * @returns {string[]}
- */
-export function relationIds(relation) {
-    const ids = [];
-    for (const entry of relation ?? []) {
-        const id = typeof entry === 'string' ? entry : entry?.id;
-        if (id) {
-            ids.push(id);
-        }
-    }
-    return ids;
-}
-/**
- * Enrolls a second wallet client into the published did:webvh document -- the
- * log half of the enrollment ceremony (the user key roster wrap happens first,
- * outside this module). Two entries, forced by prerotation (a new update key
- * must hash into the PREVIOUS entry's `nextKeyHashes`):
- *
- * 1. **Commit**: a sparse entry extending `nextKeyHashes` with the new
- *    client's update-key and staged-key hashes (document and `updateKeys`
- *    untouched).
- * 2. **Add**: an entry adding the new client's verification methods (its
- *    Ed25519 key under the four signing relationships, its X25519 twin under
- *    `keyAgreement`) and its update key to `updateKeys`.
- *
- * Both entries are signed by THIS client's active update key (quorum-of-one:
- * any single enrolled client can enroll). The ceremony is resumable from
- * durable state alone: a tear after the commit is detected by its hashes
- * already standing in `nextKeyHashes` (skip to the add entry), and a
- * completed enrollment is detected by the update key already being authorized
- * (no-op). Re-running with the same key set converges without forking the
- * log.
- *
- * Each entry publishes conditionally on the read it was built on (the add
- * entry on the mid-ceremony re-read), so a concurrent ceremony -- a revocation,
- * another enrollment -- can never be erased by this one; a lost race re-runs
- * from the top (see {@link withLogConflictRetry}) and rebases on the new head.
- *
- * @param options {object}
- * @param options.idStore {WebvhIdStore}
- * @param options.updateKeys {ClientWebvhUpdateKeys}   THIS client's seeds
- * @param options.newClient {WebvhEnrollmentKeys}   the enrollee's public halves
- * @returns {Promise<{ did: string }>}
- */
-export async function enrollWebvhClient(options) {
-    return withLogConflictRetry(() => enrollWebvhClientOnce(options));
-}
-/**
- * One attempt of {@link enrollWebvhClient}, re-invoked by the conflict retry.
- *
- * @param options {object}   see {@link enrollWebvhClient}
- * @returns {Promise<{ did: string }>}
- */
-async function enrollWebvhClientOnce({ idStore, updateKeys, newClient }) {
-    let published = await readPublishedLog({ idStore });
-    if (!published) {
-        throw new Error('did:webvh: did.jsonl is missing; nothing to enroll into.');
-    }
-    const multibases = await updateKeyMultibases({ updateKeys });
-    // Already enrolled (a completed earlier run): the new client's update key is
-    // authorized, which only the add entry writes. Idempotent no-op on the log,
-    // but it still heals a did.json the earlier run left lagging.
-    if (published.updateKeys.includes(newClient.updateKeyMultibase)) {
-        const { did } = await concludeWithPublishedLog({ idStore, published });
-        return { did };
-    }
-    // Both entries are signed by this client's active update key; a log that
-    // does not authorize it (a rotation torn elsewhere) must heal first.
-    if (!published.updateKeys.includes(multibases.update)) {
-        throw new Error("did:webvh: the published log does not authorize this client's active " +
-            'update key; finalize the pending rotation before enrolling.');
-    }
-    const newUpdateKeyHash = await deriveNextKeyHash(newClient.updateKeyMultibase);
-    const newStagedKeyHash = await deriveNextKeyHash(newClient.stagedUpdateKeyMultibase);
-    // The commit entry (skipped when a torn earlier run already published it).
-    const committed = published.nextKeyHashes.includes(newUpdateKeyHash) &&
-        published.nextKeyHashes.includes(newStagedKeyHash);
-    if (!committed) {
-        // A sparse entry re-states the authorized updateKeys, and the resolver
-        // checks each against the PREVIOUS entry's commitments -- so every
-        // currently authorized key's hash must already stand in nextKeyHashes
-        // (the carry-over convention). A log minted before the convention cannot
-        // take a non-rotating entry.
-        for (const key of published.updateKeys) {
-            if (!published.nextKeyHashes.includes(await deriveNextKeyHash(key))) {
-                throw new Error('did:webvh: the published log does not carry the active update ' +
-                    "keys' own hashes in nextKeyHashes (it predates the carry-over " +
-                    'commitment convention); re-provision the account before ' +
-                    'enrolling.');
-            }
-        }
-        const signer = await updateKeySigner({ seed: updateKeys.updateSeed });
-        const updated = await updateDID({
-            log: published.log,
-            signer,
-            alsoKnownAsWeb: true,
-            // Re-stated unchanged (the library requires them explicitly while
-            // prerotation is active); the carry-over commitments are what make the
-            // re-statement resolvable.
-            updateKeys: published.updateKeys,
-            nextKeyHashes: [
-                ...new Set([
-                    ...published.nextKeyHashes,
-                    newUpdateKeyHash,
-                    newStagedKeyHash
-                ])
-            ]
-        });
-        await publishUpdatedLog({ idStore, updated, ifMatch: published.etag });
-        // Re-read through the same verifying path the resume case uses, so the
-        // add entry below always builds on the published, resolved state. It must
-        // still be the same account: the DID the first read resolved to is what
-        // the entry just published extends.
-        published = await readPublishedLog({ idStore, expectedDid: published.did });
-        if (!published) {
-            throw new Error('did:webvh: did.jsonl vanished mid-enrollment.');
-        }
-    }
-    // The add entry: the new client's two verification methods and its update
-    // key, on top of the full existing document (updateDID replaces the
-    // verification-method set and relationship arrays wholesale).
-    const { did, doc, log, updateKeys: authorizedKeys, nextKeyHashes, etag } = published;
-    const vmId = (publicKeyMultibase) => `${did}#${publicKeyMultibase}`;
-    // The signing method is controlled by the account; the key-agreement method
-    // alone carries the controller marker, and the pair builder refuses a
-    // key-agreement key that is not the signing key's canonical twin.
-    const addedMethods = markedVerificationMethodPair({
-        controller: did,
-        signingKeyMultibase: newClient.signingKeyMultibase,
-        keyAgreementKeyMultibase: newClient.keyAgreementKeyMultibase
-    });
-    const existingMethods = (doc.verificationMethod ?? []);
-    const verificationMethods = [
-        ...existingMethods.filter(method => !addedMethods.some(added => added.id === method.id)),
-        ...addedMethods
-    ];
-    const withReference = (relation, id) => [...new Set([...relationIds(relation), id])];
-    const signingVmId = vmId(newClient.signingKeyMultibase);
-    const signer = await updateKeySigner({ seed: updateKeys.updateSeed });
-    const updated = await updateDID({
-        log,
-        signer,
-        alsoKnownAsWeb: true,
-        updateKeys: [...new Set([...authorizedKeys, newClient.updateKeyMultibase])],
-        nextKeyHashes,
-        verificationMethods,
-        authentication: withReference(doc.authentication, signingVmId),
-        assertionMethod: withReference(doc.assertionMethod, signingVmId),
-        keyAgreement: withReference(doc.keyAgreement, vmId(newClient.keyAgreementKeyMultibase)),
-        capabilityInvocation: withReference(doc.capabilityInvocation, signingVmId),
-        capabilityDelegation: withReference(doc.capabilityDelegation, signingVmId)
-    });
-    // The etag of the read this entry was built on: the mid-ceremony re-read
-    // when the commit entry ran here, the original read when it was skipped.
-    await publishUpdatedLog({ idStore, updated, ifMatch: etag });
-    return { did: updated.did };
-}
-/**
- * Rebuilds `keys.json` from the published artifacts plus a WebKMS key listing
- * -- the recovery path for a lost or rolled-back `keys.json`. List Keys is
- * authorized as `read` against the keystore controller, which only the
- * root-controlled keystore agent can invoke.
- *
- * KMS key local ids are server-generated random and appear in no published
- * artifact, so the bindings are rediscovered by public key material instead.
- * List the keystore once -- each listed description carries `keyUrl`, the
- * key's canonical invocation URL (the signable handle its alias-overridden
- * `id` erases) -- then match `did.json`'s relationship verification methods
- * by `publicKeyMultibase` and rewrite `keys.json` from what matched. The
- * `authentication` and `keyAgreement` bindings are required; `assertionMethod`
- * lists client keys only, so no KMS binding exists there and none is rebuilt.
- * When `did.jsonl` is published, its resolved DID is recorded in the `webvh`
- * block; there is nothing else to repair there, since the log's update keys are
- * client-held seeds that no keystore listing could recover.
- *
- * An unmatchable binding is unrepairable and throws: a published artifact
- * depends on a key the keystore no longer lists.
- *
- * The log read takes the same checks every other ceremony read does, and for
- * the same reason: what it reads is written straight back into the rebuilt
- * `keys.json`, so a substituted log would rewrite the `webvh` block to a wrong
- * DID and a truncated one would be adopted as this account's history. A caller
- * that still holds the account pointer passes `expectedDid` and its
- * `pinStore`; the pure-recovery caller that has lost everything but the
- * keystore has no DID to expect and passes neither, which is the one read here
- * that legitimately discovers the DID from the log itself.
- *
- * @param options {object}
- * @param options.keystoreAgent {KeystoreAgent}
- * @param options.idStore {WebvhIdStore}
- * @param [options.expectedDid] {string}   the DID the published log must
- *   resolve to
- * @param [options.pinStore] {ResourceLogPinStore}   this client's chain-head
- *   pins for the account log
- * @param [options.logId] {string}   the account log's pin-slot key, built by
- *   the caller with `accountLogPinId({ spaceId })`; required whenever a
- *   `pinStore` is supplied
- * @returns {Promise<DidWebKeyMapV2>}   the rebuilt, persisted keys.json
- */
-export async function repairKeyBindings({ keystoreAgent, idStore, expectedDid, pinStore, logId }) {
-    if (pinStore && logId === undefined) {
-        throw new TypeError('logId is required when pinStore is supplied');
-    }
-    const didDoc = (await idStore.getIdResource({
-        resourceId: DID_DOCUMENT_RESOURCE
-    }));
-    if (!didDoc) {
-        throw new Error('keys.json repair: did.json is not published; there is nothing to ' +
-            'match key bindings against.');
-    }
-    // One listing, matched by public key material below. `keyUrl` is the
-    // list-only projection field (webkms-client >= 14.7.1 types it; an older
-    // server omits it, so entries without one are skipped and simply fail to
-    // match).
-    const listed = (await keystoreAgent.listKeys());
-    const keyUrlByMultibase = new Map();
-    for (const description of listed) {
-        if (description.publicKeyMultibase && description.keyUrl) {
-            keyUrlByMultibase.set(description.publicKeyMultibase, description.keyUrl);
-        }
-    }
-    // A relationship's first keystore-backed verification method. A
-    // relationship can name several verification methods now that enrolled
-    // clients publish their own keys beside the KMS ones, so every reference is
-    // tried and the first keystore-backed one wins; a client-held key simply
-    // fails to match and is skipped.
-    const findKmsBacked = (relationship) => {
-        const tried = [];
-        for (const reference of didDoc[relationship] ?? []) {
-            const vmId = typeof reference === 'string' ? reference : reference?.id;
-            if (!vmId) {
-                continue;
-            }
-            const method = didDoc.verificationMethod?.find(entry => entry.id === vmId);
-            const publicKeyMultibase = method?.publicKeyMultibase ?? multibaseOf(vmId);
-            tried.push(publicKeyMultibase);
-            const kmsKeyId = keyUrlByMultibase.get(publicKeyMultibase);
-            if (kmsKeyId) {
-                return { bound: { vmId, kmsKeyId }, tried };
-            }
-        }
-        return { tried };
-    };
-    const bind = (relationship) => {
-        if ((didDoc[relationship] ?? []).length === 0) {
-            throw new Error(`keys.json repair: did.json declares no ${relationship} verification method.`);
-        }
-        const { bound, tried } = findKmsBacked(relationship);
-        if (!bound) {
-            throw new Error(`keys.json repair: no keystore key matches the ${relationship} ` +
-                `verification method (${tried.join(', ')}).`);
-        }
-        return bound;
-    };
-    const repaired = {
-        authentication: bind('authentication'),
-        keyAgreement: bind('keyAgreement')
-    };
-    // The webvh block, recovered from the published log: the DID and nothing
-    // else, since the update keys never left the client that minted them.
-    const published = await readPublishedLog({
-        idStore,
-        ...(expectedDid !== undefined ? { expectedDid } : {}),
-        ...(pinStore && logId !== undefined ? { pinStore, logId } : {})
-    });
-    if (published) {
-        repaired.webvh = { did: published.did };
-    }
-    // Persist the rebuilt anchor in one write.
-    await idStore.putKeyMap({ content: repaired });
-    return repaired;
-}
 //# sourceMappingURL=didWebvh.js.map