@interop/wallet-core 0.14.0 → 0.16.0

package/README.md

@@ -80,7 +80,16 @@ The subpaths:
   state alone, history escrowed -- also the completion sweep's building block),
   plus the detector that converges a roster left wrapping the current key to a
   recipient the account document no longer keys. Also the enrolled-client
-  display labels (`key-map/client-labels.json`) and their WAS-backed store.
+  display labels (`key-map/client-labels.json`) and their WAS-backed store. Also
+  the client-key record codec: the contents and strict validation of the local
+  record each wallet client keeps its own key material in (storage and wrapping
+  stay app-side).
+
+- **`@interop/wallet-core/clients`** -- the enrolled-client management surface:
+  the listing over the locally verified did:webvh log with display labels
+  merged, the disconnect-eligibility policy as pure functions, the revocation
+  cascade orchestrator (document edit, roster rotation, collection fan-out,
+  optional recovery re-mints), and the login-time roster policy.
 
 - **`@interop/wallet-core/descriptors`** -- collection encryption-descriptor
   acquisition (fetch / cache / offline fallback) and the unknown-epoch refresh
@@ -129,9 +138,9 @@ import {
 
 The `sync` and `space` subpaths are re-exported from the package root as well.
 Every other subpath (`identity`, `request`, `display`, `webvh`, `keys`,
-`descriptors`, `keyring`, `enrollment`, `recovery`) is import-directly-only, so
-consumers of the root never pull the signing / KMS / document-loader dependency
-graph.
+`clients`, `descriptors`, `keyring`, `enrollment`, `recovery`) is
+import-directly-only, so consumers of the root never pull the signing / KMS /
+document-loader dependency graph.
 
 ## Contribute
 

package/dist/clients/index.d.ts

@@ -0,0 +1,32 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/clients` subpath: the enrolled-client management
+ * surface -- the place "disconnect this wallet" lives -- and the cascades
+ * behind it.
+ *
+ * - `listAccountClients` / `currentAccountSigningKeys` -- the listing over the
+ *   locally verified did:webvh log, with display labels merged, and the same
+ *   read reduced to the key set an app grant's delegation signer is checked
+ *   against. Both take an already-verified log in place of fetching one.
+ * - `disconnectEligibility` / `revokedClientKeysFor` / `cascadeCompletion` --
+ *   the disconnect-eligibility policy as data and pure functions, so both
+ *   surfaces refuse the same rows for the same reasons and report a partial
+ *   fan-out as the resumable success it is.
+ * - `revokeAccountClient` -- the revocation cascade in dependency order
+ *   (document edit, roster rotation, collection fan-out, optional recovery
+ *   re-mints), with the app-specific stages injected.
+ * - `checkPukRosterAtLogin` / `convergePukRosterToAccount` -- the login-time
+ *   roster policy: which roster failures refuse a session, and the standing
+ *   convergence of the roster onto the account document.
+ */
+export { currentAccountSigningKeys, listAccountClients } from './listing.js';
+export type { AccountClientView, AccountLogPointer, VerifiedAccountLog } from './listing.js';
+export { cascadeCompletion, disconnectEligibility, revokedClientKeysFor } from './policy.js';
+export type { DisconnectRefusal } from './policy.js';
+export { revokeAccountClient } from './revocation.js';
+export type { CascadeCollections, ClientRevocationResult } from './revocation.js';
+export { checkPukRosterAtLogin, convergePukRosterToAccount } from './rosterPolicy.js';
+export type { AdoptedPuk } from './rosterPolicy.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/clients/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAC5E,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EACnB,MAAM,cAAc,CAAA;AAErB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AACrD,YAAY,EACV,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,iBAAiB,CAAA;AAExB,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC3B,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/clients/index.js

@@ -0,0 +1,28 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The `@interop/wallet-core/clients` subpath: the enrolled-client management
+ * surface -- the place "disconnect this wallet" lives -- and the cascades
+ * behind it.
+ *
+ * - `listAccountClients` / `currentAccountSigningKeys` -- the listing over the
+ *   locally verified did:webvh log, with display labels merged, and the same
+ *   read reduced to the key set an app grant's delegation signer is checked
+ *   against. Both take an already-verified log in place of fetching one.
+ * - `disconnectEligibility` / `revokedClientKeysFor` / `cascadeCompletion` --
+ *   the disconnect-eligibility policy as data and pure functions, so both
+ *   surfaces refuse the same rows for the same reasons and report a partial
+ *   fan-out as the resumable success it is.
+ * - `revokeAccountClient` -- the revocation cascade in dependency order
+ *   (document edit, roster rotation, collection fan-out, optional recovery
+ *   re-mints), with the app-specific stages injected.
+ * - `checkPukRosterAtLogin` / `convergePukRosterToAccount` -- the login-time
+ *   roster policy: which roster failures refuse a session, and the standing
+ *   convergence of the roster onto the account document.
+ */
+export { currentAccountSigningKeys, listAccountClients } from './listing.js';
+export { cascadeCompletion, disconnectEligibility, revokedClientKeysFor } from './policy.js';
+export { revokeAccountClient } from './revocation.js';
+export { checkPukRosterAtLogin, convergePukRosterToAccount } from './rosterPolicy.js';
+//# sourceMappingURL=index.js.map

package/dist/clients/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/clients/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAAE,yBAAyB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAO5E,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAMrD,OAAO,EACL,qBAAqB,EACrB,0BAA0B,EAC3B,MAAM,mBAAmB,CAAA"}

package/dist/clients/listing.d.ts

@@ -0,0 +1,103 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The enrolled-client listing behind a "wallets connected to this account"
+ * surface: fetch and locally verify the account's world-readable did:webvh log
+ * (the same verification step every ceremony runs), enumerate the clients it
+ * enrolls, merge their display labels, and mark the row belonging to the
+ * caller's own client.
+ *
+ * The listing IS the revocation surface, so the enumeration rule matters as
+ * much as the display: `listEnrolledWebvhClients` keys on
+ * `capabilityInvocation`, which is what structurally excludes a recovery
+ * code's key (published under `keyAgreement` only, deliberately unmarked) and
+ * the server-side conveniences (published under `authentication` /
+ * `assertionMethod`) -- neither can appear, by construction rather than by a
+ * filter someone must remember.
+ *
+ * Labels are display metadata with no authority, so a label-read failure
+ * degrades to unlabeled rows; the listing itself fails only when the log
+ * cannot be fetched or verified.
+ *
+ * The two reads are independent, so they run together, and either entry point
+ * takes an already-verified log (`verifiedLog`) in place of fetching one --
+ * the seam a caller needs to keep one verified log for a session instead of
+ * re-verifying `did.jsonl` per surface. Whether such a cache is safe to hold,
+ * and what invalidates it, is the caller's call.
+ */
+import { verifyAccountLog, type EnrolledWebvhClient } from '../webvh/index.js';
+import { type ClientLabelsStore } from '../keys/index.js';
+/**
+ * Where an account's did:webvh log is published: the account DID plus the
+ * Space and host its `id` collection is served from.
+ */
+export interface AccountLogPointer {
+    did: string;
+    spaceId: string;
+    host: string;
+}
+/**
+ * A log that has already been fetched and locally verified -- exactly what
+ * `verifyAccountLog` resolves to. Both entry points below accept one so a
+ * caller holding a still-valid result (a session-lifetime cache, or two
+ * surfaces mounting together) reads the account's clients without re-fetching
+ * and re-verifying `did.jsonl`. The cache itself is the caller's: only the
+ * caller knows which ceremonies invalidate it.
+ */
+export type VerifiedAccountLog = Awaited<ReturnType<typeof verifyAccountLog>>;
+/**
+ * One row of the listing: the log-stated client plus its display state.
+ * `updateKeyMultibase` is absent when the log attribution could not isolate
+ * the client's active update key, which is exactly when it cannot be
+ * disconnected.
+ */
+export interface AccountClientView extends EnrolledWebvhClient {
+    label?: string;
+    isCurrent: boolean;
+}
+/**
+ * Lists the wallet clients enrolled on an account, from the locally verified
+ * did:webvh log, with labels merged and the caller's own client marked.
+ *
+ * @param options {object}
+ * @param options.pointer {AccountLogPointer}   where the account log lives
+ * @param [options.labelsStore] {ClientLabelsStore}   the
+ *   `key-map/client-labels.json` store; omitted, every row is unlabeled
+ * @param [options.ownSigningKeyMultibase] {string}   this client's own signing
+ *   key, which marks its row `isCurrent`
+ * @param [options.verifiedLog] {VerifiedAccountLog}   an already-verified log
+ *   to read instead of fetching and verifying one
+ * @returns {Promise<AccountClientView[]>}
+ */
+export declare function listAccountClients({ pointer, labelsStore, ownSigningKeyMultibase, verifiedLog }: {
+    pointer: AccountLogPointer;
+    labelsStore?: ClientLabelsStore;
+    ownSigningKeyMultibase?: string;
+    verifiedLog?: VerifiedAccountLog;
+}): Promise<AccountClientView[]>;
+/**
+ * The signing-key multibases of the account's currently enrolled wallet
+ * clients, from the locally verified did:webvh log -- the key set a recorded
+ * app grant's delegation proof must name to still verify under the
+ * current-key-set rule (a grant signed by a since-disconnected client no
+ * longer verifies).
+ *
+ * This is the connected-applications surface's half of the same read: the
+ * gating on whether a session HAS a promoted account to check against stays
+ * app-side, since only the app knows what a guest or a storage-less session
+ * looks like. Throws when the log cannot be fetched or verified; a caller
+ * treating the check as best-effort catches and degrades to "unknown" rather
+ * than failing its page.
+ *
+ * @param options {object}
+ * @param options.pointer {AccountLogPointer}
+ * @param [options.verifiedLog] {VerifiedAccountLog}   an already-verified log
+ *   to read instead of fetching and verifying one
+ * @returns {Promise<Set<string>>}
+ */
+export declare function currentAccountSigningKeys({ pointer, verifiedLog }: {
+    pointer: AccountLogPointer;
+    verifiedLog?: VerifiedAccountLog;
+}): Promise<Set<string>>;
+//# sourceMappingURL=listing.d.ts.map

package/dist/clients/listing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listing.d.ts","sourceRoot":"","sources":["../../src/clients/listing.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAEL,gBAAgB,EAChB,KAAK,mBAAmB,EACzB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAE3E;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAA;AAE7E;;;;;GAKG;AACH,MAAM,WAAW,iBAAkB,SAAQ,mBAAmB;IAC5D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CAAC,EACvC,OAAO,EACP,WAAW,EACX,sBAAsB,EACtB,WAAW,EACZ,EAAE;IACD,OAAO,EAAE,iBAAiB,CAAA;IAC1B,WAAW,CAAC,EAAE,iBAAiB,CAAA;IAC/B,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,WAAW,CAAC,EAAE,kBAAkB,CAAA;CACjC,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAgB/B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,yBAAyB,CAAC,EAC9C,OAAO,EACP,WAAW,EACZ,EAAE;IACD,OAAO,EAAE,iBAAiB,CAAA;IAC1B,WAAW,CAAC,EAAE,kBAAkB,CAAA;CACjC,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAKvB"}

package/dist/clients/listing.js

@@ -0,0 +1,86 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The enrolled-client listing behind a "wallets connected to this account"
+ * surface: fetch and locally verify the account's world-readable did:webvh log
+ * (the same verification step every ceremony runs), enumerate the clients it
+ * enrolls, merge their display labels, and mark the row belonging to the
+ * caller's own client.
+ *
+ * The listing IS the revocation surface, so the enumeration rule matters as
+ * much as the display: `listEnrolledWebvhClients` keys on
+ * `capabilityInvocation`, which is what structurally excludes a recovery
+ * code's key (published under `keyAgreement` only, deliberately unmarked) and
+ * the server-side conveniences (published under `authentication` /
+ * `assertionMethod`) -- neither can appear, by construction rather than by a
+ * filter someone must remember.
+ *
+ * Labels are display metadata with no authority, so a label-read failure
+ * degrades to unlabeled rows; the listing itself fails only when the log
+ * cannot be fetched or verified.
+ *
+ * The two reads are independent, so they run together, and either entry point
+ * takes an already-verified log (`verifiedLog`) in place of fetching one --
+ * the seam a caller needs to keep one verified log for a session instead of
+ * re-verifying `did.jsonl` per surface. Whether such a cache is safe to hold,
+ * and what invalidates it, is the caller's call.
+ */
+import { listEnrolledWebvhClients, verifyAccountLog } from '../webvh/index.js';
+import { readClientLabels } from '../keys/index.js';
+/**
+ * Lists the wallet clients enrolled on an account, from the locally verified
+ * did:webvh log, with labels merged and the caller's own client marked.
+ *
+ * @param options {object}
+ * @param options.pointer {AccountLogPointer}   where the account log lives
+ * @param [options.labelsStore] {ClientLabelsStore}   the
+ *   `key-map/client-labels.json` store; omitted, every row is unlabeled
+ * @param [options.ownSigningKeyMultibase] {string}   this client's own signing
+ *   key, which marks its row `isCurrent`
+ * @param [options.verifiedLog] {VerifiedAccountLog}   an already-verified log
+ *   to read instead of fetching and verifying one
+ * @returns {Promise<AccountClientView[]>}
+ */
+export async function listAccountClients({ pointer, labelsStore, ownSigningKeyMultibase, verifiedLog }) {
+    // The log read and the label read are independent, so they run together.
+    const [{ log }, labels] = await Promise.all([
+        verifiedLog ?? verifyAccountLog(pointer),
+        labelsStore
+            ? readClientLabels({ store: labelsStore }).then(read => read.labels)
+            : Promise.resolve({})
+    ]);
+    const clients = listEnrolledWebvhClients({ log });
+    return clients.map(client => ({
+        ...client,
+        ...(labels[client.signingKeyMultibase] !== undefined
+            ? { label: labels[client.signingKeyMultibase] }
+            : {}),
+        isCurrent: client.signingKeyMultibase === ownSigningKeyMultibase
+    }));
+}
+/**
+ * The signing-key multibases of the account's currently enrolled wallet
+ * clients, from the locally verified did:webvh log -- the key set a recorded
+ * app grant's delegation proof must name to still verify under the
+ * current-key-set rule (a grant signed by a since-disconnected client no
+ * longer verifies).
+ *
+ * This is the connected-applications surface's half of the same read: the
+ * gating on whether a session HAS a promoted account to check against stays
+ * app-side, since only the app knows what a guest or a storage-less session
+ * looks like. Throws when the log cannot be fetched or verified; a caller
+ * treating the check as best-effort catches and degrades to "unknown" rather
+ * than failing its page.
+ *
+ * @param options {object}
+ * @param options.pointer {AccountLogPointer}
+ * @param [options.verifiedLog] {VerifiedAccountLog}   an already-verified log
+ *   to read instead of fetching and verifying one
+ * @returns {Promise<Set<string>>}
+ */
+export async function currentAccountSigningKeys({ pointer, verifiedLog }) {
+    const { log } = verifiedLog ?? (await verifyAccountLog(pointer));
+    return new Set(listEnrolledWebvhClients({ log }).map(client => client.signingKeyMultibase));
+}
+//# sourceMappingURL=listing.js.map

package/dist/clients/listing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listing.js","sourceRoot":"","sources":["../../src/clients/listing.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EACL,wBAAwB,EACxB,gBAAgB,EAEjB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,gBAAgB,EAA0B,MAAM,kBAAkB,CAAA;AAiC3E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,EACvC,OAAO,EACP,WAAW,EACX,sBAAsB,EACtB,WAAW,EAMZ;IACC,yEAAyE;IACzE,MAAM,CAAC,EAAE,GAAG,EAAE,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC1C,WAAW,IAAI,gBAAgB,CAAC,OAAO,CAAC;QACxC,WAAW;YACT,CAAC,CAAC,gBAAgB,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC;YACpE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAyB,EAAE,CAAC;KAChD,CAAC,CAAA;IACF,MAAM,OAAO,GAAG,wBAAwB,CAAC,EAAE,GAAG,EAAE,CAAC,CAAA;IACjD,OAAO,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC5B,GAAG,MAAM;QACT,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,KAAK,SAAS;YAClD,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE;YAC/C,CAAC,CAAC,EAAE,CAAC;QACP,SAAS,EAAE,MAAM,CAAC,mBAAmB,KAAK,sBAAsB;KACjE,CAAC,CAAC,CAAA;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAAC,EAC9C,OAAO,EACP,WAAW,EAIZ;IACC,MAAM,EAAE,GAAG,EAAE,GAAG,WAAW,IAAI,CAAC,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC,CAAA;IAChE,OAAO,IAAI,GAAG,CACZ,wBAAwB,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAC5E,CAAA;AACH,CAAC"}

package/dist/clients/policy.d.ts

@@ -0,0 +1,79 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The disconnect-eligibility policy both "connected wallets" surfaces encode
+ * as UI state, as data and pure functions -- so the rule that decides whether
+ * a row can be disconnected is one rule, and each app supplies only its own
+ * wording.
+ *
+ * Three refusals, each for a different reason:
+ *
+ * - **`self`** -- a client cannot disconnect itself. The document edit would
+ *   also refuse (on the update key), but the surface should name the real rule
+ *   and point at another connected wallet, or a recovery code.
+ * - **`last-client`** -- the account's only enrolled client cannot be
+ *   disconnected: that would abandon the account's update authority, leaving a
+ *   log nobody can ever extend. Recovery-code issuance is the answer, not this
+ *   button.
+ * - **`unattributed-update-key`** -- the log attribution could not isolate the
+ *   row's ACTIVE update key. Disconnecting with a guessed key could revoke a
+ *   different client's authority, so the row is disabled rather than guessed
+ *   at.
+ *
+ * And one non-failure: a cascade whose collection fan-out left failures
+ * behind is a **resumable success**. The wallet IS disconnected -- the
+ * document edit landed first and is the pull axis everywhere -- and the
+ * remaining re-keying is detected from durable state alone, so the next run
+ * (or the login-time completion sweep) finishes it. A surface that reported
+ * that as an error would contradict its own refreshed listing.
+ */
+import type { RevokedClientKeys } from '../webvh/index.js';
+import type { PukCascadeResult } from '../keys/index.js';
+import type { AccountClientView } from './listing.js';
+/**
+ * Why a listed row cannot be disconnected. See the module doc.
+ */
+export type DisconnectRefusal = 'self' | 'last-client' | 'unattributed-update-key';
+/**
+ * Whether one listed row can be disconnected, and -- when it cannot -- which
+ * rule refuses it.
+ *
+ * @param options {object}
+ * @param options.client {AccountClientView}   the row in question
+ * @param options.clients {AccountClientView[]}   the whole listing (the
+ *   last-client rule is a property of the account, not of the row)
+ * @returns {{ allowed: boolean, refusal?: DisconnectRefusal }}
+ */
+export declare function disconnectEligibility({ client, clients }: {
+    client: AccountClientView;
+    clients: AccountClientView[];
+}): {
+    allowed: boolean;
+    refusal?: DisconnectRefusal;
+};
+/**
+ * Narrows a listed row to the key set a revocation needs, throwing when the
+ * row's active update key could not be attributed. A row with all three key
+ * members present is exactly a `RevokedClientKeys`.
+ *
+ * @param options {object}
+ * @param options.client {AccountClientView}
+ * @returns {RevokedClientKeys}
+ */
+export declare function revokedClientKeysFor({ client }: {
+    client: AccountClientView;
+}): RevokedClientKeys;
+/**
+ * How a completed cascade should be reported: `complete` when every encrypted
+ * collection took the fresh key, `partial` when some did not -- a resumable
+ * success, never an error (see the module doc).
+ *
+ * @param options {object}
+ * @param options.collections {PukCascadeResult}   the collection fan-out result
+ * @returns {'complete' | 'partial'}
+ */
+export declare function cascadeCompletion({ collections }: {
+    collections: PukCascadeResult;
+}): 'complete' | 'partial';
+//# sourceMappingURL=policy.d.ts.map

package/dist/clients/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/clients/policy.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAA;AAErD;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAC3B,MAAM,GAAG,aAAa,GAAG,yBAAyB,CAAA;AAEpD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,MAAM,EACN,OAAO,EACR,EAAE;IACD,MAAM,EAAE,iBAAiB,CAAA;IACzB,OAAO,EAAE,iBAAiB,EAAE,CAAA;CAC7B,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,iBAAiB,CAAA;CAAE,CAWpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,MAAM,EACP,EAAE;IACD,MAAM,EAAE,iBAAiB,CAAA;CAC1B,GAAG,iBAAiB,CAYpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,WAAW,EACZ,EAAE;IACD,WAAW,EAAE,gBAAgB,CAAA;CAC9B,GAAG,UAAU,GAAG,SAAS,CAEzB"}

package/dist/clients/policy.js

@@ -0,0 +1,55 @@
+/**
+ * Whether one listed row can be disconnected, and -- when it cannot -- which
+ * rule refuses it.
+ *
+ * @param options {object}
+ * @param options.client {AccountClientView}   the row in question
+ * @param options.clients {AccountClientView[]}   the whole listing (the
+ *   last-client rule is a property of the account, not of the row)
+ * @returns {{ allowed: boolean, refusal?: DisconnectRefusal }}
+ */
+export function disconnectEligibility({ client, clients }) {
+    if (client.isCurrent) {
+        return { allowed: false, refusal: 'self' };
+    }
+    if (clients.length <= 1) {
+        return { allowed: false, refusal: 'last-client' };
+    }
+    if (!client.updateKeyMultibase) {
+        return { allowed: false, refusal: 'unattributed-update-key' };
+    }
+    return { allowed: true };
+}
+/**
+ * Narrows a listed row to the key set a revocation needs, throwing when the
+ * row's active update key could not be attributed. A row with all three key
+ * members present is exactly a `RevokedClientKeys`.
+ *
+ * @param options {object}
+ * @param options.client {AccountClientView}
+ * @returns {RevokedClientKeys}
+ */
+export function revokedClientKeysFor({ client }) {
+    if (!client.updateKeyMultibase) {
+        throw new Error("This wallet's update key could not be attributed from the account " +
+            'log, so it cannot be disconnected from here.');
+    }
+    return {
+        signingKeyMultibase: client.signingKeyMultibase,
+        keyAgreementKeyMultibase: client.keyAgreementKeyMultibase,
+        updateKeyMultibase: client.updateKeyMultibase
+    };
+}
+/**
+ * How a completed cascade should be reported: `complete` when every encrypted
+ * collection took the fresh key, `partial` when some did not -- a resumable
+ * success, never an error (see the module doc).
+ *
+ * @param options {object}
+ * @param options.collections {PukCascadeResult}   the collection fan-out result
+ * @returns {'complete' | 'partial'}
+ */
+export function cascadeCompletion({ collections }) {
+    return collections.failed.length > 0 ? 'partial' : 'complete';
+}
+//# sourceMappingURL=policy.js.map

package/dist/clients/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/clients/policy.ts"],"names":[],"mappings":"AAwCA;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,EACpC,MAAM,EACN,OAAO,EAIR;IACC,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;IAC5C,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,CAAA;IACnD,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC/B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,yBAAyB,EAAE,CAAA;IAC/D,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAA;AAC1B,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,EACnC,MAAM,EAGP;IACC,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,oEAAoE;YAClE,8CAA8C,CACjD,CAAA;IACH,CAAC;IACD,OAAO;QACL,mBAAmB,EAAE,MAAM,CAAC,mBAAmB;QAC/C,wBAAwB,EAAE,MAAM,CAAC,wBAAwB;QACzD,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;KAC9C,CAAA;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAChC,WAAW,EAGZ;IACC,OAAO,WAAW,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAA;AAC/D,CAAC"}

package/dist/clients/revocation.d.ts

@@ -0,0 +1,156 @@
+/*!
+ * Copyright (c) 2026 Interop Alliance. All rights reserved.
+ */
+/**
+ * The client-revocation cascade: disconnecting an enrolled wallet client from
+ * an account, run synchronously in the revoking client, in dependency order.
+ * One orchestrator for every wallet, with the two app-specific stages injected
+ * rather than forked.
+ *
+ * 1. **The document edit** (`revokeWebvhClient`): the revoked client's two
+ *    verification methods, its update key, and both its standing prerotation
+ *    commitments leave the account's did:webvh document in one log entry.
+ *    Under the current-key-set rule that single edit is the revoked client's
+ *    pull axis EVERYWHERE -- its invocations, and every delegation and app
+ *    grant it ever signed, stop verifying the moment its verification method
+ *    leaves the document. There is no per-collection revoke anywhere in the
+ *    cascade; apps a revoked client had connected reconnect through the
+ *    ordinary connect flow.
+ * 2. **The per-user key rotation** in the wrap-set roster, recipients resolved
+ *    from the document the edit itself just resolved to (no re-fetch of the
+ *    log this call just extended). The roster delivers, never sources, so the
+ *    revoked client's entry is dropped even before the retire filter. An
+ *    account with no roster yet stops here: the client IS disconnected, with
+ *    nothing to rotate.
+ * 3. **The collection fan-out**: every encrypted collection is re-epoch'd onto
+ *    the fresh key in parallel, so writes stop landing under epochs the
+ *    revoked client can still decrypt. Failures are collected per collection
+ *    and never abort the fan-out.
+ * 4. **The recovery re-mints** (optional): delegations the revoked client had
+ *    signed stopped chaining at stage 1, so a wallet that issues recovery
+ *    codes re-mints them here -- while the registry is still readable under
+ *    the session's pre-adoption vault keys.
+ *
+ * The revoking session then adopts the fresh key in place (`onRotationAdopted`
+ * -- profile vault keys, storage ciphers, engine restarts: whatever "in place"
+ * means for the app), so it keeps operating without a re-login.
+ *
+ * Convergence is the design: every stage detects its own completion from
+ * durable state alone -- the log entry is idempotent, the roster no-ops once
+ * the revoked entry is off the current epoch, and a collection is stale
+ * exactly when its current epoch names a non-current key generation -- so a
+ * mid-cascade crash strands nothing permanently and a naive full re-run
+ * finishes it (the login-time completion sweep is the standing backstop). The
+ * honest ceiling is unchanged: ciphertext the revoked client already fetched
+ * stays readable to it, and old epochs open to keys it already held.
+ */
+import type { IKeyAgreementKey } from '@interop/data-integrity-core';
+import type { CollectionEncryption } from '@interop/was-client';
+import type { EncryptionDescriptorStore } from '@interop/was-client/edv';
+import { type ClientWebvhUpdateKeys, type RevokedClientKeys, type WebvhIdStore } from '../webvh/index.js';
+import { type Puk, type PukCascadeResult } from '../keys/index.js';
+/**
+ * Where the cascade's collection fan-out gets its work: which encrypted
+ * collections exist (only the app knows -- a mobile replica names the
+ * collections it replicates, a web wallet also lists the app-provisioned ones
+ * remotely) and how each one's descriptor store and encryption declaration are
+ * reached.
+ */
+export interface CascadeCollections {
+    collectionIds: string[] | (() => Promise<string[]>);
+    storeFor: (collectionId: string) => EncryptionDescriptorStore;
+    isEncrypted?: (collectionId: string) => Promise<boolean>;
+}
+/**
+ * What a completed cascade reports: whether the roster actually rotated on
+ * this run (a re-run of an already-complete revocation reports `false`), the
+ * per-collection fan-out result, the document as the edit left it, and the
+ * recovery re-mint counts when that stage ran.
+ */
+export interface ClientRevocationResult {
+    rotated: boolean;
+    collections: PukCascadeResult;
+    document: object;
+    puk?: Puk;
+    rosterDescriptor?: CollectionEncryption;
+    recovery?: {
+        reminted: number;
+        skipped: number;
+    };
+}
+/**
+ * Runs the whole revocation cascade for one enrolled wallet client. See the
+ * module doc for the order and the convergence story. Throws before touching
+ * anything on a call that must not proceed (revoking this client itself, a
+ * client whose active update key was not attributed); once the document edit
+ * lands, a thrown later stage leaves durable state a naive re-run -- or the
+ * login-time sweep -- converges from.
+ *
+ * The document edit's `StagedCommitmentAmbiguousError` passes through
+ * unwrapped, so a surface can re-word it ("disconnect this wallet from the
+ * other one instead"). Match it on `err.name ===
+ * 'StagedCommitmentAmbiguousError'` -- a stable contract on that class --
+ * rather than on `instanceof`, which does not survive a linked or duplicated
+ * copy of this package.
+ *
+ * @param options {object}
+ * @param options.idStore {WebvhIdStore}   the account's `id` collection store
+ * @param options.updateKeys {ClientWebvhUpdateKeys}   THIS client's did:webvh
+ *   update-key seeds, which sign the document edit
+ * @param options.revokedClient {RevokedClientKeys}   the revoked client's
+ *   public halves (its two verification-method multibases and its active
+ *   update key)
+ * @param [options.knownLatentHashes] {string[]}   the standing recovery codes'
+ *   update-key hashes, so the document edit can tell the revoked client's
+ *   staged commitment apart from a latent recovery commitment (the one
+ *   ambiguous log shape). Best-effort on the caller's side: an unreadable
+ *   registry simply omits them
+ * @param [options.ownSigningKeyMultibase] {string}   this client's own signing
+ *   key; supplied, self-revocation is refused up front by the rule the surface
+ *   should name, rather than by the update-key check inside the edit
+ * @param options.rosterStore {EncryptionDescriptorStore}   the
+ *   `key-map/puk.json` roster store
+ * @param [options.puk] {Puk}   this client's cached per-user key
+ * @param options.clientKeyAgreementKey {IKeyAgreementKey}   this client's own
+ *   (identity) key-agreement key -- its roster entry
+ * @param [options.pinnedEpochId] {string}   the locally pinned latest-seen
+ *   roster epoch
+ * @param [options.onPukAdopted] {Function}   persists a rotated key: called
+ *   with `{ puk, latestEpochId, descriptor }` after the roster read and BEFORE
+ *   the fan-out. The key and the epoch pin must persist atomically
+ * @param options.collections {CascadeCollections}   the fan-out's work
+ * @param [options.remintRecoveryDelegations] {Function}   `({ document }) =>
+ *   Promise<{ reminted, skipped }>` -- the recovery-delegation re-mint stage,
+ *   for a wallet that issues recovery codes
+ * @param [options.onRotationAdopted] {Function}   `({ puk }) => Promise<void>`
+ *   -- the live-session adoption of a rotated key, run last so the session
+ *   keeps operating without a re-login
+ * @returns {Promise<ClientRevocationResult>}
+ */
+export declare function revokeAccountClient({ idStore, updateKeys, revokedClient, knownLatentHashes, ownSigningKeyMultibase, rosterStore, puk, clientKeyAgreementKey, pinnedEpochId, onPukAdopted, collections, remintRecoveryDelegations, onRotationAdopted }: {
+    idStore: WebvhIdStore;
+    updateKeys: ClientWebvhUpdateKeys;
+    revokedClient: RevokedClientKeys;
+    knownLatentHashes?: string[];
+    ownSigningKeyMultibase?: string;
+    rosterStore: EncryptionDescriptorStore;
+    puk?: Puk;
+    clientKeyAgreementKey: IKeyAgreementKey;
+    pinnedEpochId?: string | null;
+    onPukAdopted?: (adopted: {
+        puk: Puk;
+        latestEpochId: string;
+        descriptor: CollectionEncryption;
+    }) => Promise<void>;
+    collections: CascadeCollections;
+    remintRecoveryDelegations?: (options: {
+        document: object;
+    }) => Promise<{
+        reminted: number;
+        skipped: number;
+    }>;
+    onRotationAdopted?: (rotation: {
+        puk: Puk;
+    }) => Promise<void>;
+}): Promise<ClientRevocationResult>;
+//# sourceMappingURL=revocation.d.ts.map

package/dist/clients/revocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revocation.d.ts","sourceRoot":"","sources":["../../src/clients/revocation.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AACxE,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAClB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAKL,KAAK,GAAG,EACR,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAA;AAEzB;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAA;IACnD,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,yBAAyB,CAAA;IAC7D,WAAW,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;CACzD;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,gBAAgB,CAAA;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,gBAAgB,CAAC,EAAE,oBAAoB,CAAA;IACvC,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CACjD;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,wBAAsB,mBAAmB,CAAC,EACxC,OAAO,EACP,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,WAAW,EACX,GAAG,EACH,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,WAAW,EACX,yBAAyB,EACzB,iBAAiB,EAClB,EAAE;IACD,OAAO,EAAE,YAAY,CAAA;IACrB,UAAU,EAAE,qBAAqB,CAAA;IACjC,aAAa,EAAE,iBAAiB,CAAA;IAChC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC5B,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,WAAW,EAAE,yBAAyB,CAAA;IACtC,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,qBAAqB,EAAE,gBAAgB,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE;QACvB,GAAG,EAAE,GAAG,CAAA;QACR,aAAa,EAAE,MAAM,CAAA;QACrB,UAAU,EAAE,oBAAoB,CAAA;KACjC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACnB,WAAW,EAAE,kBAAkB,CAAA;IAC/B,yBAAyB,CAAC,EAAE,CAAC,OAAO,EAAE;QACpC,QAAQ,EAAE,MAAM,CAAA;KACjB,KAAK,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACpD,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE;QAAE,GAAG,EAAE,GAAG,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAC9D,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAuFlC"}