@cortexkit/anthropic-auth-core 2.0.2 → 2.1.0

package/dist/insula-quota.d.ts

@@ -0,0 +1,25 @@
+import type { InsulaQuotaContext, InsulaUsageEntry } from "./internal-types/claustrum/index.js";
+import { type AccountQuotaWindow, type AccountScopedQuotaWindow, type OAuthQuotaSnapshot } from './accounts.ts';
+/** An insula reading in the shape our usage poll produces, before the account identity is attached. */
+export type InsulaClaudeQuota = OAuthQuotaSnapshot & {
+    five_hour: AccountQuotaWindow;
+    seven_day: AccountQuotaWindow;
+    scoped: AccountScopedQuotaWindow[];
+    checkedAt: number;
+};
+/**
+ * Convert insula's Claude entry into our usage-poll snapshot. Every window's
+ * checkedAt is when insula fetched the reading, never when we read its cache,
+ * so a newer header or poll reading still wins. Both standard windows must be
+ * present; otherwise this returns undefined and our own poll stays in charge.
+ * The tertiary slot (legacy seven_day_opus/sonnet) is not a window we model.
+ */
+export declare function normalizeInsulaClaudeQuota(entry: InsulaUsageEntry, context: InsulaQuotaContext): InsulaClaudeQuota | undefined;
+/**
+ * Insula fetches on its own schedule, so the account's stored quota can hold
+ * a window read after insula's fetch (a response header, or our own poll).
+ * Stored quota is replaced as one snapshot, newest wins, so publishing the
+ * older insula reading as is would be refused and lose its other windows.
+ * Keep the newer reading of each window instead.
+ */
+export declare function mergeInsulaQuota(reading: InsulaClaudeQuota, stored: OAuthQuotaSnapshot | undefined): OAuthQuotaSnapshot;

package/dist/internal-types/auth-menu/terminal.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The terminal the menu draws on and reads keys from. The process's own
+ * stdin and stdout satisfy it; tests pass a scripted stand-in, so the full
+ * key-in, frame-out path runs without a real TTY.
+ */
+export interface MenuTerminal {
+    input: MenuInput;
+    output: MenuOutput;
+    /**
+     * Where SIGINT and SIGTERM are heard while a selector holds raw mode, so a
+     * kill restores the terminal. Defaults to nothing: raw mode turns Ctrl-C
+     * into a key the selector already handles.
+     */
+    signals?: MenuSignals;
+}
+export interface MenuInput {
+    /** True only on an interactive terminal; anything else gets a plain list. */
+    readonly isTTY?: boolean;
+    readonly isRaw?: boolean;
+    setRawMode(mode: boolean): unknown;
+    resume(): unknown;
+    pause(): unknown;
+    on(event: 'data', listener: (data: Buffer | string) => void): unknown;
+    removeListener(event: 'data', listener: (data: Buffer | string) => void): unknown;
+}
+export interface MenuOutput {
+    write(text: string): unknown;
+    readonly columns?: number;
+    readonly rows?: number;
+}
+export interface MenuSignals {
+    once(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    removeListener(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+/** The current process's terminal, with its signals. */
+export declare function processTerminal(): MenuTerminal;
+/**
+ * Whether keys can be read one at a time. Only the input is checked, as the
+ * plugins' menus always did: output piped to a file still gets the menu.
+ */
+export declare function isInteractive(terminal: MenuTerminal): boolean;
+/** Writes one line of plain output below the menu. */
+export declare function printLine(terminal: MenuTerminal, line?: string): void;

package/dist/internal-types/claustrum/availability.d.ts

@@ -0,0 +1,89 @@
+import { ClaustrumConsumerError } from './errors.js';
+export type VaultFailureClass = 'unreachable' | 'answered';
+/**
+ * Codes from claustrum-client's decoder and its subc transport. A retry action
+ * alone is not evidence of an outage: even transient vault refusals must win
+ * over a previously served credential. New codes fail closed until reviewed.
+ */
+export declare const VAULT_FAILURE_CLASSES: Readonly<{
+    ECONNREFUSED: "unreachable";
+    ENOENT: "unreachable";
+    ECONNRESET: "unreachable";
+    EPIPE: "unreachable";
+    ETIMEDOUT: "unreachable";
+    transport_error: "unreachable";
+    unavailable: "unreachable";
+    timeout: "unreachable";
+    route_closed: "unreachable";
+    daemon_draining: "unreachable";
+    connection_closed: "unreachable";
+    connection_dropped: "unreachable";
+    request_deadline: "unreachable";
+    deadline_exceeded_no_drop_observed: "unreachable";
+    module_reloading: "unreachable";
+    module_warming: "unreachable";
+    target_unavailable: "unreachable";
+    module_timeout: "unreachable";
+    invalid_response: "answered";
+    invalid_record_version: "answered";
+    invalid_expiry: "answered";
+    invalid_status: "answered";
+    invalid_params: "answered";
+    ttl_unsatisfiable: "answered";
+    not_found: "answered";
+    enrollment_revoked: "answered";
+    enrollment_invalid: "answered";
+    grant_denied: "answered";
+    credential_unavailable: "answered";
+    needs_reauth: "answered";
+    declined: "answered";
+    disabled: "answered";
+    identity_changed: "answered";
+    closed: "answered";
+    client_closed: "answered";
+    pending_exists: "answered";
+    pending_queue_full: "answered";
+    already_consumed: "answered";
+    superseded: "answered";
+    stale_generation: "answered";
+    missing_identity: "answered";
+    invalid_control_body: "answered";
+    unknown_module: "answered";
+    module_removed: "answered";
+    capability_denied: "answered";
+    unknown_channel: "unreachable";
+    stale_route_epoch: "unreachable";
+    capability_forbidden: "answered";
+    capability_unprovided: "answered";
+    capability_ambiguous: "answered";
+    invalid_capability_identifier: "answered";
+    binary_body_required: "answered";
+    binary_call_requires_call_binary: "answered";
+    corr_exhausted: "answered";
+    late_route_cleanup_failed: "answered";
+    reverse_request_capability_not_declared: "answered";
+    stale_route_handle: "answered";
+    reverse_request_unhandled: "answered";
+    handler_error: "answered";
+    health_error: "answered";
+    duplicate_module_id: "answered";
+    route_rejected: "answered";
+    lock_busy: "answered";
+    owner_invalid: "answered";
+    renewal_failed: "answered";
+    unsupported_platform: "answered";
+    EACCES: "answered";
+    EPERM: "answered";
+    ERR_PRIVATE_FILES_SECURITY: "answered";
+}>;
+/**
+ * An injected adapter may throw this ONLY when its connection/transport is
+ * unreachable, including a failed connect before getScoped. Do not wrap an
+ * adapter shutdown, cancellation, validation error or vault refusal in it.
+ * Its fixed message cannot echo enrollment or credential material, and its
+ * kind stays `unavailable` for callers handling ClaustrumConsumerError.
+ */
+export declare class ClaustrumUnreachableError extends ClaustrumConsumerError {
+    constructor();
+}
+export declare function classifyVaultFailure(error: unknown): VaultFailureClass;

package/dist/internal-types/claustrum/consumer.d.ts

@@ -0,0 +1,172 @@
+import type { ClaustrumReporterSource } from '@cortexkit/claustrum-client';
+import type { QuotaObservation } from '../quota/index.js';
+import type { RoutingRow } from '../routing/index.js';
+import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser, type KeptReceiptState, type VaultGrantReach } from './custody.js';
+import { type ClaustrumLogger } from './errors.js';
+import { type InsulaQuotaOptions } from './insula.js';
+import { type AccountMapper, type QuotaReceipt, type VaultRosterFile } from './roster.js';
+import { type WatchMode } from './watch.js';
+export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
+    /**
+     * The roster file: one row per vault account (route id, credential id,
+     * account identity, state, quota), plus the accounts the user declined. It
+     * never holds a token.
+     */
+    rosterPath: string;
+    /** This host's enrollment token, written by setup. */
+    tokenPath: string;
+    family: ClaustrumFamily;
+    connect: () => Promise<ClaustrumScopedClient>;
+    /**
+     * Whether the plugin currently takes its accounts from the vault (custody
+     * mode) rather than from local logins. Checked before every discovery,
+     * commit and dispatch; false closes the vault connection and refuses sends.
+     */
+    isCustodyActive?: () => boolean | Promise<boolean>;
+    /** Ids of the plugin's local pool rows; no vault route id may equal one. */
+    reservedRouteIds?: () => Iterable<string>;
+    routePrefix?: string;
+    mapAccount?: AccountMapper;
+    parseIdentity?: IdentityParser;
+    /**
+     * Issue a receipt only when the vault's served reply itself names the
+     * credential id and the roster's account identity (see
+     * `ClaustrumScopedCustody`). Set it for providers whose tokens do not reveal
+     * their account; leave it unset to accept a reply that asserts no identity.
+     */
+    requireAssertion?: boolean;
+    /**
+     * Fired once per change of the vault's view cursor, including the first
+     * roster. A poll that sees the same view does not fire, and neither does a
+     * routine token refresh, which never moves the view.
+     */
+    onRoster?: (roster: VaultRosterFile) => void;
+    onError?: (error: unknown) => void;
+    /**
+     * How often `start()` ticks. A tick lists the vault when no vault watch is
+     * open (before it is accepted, or when the vault or the client cannot
+     * watch), and otherwise only every five minutes, as a safety net. A tick
+     * polls insula (at most once a minute) only while its watch is not open.
+     */
+    pollIntervalMs?: number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    now?: () => number;
+    logger?: ClaustrumLogger;
+    /** Optional background quota source. In-band readings still use recordQuota. */
+    insula?: InsulaQuotaOptions<Q>;
+}
+/**
+ * How a started consumer learns about changes, for logs and status displays.
+ * `insula` is present when the consumer was given an insula source. Never
+ * carries secrets.
+ */
+export interface ClaustrumWatchState {
+    readonly vault: WatchMode;
+    readonly insula?: WatchMode;
+}
+export interface SendOptions {
+    /**
+     * What kind of request this is (for example `model`, `quota`, `profile`),
+     * recorded in the 401 retry log line so a retry can be traced to its caller.
+     */
+    site: string;
+    signal?: AbortSignal;
+    reporterSource?: ClaustrumReporterSource;
+}
+/**
+ * One plugin host's view of its vault accounts. It turns vault credentials
+ * into rows for `/routing`, authorizes each physical send with the vault, and
+ * reports a 401 against the exact record version that send used. Metadata
+ * (the connection and discovery) is shared and coalesced; credential reads
+ * never are. It never enrolls: a missing token is an error here, and setup
+ * is where enrollment happens.
+ */
+export declare class ClaustrumConsumer<Q = QuotaObservation> {
+    #private;
+    constructor(options: ClaustrumConsumerOptions<Q>);
+    /** The last committed roster this instance saw, without any I/O. */
+    snapshot(): VaultRosterFile | undefined;
+    /**
+     * What this consumer is granted, from its latest discovery, without any I/O.
+     * It explains an empty roster: `grants === 0` means no grant at all, while
+     * `grants > 0` means a grant that reaches no credential (`tuples` names its
+     * selector). Undefined means unknown, never zero: the vault or client is too
+     * old to send it, nothing was discovered yet, or the roster now in memory is
+     * a different view than the one this instance discovered (a peer process
+     * held the discovery lease and its newer roster was served instead).
+     */
+    grantReach(): VaultGrantReach | undefined;
+    /** How this consumer currently learns about changes, without I/O. */
+    watchState(): ClaustrumWatchState;
+    /** Whether any account is using an in-memory outage receipt, without I/O. */
+    keptReceiptState(): KeptReceiptState;
+    /** Rows for `/routing`, from the last committed roster. */
+    routingRows(): RoutingRow[];
+    refresh(): Promise<VaultRosterFile | undefined>;
+    /**
+     * Poll in the background and open the vault and insula watches. Until the
+     * vault watch is accepted, and whenever it is unavailable, every tick lists
+     * the vault exactly as before watches existed. While it is open a tick
+     * lists only when five minutes have passed since the last discovery, since
+     * the watch keeps no history; it still checks `isCustodyActive`, so a switch
+     * to local mode closes the connection as quickly as before. Insula is
+     * polled on the tick only while its own watch is not open. A host not in
+     * vault mode makes no request.
+     */
+    start(): void;
+    /**
+     * Fetch on a background tick, at most once per minute across projects with
+     * the same daemon and enrollment token path. Admission must use the cache
+     * instead, so an optional quota daemon never delays a provider request.
+     */
+    refreshInsulaQuota(): Promise<void>;
+    /**
+     * Cache-only, for unknown-quota admission with a served receipt. Undefined
+     * means poll the provider normally. Only get_scoped's asserted account_id
+     * joins insula; parsed identities and display metadata cannot substitute.
+     * Background polling should use cachedInsulaQuotaForRoute instead.
+     */
+    cachedInsulaQuota(receipt: Pick<ClaustrumScopedAttempt, 'assertedAccountIdentity'>): Promise<Q | undefined>;
+    /**
+     * Background cache lookup without fetching a credential. Re-read the roster
+     * so a peer's account replacement invalidates the old route immediately.
+     * A route without a known provider account cannot join an insula entry.
+     */
+    cachedInsulaQuotaForRoute(routeId: string): Promise<Q | undefined>;
+    /**
+     * Authorize one physical send on a vault route. The roster file is re-read
+     * first, so a decline committed by another process applies before the next
+     * poll, and a route whose credential or account changed is refused.
+     */
+    authorize(routeId: string, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
+    reportFailure(attempt: ClaustrumScopedAttempt, status: number, source: ClaustrumReporterSource): Promise<void>;
+    /**
+     * Send on a vault route. `dispatch` builds and sends the request with the
+     * receipt's token and may be called twice, so it must be able to rebuild
+     * its body. A 401 is retried once, and only when the vault now serves a new
+     * record version of the same credential and account; the final 401 is
+     * reported against the version that send actually used. Each call to
+     * `dispatch` gets its own receipt.
+     */
+    send(routeId: string, dispatch: (attempt: ClaustrumScopedAttempt, signal?: AbortSignal) => Promise<Response>, options: SendOptions): Promise<Response>;
+    /** Decline a vault account: it stays listed and never routes until accepted. */
+    decline(routeId: string): Promise<void>;
+    accept(routeId: string): Promise<void>;
+    /**
+     * Store a quota or profile observation for a vault route. The receipt the
+     * reading was taken with is required: the observation lands only while the
+     * route still holds the credential and account that receipt was served for
+     * (see `recordVaultQuota`), so a reading for a replaced account is dropped.
+     */
+    recordQuota(routeId: string, observation: QuotaObservation, attempt: QuotaReceipt): Promise<boolean>;
+    /**
+     * Store a background observation that belongs to an account rather than to
+     * a served credential (an insula reading from `cachedInsulaQuotaForRoute`).
+     * It lands only while the route is still bound to that known account, so no
+     * credential fetch is needed and a replaced account's reading is dropped.
+     * The in-memory roster is reloaded from the file, without a vault call.
+     */
+    recordAccountQuota(routeId: string, accountIdentity: string, observation: QuotaObservation): Promise<boolean>;
+    close(): void;
+}

package/dist/internal-types/claustrum/custody.d.ts

@@ -0,0 +1,299 @@
+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';
+/**
+ * Which vault rows belong to this plugin. `refreshAdapter` classifies an OAuth
+ * row by the protocol it speaks; `category` is the grant that authorizes this
+ * consumer to read it. Static API keys carry no refresh adapter, so they are
+ * admitted only when `apiKeys` is set and only by category.
+ */
+export interface ClaustrumFamily {
+    refreshAdapter: string;
+    category: string;
+    apiKeys?: boolean;
+}
+/** One vault credential this consumer may serve. Never carries bearer material. */
+export interface VaultCredential {
+    readonly credentialId: string;
+    readonly credentialType: VaultCredentialType;
+    /**
+     * The provider account the credential logs into, when the vault's adapter
+     * claims one. Absent means the adapter makes no claim, not a mismatch.
+     */
+    readonly accountIdentity?: string;
+    readonly state: string;
+    readonly email?: string;
+    readonly orgName?: string;
+}
+/**
+ * Why a listed vault record could not be used. A closed set of fixed codes, so
+ * a log line or a roster file that carries one never echoes vault data.
+ */
+export type SkippedVaultReason = 'empty credential id' | 'duplicate credential id' | 'blank account identity' | 'empty state';
+/**
+ * A vault record this consumer could not use. `credentialId` is absent when
+ * the record's id itself was unusable, so nothing can say which account the
+ * record was.
+ */
+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
+     * (ids, grants, state, identity), never over record versions, so a routine
+     * token refresh does not move it. Only equality is meaningful.
+     */
+    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;
+    readonly credentialType: VaultCredentialType;
+    readonly accountIdentity?: string;
+}
+/**
+ * Where a receipt's `accountIdentity` came from: the vault asserted it in the
+ * served reply, the plugin's `parseIdentity` read it from the served token, or
+ * neither did and it is only the roster's expectation (`none`: no identity at
+ * all).
+ */
+export type AccountIdentitySource = 'asserted' | 'parsed' | 'expected' | 'none';
+/**
+ * A receipt: what the vault served for one physical send. Each attempt gets
+ * its own. It records the exact record version served, because a 401 for
+ * this send is reported to the vault against that version.
+ */
+export interface ClaustrumScopedAttempt {
+    readonly credentialId: string;
+    readonly credentialType: VaultCredentialType;
+    /**
+     * The account this receipt is bound to: the vault's assertion, else the
+     * plugin's parse of the token, else the roster's expectation. Check
+     * `accountIdentitySource` before treating it as proof.
+     */
+    readonly accountIdentity?: string;
+    readonly accountIdentitySource: AccountIdentitySource;
+    /** The account the roster row named when this receipt was requested. */
+    readonly expectedAccountIdentity?: string;
+    /** The credential id the vault itself put in the served reply, if any. */
+    readonly assertedCredentialId?: string;
+    /**
+     * The account the vault itself put in the served reply, if any. Never filled
+     * in from the roster or from a token parse.
+     */
+    readonly assertedAccountIdentity?: string;
+    /**
+     * The non-secret Google Cloud project id the vault served in get_scoped for
+     * this attempt, if any. Never filled in from list_scoped, the roster or a
+     * token parse. A project change in the vault takes effect on the next send.
+     */
+    readonly projectId?: string;
+    /**
+     * Kept in memory only and hidden from JSON.stringify and object spreads, so
+     * logging a receipt never leaks it. Authorize again for every dispatch and retry.
+     */
+    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;
+/** Only a new version of the same account may replace an in-flight 401. */
+export declare function isScopedCredentialRotation(served: ClaustrumScopedAttempt, current: ClaustrumScopedAttempt | undefined): current is ClaustrumScopedAttempt;
+/** Why a scoped 401 did or did not retry. Never carries credential material. */
+export type ScopedRetryReason = 'rotated' | 'reauthorize-failed' | 'credential-changed' | 'account-changed' | 'version-unchanged';
+/**
+ * Decide whether a request that got a 401 should retry with the freshly
+ * re-authorized receipt, and log the decision. The vault can refresh a
+ * credential between the send and the 401; the log line lets that refresh be
+ * matched against the consumer's retry. `site` names the kind of request.
+ */
+export declare function decideScopedRetryAfter401(site: string, served: ClaustrumScopedAttempt, current: ClaustrumScopedAttempt | undefined, logger?: ClaustrumLogger): current is ClaustrumScopedAttempt;
+/**
+ * How long a served OAuth token must stay valid after the vault hands it out,
+ * 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. 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;
+    constructor(options: {
+        client: ClaustrumScopedClient;
+        family: ClaustrumFamily;
+        tokenPath?: string;
+        readToken?: () => Promise<EnrollmentTokenFile>;
+        parseIdentity?: IdentityParser;
+        /**
+         * Issue a receipt only when the vault's served reply itself names the
+         * requested credential id and the roster's (known) account identity. For
+         * providers whose tokens are opaque, where nothing else can prove which
+         * account a token belongs to. Off by default: then an absent assertion is
+         * no claim, and the receipt says where its identity came from.
+         */
+        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
+     * never hides every other account. Records outside the family are not
+     * skipped records: they simply are not this consumer's.
+     */
+    discover(signal?: AbortSignal): Promise<VaultInventory>;
+    /**
+     * 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: 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
+     * credential id with the exact record version that send was served, and
+     * signed with the enrollment token that authorized it. A receipt this
+     * 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;
+}