@interop/wallet-core 0.61.0 → 0.62.0

package/dist/clientAnnex/ladder.js

@@ -30,6 +30,10 @@ import { deriveNextKeyHash } from '@interop/did-method-webvh';
 import { hkdf } from '@noble/hashes/hkdf.js';
 import { sha256 } from '@noble/hashes/sha2.js';
 import { effectiveParameters, relationIds, updateKeyMultibase } from '../webvh/didWebvh.js';
+import { ladderVmIds, listEnrolledWebvhClients } from '../webvh/listClients.js';
+import { credentialKeyAgreementMethods, resolvedKeyAgreementMethods } from '../webvh/keyAgreement.js';
+import { survivingClientKeyProtection } from '../webvh/revokeClient.js';
+import { log as logger } from '../log.js';
 import { LADDER_SEED_BYTES } from '../unlock/unlockRecord.js';
 /**
  * The HKDF salt for rung derivation and the per-rung info prefix (the rung
@@ -39,9 +43,9 @@ import { LADDER_SEED_BYTES } from '../unlock/unlockRecord.js';
 const LADDER_SALT = 'freewallet/unlock/update-ladder/v1';
 const LADDER_RUNG_INFO_PREFIX = 'rung/';
 /**
- * The info label of the ladder VM -- the stable sibling key published in the
- * account document while the account has no enrolled client. One salt
- * for everything ladder-seed-derived, with the info namespace doing the
+ * The info label of the ladder VM -- the stable sibling key a standing
+ * credential publishes in the account document for as long as it stands. One
+ * salt for everything ladder-seed-derived, with the info namespace doing the
  * separation: `vm` can never collide with a `rung/<n>` label. Permanent.
  */
 const LADDER_VM_INFO = 'vm';
@@ -135,10 +139,15 @@ export async function ladderRung({ ladderSeed, index }) {
  * published verbatim in the account document (the seed is random, so the
  * hash-commitment rule permits it) and stable across rung spends, so a
  * delegation it signed survives every ladder advance. It carries the
- * ladder-anchored window's document-visible authority (`assertionMethod` and
+ * credential's document-visible authority (`assertionMethod` and
  * `capabilityDelegation`), while update authority stays on the rungs -- the
  * two roles never share a key.
  *
+ * Its life is the credential's: the VM is installed in the entry that makes
+ * the credential standing (`publishUnlockKey`) and struck in the entry that
+ * retires it (`removeUnlockKey`). Enrollment never touches it, so several
+ * VMs stand on an account with several standing credentials.
+ *
  * Because the key is derived, removing its verification method is never the
  * terminal remedy: a later reinstall republishes the same key under the same
  * id, and any still-unexpired delegation it signed resumes verifying the
@@ -311,6 +320,549 @@ function credentialSurvives({ entry, vmId }) {
     // commitment.
     return relationIds(entry.state.keyAgreement).includes(vmId);
 }
+/**
+ * The credential-class `keyAgreement` verification-method ids an entry
+ * INTRODUCES: those its document publishes and the previous entry's document
+ * did not. Credential-class means account-controlled
+ * (`credentialKeyAgreementMethods`), so an enrolled client's marked twin
+ * never counts. The co-introduction arm of the ladder-VM attribution reads
+ * this and refuses to act unless the answer is exactly this credential.
+ *
+ * @param options {object}
+ * @param options.doc {KeyAgreementDocument}   the entry's document
+ * @param [options.prevDoc] {KeyAgreementDocument}   the previous entry's
+ * @param options.did {string}   the account DID
+ * @returns {string[]}   in document order
+ */
+function introducedCredentialKeys({ doc, prevDoc, did }) {
+    const before = new Set((prevDoc ? credentialKeyAgreementMethods({ doc: prevDoc, did }) : []).map(method => method.id));
+    return credentialKeyAgreementMethods({ doc, did })
+        .map(method => method.id)
+        .filter((id) => id !== undefined && !before.has(id));
+}
+/**
+ * The one pre-pass over the log's effective parameters: per-entry facts, plus
+ * the commit index both walks project their positional questions through. The
+ * forward walk asks what an entry added and who signed it; the backward walk
+ * asks where a hash came from and what stood beside it there.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}
+ * @param options.params {Array<{ updateKeys: string[], nextKeyHashes: string[] }>}
+ *   the log's effective parameters, entry by entry
+ * @returns {{ facts: LadderEntryFacts[], commitIndex: Map<string, LadderCommitOrigin> }}
+ */
+function indexLadderLog({ log, params }) {
+    const facts = [];
+    const commitIndex = new Map();
+    let prevUpdateKeys = new Set();
+    let prevHashes = new Set();
+    for (const [entryIndex, entry] of params.entries()) {
+        const currentUpdateKeys = new Set(entry.updateKeys);
+        const addedKeys = entry.updateKeys.filter(key => !prevUpdateKeys.has(key));
+        const removedKeys = [...prevUpdateKeys].filter(key => !currentUpdateKeys.has(key));
+        const addedHashes = entry.nextKeyHashes.filter(hash => !prevHashes.has(hash));
+        const signers = entrySigners({ entry: log[entryIndex] });
+        addedHashes.forEach((hash, at) => {
+            if (!commitIndex.has(hash)) {
+                commitIndex.set(hash, { entryIndex, at });
+            }
+        });
+        facts.push({ addedKeys, removedKeys, addedHashes, signers });
+        prevUpdateKeys = currentUpdateKeys;
+        prevHashes = new Set(entry.nextKeyHashes);
+    }
+    return { facts, commitIndex };
+}
+/**
+ * Walks the ladder BACKWARDS from the anchor, recovering the rungs the anchor
+ * has already climbed past. Run only when no ladder seed is in hand, which is
+ * the case the anchor's staleness would otherwise decide: the one writer that
+ * advances a recorded anchor does so after a self-enrollment, and every entry
+ * the spent rungs signed would then be invisible to the forward walk.
+ *
+ * Each step reads one hash's origin and asks which of the format's two
+ * positional rules put it there
+ * (`decisions/0007-ladder-reveal-hash-order.md`). Both rules are read here in
+ * reverse, so the shapes the emitters produce forwards are the shapes this
+ * recognizes backwards.
+ *
+ * The LAST-POSITION rule is a climb. A hash appended last among its entry's
+ * additions is the committer's own next commitment, so the key that signed
+ * that entry is the rung before it. The step is taken only when the entry
+ * authorized exactly one key and that key signed the entry, which makes it a
+ * prerotation reveal rather than mere adjacency, and only when the credential
+ * itself still stands in the entry's document.
+ *
+ * The ADJACENCY rule is a handover. A hash not in last position sits beside
+ * the rung committed immediately before it, and that predecessor is revealed
+ * later by the entry that retires the committer. The step is taken only when
+ * such a revealing entry exists and the credential stands in ITS document.
+ *
+ * What each guard protects. The credential-membership test stops the walk at a
+ * plain client genesis, at the enrolled-client bind that carries no member of
+ * ours yet, and at the spent recovery code whose reveal entry commits the
+ * REPLACEMENT code's hash last -- without it the replacement's retirement
+ * would recover the spent code's key and go on to strike the fresh
+ * credential's rungs. The single-self-revealing-key test stops it at the bind
+ * entry an enrolled client signs, which authorizes no key of its own, so the
+ * binding client's update key is never recovered as a rung. The strictly
+ * decreasing entry cursor and the already-recovered test keep the walk finite
+ * and acyclic.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}
+ * @param options.facts {LadderEntryFacts[]}   from {@link indexLadderLog}
+ * @param options.commitIndex {Map<string, LadderCommitOrigin>}   likewise
+ * @param options.anchorHash {string}   `hash(anchorKeyMultibase)`
+ * @param options.credentialVmId {string}   the credential's own `keyAgreement`
+ *   verification-method id
+ * @param options.maxScan {number}   how many rungs to walk back
+ * @returns {Promise<Array<{ key: string, hash: string }>>}   the recovered
+ *   rungs, nearest the anchor first
+ */
+async function recoverEarlierRungs({ log, facts, commitIndex, anchorHash, credentialVmId, maxScan }) {
+    const recovered = [];
+    const seenHashes = new Set([anchorHash]);
+    let cursorHash = anchorHash;
+    let cursorEntry = Number.POSITIVE_INFINITY;
+    for (let step = 0; step < maxScan; step++) {
+        const origin = commitIndex.get(cursorHash);
+        if (origin === undefined || origin.entryIndex >= cursorEntry) {
+            return recovered;
+        }
+        const originFacts = facts[origin.entryIndex];
+        if (origin.at === originFacts.addedHashes.length - 1) {
+            // The last-position rule, read backwards: a climb.
+            const predecessor = originFacts.addedKeys[0];
+            if (originFacts.addedKeys.length !== 1 ||
+                predecessor === undefined ||
+                !originFacts.signers.includes(predecessor) ||
+                !credentialSurvives({
+                    entry: log[origin.entryIndex],
+                    vmId: credentialVmId
+                })) {
+                return recovered;
+            }
+            const hash = await deriveNextKeyHash(predecessor);
+            if (seenHashes.has(hash)) {
+                return recovered;
+            }
+            recovered.push({ key: predecessor, hash });
+            seenHashes.add(hash);
+            cursorHash = hash;
+            cursorEntry = origin.entryIndex;
+            continue;
+        }
+        // The adjacency rule, read backwards: a handover.
+        const partner = origin.at > 0 ? originFacts.addedHashes[origin.at - 1] : undefined;
+        if (partner === undefined || seenHashes.has(partner)) {
+            return recovered;
+        }
+        const reveal = await findRungReveal({
+            facts,
+            after: origin.entryIndex,
+            committerSigners: originFacts.signers,
+            hash: partner
+        });
+        if (reveal === undefined ||
+            !credentialSurvives({
+                entry: log[reveal.entryIndex],
+                vmId: credentialVmId
+            })) {
+            return recovered;
+        }
+        recovered.push({ key: reveal.key, hash: partner });
+        seenHashes.add(partner);
+        cursorHash = partner;
+        cursorEntry = origin.entryIndex;
+    }
+    return recovered;
+}
+/**
+ * The entry that reveals a committed hash's key while retiring one of the
+ * signers that committed it -- the handover the adjacency rule describes.
+ * Earliest such entry wins, since a key is authorized once.
+ *
+ * @param options {object}
+ * @param options.facts {LadderEntryFacts[]}
+ * @param options.after {number}   search entries strictly after this index
+ * @param options.committerSigners {string[]}   the committing entry's signers
+ * @param options.hash {string}   the committed hash whose key is sought
+ * @returns {Promise<{ entryIndex: number, key: string } | undefined>}
+ */
+async function findRungReveal({ facts, after, committerSigners, hash }) {
+    for (let entryIndex = after + 1; entryIndex < facts.length; entryIndex++) {
+        const candidate = facts[entryIndex];
+        if (!candidate.removedKeys.some(key => committerSigners.includes(key))) {
+            continue;
+        }
+        for (const key of candidate.addedKeys) {
+            if ((await deriveNextKeyHash(key)) === hash) {
+                return { entryIndex, key };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Thrown when an edit's `nextKeyHashes` would come out empty. An empty list
+ * switches prerotation off in did:webvh, so an entry that struck every
+ * commitment would leave the account with no staged key at all. Every ceremony
+ * that strikes hashes commits its own successors in the same entry, so the
+ * list is non-empty by construction; this is the assertion that says so.
+ */
+export class NextKeyHashesEmptyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NextKeyHashesEmptyError';
+    }
+}
+/**
+ * Refuses to publish an entry whose `nextKeyHashes` came out empty.
+ *
+ * @param options {object}
+ * @param options.nextKeyHashes {string[]}
+ * @param options.ceremony {string}   named in the refusal
+ * @returns {string[]}   the list, unchanged
+ */
+export function assertNextKeyHashesRemain({ nextKeyHashes, ceremony }) {
+    if (nextKeyHashes.length === 0) {
+        throw new NextKeyHashesEmptyError(`did:webvh: ${ceremony} would publish an entry committing no next key ` +
+            'hash, which switches prerotation off; the entry was not published.');
+    }
+    return nextKeyHashes;
+}
+/**
+ * The enrolled-client members an entry INTRODUCES: new `capabilityInvocation`
+ * ids, and new `keyAgreement` methods the account DID does not control (a
+ * client's marked twin). The bind-anchor read refuses any entry that
+ * introduces one, because an entry publishing a client also publishes that
+ * client's update key, and reading that key as a credential's rung 0 would
+ * anchor the walk on a surviving client.
+ *
+ * @param options {object}
+ * @param options.doc {KeyAgreementDocument}   the entry's document
+ * @param [options.prevDoc] {KeyAgreementDocument}   the previous entry's
+ * @param options.did {string}   the account DID
+ * @returns {boolean}
+ */
+function introducesEnrolledClient({ doc, prevDoc, did }) {
+    const beforeInvocation = new Set(relationIds(prevDoc?.capabilityInvocation));
+    if (relationIds(doc.capabilityInvocation).some(id => !beforeInvocation.has(id))) {
+        return true;
+    }
+    const markedIds = (entryDoc) => {
+        if (entryDoc === undefined) {
+            return new Set();
+        }
+        const credential = new Set(credentialKeyAgreementMethods({ doc: entryDoc, did }).map(method => method.id));
+        return new Set(resolvedKeyAgreementMethods({ doc: entryDoc })
+            .map(method => method.id)
+            .filter((id) => id !== undefined && !credential.has(id)));
+    };
+    const before = markedIds(prevDoc);
+    return [...markedIds(doc)].some(id => !before.has(id));
+}
+/**
+ * The anchor a credential's ladder walk starts from when the caller holds no
+ * recorded update key -- the log-only anchoring a cold browser needs. The
+ * credential's own `keyAgreement` member id is the anchor: the entry that
+ * FIRST introduced that member is the credential's bind entry, and what that
+ * entry did to the standing parameters names rung 0.
+ *
+ * Two shapes are read, both fail-closed:
+ *
+ * - the entry authorized exactly one update key and that key signed it (a
+ *   prerotation reveal, the ladder-anchored genesis shape), so rung 0 is that
+ *   key outright;
+ * - the entry authorized no key of its own and newly committed exactly one
+ *   hash (the `publishUnlockKey` bind an enrolled client signs, and the
+ *   recovery-code issuance sharing it), so rung 0's hash is that hash.
+ *
+ * Anything else is ambiguous and returns `undefined`, which the callers report
+ * as unclaimed rather than acting on. The reachable ambiguity is a bind entry
+ * introducing more than one credential-class member: a recovery
+ * add-and-retire entry introduces the fresh credential and the replacement
+ * code together, so neither is anchorable this way.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   a resolved, caller-verified log
+ * @param options.credentialVmId {string}   the credential's `keyAgreement`
+ *   verification-method id
+ * @returns {Promise<{ anchorKeyMultibase?: string, anchorHash?: string } |
+ *   undefined>}
+ */
+export async function credentialLadderAnchor({ log, credentialVmId }) {
+    const { facts } = indexLadderLog({ log, params: effectiveParameters(log) });
+    return resolveBindAnchor({ log, facts, credentialVmId });
+}
+/**
+ * The synchronous core of {@link credentialLadderAnchor}, over a pre-pass the
+ * caller already ran.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}
+ * @param options.facts {LadderEntryFacts[]}   from {@link indexLadderLog}
+ * @param options.credentialVmId {string}
+ * @returns {{ anchorKeyMultibase?: string, anchorHash?: string } | undefined}
+ */
+function resolveBindAnchor({ log, facts, credentialVmId }) {
+    const did = credentialVmId.split('#')[0];
+    if (did === undefined || did === '') {
+        return undefined;
+    }
+    // Every update key the log attributes to a client the final document still
+    // lists, so the self-signed arm can refuse one outright. A client whose
+    // active key the log cannot attribute leaves that arm unable to refuse
+    // anything, so no anchor is named at all.
+    const enrolledClients = listEnrolledWebvhClients({ log });
+    if (enrolledClients.some(client => client.updateKeyMultibase === undefined)) {
+        return undefined;
+    }
+    const enrolledClientKeys = new Set(enrolledClients
+        .map(client => client.updateKeyMultibase)
+        .filter((key) => key !== undefined));
+    let prevDoc;
+    for (const [index, entry] of log.entries()) {
+        const doc = entry.state;
+        if (doc === undefined) {
+            continue;
+        }
+        const introduced = introducedCredentialKeys({ doc, prevDoc, did });
+        const prevDocBefore = prevDoc;
+        prevDoc = doc;
+        if (!introduced.includes(credentialVmId)) {
+            continue;
+        }
+        // The bind entry. More than one credential-class member introduced here
+        // and nothing below can say which addition is whose.
+        if (introduced.length !== 1) {
+            return undefined;
+        }
+        const bind = facts[index];
+        if (bind === undefined) {
+            return undefined;
+        }
+        // The fourth condition: an entry that also publishes an enrolled client
+        // names no credential's rung. The remembered recovery's add-and-retire
+        // entry is exactly this shape -- the new client's key-agreement method is
+        // client-marked, so the credential-class count above sees only the
+        // replacement code and the ambiguity guard does not fire, while the one
+        // key the entry authorizes is the CLIENT's update key.
+        if (introducesEnrolledClient({
+            doc: doc,
+            prevDoc: prevDocBefore,
+            did
+        })) {
+            return undefined;
+        }
+        const revealed = bind.addedKeys[0];
+        if (bind.addedKeys.length === 1 &&
+            revealed !== undefined &&
+            bind.signers.includes(revealed) &&
+            // Belt and braces beside the condition above: never anchor on a key the
+            // log attributes to an enrolled client, whichever entry published it.
+            !enrolledClientKeys.has(revealed)) {
+            return { anchorKeyMultibase: revealed };
+        }
+        if (bind.addedKeys.length === 0 && bind.addedHashes.length === 1) {
+            // No enrolled-client check of its own: this arm reads a hash rather
+            // than a key, and no ceremony fuses a credential bind with a client's
+            // hash commitment.
+            return { anchorHash: bind.addedHashes[0] };
+        }
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Whether one retiring credential's rung inventory can be claimed from the log
+ * at all: its bind entry must name an anchor, and the walk from that anchor
+ * must not refuse. This is the log-only test, so it answers the same before
+ * and after the retirement entry lands -- which is what lets a resumed run
+ * report the same unclaimed set the first run reported.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}
+ * @param options.credentialVmId {string}
+ * @param options.maxScan {number}
+ * @returns {Promise<LadderStandingInventory | undefined>}   the walk's result,
+ *   or `undefined` when the credential cannot be claimed
+ */
+async function claimLadderInventory({ log, credentialVmId, maxScan }) {
+    try {
+        return await attributeLadderInventory({ log, credentialVmId, maxScan });
+    }
+    catch {
+        // An ambiguous anchor or an ambiguous history. Fail closed.
+        return undefined;
+    }
+}
+/**
+ * The strike a retirement entry ALREADY published, recomputed by re-running
+ * {@link attributeRetiredCredentialRungs} over the log as it stood just before
+ * that entry. A resumed ceremony reports what its first run reported this way,
+ * rather than through a second definition of "unclaimed" that could answer
+ * differently.
+ *
+ * The entry is located by the key it authorized: every ceremony that calls
+ * this detects its own completion by that key standing in `updateKeys`, and
+ * the entry that FIRST authorized it is the one to walk back to. A log that
+ * does not authorize the key, or authorizes it at the genesis entry, has no
+ * usable prefix and is refused: a caller that reached this had already seen
+ * the key authorized, so either shape is a caller defect rather than a
+ * state to answer for.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   the post-entry log
+ * @param options.authorizedKeyMultibase {string}   the update key the entry
+ *   authorized
+ * @param options.credentialVmIds {string[]}   the credentials the entry
+ *   retired, as the caller derived them from the log
+ * @param [options.protectedHashes] {string[]}   the same set the first run
+ *   passed
+ * @param [options.protectedKeys] {string[]}   likewise
+ * @param [options.maxScan] {number}
+ * @returns {Promise<{ struckHashes: string[], struckKeys: string[],
+ *   unclaimedCredentialVmIds: string[] }>}
+ */
+export async function retiredCredentialRungsBeforeKey({ log, authorizedKeyMultibase, credentialVmIds, protectedHashes = [], protectedKeys = [], maxScan = LADDER_MAX_SCAN }) {
+    const params = effectiveParameters(log);
+    const entryIndex = params.findIndex(entry => entry.updateKeys.includes(authorizedKeyMultibase));
+    if (entryIndex <= 0) {
+        throw new Error(`retiredCredentialRungsBeforeKey: the log ${entryIndex < 0 ? 'never authorizes' : 'authorizes at genesis'} update key ${authorizedKeyMultibase}, so no pre-entry prefix exists`);
+    }
+    return attributeRetiredCredentialRungs({
+        log: log.slice(0, entryIndex),
+        credentialVmIds,
+        protectedHashes,
+        protectedKeys,
+        maxScan
+    });
+}
+/**
+ * What a full retirement must strike from the standing parameters for a set of
+ * credentials being retired in one entry: their committed rung hashes, and any
+ * rung of theirs standing revealed in `updateKeys`. Each credential is
+ * anchored from the log alone ({@link credentialLadderAnchor}), so a cold
+ * browser holding no registry and no seed can still strike them.
+ *
+ * The bias is under-striking, deliberately. Over-striking is silent and
+ * unhealable -- a surviving credential or client keeps its verification
+ * methods and its roster wrap, and only fails when someone finally uses it --
+ * while under-striking leaves a committed rung a retired credential's holder
+ * could reveal, which the report names. Five things keep it that way:
+ *
+ * - a credential whose anchor is ambiguous or whose walk refuses is reported
+ *   as unclaimed and nothing of its is struck;
+ * - only what the walk positively claims is a candidate;
+ * - a hash or key the caller names as its own (`protectedHashes` /
+ *   `protectedKeys`, the successors the entry itself commits) is dropped;
+ * - every SURVIVING enrolled client's active update key, its carry-over hash
+ *   and its staged hash are dropped, whatever the walk claimed
+ *   ({@link survivingClientKeyProtection}). That guard is structural rather
+ *   than a property of the walk, because a mis-anchored walk landing on a
+ *   client's key would otherwise end that client's ability to extend the
+ *   account log for good. The walks therefore run FIRST, and the hashes they
+ *   claimed are passed to the protection as known-latent, so a retiring
+ *   credential's own rung cannot make a client's staged attribution ambiguous
+ *   and get itself protected as a candidate;
+ * - a listed enrolled client whose ACTIVE update key the log cannot attribute
+ *   withholds the WHOLE strike: nothing is struck and every credential is
+ *   reported, since the structural guard cannot say what that client holds.
+ *
+ * The report is a not-fully-retired report rather than a nothing-happened one.
+ * A credential appears on `unclaimedCredentialVmIds` when its walk refused,
+ * when it claimed nothing, AND when any single hash or key it claimed was
+ * withheld by one of the kept sets. The rest of that credential's claims are
+ * still struck; what the caller must not be told is that a partial retirement
+ * was a whole one.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   a resolved, caller-verified log, read BEFORE
+ *   the entry is built
+ * @param options.credentialVmIds {string[]}   the retiring credentials'
+ *   `keyAgreement` verification-method ids
+ * @param [options.protectedHashes] {string[]}   hashes the entry itself
+ *   commits, never struck
+ * @param [options.protectedKeys] {string[]}   update keys the entry itself
+ *   authorizes, never struck
+ * @param [options.maxScan] {number}   the ladder walk's bound
+ * @returns {Promise<{ struckHashes: string[], struckKeys: string[],
+ *   unclaimedCredentialVmIds: string[] }>}
+ */
+export async function attributeRetiredCredentialRungs({ log, credentialVmIds, protectedHashes = [], protectedKeys = [], maxScan = LADDER_MAX_SCAN }) {
+    // The walks first, so what they claimed can be vouched for as latent when
+    // the surviving clients' staged hashes are attributed below.
+    const claims = new Map();
+    const claimedHashes = new Set();
+    for (const credentialVmId of credentialVmIds) {
+        const inventory = await claimLadderInventory({
+            log,
+            credentialVmId,
+            maxScan
+        });
+        claims.set(credentialVmId, inventory);
+        for (const hash of inventory?.committedHashes ?? []) {
+            claimedHashes.add(hash);
+        }
+    }
+    // The structural guard, resolved once from the log rather than per
+    // credential: what the account's surviving enrolled clients hold.
+    const surviving = await survivingClientKeyProtection({
+        log,
+        retiredVmIds: credentialVmIds,
+        knownLatentHashes: [...claimedHashes]
+    });
+    if (surviving.ambiguous.length > 0) {
+        logger.warn('Withholding a credential rung strike: an enrolled client whose ' +
+            'active update key the log cannot attribute would be unprotected', { clients: surviving.ambiguous });
+        return {
+            struckHashes: [],
+            struckKeys: [],
+            unclaimedCredentialVmIds: [...credentialVmIds]
+        };
+    }
+    const keptHashes = new Set([...protectedHashes, ...surviving.hashes]);
+    const keptKeys = new Set([...protectedKeys, ...surviving.keys]);
+    const struckHashes = new Set();
+    const struckKeys = new Set();
+    const unclaimedCredentialVmIds = [];
+    for (const credentialVmId of credentialVmIds) {
+        const inventory = claims.get(credentialVmId);
+        if (inventory === undefined) {
+            unclaimedCredentialVmIds.push(credentialVmId);
+            continue;
+        }
+        let withheld = false;
+        let struckAny = false;
+        for (const hash of inventory.committedHashes) {
+            if (keptHashes.has(hash)) {
+                withheld = true;
+                continue;
+            }
+            struckHashes.add(hash);
+            struckAny = true;
+        }
+        for (const key of inventory.revealedKeys) {
+            if (keptKeys.has(key)) {
+                withheld = true;
+                continue;
+            }
+            struckKeys.add(key);
+            struckAny = true;
+        }
+        if (withheld || !struckAny) {
+            unclaimedCredentialVmIds.push(credentialVmId);
+        }
+    }
+    return {
+        struckHashes: [...struckHashes],
+        struckKeys: [...struckKeys],
+        unclaimedCredentialVmIds
+    };
+}
 /**
  * Attributes a ladder's FULL standing inventory from the log -- the retirement
  * counterpart of {@link attributeLadderRung}, which recovers only the single
@@ -351,35 +903,115 @@ function credentialSurvives({ entry, vmId }) {
  *   commitment in that position instead, and striking that would leave the
  *   replacement unusable and unhealable;
  * - a claim or revealed key that later leaves the parameters without a
- *   completion was struck by some other edit and simply stops standing.
+ *   completion was struck by some other edit and simply stops standing;
+ * - a ladder VM standing in the final document belongs to this ladder on
+ *   either of two arms, asked at the entry that PUBLISHED it (the entry at
+ *   which the id appeared among the document's ladder VMs). The SIGNER arm:
+ *   that entry was signed by a key this ladder accounted for at that point,
+ *   which covers every install a ladder rung signs (the ladder-anchored
+ *   genesis, the ladder-VM install, the transient recovery's add-and-retire
+ *   entry). The CO-INTRODUCTION arm: that entry also introduced this
+ *   credential's own `keyAgreement` member (`credentialVmId`), which is what
+ *   reaches a bind entry an ENROLLED CLIENT signed -- the shape
+ *   `publishUnlockKey` writes, whose signer is the binding client's update
+ *   key rather than a rung. Three guards keep that arm from over-claiming:
+ *   it needs `credentialVmId` in hand, the entry must introduce exactly ONE
+ *   credential-class `keyAgreement` member (the account-controlled class,
+ *   `credentialKeyAgreementMethods`; the transient recovery entry introduces
+ *   two and is left to the signer arm), and the entry must introduce exactly
+ *   ONE ladder VM. The question is anchored rather than free-standing: it
+ *   answers "is this VM mine", and a VM no anchored ladder claims is
+ *   identified by subtraction and left standing, since striking a key this
+ *   ladder cannot show it owns would take out a surviving credential's.
+ *   The COMMITMENT arm: that entry committed a hash the ladder knows a priori
+ *   (the anchor's, a seed-derived rung's, or one the backward pre-pass
+ *   recovered), introduced exactly one ladder VM, and introduced no OTHER
+ *   credential's `keyAgreement` member. It reaches the reinstall an
+ *   `establishStandingUnlock` re-run writes, which mints a fresh ladder seed
+ *   for a credential whose member already stands, so neither of the other
+ *   arms can see it. Like the co-introduction arm it needs `credentialVmId`
+ *   in hand, since with no id the foreign-member guard would pass vacuously.
+ *
+ * The attribution is anchor-invariant across the shapes where each rung's
+ * hash was committed by an entry that also revealed the previous rung, or by
+ * a handover. The signer arm's key set is the anchor plus every earlier rung
+ * a backward pre-pass recovers from the log's own positional rules ({@link
+ * recoverEarlierRungs}, over `decisions/0007-ladder-reveal-hash-order.md`),
+ * so an entry a spent rung signed is attributed however far the anchor has
+ * since climbed. The ladder seed (`ladderSeed`) remains a shortcut and a
+ * cross-check rather than a requirement: it makes every rung's key and hash
+ * known outright and skips the pre-pass. A residue no arm can attribute is
+ * still released -- the retirement then strikes what the recorded inventory
+ * names and nothing more. More than one ladder reveal standing or arriving at
+ * once matches no legitimate history and fails closed ({@link
+ * LadderAttributionError}).
  *
- * With the ladder seed in hand (`ladderSeed`), every rung's key and hash are
- * additionally known a priori, so the attribution does not depend on the
- * anchor being current; without it, the walk is anchored on
- * `anchorKeyMultibase` and on `credentialVmId` alone, and a residue neither
- * can attribute is released -- the retirement then strikes what the recorded
- * inventory names and nothing more. More than one ladder reveal standing or
- * arriving at once matches no legitimate history and fails closed
- * ({@link LadderAttributionError}).
+ * One shape is out of reach seedlessly, and it is reachable today. The
+ * last-client transition strikes the ladder VM and reinstalls it in the same
+ * run (`forgetLastEnrolledClient` stage 1): same seed, the credential's
+ * member standing, the acting rung's hash still committed, and no hash added.
+ * A later self-enrollment then spends that already-revealed rung, so its
+ * reveal-and-commit entry authorizes no key while committing the next rung's
+ * hash, and the registry anchor advances to that next rung. The backward walk
+ * climbs from the anchor by asking which key the entry that committed its
+ * hash authorized; that entry authorized none, so the walk cannot name the
+ * rung that signed it, and the earlier rung and the reinstalled VM go
+ * unrecovered. A seedless retirement then reports the VM as `unclaimed` and
+ * leaves it standing. Tracked as WC-158.
+ *
+ * The anchor comes in three forms, and the walk is the same afterwards. A
+ * recorded update-key multibase (`anchorKeyMultibase`) is what a caller
+ * holding a registry entry passes. A hash (`anchorHash`) is the same anchor
+ * with the key withheld: the rung is picked up when the log reveals it, since
+ * the reveal test already matches on the commitment. With neither, and a
+ * `credentialVmId` in hand, the anchor is read off the credential's bind entry
+ * ({@link credentialLadderAnchor}) -- the cold-browser mode, where no registry
+ * is readable before the entry is written. An anchor the bind entry cannot
+ * name unambiguously refuses with {@link LadderAttributionError} rather than
+ * walking from a guess.
  *
  * @param options {object}
  * @param options.log {DIDLog}   a resolved, caller-verified log
- * @param options.anchorKeyMultibase {string}   the credential's recorded
+ * @param [options.anchorKeyMultibase] {string}   the credential's recorded
  *   update-key multibase (bind-time rung 0, or a refreshed later rung)
+ * @param [options.anchorHash] {string}   the same anchor as a committed hash,
+ *   for a caller that resolved one without the key
  * @param [options.ladderSeed] {Uint8Array}   the credential's ladder seed,
  *   when the caller holds it
  * @param [options.credentialVmId] {string}   the credential's own
  *   `keyAgreement` verification-method id, which tells a climb (the
  *   credential stands afterwards) from a spend (its inventory goes in the same
- *   entry)
+ *   entry), which the ladder VM's co-introduction arm is anchored on, and
+ *   which supplies the anchor itself when neither anchor form is passed
  * @param [options.maxScan] {number}   seeded pre-derivation bound; defaults to
  *   {@link LADDER_MAX_SCAN}
- * @returns {Promise<LadderStandingInventory>}   what currently stands; both
- *   arrays empty when the log carries nothing of the ladder any more
+ * @returns {Promise<LadderStandingInventory>}   what currently stands; every
+ *   array empty when the log carries nothing of the ladder any more
  */
-export async function attributeLadderInventory({ log, anchorKeyMultibase, ladderSeed, credentialVmId, maxScan = LADDER_MAX_SCAN }) {
-    const anchorHash = await deriveNextKeyHash(anchorKeyMultibase);
-    const ladderKeys = new Set([anchorKeyMultibase]);
+export async function attributeLadderInventory({ log, anchorKeyMultibase, anchorHash: suppliedAnchorHash, ladderSeed, credentialVmId, maxScan = LADDER_MAX_SCAN }) {
+    const params = effectiveParameters(log);
+    const { facts, commitIndex } = indexLadderLog({ log, params });
+    // The anchor, in the caller's order of preference: the recorded update key,
+    // a hash the caller resolved itself, or -- holding neither, the cold-browser
+    // case -- the credential's own bind entry, read off the log.
+    let anchorKey = anchorKeyMultibase;
+    let anchorHash = suppliedAnchorHash;
+    if (anchorKey === undefined && anchorHash === undefined) {
+        const resolved = credentialVmId === undefined
+            ? undefined
+            : resolveBindAnchor({ log, facts, credentialVmId });
+        if (resolved === undefined) {
+            throw new LadderAttributionError('The ladder walk was given no anchor, and the log does not name an ' +
+                'unambiguous bind entry for this credential; refusing to ' +
+                'attribute an ambiguous history.');
+        }
+        anchorKey = resolved.anchorKeyMultibase;
+        anchorHash = resolved.anchorHash;
+    }
+    if (anchorHash === undefined) {
+        anchorHash = await deriveNextKeyHash(anchorKey);
+    }
+    const ladderKeys = new Set(anchorKey === undefined ? [] : [anchorKey]);
     // What the ladder knows a priori: the recorded key's hash and, with the
     // seed in hand, every rung's. A claim outside this set is held on the
     // evidence of the entry that committed it, and released again when a
@@ -395,33 +1027,45 @@ export async function attributeLadderInventory({ log, anchorKeyMultibase, ladder
             ladderHashes.add(rungHash);
         }
     }
-    const params = effectiveParameters(log);
+    // Without the seed, the anchor alone would hide every entry a spent rung
+    // signed. Recover those rungs from the log's positional rules first, and
+    // treat them exactly as seed-derived ones: known a priori, on both sets.
+    if (!ladderSeed && credentialVmId !== undefined) {
+        const earlier = await recoverEarlierRungs({
+            log,
+            facts,
+            commitIndex,
+            anchorHash,
+            credentialVmId,
+            maxScan
+        });
+        for (const rung of earlier) {
+            ladderKeys.add(rung.key);
+            derivedHashes.add(rung.hash);
+            ladderHashes.add(rung.hash);
+        }
+    }
     let pending;
-    let prevUpdateKeys = new Set();
     let prevHashes = new Set();
-    // Where each standing hash was FIRST committed: the entry's signers, the
-    // hash appended immediately after it there, and whether that successor
-    // closed the entry's additions. Read back at a reveal whose committing
-    // entry the reveal itself retires (below).
-    const firstCommit = new Map();
+    // Whether the entry that published each ladder VM seen so far was signed by
+    // a key this ladder accounted for at that point. Re-answered at every
+    // publication, so a VM struck and later republished by another ladder is
+    // attributed to whoever put the standing copy there.
+    let prevLadderVmIds = new Set();
+    let prevEntryDoc;
+    const ladderVmClaims = new Map();
+    // The account DID, read off the credential's own verification-method id:
+    // the co-introduction arm needs it to tell a credential-class
+    // `keyAgreement` member (controlled by the account) from an enrolled
+    // client's marked twin.
+    const credentialDid = credentialVmId?.split('#')[0];
     for (const [index, entry] of params.entries()) {
         const currentUpdateKeys = new Set(entry.updateKeys);
-        const addedKeys = entry.updateKeys.filter(key => !prevUpdateKeys.has(key));
-        const removedKeys = [...prevUpdateKeys].filter(key => !currentUpdateKeys.has(key));
-        // Order-preserving on purpose: the completion transfer below reads the
-        // claim committed immediately after the client's update-key hash as its
-        // staged hash (the reveal entry's append order, a ratified convention).
-        const addedHashes = entry.nextKeyHashes.filter(hash => !prevHashes.has(hash));
-        const signers = entrySigners({ entry: log[index] });
-        addedHashes.forEach((hash, at) => {
-            if (!firstCommit.has(hash)) {
-                firstCommit.set(hash, {
-                    signers,
-                    successor: addedHashes[at + 1],
-                    successorLast: at + 2 === addedHashes.length
-                });
-            }
-        });
+        // The pre-pass keeps these order-preserving on purpose: the completion
+        // transfer below reads the claim committed immediately after the client's
+        // update-key hash as its staged hash (the reveal entry's append order, a
+        // ratified convention).
+        const { addedKeys, removedKeys, addedHashes } = facts[index];
         // Completion first: the pending revealed rung left `updateKeys`. When the
         // same entry authorizes a key whose hash sits among the reveal's claims,
         // the enrollment completed -- that hash and its successor (the client's
@@ -499,19 +1143,24 @@ export async function attributeLadderInventory({ log, anchorKeyMultibase, ladder
             // credential survives or the seed derives it.
             const keyHash = await deriveNextKeyHash(key);
             const origin = prevHashes.has(keyHash)
-                ? firstCommit.get(keyHash)
+                ? commitIndex.get(keyHash)
                 : undefined;
-            if (origin?.successor !== undefined &&
-                !origin.successorLast &&
-                origin.signers.some(signer => removedKeys.includes(signer))) {
-                pending.claims.unshift(origin.successor);
-                ladderHashes.add(origin.successor);
+            const originFacts = origin === undefined ? undefined : facts[origin.entryIndex];
+            if (origin !== undefined && originFacts !== undefined) {
+                const successor = originFacts.addedHashes[origin.at + 1];
+                const successorLast = origin.at + 2 === originFacts.addedHashes.length;
+                if (successor !== undefined &&
+                    !successorLast &&
+                    originFacts.signers.some(signer => removedKeys.includes(signer))) {
+                    pending.claims.unshift(successor);
+                    ladderHashes.add(successor);
+                }
             }
         }
         else if (pending && ladderSigned({ entry: log[index], ladderKeys })) {
             // The rung is still revealed AND signed this entry, so the hashes it
-            // commits were committed under the rung's authority (the
-            // ladder-anchored window's separate commit entry) and join its claims.
+            // commits were committed under the rung's authority and join its
+            // claims.
             // Signature, not mere presence in `updateKeys`, is what attributes
             // them: the rung's reveal outlives the ceremony that revealed it, so
             // claiming everything committed afterwards would sweep up hashes of
@@ -522,7 +1171,46 @@ export async function attributeLadderInventory({ log, anchorKeyMultibase, ladder
                 ladderHashes.add(hash);
             }
         }
-        prevUpdateKeys = currentUpdateKeys;
+        // After the reveal branch, so a VM installed by the very entry that
+        // reveals the rung signing it (the ladder-anchored genesis, the ladder-VM
+        // install) is attributed to this ladder rather than missed.
+        const entryDoc = log[index]?.state;
+        const publishedVmIds = entryDoc ? ladderVmIds({ doc: entryDoc }) : [];
+        const newVmIds = publishedVmIds.filter(vmId => !prevLadderVmIds.has(vmId));
+        // The co-introduction arm, under its three guards (see the header): one
+        // new ladder VM, one newly introduced credential-class `keyAgreement`
+        // member, and that member is this credential's. It is what reaches the
+        // bind entry an enrolled client signs, which no rung stands behind.
+        const introduced = credentialDid !== undefined && entryDoc !== undefined
+            ? introducedCredentialKeys({
+                doc: entryDoc,
+                prevDoc: prevEntryDoc,
+                did: credentialDid
+            })
+            : [];
+        const coIntroduced = credentialVmId !== undefined &&
+            newVmIds.length === 1 &&
+            introduced.length === 1 &&
+            introduced[0] === credentialVmId;
+        // The COMMITMENT arm (see the header): the entry committed a hash this
+        // ladder knows a priori, published one ladder VM, and introduced no other
+        // credential's member. `derivedHashes` rather than `ladderHashes`: a hash
+        // held on the evidence of the entry that committed it is not proof of
+        // ownership, and reading one here would claim a VM on a claim the
+        // completion may yet release. It needs `credentialVmId` in hand for the
+        // same reason the co-introduction arm does: with no id, `introduced` is
+        // empty and the foreign-member guard would pass vacuously.
+        const commitmentClaimed = credentialVmId !== undefined &&
+            newVmIds.length === 1 &&
+            addedHashes.some(hash => derivedHashes.has(hash)) &&
+            introduced.every(id => id === credentialVmId);
+        for (const vmId of newVmIds) {
+            ladderVmClaims.set(vmId, coIntroduced ||
+                commitmentClaimed ||
+                ladderSigned({ entry: log[index], ladderKeys }));
+        }
+        prevLadderVmIds = new Set(publishedVmIds);
+        prevEntryDoc = entryDoc;
         prevHashes = new Set(entry.nextKeyHashes);
     }
     const final = params[params.length - 1] ?? {
@@ -531,7 +1219,8 @@ export async function attributeLadderInventory({ log, anchorKeyMultibase, ladder
     };
     return {
         revealedKeys: final.updateKeys.filter(key => ladderKeys.has(key)),
-        committedHashes: final.nextKeyHashes.filter(hash => ladderHashes.has(hash))
+        committedHashes: final.nextKeyHashes.filter(hash => ladderHashes.has(hash)),
+        ladderVmIds: [...prevLadderVmIds].filter(vmId => ladderVmClaims.get(vmId) === true)
     };
 }
 //# sourceMappingURL=ladder.js.map