@interop/wallet-core 0.48.0 → 0.50.0

package/dist/clientAnnex/gc.d.ts

@@ -0,0 +1,255 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * Client-annex GC: the quarterly wholesale replacement of the annex
+ * generation, and the collection of everything it leaves behind.
+ *
+ * The ceremony has two halves with different rhythms:
+ *
+ * - The SWAP runs on the fixed quarterly cadence (90 days, at the first
+ *   durable login after the period elapses -- coarse on purpose, so the
+ *   account log's permanent pointer-entry rhythm reveals little about
+ *   transient-use frequency), and only when the pointed generation is
+ *   GC-quiet (the 24-hour max-visit quiet bound over its newest entry's
+ *   `versionTime`, with a skew-margin grace hour -- a deferral policy only,
+ *   never a session expiry). Its stage order is fixed: mint + genesis,
+ *   install the fresh generation's delegation service entry, revoke the old
+ *   generation's delegation, re-point the account document. Revoke lands
+ *   before the re-point (closing the window where a fail-open non-conforming
+ *   server still honors the old delegation -- and the revocation POST itself
+ *   only verifies while the pointer still makes the old chain resolve), and
+ *   before the delete (the POST needs the capability bytes the delete
+ *   destroys).
+ *
+ * - The COLLECT fan-out is predicate-driven and runs at every durable login:
+ *   every `gen-` collection the pointer does not name -- the generation a
+ *   swap just superseded, a torn GC's leftover, a torn signup's orphan, a
+ *   double-genesis loser -- gets identical treatment (revoke its embedded
+ *   delegation blind, reading the server's 400 already-revoked answer as
+ *   success; write the digest; delete), so a GC torn anywhere resumes at the
+ *   next login instead of waiting a quarter. Failures are collected per
+ *   generation and never abort the fan-out: a partial pass is a resumable
+ *   success.
+ *
+ * The completion predicate is durable state alone (exactly one `gen-`
+ * collection exists in the auxiliary Space and it is the one the pointer
+ * names); no marker resource exists anywhere -- the account document's
+ * pointer-update entry is the record, and the cadence is read off its
+ * `versionTime`. The digest (`GenerationCollect`, built by the caller's
+ * `recordDigest` over `@interop/wallet-core/space`'s builder) is written
+ * before the delete: it is the owner's only record of the collected window's
+ * visits surviving the delete, and compromise detection ends at digest
+ * granularity.
+ *
+ * Honest limitations: the "no unexpired delegation names a dead generation"
+ * conjunct is an ordering obligation, not a check (the revocation protocol
+ * exposes no read endpoint, and the dead generation's delegation bytes are
+ * destroyed with its collection); orphaned generations are
+ * authorization-inert (no delegation ever names an unpointed generation
+ * under pointer equality), so what accretes between passes is a storage
+ * leak, never an authority leak.
+ */
+import type { DIDLog } from '@interop/did-method-webvh';
+import type { ZcapClient } from '@interop/ezcap';
+import type { WasClient } from '@interop/was-client';
+import type { ResourceLogPinStore } from '../resourceLog/pin.js';
+import type { ClientWebvhUpdateKeys, PublishedWebvhLog, WebvhIdStore } from '../webvh/didWebvh.js';
+/**
+ * The fixed GC cadence: a generation is replaced at the first durable login
+ * 90 days after the current pointer value was established. Wallet GC policy
+ * over the account log's own timestamps, never a stored or wire value.
+ */
+export declare const GENERATION_GC_PERIOD_MS: number;
+/**
+ * The quiet bound: a generation is GC-quiet when its newest entry's
+ * `versionTime` is over 24 hours old. The bound defers the swap only; it
+ * never expires a session. A visit outliving it merely loses guaranteed
+ * guard protection, and in the rare case a quarterly pass lands on one, the
+ * session's next authorization failure maps to the generation-lapse retry
+ * state.
+ */
+export declare const GENERATION_QUIET_BOUND_MS: number;
+/**
+ * The skew-margin grace floor on the quiet bound: three clocks meet at the
+ * guard check (the enrolling writer's, any prior entry writer's, and the
+ * GC-running client's), and `versionTime` is asserted by the writer's clock,
+ * so the guard compares against the bound plus this margin. An hour is
+ * generous against real-world skew and defers the swap by at most an hour
+ * against a quarterly cadence.
+ */
+export declare const GENERATION_QUIET_GRACE_MS: number;
+/**
+ * The `versionTime` of the account-log entry that established the CURRENT
+ * `#DelegatedClients` pointer value: the newest entry whose state names a
+ * different annex DID than the entry before it (or the first entry, when
+ * the pointer has been there since genesis). This is the cadence's clock --
+ * "the pointer-update entry is the record" -- and it is read off the log a
+ * durable login has already verified, so the cadence costs no extra fetch
+ * and every enrolled client agrees on it.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   the VERIFIED account log
+ * @returns {string | undefined}   the establishing entry's `versionTime`,
+ *   or undefined when no entry carries a pointer
+ */
+export declare function delegatedClientsPointerEstablishedAt({ log }: {
+    log: DIDLog;
+}): string | undefined;
+/**
+ * Whether the quarterly swap is due: the current pointer value was
+ * established {@link GENERATION_GC_PERIOD_MS} or more ago. A log with no
+ * pointer is never due (there is no generation to replace).
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   the VERIFIED account log
+ * @param [options.now] {number}   epoch milliseconds, for tests
+ * @returns {boolean}
+ */
+export declare function clientAnnexGcDue({ log, now }: {
+    log: DIDLog;
+    now?: number;
+}): boolean;
+/**
+ * The live-entry guard: whether a generation is GC-quiet -- its newest
+ * entry's `versionTime` is older than the quiet bound plus the skew grace
+ * margin. Applies to the POINTED generation only (an unpointed generation
+ * authorizes nothing under pointer equality, so nothing inside it ever
+ * defers deletion). An unparseable `versionTime` reads as not quiet: the
+ * swap defers rather than abandoning a possibly-live visit.
+ *
+ * @param options {object}
+ * @param options.log {DIDLog}   the pointed generation's VERIFIED annex
+ *   log
+ * @param [options.now] {number}   epoch milliseconds, for tests
+ * @returns {boolean}
+ */
+export declare function generationQuiet({ log, now }: {
+    log: DIDLog;
+    now?: number;
+}): boolean;
+/**
+ * What the swap half of one GC pass did. `replaced` is the successful swap;
+ * `not-due` and `deferred-live` are the two healthy skips (cadence and quiet
+ * bound); `no-pointer` means the account has no annex posture (the whole
+ * pass no-ops -- without a pointer there is no auxiliary Space to list);
+ * `no-ladder-seed` means the swap was due but the login held no ladder seed
+ * to mint with (a non-standing record); `failed` means a swap stage threw --
+ * reported in `failed` under the pointed generation's id, with the collect
+ * fan-out still run.
+ */
+export type ClientAnnexGcSwapOutcome = 'replaced' | 'not-due' | 'deferred-live' | 'no-pointer' | 'no-ladder-seed' | 'failed';
+/**
+ * One GC pass's report: the swap outcome, the annex DID the account
+ * points at after the pass, the generation ids collected (revoked, digested,
+ * deleted), and the per-generation failures. A report with `failed` entries
+ * is a resumable success -- the next durable login's pass picks up exactly
+ * the generations still listed.
+ */
+export interface ClientAnnexGcReport {
+    swap: ClientAnnexGcSwapOutcome;
+    pointedDid?: string;
+    collected: string[];
+    failed: Array<{
+        generationId: string;
+        error: unknown;
+    }>;
+}
+/**
+ * One annex GC pass: the quarterly swap when due and quiet, then the
+ * predicate-driven collect fan-out over every non-pointed `gen-` collection.
+ * See the module header for the stage order and its load-bearing constraints.
+ *
+ * Convergence: every stage detects completion from durable state. A re-run
+ * after a tear re-POSTs the revocation blind (400 already-revoked reads as
+ * success), re-writes the digest (the deterministic payload id collapses the
+ * second row at read time), and re-runs the idempotent delete; a swap torn
+ * before its re-point leaves an unpointed fresh generation the same fan-out
+ * collects.
+ *
+ * @param options {object}
+ * @param options.was {WasClient}   the storage client, signing as an
+ *   enrolled client (root tier on both the account and auxiliary Spaces)
+ * @param options.wasServerUrl {string}   the account pointer's host
+ * @param options.accountSpaceId {string}   the ACCOUNT Space's id (the
+ *   generation delegation's target subtree)
+ * @param options.account {object}   the VERIFIED account log
+ *   (`{ did, doc, log }` -- `verifyAccountLog`'s shape)
+ * @param options.idStore {WebvhIdStore}   the account log's id store, for
+ *   the re-point
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   this enrolled client's
+ *   update keys, signing the re-point entry
+ * @param options.zcapClient {ZcapClient}   signs the fresh generation
+ *   delegation (the promoted account keyId)
+ * @param [options.ladderSeed] {Uint8Array}   the login credential's ladder
+ *   seed; absent, a due swap reports `no-ladder-seed` and only the collect
+ *   fan-out runs
+ * @param options.recordDigest {Function}
+ *   `({ generationId, firstEntry, lastEntry, entryCount }) => Promise<void>`
+ *   -- writes the GenerationCollect wallet-activity row; called before the
+ *   delete, and a throw keeps the generation for the next pass
+ * @param [options.onCollected] {Function}
+ *   `({ generationId }) => Promise<void>` -- local cleanup after a
+ *   generation's delete (the caller's annex pin-slot drop); a throw is
+ *   reported but cannot be retried (the collection is already gone)
+ * @param [options.pinStore] {ResourceLogPinStore}   chain-head pins for the
+ *   account-log re-point and the pointed generation's read
+ * @param [options.now] {number}   epoch milliseconds, for tests
+ * @returns {Promise<ClientAnnexGcReport>}
+ */
+export declare function runClientAnnexGc({ was, wasServerUrl, accountSpaceId, account, idStore, updateKeys, zcapClient, ladderSeed, recordDigest, onCollected, pinStore, now }: {
+    was: WasClient;
+    wasServerUrl: string;
+    accountSpaceId: string;
+    account: Pick<PublishedWebvhLog, 'did' | 'doc' | 'log'>;
+    idStore: WebvhIdStore;
+    updateKeys: ClientWebvhUpdateKeys;
+    zcapClient: ZcapClient;
+    ladderSeed?: Uint8Array;
+    recordDigest: (digest: {
+        generationId: string;
+        firstEntry?: string;
+        lastEntry?: string;
+        entryCount?: number;
+    }) => Promise<void>;
+    onCollected?: (options: {
+        generationId: string;
+    }) => Promise<void>;
+    pinStore?: ResourceLogPinStore;
+    now?: number;
+}): Promise<ClientAnnexGcReport>;
+/**
+ * AN OFF-CADENCE GENERATION SWAP: replaces the pointed annex generation
+ * outside the quarterly rhythm -- the credential-rotation ceremony's
+ * fallback when no distinct committed rung can sign a strike entry
+ * (`retireClientAnnexRung`): a fresh generation minted from a SURVIVING
+ * credential's seed commits only that credential's rung-0 hash, so the
+ * retired credential's annex posture dies with the whole generation the
+ * moment the re-point lands. The abandoned generation is an ordinary
+ * non-pointed `gen-` collection the standing collect fan-out picks up at the
+ * next durable login.
+ *
+ * Same four swap stages and ordering as the quarterly GC swap, minus the
+ * cadence and quiet gates (the caller's reason for swapping is authority
+ * removal, not hygiene). The pointed generation's log is read for the revoke
+ * stage's delegation bytes; unreadable, the revoke is skipped and pointer
+ * equality retires the old delegation on a conforming server.
+ *
+ * @param options {object}   see {@link runClientAnnexGc} for the shared
+ *   members ({ was, wasServerUrl, accountSpaceId, account, idStore,
+ *   updateKeys, zcapClient, pinStore }); `ladderSeed` here is the SURVIVING
+ *   credential's seed the fresh generation is minted from
+ * @returns {Promise<string>}   the fresh annex DID
+ */
+export declare function swapClientAnnexGeneration({ was, wasServerUrl, accountSpaceId, account, idStore, updateKeys, zcapClient, ladderSeed, pinStore }: {
+    was: WasClient;
+    wasServerUrl: string;
+    accountSpaceId: string;
+    account: Pick<PublishedWebvhLog, 'did' | 'doc'>;
+    idStore: WebvhIdStore;
+    updateKeys: ClientWebvhUpdateKeys;
+    zcapClient: ZcapClient;
+    ladderSeed: Uint8Array;
+    pinStore?: ResourceLogPinStore;
+}): Promise<string>;
+//# sourceMappingURL=gc.d.ts.map

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

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