@interop/wallet-core 0.49.0 → 0.51.0

package/dist/clientAnnex/forgetLast.d.ts

@@ -0,0 +1,291 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The LAST durable client's forget: the two-entry transition ceremony that
+ * takes an account from one enrolled durable client to the client-less,
+ * ladder-anchored state -- the same state a credential-anchored signup and a
+ * transient recovery produce. Decision 0004's 2026-08-19 amendment fixes the
+ * entry order, and it is forced twice over: the server's revocation endpoint
+ * verifies a to-be-revoked capability's chain against the CURRENTLY resolved
+ * document (so a ladder-signed chain revokes only while the ladder VM is
+ * published), and the ladder VM carries no `capabilityInvocation` (so once
+ * the client's verification method is gone, nothing can sign the revocation
+ * POST at all). So:
+ *
+ * 1. **The install entry** ({@link installLadderVmWebvh}): the ladder VM
+ *    joins the document while the client's whole footprint stays -- the
+ *    both-present transitional state. This is the ceremony's
+ *    posture-changing document version under the ceremony-tail license.
+ * 2. **The roster rotation**, ladder-signed, anchored at the install entry,
+ *    HTTP-invoked under the still-standing client: the user key rotates off
+ *    this client's wrap in ONE append (the license's one-shot shape), read
+ *    back through the credential's standing wrap. Because the append's
+ *    signer is the ladder VM -- a key the post-removal document still lists
+ *    -- the roster log needs no seal completer afterwards, which matters on
+ *    an account where no enrolled client's login sweep will ever run again.
+ * 3. **The collection fan-out**, still under this client's invocation
+ *    authority: every encrypted collection re-epochs onto the fresh key.
+ * 4. **The generation-delegation replacement and revocations**: a fresh
+ *    ladder-signed generation delegation replaces the embedded one
+ *    unconditionally (the forced renewal), and then EVERY still-unexpired
+ *    delegation the annex log's history ever embedded that this
+ *    credential's ladder VM signed is revoked at the server (a renewal
+ *    inside the 30-day window can leave two) -- closing the resurrection
+ *    window a reinstalled derived-key VM would otherwise reopen. The
+ *    replacement is what keeps the account transient-login-reachable after
+ *    the transition; replace-before-revoke is what keeps a torn run from
+ *    stranding the generation delegation-less.
+ * 5. **The other unlock methods' record re-mint** (`unlockMethods`): every
+ *    other standing credential's and recovery code's bridge (and
+ *    `delegatedClients` sibling, where the record carries one) is re-signed
+ *    by the ladder VM and its record re-sealed through the entry's
+ *    management zcap -- the revocation cascade's re-mint pass
+ *    (`remintRecoveryDelegations`), run with the ladder VM as the delegating
+ *    and record-signing key and the forgotten client named as retiring, so
+ *    every delegation it signed counts as rotted ahead of the removal entry.
+ *    Delegations the removed client had signed rot at that entry, and on a
+ *    client-less account no durable login's refresh block will ever run
+ *    again to heal them, so this is the one pass that reaches them. The
+ *    HTTP side still invokes under the still-standing client (the
+ *    management zcaps are granted to the account DID, which only an enrolled
+ *    client can invoke) -- which is why the stage must run before the
+ *    removal entry. The pass walks every entry and reports each one's fate,
+ *    but the ceremony does not carry a failure past this point: a `failed`
+ *    entry refuses the removal entry ({@link RecordRemintFailedError},
+ *    naming the records the pass could not reach), since after the removal
+ *    nothing could ever re-sign that record's bridge. The client stays
+ *    enrolled, and a re-run reaches the entry again.
+ * 6. **The record re-bind seam** (`onBeforeRemoval`): the caller re-signs
+ *    the LOGIN credential's bridge and `delegatedClients` sibling with the
+ *    ladder VM and re-seals its unlock record with the credential in hand
+ *    (a full re-wrap, proof verified rather than settled) -- the one record
+ *    stage 5 need not reach.
+ * 7. **The removal entry** ({@link forgetLastWebvhClient}): the client's
+ *    whole document footprint out while the installed ladder VM keeps the
+ *    account anchored. The app's local wipe runs after this ceremony
+ *    returns.
+ *
+ * Torn-state map: every stage detects completion from durable state, so a
+ * run torn anywhere before the removal entry reads as "not forgotten" and a
+ * re-run converges -- the install entry is idempotent, an already-rotated
+ * roster skips the append (no second ladder-signed append is ever
+ * attempted), the fan-out is staleness-driven, a re-POSTed revocation's 400
+ * already-revoked answer reads as success (decision 0006's resume contract),
+ * and the forced replacement re-mints (the prior run's fresh delegation is
+ * then revoked as history, so a re-run churns one delegation and strands
+ * nothing), and the record re-mint re-checks staleness per entry (a record
+ * already ladder-signed reads as current, one whose re-mint failed is still
+ * rotted and is re-minted). Torn after the removal entry is the
+ * finish-the-wipe state the app's next login maps.
+ *
+ * The honest limitation is the cascade's, as everywhere: ciphertext this
+ * browser already fetched stays forensically recoverable from its storage,
+ * and old epochs stay open to keys it already held.
+ */
+import type { DIDLog } from '@interop/did-method-webvh';
+import type { IKeyAgreementKey, IZcap } from '@interop/data-integrity-core';
+import type { ZcapClient } from '@interop/ezcap';
+import type { CollectionEncryption, IDelegatedZcap } from '@interop/was-client';
+import type { EncryptionDescriptorStore } from '@interop/was-client/edv';
+import { type RevokedClientKeys } from '../webvh/revokeClient.js';
+import type { ResourceLogPinStore } from '../resourceLog/index.js';
+import { type CascadeCollections, type UserKey, type UserKeyCascadeResult } from '../keys/index.js';
+import type { UnlockLogStore } from '../unlock/standingWebvh.js';
+import type { AccountPointer } from '../keyring/record.js';
+import { type RecordRemintOutcome, type RecoveryDelegationEntry } from '../recovery/recoveryDelegation.js';
+import { type ClientAnnexWriteStore } from './log.js';
+/**
+ * What the ceremony's generation stage did: the revoked delegation ids, and
+ * whether the forced replacement landed. A `skipped` reason names the stage
+ * that could not run -- `no-pointer` (the account points at no generation:
+ * nothing to revoke or replace), `log-unreadable` (the pointed generation's
+ * `did.jsonl` is gone; the delegation bytes are unrecoverable, decision
+ * 0006's honest limit), `rung-uncommitted` (this credential cannot write the
+ * generation's log; the account lands delegation-less until a
+ * fresh-generation heal), `already-removed` (the whole ceremony completed on
+ * an earlier run; nothing here can still invoke) -- and a skip never fails
+ * the ceremony.
+ */
+export interface GenerationDelegationRetirement {
+    revoked: string[];
+    replaced: boolean;
+    skipped?: 'no-pointer' | 'log-unreadable' | 'rung-uncommitted' | 'already-removed';
+}
+/**
+ * The other unlock methods' reach for the record re-mint stage: the registry
+ * entries to walk (the OTHER methods' -- the login credential's own record is
+ * the `onBeforeRemoval` seam's, re-wrapped with the credential in hand; an
+ * entry for it here is harmless but redundant), the unlock Spaces' storage
+ * server, the management-zcap client factory (invoking as the still-standing
+ * client), and the registry record-back seam. The shape is the revocation
+ * cascade's re-mint seams verbatim, so an app binds both from one place.
+ */
+export interface UnlockMethodsRemintReach<Entry extends RecoveryDelegationEntry = RecoveryDelegationEntry> {
+    entries: Entry[];
+    pointer: AccountPointer;
+    storageServerUrl: string;
+    managementZcapClient: (options: {
+        capability: IZcap;
+    }) => ZcapClient;
+    recordEntry: (options: {
+        entry: Entry;
+    }) => Promise<void>;
+}
+/**
+ * What a completed last-client forget reports: whether the install entry ran
+ * on this call (`false` on a resumed run), whether the roster's wrap for the
+ * forgotten client was retired on this run, the per-collection fan-out
+ * result, the generation stage's report, the other unlock methods' record
+ * re-mint report (present when the caller supplied the reach: the counts and
+ * every entry's fate; a completed ceremony never carries a `failed` outcome,
+ * since that refuses the removal entry instead), the document as the removal
+ * entry left it, and -- when the account has a roster -- the rotated key with
+ * the roster descriptor it was read from.
+ */
+export interface LastDurableClientForgetResult {
+    installed: boolean;
+    rotated: boolean;
+    collections: UserKeyCascadeResult;
+    generation: GenerationDelegationRetirement;
+    unlockMethods?: {
+        reminted: number;
+        skipped: number;
+        outcomes: RecordRemintOutcome[];
+    };
+    did: string;
+    document: object;
+    userKey?: UserKey;
+    rosterDescriptor?: CollectionEncryption;
+}
+/**
+ * The record re-mint stage could not reach every other unlock method's
+ * record, so the removal entry was refused: `failed` names the entries whose
+ * re-mint threw (each carrying its cause), and `unlockMethods` is the whole
+ * stage report. The forgotten client is still enrolled and every stage
+ * before this one has landed, so a re-run resumes at the re-mint. Matched
+ * on `name` (the errors cross app-injected seams that may resolve to another
+ * copy of this package).
+ */
+export declare class RecordRemintFailedError extends Error {
+    readonly failed: RecordRemintOutcome[];
+    readonly unlockMethods: NonNullable<LastDurableClientForgetResult['unlockMethods']>;
+    constructor({ unlockMethods }: {
+        unlockMethods: NonNullable<LastDurableClientForgetResult['unlockMethods']>;
+    });
+}
+/**
+ * Forgets the account's LAST enrolled durable client -- this browser's own
+ * -- transitioning the account to the client-less, ladder-anchored state.
+ * See the module doc for the stage order and the torn-state map. The caller
+ * runs the local wipe only after this resolves. An account with another
+ * enrolled durable client refuses: that forget is the ordinary ceremony
+ * (`forgetDurableClient`), reached first, whose `LastDurableClientForgetError`
+ * is what routes callers here.
+ *
+ * @param options {object}
+ * @param options.logStore {UnlockLogStore}   the credential's delegated
+ *   `did.jsonl` bridge store; also serves the ceremony's public reads. The
+ *   caller is expected to have verified the account log under its own
+ *   chain-head pins in the same session (the ceremony re-reads through the
+ *   seam and checks `expectedDid`, but carries no account-log pin store
+ *   itself)
+ * @param options.ladderSeed {Uint8Array}   the login credential's ladder seed
+ * @param options.forgottenClient {RevokedClientKeys}   this client's public
+ *   halves; an `updateKeyMultibase` the log does not authorize (stale, or the
+ *   staged key) is re-derived from the log
+ * @param options.forgottenKeyAgreementKeyMultibase {string}   this client's
+ *   identity key-agreement key (the X25519 twin), naming its roster wrap
+ * @param [options.knownLatentHashes] {string[]}   standing latent commitments
+ *   the caller vouches for (the recovery registry's update-key hashes),
+ *   excluded from the staged-hash attribution
+ * @param options.expectedDid {string}   the account DID from the caller's
+ *   stored account pointer
+ * @param options.rosterStoreFor {Function}   `({ did, log }) => store` --
+ *   builds the `key-map/user-key.jsonl` roster store whose appends are
+ *   SIGNED BY THE LADDER VM and whose controller view resolves from the
+ *   supplied post-install log (the posture-changing anchor the ceremony-tail
+ *   license admits), while its HTTP requests invoke under the still-standing
+ *   client
+ * @param options.credentialKeyAgreementKey {IKeyAgreementKey}   the standing
+ *   credential's key-agreement key -- the recipient whose wrap survives the
+ *   rotation, reading the fresh key back and unwrapping the generations for
+ *   the fan-out
+ * @param [options.userKey] {UserKey}   this client's cached user key
+ * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
+ *   roster epoch
+ * @param [options.onUserKeyAdopted] {Function}   persists a rotated key:
+ *   called with `{ userKey, latestEpochId, descriptor }` after the roster
+ *   read and BEFORE the fan-out
+ * @param options.collections {CascadeCollections}   the fan-out's work
+ * @param options.annex {object}   the generation stage's reach:
+ * @param options.annex.storeFor {Function}
+ *   `({ spaceId, generationId }) => ClientAnnexWriteStore` -- the pointed
+ *   generation's log store, reading and writing under the still-standing
+ *   client's authority
+ * @param options.annex.revoke {Function}   `(delegation) => Promise<void>`
+ *   -- POSTs a revocation (was-client's `WasClient#revoke`, bound by the
+ *   caller; the invocation signs as the still-standing client)
+ * @param options.annex.wasServerUrl {string}   the ACCOUNT Space's storage
+ *   server (the fresh generation delegation's target host)
+ * @param options.annex.accountSpaceId {string}   the ACCOUNT Space's id (the
+ *   fresh delegation's target subtree)
+ * @param [options.annex.pinStore] {ResourceLogPinStore}   chain-head pins
+ *   for the pointed generation's read
+ * @param [options.unlockMethods] {UnlockMethodsRemintReach}   the other
+ *   unlock methods' record re-mint reach (stage 5): the registry entries
+ *   whose bridge (and sibling) the ladder VM re-signs and whose records it
+ *   re-seals through their management zcaps, invoked as the still-standing
+ *   client. Omitted, the stage is skipped and the result carries no
+ *   `unlockMethods` report -- the residue decision 0004's amendment stated.
+ *   Supplied, an entry the pass could not re-mint refuses the removal entry
+ *   (`RecordRemintFailedError`)
+ * @param [options.onBeforeRemoval] {Function}
+ *   `({ did, doc, log }) => Promise<void>` -- the record re-bind seam: runs
+ *   after the record re-mint stage, immediately before the removal entry,
+ *   with the post-install published state. The caller re-signs the login
+ *   credential's bridge and `delegatedClients` sibling with the ladder VM
+ *   and re-seals its unlock record here. Must be idempotent (a resumed run
+ *   invokes it again)
+ * @param [options.now] {number}   epoch milliseconds, for tests
+ * @returns {Promise<LastDurableClientForgetResult>}
+ */
+export declare function forgetLastDurableClient({ logStore, ladderSeed, forgottenClient, forgottenKeyAgreementKeyMultibase, knownLatentHashes, expectedDid, rosterStoreFor, credentialKeyAgreementKey, userKey, pinnedEpochId, onUserKeyAdopted, collections, annex, unlockMethods, onBeforeRemoval, now }: {
+    logStore: UnlockLogStore;
+    ladderSeed: Uint8Array;
+    forgottenClient: RevokedClientKeys;
+    forgottenKeyAgreementKeyMultibase: string;
+    knownLatentHashes?: string[];
+    expectedDid: string;
+    rosterStoreFor: (options: {
+        did: string;
+        log: DIDLog;
+    }) => EncryptionDescriptorStore;
+    credentialKeyAgreementKey: IKeyAgreementKey;
+    userKey?: UserKey;
+    pinnedEpochId?: string | null;
+    onUserKeyAdopted?: (adopted: {
+        userKey: UserKey;
+        latestEpochId: string;
+        descriptor: CollectionEncryption;
+    }) => Promise<void>;
+    collections: CascadeCollections;
+    annex: {
+        storeFor: (options: {
+            spaceId: string;
+            generationId: string;
+        }) => ClientAnnexWriteStore;
+        revoke: (delegation: IDelegatedZcap) => Promise<void>;
+        wasServerUrl: string;
+        accountSpaceId: string;
+        pinStore?: ResourceLogPinStore;
+    };
+    unlockMethods?: UnlockMethodsRemintReach;
+    onBeforeRemoval?: (published: {
+        did: string;
+        doc: object;
+        log: DIDLog;
+    }) => Promise<void>;
+    now?: number;
+}): Promise<LastDurableClientForgetResult>;
+//# sourceMappingURL=forgetLast.d.ts.map

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

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