@interop/wallet-core 0.55.0 → 0.57.0

package/dist/clientAnnex/establish.js

@@ -0,0 +1,660 @@
+import { ensurePromotedSpaceController, mintSpaceId } from '../genesis/accountGenesis.js';
+import { effectiveParameters, keyAgreementCommitment, readPublishedLog } from '../webvh/didWebvh.js';
+import { accountLogPinId } from '../webvh/verifyLog.js';
+import { didKeyZcapClient } from '../webvh/zcap.js';
+import { delegateLogWrite, delegationProofKeyId } from '../recovery/recoveryDelegation.js';
+import { mintUserKey } from '../keys/index.js';
+import { attributeLadderRung } from './ladder.js';
+import { ladderVmAgent, ladderVmZcapClient } from './zcap.js';
+import { clientAnnexDidParts, clientAnnexLogPinId, clientAnnexLogStore, ensureGenerationDelegationCurrent, mintCredentialClientAnnexGeneration, mintDelegatedClientsDelegation, setDelegatedClientsPointer } from './log.js';
+import { ladderSignedGenerationDelegationMinter, pointerEntryUpdateKeys, resolveClientAnnexSpaceId } from './heal.js';
+import { ensureCredentialAnchoredAccountGenesis } from './credentialAnchoredGenesis.js';
+import { ensureRosterDeliveredEpochs } from './rosterDeliveredEpochs.js';
+/**
+ * The stage-3 primitive: ensure the account document points at a client-annex
+ * generation, minting and pointing one when it does not. Gated on the
+ * pointer: a document already carrying `#DelegatedClients` is returned
+ * as-is (`generationMinted: false`). Otherwise the annex Space resolves in
+ * the settled order ({@link resolveClientAnnexSpaceId}: the sibling
+ * delegation's target, else a fresh Space minted here), and the fold runs in
+ * the standing sub-step order: mint the generation, embed the generation
+ * delegation while the Space still answers to its creation controller, flip
+ * the Space's controller to the account DID, then append the pointer entry
+ * -- strictly last in the block, so pointer-present implies every prior
+ * sub-step landed. The pointer entry signs by ladder attribution of the
+ * currently revealed rung, and every log touch rides the caller's chain-head
+ * pin store.
+ *
+ * Two invocation authorities, heal's pattern. A caller holding a standing
+ * invocation authority (`invocation`: an enrolled client's storage handle
+ * plus the sibling capability its annex writes ride) converges onto the
+ * sibling-named Space as-is -- the Space is already account-controlled, so
+ * no flip runs. The bootstrap-only caller (the establishment) can write a
+ * sibling-named Space only while it still answers to the bootstrap did:key
+ * (a tear before the flip); one an earlier run already flipped refuses its
+ * writes, and that authorization refusal falls back to the fresh-mint arm
+ * rather than failing the run. The bootstrap arm's own controller flip
+ * swallows ONLY an authorization-class refusal (a concurrent run flipped
+ * first); a transport failure there aborts BEFORE the pointer entry, since
+ * a document pointing at a generation whose Space still answers to the bare
+ * ladder did:key would be unreachable forever.
+ *
+ * The fold shape is fixed (a separate pointer entry); a ceremony whose
+ * pointer move must ride another log entry atomically (the transient
+ * recovery's add-and-retire) keeps its own inline fold rather than
+ * parameterizing this one.
+ *
+ * @param options {object}
+ * @param options.account {object}   the VERIFIED account log view
+ *   (`{ did, doc, log }`; never re-fetched here)
+ * @param options.wasServerUrl {string}   the account pointer's host
+ * @param options.accountSpaceId {string}   the ACCOUNT Space's id (the
+ *   generation delegation's target subtree, and the account-log pin slot)
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
+ * @param options.was {WasClient}   the bootstrap storage client (the ladder
+ *   VM's bare did:key), used by the fresh-mint arm
+ * @param options.mintController {string}   the annex Space's creation
+ *   controller (a did:key; the ladder VM's bare did:key here)
+ * @param options.mintGenerationDelegation {Function}
+ *   `({ clientAnnexDid }) => Promise<IZcap>` -- the generation-delegation
+ *   minter (ladder-VM-signed on a ladder-anchored account)
+ * @param options.idStore {WebvhIdStore}   the ACCOUNT log's store
+ * @param [options.updateKeys] {ClientWebvhUpdateKeys}   the pointer entry's
+ *   signing pair; absent, it is recovered by ladder attribution of the
+ *   supplied log's current parameters
+ * @param [options.delegatedClients] {IZcap}   the record's sibling
+ *   delegation, for the Space resolution's settled order
+ * @param [options.invocation] {object}   a standing invocation authority for
+ *   the sibling-named Space's writes: `was` (the standing client's storage
+ *   handle) and `capability` (the sibling delegation the annex writes ride).
+ *   Absent, the sibling-named Space is attempted under the bootstrap client
+ *   and an authorization refusal falls back to a fresh mint
+ * @param [options.logOnly] {boolean}   pointer entries publish the log only
+ *   (a bridge-delegated writer has no `did.json` projection rights); the
+ *   establishment's root window omits it
+ * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins; slot
+ *   keys are derived here per log
+ * @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
+ */
+export async function ensurePointedClientAnnexGeneration({ account, wasServerUrl, accountSpaceId, ladderSeed, was, mintController, mintGenerationDelegation, idStore, updateKeys, delegatedClients, invocation, logOnly, pinStore, now }) {
+    const { pointer, annexSpaceId } = resolveClientAnnexSpaceId({
+        doc: account.doc,
+        ...(delegatedClients !== undefined ? { delegatedClients } : {})
+    });
+    if (pointer !== undefined) {
+        return {
+            clientAnnexDid: pointer,
+            generationMinted: false,
+            spaceMinted: false
+        };
+    }
+    // The pre-flight attribution precedes the mint (never mint a generation
+    // the pointer entry could not then name), unless the caller supplied the
+    // signing pair itself.
+    const entryKeys = updateKeys ??
+        (await pointerEntryUpdateKeys({ ladderSeed, log: account.log }));
+    const pointGeneration = async (clientAnnexDid) => setDelegatedClientsPointer({
+        idStore,
+        updateKeys: entryKeys,
+        clientAnnexDid,
+        expectedDid: account.did,
+        ...(logOnly !== undefined ? { logOnly } : {}),
+        ...(pinStore !== undefined
+            ? { pinStore, logId: accountLogPinId({ spaceId: accountSpaceId }) }
+            : {})
+    });
+    // The standing-authority arm: the sibling-named Space is already
+    // account-controlled, its writes ride the supplied capability, and no
+    // flip runs (heal's existing-Space pattern).
+    if (annexSpaceId !== undefined && invocation !== undefined) {
+        const minted = await mintCredentialClientAnnexGeneration({
+            was: invocation.was,
+            wasServerUrl,
+            spaceId: annexSpaceId,
+            controller: account.did,
+            ladderSeed,
+            capability: invocation.capability
+        });
+        const ensured = await ensureGenerationDelegationCurrent({
+            store: clientAnnexLogStore({
+                was: invocation.was,
+                spaceId: annexSpaceId,
+                generationId: minted.generationId,
+                capability: invocation.capability
+            }),
+            ladderSeed,
+            generationId: minted.generationId,
+            mintGenerationDelegation,
+            expectedDid: minted.did,
+            ...(pinStore !== undefined
+                ? {
+                    pinStore,
+                    logId: clientAnnexLogPinId({
+                        spaceId: annexSpaceId,
+                        generationId: minted.generationId
+                    })
+                }
+                : {}),
+            ...(now !== undefined ? { now } : {})
+        });
+        await pointGeneration(minted.did);
+        return {
+            clientAnnexDid: minted.did,
+            generationDelegation: ensured.delegation,
+            generationMinted: true,
+            spaceMinted: false
+        };
+    }
+    // The bootstrap arm: mint, embed the delegation while the Space still
+    // answers to its creation controller, flip, then the pointer entry.
+    const bootstrapArm = async ({ spaceId, spaceMinted }) => {
+        const minted = await mintCredentialClientAnnexGeneration({
+            was,
+            wasServerUrl,
+            spaceId,
+            controller: mintController,
+            ladderSeed
+        });
+        const ensured = await ensureGenerationDelegationCurrent({
+            store: clientAnnexLogStore({
+                was,
+                spaceId,
+                generationId: minted.generationId
+            }),
+            ladderSeed,
+            generationId: minted.generationId,
+            mintGenerationDelegation,
+            expectedDid: minted.did,
+            ...(pinStore !== undefined
+                ? {
+                    pinStore,
+                    logId: clientAnnexLogPinId({
+                        spaceId,
+                        generationId: minted.generationId
+                    })
+                }
+                : {}),
+            ...(now !== undefined ? { now } : {})
+        });
+        // The controller flip. ONLY an authorization-class refusal is swallowed
+        // (a concurrent run flipped first, so the Space no longer answers to
+        // this client); a transport failure aborts BEFORE the pointer entry --
+        // publishing a pointer at a generation whose Space still answers to the
+        // bare ladder did:key would leave it unreachable forever, with nothing
+        // downstream ever re-running the flip.
+        try {
+            await was
+                .space(spaceId)
+                .configure({ controller: account.did, force: true });
+        }
+        catch (err) {
+            if (!authorizationRefusal(err)) {
+                throw err;
+            }
+        }
+        await pointGeneration(minted.did);
+        return {
+            clientAnnexDid: minted.did,
+            generationDelegation: ensured.delegation,
+            generationMinted: true,
+            spaceMinted
+        };
+    };
+    if (annexSpaceId !== undefined) {
+        // A sibling-named Space under bootstrap authority alone: writable only
+        // while it still answers to the bootstrap did:key (a tear before the
+        // flip). One an earlier run already flipped refuses these writes; that
+        // refusal falls back to the fresh mint below, and the flipped Space
+        // stays the recorded orphan residue.
+        try {
+            return await bootstrapArm({ spaceId: annexSpaceId, spaceMinted: false });
+        }
+        catch (err) {
+            if (!authorizationRefusal(err)) {
+                throw err;
+            }
+        }
+    }
+    return bootstrapArm({ spaceId: mintSpaceId(), spaceMinted: true });
+}
+/**
+ * Whether an error is an authorization-class refusal (401/403, on the error,
+ * its `cause`, or its carried response) rather than a transport or logic
+ * failure. Matched structurally: was-client surfaces server refusals with
+ * the HTTP status attached, and error classes do not survive crossing
+ * package copies.
+ *
+ * @param err {unknown}
+ * @returns {boolean}
+ */
+function authorizationRefusal(err) {
+    const candidates = [err, err?.cause];
+    for (const candidate of candidates) {
+        if (candidate === null || typeof candidate !== 'object') {
+            continue;
+        }
+        const carried = candidate;
+        const status = carried.status ?? carried.response?.status;
+        if (status === 401 || status === 403) {
+            return true;
+        }
+        if (carried.name === 'NotAllowedError' ||
+            carried.name === 'ForbiddenError' ||
+            carried.name === 'UnauthorizedError') {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Runs the whole credential-anchored establishment for one unlock credential
+ * (see the module doc for the stage order and its whys). Idempotent under
+ * re-run from durable state alone; a torn run converges by running again.
+ *
+ * @param options {object}
+ * @param options.wasServerUrl {string}   the account pointer's host
+ * @param options.spaceId {string}   the ACCOUNT Space's id, minted by the
+ *   caller and carried in the account pointer (never minted here)
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed --
+ *   freshly minted on a signup, recovered from the record on a heal re-run
+ * @param options.standing {object}   the credential's standing client
+ *   identity, from a BINDING-VERIFIED record or a fresh derivation:
+ *   `clientDid`, `keyAgreementKeyMultibase`, `recipientKid`, and
+ *   `keyAgreementKey` (the private-half key-agreement key, for the
+ *   adopted-roster read-back)
+ * @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 }) =>
+ *   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
+ * @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)
+ * @param options.idStore {WebvhIdStore}   the account's `id` collection
+ *   store, signing as the same bootstrap did:key
+ * @param [options.expectedDid] {string}   the account DID, when the caller's
+ *   pointer already names one (a heal re-run)
+ * @param options.lowEntropy {boolean}   whether the credential is
+ *   low-entropy. REQUIRED (the compiler backstop at the passkey call site,
+ *   where dropping it would publish the commitment and break the verbatim
+ *   published key that call site's readers trigger on), and it still FAILS
+ *   SAFE at runtime: the `keyAgreement` key publishes as a hash commitment
+ *   unless the value is exactly `false` -- a verbatim KDF-derived key in
+ *   the world-readable document is a standing offline-grind oracle
+ *   removable only by credential rotation
+ * @param [options.email] {string}   -- not taken here; carried inside the
+ *   caller's `bindRecord` closure
+ * @param [options.priorCreatedAt] {string}   the previous bind's freshness
+ *   stamp, from a standing keyring hit. Its presence SKIPS stage 1: the
+ *   record already carries the ladder seed, and a DID-less re-write could
+ *   downgrade a sibling browser's completed re-bind
+ * @param [options.delegatedClients] {IZcap}   the record's sibling
+ *   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.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
+ *   bound no keystore this run. A throw is collected, never fatal
+ * @param [options.beforePromotion] {Function}   runs after the re-bind and
+ *   BEFORE the controller promotion -- the last window where a root
+ *   invocation under the bootstrap did:key works (the signup's registry
+ *   write). NOT swallowed here: a throw fails the establishment, so a hook
+ *   that must be best-effort swallows its own failures
+ * @param [options.pinStore] {ResourceLogPinStore}   the chain-head pin store
+ *   for every log read here (a transient visit's in-memory handle, or a
+ *   durable one when a remembered caller seeds its own pin)
+ * @param [options.now] {number}   epoch milliseconds, for tests
+ * @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
+ *   (the underlying failure as `cause`); the record stays DID-less, so the
+ *   next login's heal re-runs the establishment
+ */
+export function establishCredentialAnchoredAccount(options) {
+    // Refused synchronously, before any write: the required hooks are the
+    // persist-before-publish seams, and a run without them could publish a
+    // rung nobody can re-derive.
+    if (typeof options.bindRecord !== 'function') {
+        throw new TypeError('establishCredentialAnchoredAccount requires bindRecord: the unlock ' +
+            'record must be durably written before anything publishes.');
+    }
+    if (typeof options.rosterStoreFor !== 'function') {
+        throw new TypeError('establishCredentialAnchoredAccount requires rosterStoreFor: the ' +
+            "user-key roster is the account's decryption root.");
+    }
+    if (typeof options.bootstrapWasFor !== 'function') {
+        throw new TypeError('establishCredentialAnchoredAccount requires bootstrapWasFor: every ' +
+            "pre-promotion write signs as the ladder VM's bare did:key.");
+    }
+    return establishCredentialAnchoredAccountChecked(options);
+}
+/**
+ * The checked body of {@link establishCredentialAnchoredAccount}.
+ *
+ * @param options {object}   see {@link establishCredentialAnchoredAccount}
+ * @returns {Promise<CredentialAnchoredEstablishment>}
+ */
+async function establishCredentialAnchoredAccountChecked({ wasServerUrl, spaceId, ladderSeed, standing, bindRecord, rosterStoreFor, bootstrapWasFor, idStore, expectedDid, lowEntropy, priorCreatedAt, delegatedClients, provideDidWebKeys, promoteKeystore, beforePromotion, pinStore, now }) {
+    const bootstrapAgent = await ladderVmAgent({ ladderSeed });
+    const bootstrapZcap = didKeyZcapClient({ keyAgent: bootstrapAgent });
+    const bootstrapWas = bootstrapWasFor({ keyAgent: bootstrapAgent });
+    const pointer = { spaceId, host: wasServerUrl };
+    const failed = [];
+    // The hash-commitment rule, failing safe: a KDF-derived public key
+    // published verbatim in the world-readable document is a standing
+    // offline-grind oracle, so only an EXPLICIT `lowEntropy: false` publishes
+    // the key itself; absent or ambiguous, the commitment publishes.
+    const keyAgreement = lowEntropy === false
+        ? { publicKeyMultibase: standing.keyAgreementKeyMultibase }
+        : {
+            commitment: await keyAgreementCommitment({
+                keyAgreementKeyMultibase: standing.keyAgreementKeyMultibase
+            })
+        };
+    // 1. The interim bridge and the first bind -- skipped when the caller's
+    // record already carries the ladder seed (`priorCreatedAt` from a standing
+    // hit): a DID-less re-write here could downgrade a sibling browser's
+    // completed re-bind.
+    let firstBindCreatedAt = priorCreatedAt;
+    if (priorCreatedAt === undefined) {
+        const interimBridge = await delegateLogWrite({
+            zcapClient: bootstrapZcap,
+            pointer,
+            recoveryClientDid: standing.clientDid
+        });
+        const firstBind = await bindRecord({
+            controller: bootstrapAgent.id,
+            pointer,
+            delegation: interimBridge
+        });
+        assertBindResult({ bind: firstBind, stage: 'first bind' });
+        firstBindCreatedAt = firstBind.createdAt;
+    }
+    // 2. The genesis ceremony under the bootstrap did:key. The candidate user
+    // key seeds a fresh roster; an adopted (heal) roster keeps its own.
+    const candidateUserKey = await mintUserKey();
+    const genesis = await ensureCredentialAnchoredAccountGenesis({
+        was: bootstrapWas,
+        wasServerUrl,
+        spaceId,
+        ladderSeed,
+        keyAgreement,
+        standingRecipient: {
+            id: standing.recipientKid,
+            publicKeyMultibase: standing.keyAgreementKeyMultibase
+        },
+        userKey: candidateUserKey,
+        idStore,
+        rosterStoreFor,
+        ...(expectedDid !== undefined ? { expectedDid } : {}),
+        ...(provideDidWebKeys ? { provideDidWebKeys } : {}),
+        ...(pinStore !== undefined ? { accountLogPinStore: pinStore } : {}),
+        promoteController: false
+    });
+    // The KMS stage stays best-effort: a failed thunk is the ceremony's
+    // collected `didWebKeys` stage, reported on the result and never fatal --
+    // the account proceeds keystore-less and a later pass heals it. The
+    // landing check below deliberately ignores this stage.
+    for (const entry of genesis.failed) {
+        if (entry.stage === 'didWebKeys') {
+            failed.push({ stage: 'didWebKeys', error: entry.error });
+        }
+    }
+    const did = genesis.did;
+    const fullPointer = { spaceId, host: wasServerUrl, did };
+    // The ceremony collects its roster and epoch failures instead of
+    // throwing; here they are fatal. A roster that never landed leaves the
+    // candidate key held in this tab's memory alone, and a registry sealed
+    // under it would be unreadable forever. Refusing BEFORE the re-bind keeps
+    // the record DID-less, which is exactly what routes the next login into
+    // the establishment re-run that converges.
+    assertGenesisLanded({ failed: genesis.failed, epochs: genesis.epochs });
+    if (!genesis.rosterDescriptor) {
+        throw new Error('The user-key roster genesis did not land.');
+    }
+    // 2c. The adopted-roster arm: a re-run that adopted an earlier run's
+    // roster recovers the real user key from the credential's standing wrap
+    // and completes the collection epochs under it -- the one installer,
+    // through the shared mint-policy stage.
+    let userKey = candidateUserKey;
+    if (genesis.rosterDescriptor.currentEpoch !== candidateUserKey.id) {
+        const delivered = await ensureRosterDeliveredEpochs({
+            store: rosterStoreFor({ did }),
+            candidateUserKey,
+            clientKeyAgreementKey: standing.keyAgreementKey,
+            was: bootstrapWas,
+            spaceId
+        });
+        if (delivered.outcome === 'no-wrap') {
+            throw new Error('The adopted user-key roster could not be read back with this ' +
+                'credential.', { cause: delivered.error });
+        }
+        userKey = delivered.userKey;
+        assertGenesisLanded({ failed: [], epochs: delivered.epochs });
+    }
+    // 3. The annex generation block, so the very next login can enroll a
+    // transient client: reuse the pointed one; resolve, mint, embed the
+    // delegation, flip the auxiliary Space's controller, and point otherwise.
+    const published = await readPublishedLog({
+        idStore,
+        expectedDid: did,
+        ...(pinStore !== undefined
+            ? { pinStore, logId: accountLogPinId({ spaceId }) }
+            : {})
+    });
+    if (published === undefined) {
+        throw new Error('The account log the genesis published could not be read.');
+    }
+    // The bind-time REVEALED rung, attributed from the published log's current
+    // parameters (rung 0 on a fresh establishment) -- resolved HERE, before
+    // stage 3 and strictly before the re-bind: on an account whose document no
+    // longer anchors this ladder (a struck ladder VM), the attribution throws
+    // while the record is still in its pre-re-bind shape, rather than after a
+    // re-bind that would leave a rebound record with no registry entry and no
+    // mender. A committed-only rung refuses too: it cannot sign, and recording
+    // it as the registry's update key would misstate the standing rung.
+    const attributed = await attributeLadderRung({
+        ladderSeed,
+        published: currentLogParameters(published)
+    });
+    if (attributed.state !== 'revealed') {
+        throw new Error("No revealed rung of this credential's ladder stands in the account " +
+            "log's current update keys; the establishment cannot proceed.");
+    }
+    const generation = await ensurePointedClientAnnexGeneration({
+        account: published,
+        wasServerUrl,
+        accountSpaceId: spaceId,
+        ladderSeed,
+        was: bootstrapWas,
+        mintController: bootstrapAgent.id,
+        mintGenerationDelegation: ladderSignedGenerationDelegationMinter({
+            accountDid: did,
+            ladderSeed,
+            wasServerUrl,
+            spaceId,
+            ...(now !== undefined ? { now } : {})
+        }),
+        idStore,
+        ...(delegatedClients !== undefined ? { delegatedClients } : {}),
+        ...(pinStore !== undefined ? { pinStore } : {}),
+        ...(now !== undefined ? { now } : {})
+    });
+    const clientAnnex = clientAnnexDidParts({ did: generation.clientAnnexDid });
+    // 4. The final bridge and sibling, ladder-VM-signed (they must survive
+    // promotion, which the interim did:key-signed bridge cannot), and the
+    // re-bind: full pointer, both delegations, the management zcap to the
+    // account DID.
+    const ladderZcap = await ladderVmZcapClient({ accountDid: did, ladderSeed });
+    const bridge = await delegateLogWrite({
+        zcapClient: ladderZcap,
+        pointer: fullPointer,
+        recoveryClientDid: standing.clientDid
+    });
+    const sibling = await mintDelegatedClientsDelegation({
+        zcapClient: ladderZcap,
+        wasServerUrl,
+        clientAnnexSpaceId: clientAnnex.spaceId,
+        controller: standing.clientDid,
+        ...(now !== undefined ? { now } : {})
+    });
+    const rebind = await bindRecord({
+        controller: bootstrapAgent.id,
+        pointer: fullPointer,
+        delegation: bridge,
+        delegatedClients: sibling,
+        delegateManagementTo: did,
+        ...(firstBindCreatedAt !== undefined
+            ? { priorCreatedAt: firstBindCreatedAt }
+            : {})
+    });
+    assertBindResult({ bind: rebind, stage: 're-bind' });
+    const delegationKeyId = delegationProofKeyId(bridge);
+    const delegatedClientsKeyId = delegationProofKeyId(sibling);
+    const establishment = {
+        did,
+        unlockSpaceId: rebind.unlockSpaceId,
+        ...(rebind.manageCapability
+            ? { manageCapability: rebind.manageCapability }
+            : {}),
+        standingFields: {
+            rosterKid: standing.recipientKid,
+            keyAgreementKeyMultibase: standing.keyAgreementKeyMultibase,
+            updateKeyMultibase: attributed.rung.keyMultibase,
+            unlockClientDid: standing.clientDid,
+            ...(delegationKeyId ? { delegationKeyId } : {}),
+            ...(zcapExpires(bridge)
+                ? { delegationExpires: zcapExpires(bridge) }
+                : {}),
+            ...(delegatedClientsKeyId ? { delegatedClientsKeyId } : {}),
+            ...(zcapExpires(sibling)
+                ? { delegatedClientsExpires: zcapExpires(sibling) }
+                : {}),
+            ...(rebind.unlockKeyAgreementKeyId
+                ? { unlockKeyAgreementKeyId: rebind.unlockKeyAgreementKeyId }
+                : {}),
+            ...(rebind.unlockKeyAgreementKeyMultibase
+                ? {
+                    unlockKeyAgreementKeyMultibase: rebind.unlockKeyAgreementKeyMultibase
+                }
+                : {})
+        },
+        ...(genesis.epochsSkipped ? { epochsSkipped: genesis.epochsSkipped } : {}),
+        failed
+    };
+    // 5. The caller's pre-promotion tail (the signup's registry write): the
+    // last window where a root invocation under the bootstrap did:key works.
+    // A throw here fails the establishment (some callers' registry writes
+    // must land in this window or the credential has no rebuild); a hook that
+    // must be best-effort swallows its own failures.
+    if (beforePromotion) {
+        await beforePromotion({
+            was: bootstrapWas,
+            zcapClient: bootstrapZcap,
+            did,
+            userKey,
+            establishment
+        });
+    }
+    // 6. The promotion, last: from here on the ladder's authority is exactly
+    // its licensed document inventory (delegation and log-anchored signing),
+    // and the bootstrap did:key stops verifying.
+    await ensurePromotedSpaceController({
+        was: bootstrapWas,
+        wasAsClient: bootstrapWas,
+        spaceId,
+        did
+    });
+    // The keystore half of the promotion, best-effort like every KMS touch
+    // here: the caller's closure no-ops when its KMS stage bound no keystore
+    // this run, and a throw is collected, never fatal -- the keystore's KMS
+    // authority is independent of the Space controller, so a failed promotion
+    // is retryable.
+    if (promoteKeystore) {
+        try {
+            await promoteKeystore({ did });
+        }
+        catch (err) {
+            failed.push({ stage: 'keystorePromotion', error: err });
+        }
+    }
+    return establishment;
+}
+/**
+ * The current `updateKeys` / `nextKeyHashes` view of a published log, for
+ * the bind-time rung attribution.
+ *
+ * @param published {PublishedWebvhLog}
+ * @returns {object}
+ */
+export function currentLogParameters(published) {
+    const params = effectiveParameters(published.log);
+    return params[params.length - 1] ?? { updateKeys: [], nextKeyHashes: [] };
+}
+/**
+ * A delegation's `expires` caveat, when it carries one.
+ *
+ * @param zcap {IZcap}
+ * @returns {string | undefined}
+ */
+export function zcapExpires(zcap) {
+    return zcap.expires;
+}
+/**
+ * Asserts a `bindRecord` result carries the members the ceremony reads --
+ * the observable half of the hook's standing-layout obligation (the sealed
+ * members are the codec's own duty and cannot be checked from here).
+ *
+ * @param options {object}
+ * @param options.bind {CredentialAnchoredBindResult}
+ * @param options.stage {string}
+ * @throws {TypeError}
+ */
+export function assertBindResult({ bind, stage }) {
+    if (typeof bind?.createdAt !== 'string' || bind.createdAt.length === 0) {
+        throw new TypeError(`The bindRecord hook's ${stage} returned no createdAt stamp; the ` +
+            're-bind cannot advance past it.');
+    }
+    if (typeof bind.unlockSpaceId !== 'string' ||
+        bind.unlockSpaceId.length === 0) {
+        throw new TypeError(`The bindRecord hook's ${stage} returned no unlockSpaceId; the ` +
+            'record it wrote cannot be located.');
+    }
+}
+/**
+ * Refuses a genesis whose roster or epoch stages did not land: the ceremony
+ * reports them on `failed` (a stage that could not run) and on
+ * `epochs.failed` (a collection the fan-out could not epoch) rather than
+ * throwing, and on a credential-anchored account no login-time sweep ever
+ * finishes them -- the establishment re-run is the only mender, so the
+ * establishment must stop here for it to be reached. A failed `didWebKeys`
+ * stage is deliberately NOT refused: the KMS stage is best-effort (reported
+ * on the result), and a keystore-less account is complete.
+ *
+ * @param options {object}
+ * @param options.failed {Array}   the ceremony's collected stage failures
+ * @param [options.epochs] {WalletSpaceEpochsResult}   the collection
+ *   epoch fan-out's result, when the stage ran
+ * @throws {Error}   carrying the first underlying failure as `cause`
+ */
+function assertGenesisLanded({ failed, epochs }) {
+    const stage = failed.find(entry => entry.stage === 'roster' || entry.stage === 'epochs');
+    if (stage) {
+        throw new Error(`The credential-anchored genesis's ${stage.stage} stage failed.`, { cause: stage.error });
+    }
+    const collection = epochs?.failed[0];
+    if (collection) {
+        throw new Error('The credential-anchored genesis could not install a key epoch on ' +
+            `collection "${collection.collectionId}".`, { cause: collection.error });
+    }
+}
+//# sourceMappingURL=establish.js.map