@interop/wallet-core 0.49.0 → 0.50.0

package/dist/clientAnnex/index.js

@@ -0,0 +1,60 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/clientAnnex` subpath: the client annex -- the
+ * authoring and maintenance surface of everything anchored on a standing
+ * credential's ladder rather than on an enrolled durable client. One boundary
+ * rule holds throughout: this subpath imports from the base subpaths;
+ * nothing in the base imports from it (enforced in the lint pass, with one
+ * pinned exception -- `unlock/standingWebvh.ts` uses the shared ladder
+ * attribution helpers here, never the annex log machinery). The verify-side
+ * halves every wallet needs regardless of posture stay in the base: the
+ * resource-log ladder-append license and `ControllerPosture` ladder-key
+ * computation (`resourceLog`), `ladderVmIds` recognition (`webvh`), the
+ * unlock-record codec with its `ladder` and `delegatedClients` members
+ * (`unlock`), the standing-zcap staleness policy and the generalized log
+ * store seams (`webvh`), and the `GenerationCollect` activity builder
+ * (`space`).
+ *
+ * - The ladder (`ladder.ts`): rung and ladder-VM derivation from the record's
+ *   random seed, and the shared attribution walks (`attributeLadderRung`,
+ *   `attributeLadderPosture`) that recover the ladder's state from the
+ *   published log itself.
+ * - The annex log (`log.ts`) and its GC (`gc.ts`): the disposable sidecar
+ *   did:webvh of GC'd generations holding transient per-visit verification
+ *   methods, the generation delegation, the account document's
+ *   `#DelegatedClients` pointer, and the quarterly swap-and-collect.
+ * - ZCap signing as the ladder VM (`zcap.ts`): `ladderVmZcapClient` and the
+ *   bootstrap `ladderVmAgent`.
+ * - The ladder-anchored account-log ceremonies (`ladderAnchored.ts`):
+ *   ladder-anchored genesis, the self-enrolling continuation, the one-entry
+ *   forget -- plus the composed flows around them (`selfEnroll.ts`,
+ *   `forget.ts`), the credential-anchored account genesis
+ *   (`credentialAnchoredGenesis.ts`), and the transient-recovery
+ *   continuation (`recoveryLadderAnchored.ts`).
+ *
+ * The subsystem's decision records are the subpath's reading list:
+ * `decisions/0002` (annex log update authority is static rung 0),
+ * `decisions/0003` (generation identity and the ladder HKDF label family),
+ * `decisions/0005` (the `delegatedClients` sealed record member),
+ * `decisions/0006` (generation GC observables and the `GenerationCollect`
+ * digest), and `decisions/0007` (the reveal entry's hash order).
+ */
+export { attributeLadderPosture, attributeLadderRung, clientAnnexRung, clientAnnexRungSeed, generateLadderSeed, LADDER_MAX_SCAN, LadderAttributionError, ladderRung, ladderRungSeed, ladderVmKeyMultibase, ladderVmSeed } from './ladder.js';
+export { assertGenerationId, clampGrantExpires, CLIENT_ANNEX_SPACE_TYPE, clientAnnexDidParts, clientAnnexLogPinId, clientAnnexLogStore, ClientAnnexRungUncommittedError, commitClientAnnexRung, createClientAnnexLog, DELEGATED_CLIENTS_DELEGATION_ACTIONS, DELEGATED_CLIENTS_DELEGATION_TTL_MS, DELEGATED_CLIENTS_SERVICE_TYPE, delegatedClientsDelegationMinter, delegatedClientsDelegationSpaceId, delegatedClientsPointer, delegatedClientsServiceEntry, embeddedGenerationDelegation, enrollClientAnnexTransientClient, enrollTransientClient, ensureClientAnnexSpace, ensureGenerationDelegationCurrent, GENERATION_DELEGATION_ACTIONS, GENERATION_DELEGATION_SERVICE_TYPE, GENERATION_DELEGATION_TTL_MS, GENERATION_ID_PREFIX, generationDelegationHistory, generationDelegationServiceEntry, mintClientAnnexGeneration, mintCredentialClientAnnexGeneration, mintDelegatedClientsDelegation, mintGenerationDelegation, mintGenerationId, retireClientAnnexRung, revokeTreatingAlreadyRevokedAsSuccess, servicesPointedAtClientAnnex, setDelegatedClientsPointer } from './log.js';
+export { clientAnnexGcDue, delegatedClientsPointerEstablishedAt, GENERATION_GC_PERIOD_MS, GENERATION_QUIET_BOUND_MS, GENERATION_QUIET_GRACE_MS, generationQuiet, runClientAnnexGc, swapClientAnnexGeneration } from './gc.js';
+export { ladderVmAgent, ladderVmZcapClient } from './zcap.js';
+export { createLadderAnchoredAccountLog, ensureLadderAnchoredDidWebvh, forgetLastWebvhClient, forgetWebvhClient, installLadderVmWebvh, LastDurableClientForgetError, selfEnrollWebvhClient } from './ladderAnchored.js';
+export { selfEnrollClientCore } from './selfEnroll.js';
+export { forgetDurableClient } from './forget.js';
+export { forgetLastDurableClient } from './forgetLast.js';
+export { ensureCredentialAnchoredAccountGenesis, mintCredentialAnchoredAccountKeySet } from './credentialAnchoredGenesis.js';
+export { recoverWebvhLadderAnchored } from './recoveryLadderAnchored.js';
+// The ladder VM's pure document builder and the ladder-anchored genesis log
+// assembly stay defined in `webvh/didWebvh.ts` (the genesis document
+// builder's two-armed clientKeys XOR ladderVm signature is base API, and the
+// ladder arm calls `ladderVerificationMethod` internally), but this subpath
+// is their public home.
+export { createLadderAnchoredWebvhLog, ladderVerificationMethod } from '../webvh/didWebvh.js';
+//# sourceMappingURL=index.js.map

package/dist/clientAnnex/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/clientAnnex/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,UAAU,EACV,cAAc,EACd,oBAAoB,EACpB,YAAY,EACb,MAAM,aAAa,CAAA;AAOpB,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,uBAAuB,EACvB,mBAAmB,EACnB,mBAAmB,EACnB,mBAAmB,EACnB,+BAA+B,EAC/B,qBAAqB,EACrB,oBAAoB,EACpB,oCAAoC,EACpC,mCAAmC,EACnC,8BAA8B,EAC9B,gCAAgC,EAChC,iCAAiC,EACjC,uBAAuB,EACvB,4BAA4B,EAC5B,4BAA4B,EAC5B,gCAAgC,EAChC,qBAAqB,EACrB,sBAAsB,EACtB,iCAAiC,EACjC,6BAA6B,EAC7B,kCAAkC,EAClC,4BAA4B,EAC5B,oBAAoB,EACpB,2BAA2B,EAC3B,gCAAgC,EAChC,yBAAyB,EACzB,mCAAmC,EACnC,8BAA8B,EAC9B,wBAAwB,EACxB,gBAAgB,EAChB,qBAAqB,EACrB,qCAAqC,EACrC,4BAA4B,EAC5B,0BAA0B,EAC3B,MAAM,UAAU,CAAA;AAGjB,OAAO,EACL,gBAAgB,EAChB,oCAAoC,EACpC,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,eAAe,EACf,gBAAgB,EAChB,yBAAyB,EAC1B,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AAE7D,OAAO,EACL,8BAA8B,EAC9B,4BAA4B,EAC5B,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,4BAA4B,EAC5B,qBAAqB,EACtB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAEtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAGjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAOzD,OAAO,EACL,sCAAsC,EACtC,mCAAmC,EACpC,MAAM,gCAAgC,CAAA;AAEvC,OAAO,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAExE,4EAA4E;AAC5E,qEAAqE;AACrE,6EAA6E;AAC7E,4EAA4E;AAC5E,wBAAwB;AACxB,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACzB,MAAM,sBAAsB,CAAA"}

package/dist/{unlock → clientAnnex}/ladder.d.ts

@@ -1,8 +1,4 @@
-/**
- * The byte length of a ladder seed: 32 random bytes, minted at bind time and
- * carried only inside the unlock record's sealed ladder member.
- */
-export declare const LADDER_SEED_BYTES = 32;
+import type { DIDLog } from '@interop/did-method-webvh';
 /**
  * How many rungs {@link attributeLadderRung} derives before concluding the
  * log commits none of them. Generous: one rung is consumed per
@@ -65,7 +61,7 @@ export declare 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
- * client-less window's document-visible authority (`assertionMethod` and
+ * ladder-anchored window's document-visible authority (`assertionMethod` and
  * `capabilityDelegation`), while update authority stays on the rungs -- the
  * two roles never share a key.
  *
@@ -94,17 +90,17 @@ export declare function ladderVmKeyMultibase({ ladderSeed }: {
     ladderSeed: Uint8Array;
 }): Promise<string>;
 /**
- * Derives the 32-byte update-key seed of a companion generation's rung 0 --
- * the credential's STATIC update key on that generation's companion log. The
+ * Derives the 32-byte update-key seed of an annex generation's rung 0 --
+ * the credential's STATIC update key on that generation's annex log. The
  * sequence is domain-separated per generation by the generation id
  * (`<generationId>/rung/0` under the one {@link LADDER_SALT}): one shared
  * sequence
- * would hand the storage host, a legitimate reader of the private companion,
+ * would hand the storage host, a legitimate reader of the private annex,
  * a revealed key matching the ACCOUNT log's standing commitment, and a fresh
  * per-generation sequence is what makes GC replacement self-healing (no rung
  * index survives the deleted log, and none is needed).
  *
- * The generation id is trusted here rather than re-validated -- the companion
+ * The generation id is trusted here rather than re-validated -- the annex
  * ceremonies assert the `gen-<random>` shape (`assertGenerationId`)
  * before any derivation, and the label families stay disjoint for any
  * generation id regardless (an account-rung label carries exactly one
@@ -115,22 +111,22 @@ export declare function ladderVmKeyMultibase({ ladderSeed }: {
  * @param options.generationId {string}   the generation collection's name
  * @returns {Uint8Array}
  */
-export declare function companionRungSeed({ ladderSeed, generationId }: {
+export declare function clientAnnexRungSeed({ ladderSeed, generationId }: {
     ladderSeed: Uint8Array;
     generationId: string;
 }): Uint8Array;
 /**
- * Derives a companion generation's rung 0 in full: seed and public multibase.
- * Deliberately index-free -- the companion chain has length one, so there is
+ * Derives an annex generation's rung 0 in full: seed and public multibase.
+ * Deliberately index-free -- the annex chain has length one, so there is
  * no rung to advance to and no attribution scan to run (see
- * {@link companionRungSeed}).
+ * {@link clientAnnexRungSeed}).
  *
  * @param options {object}
  * @param options.ladderSeed {Uint8Array}
  * @param options.generationId {string}   the generation collection's name
  * @returns {Promise<{ seed: Uint8Array, keyMultibase: string }>}
  */
-export declare function companionRung({ ladderSeed, generationId }: {
+export declare function clientAnnexRung({ ladderSeed, generationId }: {
     ladderSeed: Uint8Array;
     generationId: string;
 }): Promise<{
@@ -175,4 +171,82 @@ export declare function attributeLadderRung({ ladderSeed, published, maxScan }:
     rung: LadderRung;
     state: LadderRungState;
 }>;
+/**
+ * Everything of one ladder that currently stands in the published log's
+ * parameters: the revealed rung keys still authorized in `updateKeys` and the
+ * committed hashes the ladder accounts for in `nextKeyHashes` -- including,
+ * for a torn self-enrollment, the hashes the reveal entry committed under the
+ * rung's authority for a client that was never published (its update- and
+ * staged-key hashes), which are as much a latent re-seizure credential as the
+ * rung's own commitment.
+ */
+export interface LadderStandingPosture {
+    revealedKeys: string[];
+    committedHashes: string[];
+}
+/**
+ * Attributes a ladder's FULL standing posture from the log -- the retirement
+ * counterpart of {@link attributeLadderRung}, which recovers only the single
+ * current rung. Retiring a credential must strike every standing artifact its
+ * ladder accounts for, so this walks the log's effective parameters forward
+ * from an anchor (the recorded bind-time rung, however stale) and tracks the
+ * ladder's footprint entry by entry:
+ *
+ * - a newly authorized key whose hash was a known ladder commitment is a rung
+ *   REVEAL; the hashes that entry newly commits are claimed by the ladder,
+ *   as are those of any later entry the ladder itself signed, since the
+ *   rung's authority stood behind them. Hashes an entry signed by some other
+ *   key commits stay OUT, even while the rung sits in `updateKeys`: a rung
+ *   stands revealed indefinitely after a forget (and after a torn
+ *   self-enrollment), and the account's enrolled clients go on extending the
+ *   log the whole time;
+ * - the entry that retires the revealed rung while authorizing a key whose
+ *   hash sits among those claims is the enrollment's COMPLETION: the new
+ *   client's update-key hash and the claim committed immediately after it
+ *   (its staged hash -- a reveal-and-commit entry appends the credential's
+ *   own next commitment LAST among its newly committed hashes, the ordering
+ *   convention in `decisions/0007-ladder-reveal-hash-order.md`) transfer to
+ *   the client and stop being ladder-owned. What the completion did not
+ *   transfer stays ladder-owned only where the ladder can say so POSITIVELY:
+ *   the hash derives from the ladder's own seed (or is the recorded key's),
+ *   or the credential itself survives the completing entry, which is what
+ *   makes the residue its next standing commitment. A SPEND -- the recovery
+ *   continuation, whose one entry retires the code's own posture and
+ *   publishes its successor's -- leaves the replacement credential's
+ *   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.
+ *
+ * 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
+ * posture names and nothing more. More than one ladder reveal standing or
+ * arriving at once matches no legitimate history and fails closed
+ * ({@link LadderAttributionError}).
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   a resolved, caller-verified log
+ * @param options.anchorKeyMultibase {string}   the credential's recorded
+ *   update-key multibase (bind-time rung 0, or a refreshed later rung)
+ * @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 posture goes in the same
+ *   entry)
+ * @param [options.maxScan] {number}   seeded pre-derivation bound; defaults to
+ *   {@link LADDER_MAX_SCAN}
+ * @returns {Promise<LadderStandingPosture>}   what currently stands; both
+ *   arrays empty when the log carries nothing of the ladder any more
+ */
+export declare function attributeLadderPosture({ log, anchorKeyMultibase, ladderSeed, credentialVmId, maxScan }: {
+    log: DIDLog;
+    anchorKeyMultibase: string;
+    ladderSeed?: Uint8Array;
+    credentialVmId?: string;
+    maxScan?: number;
+}): Promise<LadderStandingPosture>;
 //# sourceMappingURL=ladder.d.ts.map

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

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