@interop/wallet-core 0.49.0 → 0.50.0

package/dist/clientAnnex/ladderAnchored.d.ts

@@ -0,0 +1,276 @@
+import type { DIDDoc, DIDLog } from '@interop/did-method-webvh';
+import type { ClientWebvhUpdateKeys, WebvhEnrollmentKeys, WebvhIdStore } from '../webvh/didWebvh.js';
+import type { ResourceLogPinStore } from '../resourceLog/index.js';
+import { type RevokedClientKeys } from '../webvh/revokeClient.js';
+import { type UnlockKeyAgreementPublication, type UnlockLogStore } from '../unlock/standingWebvh.js';
+/**
+ * LADDER-ANCHORED GENESIS: assembles the one-entry did:webvh log of an account
+ * with zero enrolled durable clients, anchored on the minting credential's
+ * ladder alone. Everything derives from the ladder seed: rung 0 is the sole
+ * `updateKeys` member and signs the entry, `nextKeyHashes` commits rung 0's
+ * own carry-over hash plus rung 1 (the staged rung) -- the carry-over hash is
+ * what the first durable self-enrollment's reveal-and-commit entry,
+ * re-stating `updateKeys` containing rung 0, requires --
+ * and the ladder VM (the stable sibling) is published under `assertionMethod`
+ * and `capabilityDelegation` only. The credential's `keyAgreement` posture
+ * entry is FOLDED INTO GENESIS -- no enrolled client exists to run the
+ * separate bind entry ({@link publishUnlockKey}) -- so the genesis
+ * `keyAgreement` array holds only the credential's entry.
+ *
+ * The ladder-anchored window this opens is closed by the credential's first
+ * durable self-enrollment ({@link selfEnrollWebvhClient}), whose add entry
+ * atomically publishes the client, retires rung 0, and removes the ladder VM.
+ *
+ * The caller owns publication (conditional, create-only) and the pointer
+ * write that follows; this assembles and signs the log only.
+ *
+ * @param options {object}
+ * @param options.wasServerUrl {string}
+ * @param options.spaceId {string}
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
+ * @param options.keyAgreement {UnlockKeyAgreementPublication}   the
+ *   credential's key-agreement publication (commitment or verbatim)
+ * @returns {Promise<{ log: DIDLog, webDoc: object, did: string }>}
+ */
+export declare function createLadderAnchoredAccountLog({ wasServerUrl, spaceId, ladderSeed, keyAgreement }: {
+    wasServerUrl: string;
+    spaceId: string;
+    ladderSeed: Uint8Array;
+    keyAgreement: UnlockKeyAgreementPublication;
+}): Promise<{
+    log: DIDLog;
+    webDoc: object;
+    did: string;
+}>;
+/**
+ * LADDER-ANCHORED GENESIS AS AN ENSURE: probe, adopt, or create-and-publish --
+ * {@link createLadderAnchoredAccountLog} with the durable-flow `ensureDidWebvh`
+ * convention wrapped around it. The convergence rule is what makes signup a
+ * ceremony rather than a bare create: `createDID` timestamps the genesis
+ * entry, so a naive re-run of a torn signup mints a DIFFERENT SCID and its
+ * create-if-absent PUT can never land. So a published log is ADOPTED instead
+ * -- iff `attributeLadderRung` attributes its update parameters to this
+ * credential's ladder (rung revealed or committed; a foreign log fails
+ * closed with `LadderAttributionError` and is never built on).
+ *
+ * The publish is a conditional create-if-absent, so a concurrent signup's
+ * winner is adopted on the conflict re-run rather than erased. On the create
+ * path a supplied `pinStore` is written from the log this run minted (the
+ * account-log trust-on-first-use convention: the creator knows the true
+ * genesis); on the probe path the read itself carries the pin check.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}
+ * @param options.wasServerUrl {string}
+ * @param options.spaceId {string}
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
+ * @param options.keyAgreement {UnlockKeyAgreementPublication}   the
+ *   credential's key-agreement publication (commitment or verbatim)
+ * @param [options.expectedDid] {string}   the DID the published log must
+ *   resolve to, when the caller holds the account pointer; a heal login on a
+ *   fresh terminal legitimately holds none
+ * @param [options.pinStore] {ResourceLogPinStore}   this client's chain-head
+ *   pins; the account log's slot is keyed by `accountLogPinId` over the
+ *   `spaceId` above
+ * @returns {Promise<{ did: string }>}
+ */
+export declare function ensureLadderAnchoredDidWebvh(options: {
+    idStore: WebvhIdStore;
+    wasServerUrl: string;
+    spaceId: string;
+    ladderSeed: Uint8Array;
+    keyAgreement: UnlockKeyAgreementPublication;
+    expectedDid?: string;
+    pinStore?: ResourceLogPinStore;
+}): Promise<{
+    did: string;
+}>;
+/**
+ * SELF-ENROLLMENT (run by the credential-derived client through the delegated
+ * `did.jsonl` PUT): writes the standing continuation described in the module
+ * doc -- the reveal-and-commit entry signed by the attributed ladder rung,
+ * then the add entry signed by the new ordinary client's update key, which
+ * also retires the spent rung. Resumable from durable state alone: a
+ * completed continuation is detected by the new client's update key already
+ * being authorized (no-op), a torn one by the attribution finding the rung
+ * already revealed. Both entries publish conditionally on the read they were
+ * built on, and a race lost to a concurrent ceremony re-runs from the top --
+ * re-attributing, which is exactly the retry-up-the-ladder resolution.
+ *
+ * @param options {object}
+ * @param options.store {UnlockLogStore}   public log read + delegated PUT
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed, from
+ *   its unlock record
+ * @param options.newClientKeys {WebvhEnrollmentKeys}   the new ordinary
+ *   client's public halves
+ * @param options.newClientUpdateSeeds {ClientWebvhUpdateKeys}   the new
+ *   client's update-key seeds (minted by the self-enrolling flow, which
+ *   therefore holds them and can sign the add entry)
+ * @param [options.expectedDid] {string}   the account DID the log must resolve
+ *   to, from the credential-authenticated pointer
+ * @returns {Promise<{ did: string, webDoc?: object }>}   the account DID and,
+ *   when the add entry ran here, the final `did.json` projection for the
+ *   enrolled session to republish
+ */
+export declare function selfEnrollWebvhClient(options: {
+    store: UnlockLogStore;
+    ladderSeed: Uint8Array;
+    newClientKeys: WebvhEnrollmentKeys;
+    newClientUpdateSeeds: ClientWebvhUpdateKeys;
+    expectedDid?: string;
+}): Promise<{
+    did: string;
+    webDoc?: object;
+}>;
+/**
+ * Thrown when the client being forgotten is the account's LAST enrolled
+ * durable client. Removing it through this entry would leave the document
+ * with no client and no ladder verification method -- an account nothing can
+ * invoke for -- so that case is its own ceremony (the two-entry
+ * ladder-VM-install shape), and this primitive refuses rather than
+ * transitioning the account by accident.
+ *
+ * **`name` is a stable contract.** It is always the string
+ * `'LastDurableClientForgetError'`, and a consumer should match on that
+ * rather than on `instanceof`: a wallet app that links this package (or holds
+ * two copies of it through a dependency tree) gets a different class object
+ * for the same error, so `instanceof` silently fails there while the name
+ * does not.
+ */
+export declare class LastDurableClientForgetError extends Error {
+    constructor();
+}
+/**
+ * FORGET (run by the forgetting client itself, through the standing
+ * credential's bridge): removes THIS browser's enrolled client from the
+ * published document in ONE atomic ladder-signed entry -- self-enrollment in
+ * reverse, collapsed to a single entry because a removal reveals no new key.
+ * The signer is the credential's current ladder rung, recovered from the log
+ * itself ({@link attributeLadderRung}): its hash stands committed by the
+ * credential's posture (or the rung is already revealed), which is exactly
+ * what lets it reveal itself in the entry it signs under prerotation. The
+ * entry's members are the revocation removal's, verbatim
+ * (`clientRemovalTarget` / `clientRemovalFields`, shared with
+ * `revokeWebvhClient` so the two removal shapes cannot drift): the client's
+ * verification methods out of the document and all five relations, its update
+ * key out of `updateKeys`, and its carry-over and staged hashes out of
+ * `nextKeyHashes` -- plus the acting rung into `updateKeys` with its own hash
+ * kept committed (the carry-over convention).
+ *
+ * Atomicity is the point of the one-entry shape: no torn state exists where
+ * the rung is revealed and the client still stands. The honest residue is the
+ * acting rung itself -- no entry can remove its own signing key, so the rung
+ * stands REVEALED in `updateKeys` afterwards (the same standing state the
+ * ladder-anchored postures live in). That is credential-held authority, not
+ * the forgotten client's: only the ladder seed derives it, the credential's
+ * next self-enrollment consumes and retires it, and retiring the credential
+ * itself strikes it (`attributeLadderPosture`).
+ *
+ * Forgetting the LAST enrolled durable client is refused
+ * ({@link LastDurableClientForgetError}): that transition -- to the
+ * client-less, ladder-anchored state -- is its own two-entry ceremony.
+ *
+ * Idempotent: a client with no remaining presence is a no-op that returns the
+ * published state unchanged, so a naive re-run after a torn ceremony
+ * converges. The entry publishes conditionally on the log this call read; a
+ * lost race re-runs, re-attributes, and rebases on the winner's head.
+ *
+ * @param options {object}
+ * @param options.store {UnlockLogStore}   the credential's delegated
+ *   `did.jsonl` bridge store
+ * @param options.ladderSeed {Uint8Array}   the 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.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 the log must resolve
+ *   to, from the caller's stored account pointer
+ * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}   the account
+ *   DID and the document and log as the removal entry leaves them (unchanged
+ *   on the idempotent no-op path)
+ */
+export declare function forgetWebvhClient(options: {
+    store: UnlockLogStore;
+    ladderSeed: Uint8Array;
+    forgottenClient: RevokedClientKeys;
+    knownLatentHashes?: string[];
+    expectedDid?: string;
+}): Promise<{
+    did: string;
+    doc: DIDDoc;
+    log: DIDLog;
+}>;
+/**
+ * THE LAST-CLIENT REMOVAL ENTRY (the two-entry transition ceremony's second
+ * entry): {@link forgetWebvhClient}'s removal shape with the last-client
+ * refusal inverted -- the forgotten client IS the last enrolled durable
+ * client, and the account stays invocable because the ladder VM the install
+ * entry published ({@link installLadderVmWebvh}) remains in the document. A
+ * document NOT carrying this credential's ladder VM refuses: publishing the
+ * entry would strand the account with neither a durable client nor the
+ * ladder anchor. Run only from the composed ceremony
+ * (`forgetLastDurableClient`), which sequences the install entry and the
+ * delegation revocations before it.
+ *
+ * @param options {object}   see {@link forgetWebvhClient}
+ * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog }>}
+ */
+export declare function forgetLastWebvhClient(options: {
+    store: UnlockLogStore;
+    ladderSeed: Uint8Array;
+    forgottenClient: RevokedClientKeys;
+    knownLatentHashes?: string[];
+    expectedDid?: string;
+}): Promise<{
+    did: string;
+    doc: DIDDoc;
+    log: DIDLog;
+}>;
+/**
+ * THE LADDER-VM INSTALL ENTRY (the two-entry transition ceremony's first
+ * entry): publishes the credential's ladder VM -- the stable sibling, under
+ * `assertionMethod` and `capabilityDelegation` only -- while the last durable
+ * client's whole footprint stays untouched: the both-present transitional
+ * state the no-neither invariant permits. The entry is ladder-signed by the
+ * attributed rung, which reveals itself into `updateKeys` with its own hash
+ * kept committed (the carry-over convention), exactly the removal entry's
+ * rung math -- so a torn ceremony's re-run re-attributes the now-revealed
+ * rung and carries on.
+ *
+ * This entry is what makes the transition's document version POSTURE-CHANGING
+ * under the ceremony-tail license (the ladder-VM set gains a member), so the
+ * ceremony's ONE ladder-signed roster append anchors here -- and it is what
+ * lets the delegation revocations that follow verify their ladder-signed
+ * chains against the currently resolved document while the still-standing
+ * client signs the invocations.
+ *
+ * Idempotent: a document already carrying this credential's ladder VM (by
+ * the relation-asymmetry recognition) returns unchanged with
+ * `installed: false`. The entry publishes conditionally on the log this call
+ * read; a lost race re-runs, re-attributes, and rebases on the winner's
+ * head.
+ *
+ * @param options {object}
+ * @param options.store {UnlockLogStore}   the credential's delegated
+ *   `did.jsonl` bridge store
+ * @param options.ladderSeed {Uint8Array}   the credential's ladder seed
+ * @param [options.expectedDid] {string}   the account DID the log must resolve
+ *   to, from the caller's stored account pointer
+ * @returns {Promise<{ did: string, doc: DIDDoc, log: DIDLog, installed: boolean }>}
+ *   the account DID and the document and log as the install entry leaves them
+ *   (unchanged on the idempotent no-op path); `installed` says whether the
+ *   entry ran on this call
+ */
+export declare function installLadderVmWebvh(options: {
+    store: UnlockLogStore;
+    ladderSeed: Uint8Array;
+    expectedDid?: string;
+}): Promise<{
+    did: string;
+    doc: DIDDoc;
+    log: DIDLog;
+    installed: boolean;
+}>;
+//# sourceMappingURL=ladderAnchored.d.ts.map

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

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