@cortexkit/antigravity-auth-core 3.0.6 → 3.0.8

package/dist/common-auth-embedded/claustrum/custody.d.ts

@@ -1,9 +1,14 @@
 import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
 import { type ClaustrumLogger } from './errors.js';
 import type { InsulaUsageTransport } from './insula.js';
+import { type ScopedWatchSource, type WatchMode } from './watch.js';
+/**
+ * `watchScoped` is present from claustrum-client 0.12.0. Hosts detect it at
+ * run time and keep polling without it.
+ */
 export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'> & {
     insula?: InsulaUsageTransport;
-};
+} & ScopedWatchSource;
 /** The two credential types a plugin's family can hold; routing differs by type. */
 export type VaultCredentialType = 'oauth' | 'api_key';
 /**
@@ -44,6 +49,30 @@ export interface SkippedVaultRecord {
     readonly credentialId?: string;
     readonly reason: SkippedVaultReason;
 }
+/**
+ * One grant this consumer's enrollment holds, as the vault's list reply names
+ * it: for example `{ selectorKind: 'category', selector: 'openai-native',
+ * operation: 'read' }`. `selectorKind` is `exact` (the selector is a credential
+ * id) or `category` (a bare category name); both open strings.
+ */
+export interface VaultGrantTuple {
+    readonly selectorKind: string;
+    readonly selector: string;
+    readonly operation: string;
+}
+/**
+ * What this consumer is granted, independent of what those grants currently
+ * reach. It is what tells two empty listings apart: no rows with `grants === 0`
+ * means no grant at all (the fix is `ck auth grant`), while no rows with
+ * `grants > 0` means a grant that reaches no credential, usually logins that
+ * lack the category (`ck auth reclassify --from-registry`); `tuples` names the
+ * selector that matched nothing. Never written to the roster file.
+ */
+export interface VaultGrantReach {
+    /** How many grants the consumer holds, deposit grants excluded. */
+    readonly grants: number;
+    readonly tuples: readonly VaultGrantTuple[];
+}
 export interface VaultInventory {
     /**
      * The vault's change cursor: a digest over exactly what this consumer can see
@@ -53,6 +82,11 @@ export interface VaultInventory {
     readonly view: string;
     readonly credentials: readonly VaultCredential[];
     readonly skipped: readonly SkippedVaultRecord[];
+    /**
+     * The consumer's grants, as the vault's list reply named them. Undefined means unknown
+     * (the vault or client predates the fields), never zero grants.
+     */
+    readonly grantReach?: VaultGrantReach;
 }
 export interface ClaustrumScopedIdentity {
     readonly credentialId: string;
@@ -103,6 +137,57 @@ export interface ClaustrumScopedAttempt {
     readonly accessToken: string;
     readonly recordVersion: number;
     readonly expiresAtMs: number | null;
+    /**
+     * True when this receipt was not freshly served but is the last token kept
+     * from an earlier read, used because the vault could not be reached. A 401
+     * with such a receipt must not be retried and is not reported to the vault,
+     * which is unreachable.
+     */
+    readonly fromKeptReceipt?: true;
+}
+export interface KeptReceiptState {
+    readonly active: boolean;
+    readonly since: number | null;
+}
+export interface ClaustrumRosterWatchOptions {
+    /**
+     * Run the host's own discovery (`custody.discover()`, then its roster
+     * commit). Called with the newest notice's view when that view differs from
+     * the last discovered one, when a notice shows a sequence gap or a new
+     * epoch, and on the first notice of a watch re-opened after a close (the
+     * time between two watches was not observed). One call runs at a time;
+     * notices that arrive meanwhile earn at most one more call, which runs only
+     * if the view still differs. A rejection goes to `onError`.
+     */
+    onView: (view: string) => unknown;
+    /**
+     * The view of the roster the host last committed. Defaults to the view of
+     * the last successful `custody.discover()` (outage probes excluded). Pass it
+     * when the host can commit a roster it did not list itself (a peer process
+     * held the discovery lease) or can fail after listing.
+     */
+    view?: () => string | undefined;
+    /**
+     * Called whenever the mode changes. The watch starts in `polling`. Keep the
+     * host's own list timer at its usual pace unless the mode is `watching`.
+     */
+    onMode?: (mode: WatchMode) => void;
+    /**
+     * The vault refused the watch, and its confirming `list_scoped` read it with
+     * this error (a revoked enrollment answers `not_found`). Custody has already
+     * applied it as it applies a refused discovery (`listFailed`: every kept
+     * receipt is dropped); handle it as the host handles that refusal.
+     */
+    onRefused?: (error: unknown) => void;
+    /** A failed `onView`, or a watch that could not be opened. */
+    onError?: (error: unknown) => void;
+}
+/** A vault watch held by a custody; see `ClaustrumScopedCustody.watchRoster`. */
+export interface ClaustrumRosterWatch {
+    /** How the host currently learns about changes. */
+    readonly mode: WatchMode;
+    /** Stop the watch and its timers. Safe to call more than once. */
+    close(): void;
 }
 /** Reads the provider identity a served token executes under, when the plugin can tell. */
 export type IdentityParser = (accessToken: string) => string | undefined;
@@ -122,13 +207,15 @@ export declare function decideScopedRetryAfter401(site: string, served: Claustru
  * so it cannot expire while a long request is still using it.
  */
 export declare const SERVING_MARGIN_MS = 300000;
+/** A kept receipt needs a minute of headroom, not the vault's refresh demand. */
+export declare const KEPT_RECEIPT_MARGIN_MS = 60000;
 /**
  * Reads this consumer's vault credentials (list, fetch, 401 report), with the
- * enrollment token as authorization. Used by every host of a plugin. There is
- * deliberately no credential cache and no single-flight of credential reads:
- * each physical send is authorized by the vault, so a revoked enrollment or a
- * changed record takes effect on the next send. The enrollment token is
- * re-read per operation so an operator's reissue on disk is picked up.
+ * enrollment token as authorization. Used by every host of a plugin. Every
+ * physical send asks the vault first while reachable. Only an unreachable vault permits
+ * reuse of the last validated receipt, in memory and bounded by its expiry.
+ * The enrollment token is re-read per operation so revocation and disconnect
+ * still take effect without a process restart.
  */
 export declare class ClaustrumScopedCustody {
     #private;
@@ -148,7 +235,13 @@ export declare class ClaustrumScopedCustody {
         requireAssertion?: boolean;
         now?: () => number;
         logger?: ClaustrumLogger;
+        setTimeoutImpl?: typeof setTimeout;
+        clearTimeoutImpl?: typeof clearTimeout;
     });
+    /** A watch losing its transport is the same outage as an unreachable read. */
+    transportLost(error?: unknown): void;
+    /** Any vault answer ends transport fallback, even when it refuses access. */
+    reachable(): void;
     /**
      * List this consumer's credentials. A record that cannot be used is skipped
      * and warned about rather than failing the whole list, so one bad record
@@ -157,15 +250,23 @@ export declare class ClaustrumScopedCustody {
      */
     discover(signal?: AbortSignal): Promise<VaultInventory>;
     /**
-     * Fetch the credential for one physical send and wrap it in a fresh receipt.
-     * The vault's served identity (or, without one, the plugin's parse of the
-     * token) must equal the roster's when both are present. Without
-     * `requireAssertion`, absence on either side proves nothing and does not
-     * refuse; the receipt records what the vault asserted separately from what
-     * the roster expected. With it, a reply that does not itself name the
-     * credential id and the expected account is refused.
+     * Apply a failed account listing: any answer from the vault (a refusal such
+     * as a revoked enrollment's `not_found`) drops every kept receipt, while an
+     * unreachable vault keeps them. A vault watch that ends with the same
+     * refusal calls this too, so both paths treat it alike.
      */
-    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
+    listFailed(error: unknown): void;
+    /** Discard bearer material when a route is removed, declined or rebound. */
+    forget(credentialId: string): void;
+    /** Apply an already-held roster; this never fetches credentials or writes it. */
+    retain(identities: readonly (ClaustrumScopedIdentity & {
+        enabled: boolean;
+        state: string;
+    })[]): void;
+    /** A frozen, non-secret summary for a plugin's status display. */
+    keptReceiptState(): KeptReceiptState;
+    /** Ask the vault while reachable; retain one validated receipt in memory only. */
+    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal, routeId?: string): Promise<ClaustrumScopedAttempt>;
     /**
      * Report that a send this consumer actually made was rejected. Only a 401
      * is reported (the vault refuses 429, 402 and 5xx reports), addressed by
@@ -174,5 +275,25 @@ export declare class ClaustrumScopedCustody {
      * custody did not issue is refused rather than reported.
      */
     reportFailure(attempt: ClaustrumScopedAttempt, status: number, reporterSource: ClaustrumReporterSource): Promise<void>;
+    /**
+     * Watch this consumer's visible vault accounts instead of listing them on a
+     * short timer. Opens one `watchScoped` on this custody's client and calls
+     * `onView` when the host must run its discovery (see
+     * `ClaustrumRosterWatchOptions`). A claustrum-client without `watchScoped`
+     * (before 0.12.0) or a vault that answers `unknown_method` reports
+     * `fallback` and opens nothing. A watch that closes before any notice was
+     * never accepted: the client reads once to learn why, and the watch reports
+     * `fallback` and tries one new watch after `WATCH_RETRY_MS`, never in a
+     * loop. A watch that closes after notices is re-opened after
+     * `RESUBSCRIBE_BACKOFF_MS`, doubling per close in a row. A lost transport
+     * starts this custody's outage, exactly as an unreachable call does, and
+     * the first notice of a watch ends it. Timers are unreferenced; `close()`
+     * on the returned watch or on this custody stops it.
+     *
+     * The watch keeps no history, so the host still lists on a slow timer while
+     * the mode is `watching`: every `SAFETY_POLL_MS` (five minutes). In any
+     * other mode the host keeps its usual list timer.
+     */
+    watchRoster(options: ClaustrumRosterWatchOptions): ClaustrumRosterWatch;
     close(): void;
 }

package/dist/common-auth-embedded/claustrum/custody.js

@@ -1,11 +1,15 @@
 import { ClaustrumCredentialError, } from '@cortexkit/claustrum-client';
 import { createLogger } from '../logger/index.js';
+import { ClaustrumUnreachableError, classifyVaultFailure, } from './availability.js';
 import { readClaustrumEnrollmentToken } from './enrollment.js';
 import { ClaustrumConsumerError } from './errors.js';
 import { CUSTODY_PLACEHOLDER_PREFIX } from './host-slot.js';
+import { ScopedRosterWatch, } from './watch.js';
 /** Only a new version of the same account may replace an in-flight 401. */
 export function isScopedCredentialRotation(served, current) {
     return (current !== undefined &&
+        !current.fromKeptReceipt &&
+        !served.fromKeptReceipt &&
         current.credentialId === served.credentialId &&
         current.accountIdentity === served.accountIdentity &&
         current.recordVersion !== served.recordVersion);
@@ -45,6 +49,8 @@ export function decideScopedRetryAfter401(site, served, current, logger = defaul
  * so it cannot expire while a long request is still using it.
  */
 export const SERVING_MARGIN_MS = 300_000;
+/** A kept receipt needs a minute of headroom, not the vault's refresh demand. */
+export const KEPT_RECEIPT_MARGIN_MS = 60_000;
 function invalidMaterial() {
     return new ClaustrumConsumerError('invalid-material', 'Claustrum returned invalid credential material');
 }
@@ -83,13 +89,28 @@ function credentialTypeOf(row, family) {
         return row.refreshAdapter === undefined ? 'api_key' : undefined;
     return undefined;
 }
+/**
+ * The grants named in the vault's list reply, or undefined when it names none.
+ * Both fields must be present: a reply carrying only one of them is treated as
+ * unknown rather than completed with a guess. claustrum-client already refuses
+ * a malformed value, so nothing here validates it again.
+ */
+function grantReachOf(listed) {
+    const { grants, grantTuples } = listed;
+    if (grants === undefined || grantTuples === undefined)
+        return undefined;
+    return Object.freeze({
+        grants,
+        tuples: Object.freeze(grantTuples.map(({ selectorKind, selector, operation }) => Object.freeze({ selectorKind, selector, operation }))),
+    });
+}
 /**
  * Reads this consumer's vault credentials (list, fetch, 401 report), with the
- * enrollment token as authorization. Used by every host of a plugin. There is
- * deliberately no credential cache and no single-flight of credential reads:
- * each physical send is authorized by the vault, so a revoked enrollment or a
- * changed record takes effect on the next send. The enrollment token is
- * re-read per operation so an operator's reissue on disk is picked up.
+ * enrollment token as authorization. Used by every host of a plugin. Every
+ * physical send asks the vault first while reachable. Only an unreachable vault permits
+ * reuse of the last validated receipt, in memory and bounded by its expiry.
+ * The enrollment token is re-read per operation so revocation and disconnect
+ * still take effect without a process restart.
  */
 export class ClaustrumScopedCustody {
     #client;
@@ -101,7 +122,20 @@ export class ClaustrumScopedCustody {
     #logger;
     #provenance = new WeakMap();
     #reports = new WeakMap();
+    #kept = new Map();
+    #keptAttempts = new WeakMap();
+    #setTimeout;
+    #clearTimeout;
+    #outage = false;
+    #outageError = new ClaustrumUnreachableError();
+    #probeTimer;
+    #probing = false;
+    #lastProbeAt = -Infinity;
+    #probeDelay = 2_000;
     #closed = false;
+    /** The view of the last successful `discover()`, for `watchRoster`. */
+    #discoveredView;
+    #watches = new Set();
     constructor(options) {
         const tokenPath = options.tokenPath;
         if (options.readToken) {
@@ -119,6 +153,65 @@ export class ClaustrumScopedCustody {
         this.#requireAssertion = options.requireAssertion ?? false;
         this.#now = options.now ?? Date.now;
         this.#logger = options.logger ?? defaultLogger;
+        this.#setTimeout = options.setTimeoutImpl ?? setTimeout;
+        this.#clearTimeout = options.clearTimeoutImpl ?? clearTimeout;
+    }
+    /** A watch losing its transport is the same outage as an unreachable read. */
+    transportLost(error) {
+        if (this.#closed || this.#outage)
+            return;
+        this.#outage = true;
+        this.#outageError =
+            error instanceof ClaustrumCredentialError
+                ? error
+                : new ClaustrumUnreachableError();
+        this.#logger.warn('serving kept vault receipt', { reason: 'unreachable' });
+        this.#scheduleProbe();
+    }
+    /** Any vault answer ends transport fallback, even when it refuses access. */
+    reachable() {
+        if (this.#closed || !this.#outage)
+            return;
+        this.#outage = false;
+        if (this.#probeTimer)
+            this.#clearTimeout(this.#probeTimer);
+        this.#probeTimer = undefined;
+        this.#probeDelay = 2_000;
+        for (const kept of this.#kept.values())
+            kept.since = null;
+        (this.#logger.info ?? defaultLogger.info)('vault receipt serving resumed', { reason: 'reachable' });
+    }
+    #scheduleProbe() {
+        if (this.#closed || !this.#outage || this.#probeTimer || this.#probing)
+            return;
+        this.#probeTimer = this.#setTimeout(() => {
+            this.#probeTimer = undefined;
+            this.#probe(true);
+        }, this.#probeDelay);
+        this.#probeTimer.unref?.();
+    }
+    #probe(idle = false) {
+        if (this.#closed || !this.#outage || this.#probing)
+            return;
+        if (this.#now() - this.#lastProbeAt < 1_000) {
+            this.#scheduleProbe();
+            return;
+        }
+        this.#lastProbeAt = this.#now();
+        this.#probing = true;
+        // Both triggers share list_scoped discovery, including its receipt-drop rules.
+        // Sends never await discovery or let idle backoff delay the next send probe.
+        // A probe commits no roster, so it is not the host's discovery and does
+        // not move the view a roster watch compares notices against.
+        void this.#list()
+            .catch(() => {
+            if (idle && this.#outage)
+                this.#probeDelay = Math.min(this.#probeDelay * 2, 30_000);
+        })
+            .finally(() => {
+            this.#probing = false;
+            this.#scheduleProbe();
+        });
     }
     #check(signal) {
         if (this.#closed)
@@ -157,17 +250,24 @@ export class ClaustrumScopedCustody {
         }
         catch (error) {
             this.#check(signal);
+            if (classifyVaultFailure(error) === 'unreachable')
+                this.transportLost(error);
+            else
+                this.reachable();
             // Keep the vault's own refusals (ClaustrumCredentialError, carrying
             // code, class and action); replace any other error, whose text may echo
             // request params that include the enrollment token.
             if (error instanceof ClaustrumCredentialError)
                 throw error;
+            if (classifyVaultFailure(error) === 'unreachable')
+                throw new ClaustrumUnreachableError();
             throw new ClaustrumConsumerError('unavailable', 'Claustrum scoped operation unavailable');
         }
         finally {
             removeAbortListener?.();
         }
         this.#check(signal);
+        this.reachable();
         return result;
     }
     /**
@@ -177,8 +277,27 @@ export class ClaustrumScopedCustody {
      * skipped records: they simply are not this consumer's.
      */
     async discover(signal) {
-        const token = await this.#token(signal);
-        const inventory = await this.#call(() => this.#client.listScoped(token), signal);
+        const inventory = await this.#list(signal);
+        this.#discoveredView = inventory.view;
+        return inventory;
+    }
+    async #list(signal) {
+        let inventory;
+        let token;
+        try {
+            token = await this.#token(signal);
+        }
+        catch (error) {
+            this.#kept.clear();
+            throw error;
+        }
+        try {
+            inventory = await this.#call(() => this.#client.listScoped(token), signal);
+        }
+        catch (error) {
+            this.listFailed(error);
+            throw error;
+        }
         const skipped = [];
         const candidates = [];
         const counts = new Map();
@@ -217,29 +336,128 @@ export class ClaustrumScopedCustody {
         }
         for (const record of skipped)
             this.#logger.warn('skipped malformed vault record', record);
+        const grantReach = grantReachOf(inventory);
         return {
             view: inventory.view,
             credentials: Object.freeze(credentials),
             skipped: Object.freeze(skipped),
+            ...(grantReach && { grantReach }),
         };
     }
     /**
-     * Fetch the credential for one physical send and wrap it in a fresh receipt.
-     * The vault's served identity (or, without one, the plugin's parse of the
-     * token) must equal the roster's when both are present. Without
-     * `requireAssertion`, absence on either side proves nothing and does not
-     * refuse; the receipt records what the vault asserted separately from what
-     * the roster expected. With it, a reply that does not itself name the
-     * credential id and the expected account is refused.
+     * Apply a failed account listing: any answer from the vault (a refusal such
+     * as a revoked enrollment's `not_found`) drops every kept receipt, while an
+     * unreachable vault keeps them. A vault watch that ends with the same
+     * refusal calls this too, so both paths treat it alike.
+     */
+    listFailed(error) {
+        if (classifyVaultFailure(error) === 'unreachable')
+            this.transportLost(error);
+        else {
+            this.reachable();
+            this.#kept.clear();
+        }
+    }
+    /** Discard bearer material when a route is removed, declined or rebound. */
+    forget(credentialId) {
+        this.#kept.delete(credentialId);
+    }
+    /** Apply an already-held roster; this never fetches credentials or writes it. */
+    retain(identities) {
+        const current = new Map(identities.map((identity) => [identity.credentialId, identity]));
+        for (const [id, kept] of this.#kept) {
+            const identity = current.get(id);
+            if (!identity?.enabled ||
+                identity.state !== 'active' ||
+                identity.credentialType !== kept.attempt.credentialType ||
+                identity.accountIdentity !== kept.attempt.expectedAccountIdentity)
+                this.forget(id);
+        }
+    }
+    /** A frozen, non-secret summary for a plugin's status display. */
+    keptReceiptState() {
+        let since = null;
+        for (const [id, kept] of this.#kept) {
+            if (!this.#usable(kept.attempt)) {
+                this.forget(id);
+                continue;
+            }
+            if (kept.since !== null)
+                since = Math.min(since ?? kept.since, kept.since);
+        }
+        return Object.freeze({ active: since !== null, since });
+    }
+    #usable(attempt) {
+        return attempt.expiresAtMs === null
+            ? attempt.credentialType === 'api_key'
+            : attempt.expiresAtMs - this.#now() > KEPT_RECEIPT_MARGIN_MS;
+    }
+    /** Ask the vault while reachable; retain one validated receipt in memory only. */
+    async authorize(identity, signal, routeId = 'vault') {
+        this.#check(signal);
+        const { credentialId, credentialType, accountIdentity } = identity;
+        let kept = this.#kept.get(credentialId);
+        if (kept &&
+            (kept.attempt.credentialType !== credentialType ||
+                kept.attempt.expectedAccountIdentity !== accountIdentity)) {
+            this.forget(credentialId);
+            kept = undefined;
+        }
+        // A missing or invalid enrollment is not a transport outage.
+        let token;
+        try {
+            token = await this.#token(signal);
+        }
+        catch (error) {
+            this.#kept.clear();
+            throw error;
+        }
+        if (this.#outage && kept) {
+            this.#probe();
+            return this.#serveKept(credentialId, kept, token, routeId);
+        }
+        try {
+            const attempt = await this.#authorizeFresh({ credentialId, credentialType, accountIdentity }, token, signal);
+            this.#kept.set(credentialId, { attempt, routeId, since: null });
+            return attempt;
+        }
+        catch (error) {
+            this.#check(signal);
+            if (classifyVaultFailure(error) !== 'unreachable') {
+                this.forget(credentialId);
+                throw error;
+            }
+            return this.#serveKept(credentialId, kept, token, routeId, error);
+        }
+    }
+    #serveKept(credentialId, kept, token, routeId, error = this.#outageError) {
+        // A concurrent refusal or 401 may already have discarded this entry.
+        if (!kept ||
+            this.#kept.get(credentialId) !== kept ||
+            !this.#usable(kept.attempt)) {
+            this.forget(credentialId);
+            throw error;
+        }
+        if (kept.since === null)
+            kept.since = this.#now();
+        const attempt = Object.freeze(Object.defineProperty({ ...kept.attempt, fromKeptReceipt: true }, 'accessToken', { value: kept.attempt.accessToken, enumerable: false }));
+        this.#provenance.set(attempt, token);
+        this.#keptAttempts.set(attempt, routeId);
+        return attempt;
+    }
+    /**
+     * Fetch and validate a fresh receipt before retaining it. The vault assertion
+     * (or the plugin's token parse) must agree with the roster when both exist.
+     * With requireAssertion, an absent assertion also refuses rather than
+     * treating the roster's expectation as proof of the served account.
      */
-    async authorize(identity, signal) {
+    async #authorizeFresh(identity, token, signal) {
         if (!identity.credentialId)
             throw new ClaustrumConsumerError('route-unavailable', 'Claustrum dispatch requires a credential id');
         // Capture the caller's fields before yielding so a later mutation cannot move the fence.
         const { credentialId, credentialType, accountIdentity } = identity;
         if (this.#requireAssertion && accountIdentity === undefined)
             throw new ClaustrumConsumerError('identity-unasserted', 'Claustrum dispatch requires a known account identity');
-        const token = await this.#token(signal);
         const served = await this.#call(() => this.#client.getScoped({
             credentialId,
             enrollmentToken: token,
@@ -321,6 +539,21 @@ export class ClaustrumScopedCustody {
         const token = this.#provenance.get(attempt);
         if (!token)
             throw new ClaustrumConsumerError('no-receipt', 'Claustrum failure report requires an original dispatch receipt');
+        const keptRoute = this.#keptAttempts.get(attempt);
+        if (keptRoute !== undefined) {
+            this.forget(attempt.credentialId);
+            this.#logger.debug('scoped 401 not reported', {
+                routeId: keptRoute,
+                reason: 'kept-receipt',
+            });
+            return;
+        }
+        // The provider rejected this token, so it must not come back as a kept
+        // receipt during a later outage. Drop it before reporting, so a report that
+        // fails because the vault is unreachable still drops it.
+        const kept = this.#kept.get(attempt.credentialId);
+        if (kept && kept.attempt.recordVersion === attempt.recordVersion)
+            this.forget(attempt.credentialId);
         const pending = this.#reports.get(attempt);
         if (pending)
             return pending;
@@ -345,10 +578,72 @@ export class ClaustrumScopedCustody {
             throw error;
         }
     }
+    /**
+     * Watch this consumer's visible vault accounts instead of listing them on a
+     * short timer. Opens one `watchScoped` on this custody's client and calls
+     * `onView` when the host must run its discovery (see
+     * `ClaustrumRosterWatchOptions`). A claustrum-client without `watchScoped`
+     * (before 0.12.0) or a vault that answers `unknown_method` reports
+     * `fallback` and opens nothing. A watch that closes before any notice was
+     * never accepted: the client reads once to learn why, and the watch reports
+     * `fallback` and tries one new watch after `WATCH_RETRY_MS`, never in a
+     * loop. A watch that closes after notices is re-opened after
+     * `RESUBSCRIBE_BACKOFF_MS`, doubling per close in a row. A lost transport
+     * starts this custody's outage, exactly as an unreachable call does, and
+     * the first notice of a watch ends it. Timers are unreferenced; `close()`
+     * on the returned watch or on this custody stops it.
+     *
+     * The watch keeps no history, so the host still lists on a slow timer while
+     * the mode is `watching`: every `SAFETY_POLL_MS` (five minutes). In any
+     * other mode the host keeps its usual list timer.
+     */
+    watchRoster(options) {
+        this.#check();
+        const watch = new ScopedRosterWatch({
+            client: this.#client,
+            enrollmentToken: () => this.#token(),
+            view: options.view ?? (() => this.#discoveredView),
+            discover: async (view) => {
+                await options.onView(view);
+            },
+            onRefused: (error) => {
+                // Apply a refused watch as discover() applies a refused account
+                // listing: every kept receipt is dropped.
+                this.listFailed(error);
+                options.onRefused?.(error);
+            },
+            onTransportLost: () => this.transportLost(),
+            onReachable: () => this.reachable(),
+            onError: options.onError,
+            onMode: options.onMode,
+            logger: this.#logger,
+            now: this.#now,
+            setTimeoutImpl: this.#setTimeout,
+            clearTimeoutImpl: this.#clearTimeout,
+        });
+        this.#watches.add(watch);
+        watch.start();
+        return {
+            get mode() {
+                return watch.mode;
+            },
+            close: () => {
+                this.#watches.delete(watch);
+                watch.stop();
+            },
+        };
+    }
     close() {
         if (this.#closed)
             return;
         this.#closed = true;
+        if (this.#probeTimer)
+            this.#clearTimeout(this.#probeTimer);
+        this.#probeTimer = undefined;
+        for (const watch of this.#watches)
+            watch.stop();
+        this.#watches.clear();
+        this.#kept.clear();
         this.#client.close();
     }
 }

package/dist/common-auth-embedded/claustrum/errors.d.ts

@@ -11,6 +11,7 @@ export declare class ClaustrumConsumerError extends Error {
 }
 /** The structural logger every class here accepts; `/logger`'s `createLogger` satisfies it. */
 export interface ClaustrumLogger {
+    info?(message: string, data?: unknown): void;
     warn(message: string, data?: unknown): void;
     debug(message: string, data?: unknown): void;
 }