@cortexkit/anthropic-auth-core 2.0.2 → 2.1.0

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

@@ -0,0 +1,164 @@
+import { type ClaustrumClientOptions as ClaustrumEnrollmentClientOptions, type EnrollmentPollOutcome, type EnrollmentTokenFile, writeEnrollmentTokenFile } from '@cortexkit/claustrum-client';
+/**
+ * Codes the vault's closed enrollment-refusal vocabulary marks permanent. The
+ * client labels some module error frames transient/retry regardless, so the
+ * producer's code takes precedence over the client's action for these.
+ */
+export declare const TERMINAL_ENROLLMENT_CODES: ReadonlySet<string>;
+/** Codes that are always worth another ceremony tick, whatever the action says. */
+export declare const RETRYABLE_ENROLLMENT_CODES: ReadonlySet<string>;
+export type EnrollmentDisposition = 'terminal' | 'retry';
+/**
+ * Classify an enrollment transport refusal as `(code, disposition)`. The
+ * vault's own code wins: a terminal code is terminal even when the client
+ * says retry, queue saturation is retryable even when it says gone, and any
+ * other code follows the client's action. Errors that are not producer
+ * refusals return undefined and are the caller's to rethrow.
+ */
+export declare function classifyEnrollmentError(error: unknown): {
+    code: string;
+    disposition: EnrollmentDisposition;
+} | undefined;
+/**
+ * The name a plugin proposes for one host, for example `openai-auth-opencode`.
+ * Each host enrolls separately so the operator can revoke one without the other.
+ */
+export declare function enrollmentName(plugin: string, host: string): string;
+export interface ClaustrumEnrollmentClient {
+    enrollPropose(input: {
+        name: string;
+        requestSecretHash: string;
+    }): Promise<{
+        requestId: string;
+    }>;
+    enrollPoll(input: {
+        requestId: string;
+        requestSecret: string;
+    }): Promise<EnrollmentPollOutcome>;
+}
+export interface ClaustrumEnrollmentConnection extends ClaustrumEnrollmentClient {
+    close(): void;
+}
+/**
+ * Connect the enrollment ceremony. Setup calls this; the request path never
+ * does. `connectionFile` is required because this library reads no
+ * environment and knows no host paths.
+ */
+export declare function connectClaustrumEnrollmentClient(options: ClaustrumEnrollmentClientOptions & {
+    connectionFile: string;
+}): Promise<ClaustrumEnrollmentConnection>;
+export type ClaustrumEnrollmentStatus = {
+    state: 'idle';
+} | {
+    state: 'pending';
+    proposedName: string;
+    requestId?: string;
+    retryCode?: string;
+} | {
+    state: 'approved';
+    proposedName: string;
+    approvedName?: string;
+    tokenGeneration: number;
+} | {
+    state: 'denied';
+    proposedName: string;
+} | {
+    state: 'blocked';
+    proposedName: string;
+    code: string;
+} | {
+    state: 'unavailable';
+    proposedName: string;
+    code: string;
+} | {
+    state: 'busy';
+};
+export interface ClaustrumEnrollmentPaths {
+    statePath: string;
+    tokenPath: string;
+}
+/** The ceremony state file sits next to the token: `x.json` pairs with `x-state.json`. */
+export declare function getClaustrumEnrollmentPaths(tokenPath: string): ClaustrumEnrollmentPaths;
+/**
+ * One host's token and state paths. Every host gets its own pair under the
+ * plugin's state directory, so an OpenCode enrollment and a Pi enrollment can
+ * be approved and revoked independently. A plugin-resolved override replaces
+ * the default token path; a relative override resolves against `cwd`.
+ */
+export declare function hostEnrollmentPaths(input: {
+    stateDir: string;
+    host: string;
+    override?: string;
+    cwd?: string;
+}): ClaustrumEnrollmentPaths;
+/** Account-file paths are injectable for isolated setup tests; no environment overrides. */
+export interface EnrollmentAncestorOptions {
+    passwdPath?: string;
+    groupPath?: string;
+}
+/**
+ * Protect setup writes from directory replacement. On POSIX, group write access
+ * is safe only when local records prove the effective user's group is private;
+ * sticky ancestors are accepted. Windows uses the shared safe-parent policy.
+ */
+export declare function refuseWritableAncestor(parent: string, options?: EnrollmentAncestorOptions): Promise<void>;
+export declare function readClaustrumEnrollmentStatus(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentStatus>;
+/**
+ * Resolve the host's account mode from its enrollment files. It never changes
+ * their contents or the host's mode. On Windows, reading them may create a
+ * missing private state folder and tighten an enrollment file's permissions to
+ * owner-only, as every private-file read there does.
+ */
+export declare function enrollmentAuthority(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<'vault' | 'local' | 'unreadable'>;
+/**
+ * Read fresh bearer material for one scoped operation; never publish it.
+ * Re-reading per operation is what lets an operator reissue a token on disk.
+ */
+export declare function readClaustrumEnrollmentToken(tokenPath: string): Promise<EnrollmentTokenFile>;
+/**
+ * The enrollment ceremony for one host. Run it from setup only: it proposes,
+ * polls and persists, and every step can wait on an operator. The request
+ * path reads the resulting token and never calls into this class.
+ */
+export declare class ClaustrumEnrollmentManager {
+    #private;
+    constructor(options: {
+        client: ClaustrumEnrollmentClient;
+        paths: ClaustrumEnrollmentPaths;
+        proposedName: string;
+        now?: () => number;
+        mintSecret?: () => string;
+        writeTokenFile?: typeof writeEnrollmentTokenFile;
+        ancestorOptions?: EnrollmentAncestorOptions;
+    });
+    status(): Promise<ClaustrumEnrollmentStatus>;
+    resetTerminal(): Promise<ClaustrumEnrollmentResetResult>;
+    reconcile(): Promise<ClaustrumEnrollmentStatus>;
+}
+export type ClaustrumEnrollmentResetResult = 'reset' | 'idle' | 'refused-pending' | 'refused-approved' | 'busy';
+/** Reset local terminal metadata without connecting to the credential daemon. */
+export declare function resetClaustrumEnrollmentState(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentResetResult>;
+export type ClaustrumEnrollmentDisconnectResult = 'disconnected' | 'idle' | 'busy';
+/**
+ * Disconnect this host from the vault on disk: remove its enrollment token,
+ * then its ceremony state, so `enrollmentAuthority` reports `local` again.
+ * This is the disconnect every plugin uses. Removing only the token is not
+ * enough: an approved state without a token is still vault mode and refuses,
+ * by design. It never contacts the credential daemon, so the enrollment stays
+ * approved in the vault until the operator revokes it there; a later Connect
+ * starts a new ceremony. A pending request is abandoned the same way.
+ *
+ * Takes the ceremony lock `reconcile()` and `resetClaustrumEnrollmentState`
+ * take, and returns `busy` without deleting anything while another process
+ * holds it. State naming another consumer refuses with `wrong-consumer` and
+ * both files stay. The token goes first: a crash between the two deletions
+ * leaves an approved state without a token, which is still vault mode (it
+ * refuses rather than falls back to local accounts), and calling this again
+ * finishes the job. Returns `idle` when neither file exists. Nothing else in
+ * the directory is touched. The token is removed without being parsed, so a
+ * corrupt token does not stand in the way. A malformed state file (bad JSON
+ * or wrong shape) is removed too, since it is what makes `enrollmentAuthority`
+ * report `unreadable`; a state file that fails the safety checks (symlink,
+ * wrong owner, not owner-only) refuses with `unsafe-file` and both files stay.
+ */
+export declare function disconnectClaustrumEnrollment(paths: ClaustrumEnrollmentPaths, proposedName: string): Promise<ClaustrumEnrollmentDisconnectResult>;

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

@@ -0,0 +1,17 @@
+/**
+ * Every refusal the `/claustrum` code raises itself. Refusals sent by the
+ * vault keep arriving as the client's own `ClaustrumCredentialError` (a
+ * `code`, a `class` and an `action`), so callers can tell the vault's verdict
+ * apart from a check made on this side.
+ */
+export type ClaustrumConsumerFailureKind = 'closed' | 'not-enrolled' | 'invalid-token' | 'unavailable' | 'identity-changed' | 'identity-unasserted' | 'insufficient-validity' | 'invalid-material' | 'not-active' | 'route-unavailable' | 'route-declined' | 'no-receipt' | 'unsafe-file' | 'invalid-state' | 'wrong-consumer' | 'roster-busy' | 'host-slot-login' | 'host-slot-placeholder' | 'placeholder-refresh';
+export declare class ClaustrumConsumerError extends Error {
+    readonly kind: ClaustrumConsumerFailureKind;
+    constructor(kind: ClaustrumConsumerFailureKind, message: string);
+}
+/** 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;
+}

package/dist/internal-types/claustrum/host-slot.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The host's own auth slot (OpenCode's stored login for the provider, Pi's
+ * equivalent) must hold something, or the host drops the provider. Under
+ * custody it holds this placeholder: an OAuth-shaped value that is never a
+ * credential. Its empty access token also makes the vault's sealer refuse it,
+ * should it ever be offered for import.
+ */
+export declare const CUSTODY_PLACEHOLDER_PREFIX = "claustrum-tombstone:v1:";
+export declare function custodyPlaceholderKey(provider: string): string;
+export declare function custodyPlaceholder(provider: string): {
+    type: 'oauth';
+    access: '';
+    refresh: string;
+    expires: 0;
+};
+export declare function isCustodyPlaceholderValue(value: unknown): value is string;
+export declare function isCustodyPlaceholder(auth: unknown, provider: string): boolean;
+/** What the host slot holds: the custody placeholder, a real login, or nothing usable. */
+export type HostSlotContent = 'placeholder' | 'login' | 'empty';
+export declare function classifyHostSlot(auth: unknown, provider: string): HostSlotContent;
+/**
+ * Check the host slot against the plugin's mode before serving anything.
+ *
+ * - Custody mode with a real login in the slot fails closed: someone signed in
+ *   through the host while the vault owns the accounts, and serving either the
+ *   login or the vault would silently pick one. The plugin surfaces the error
+ *   and the user chooses (leave custody, or remove the login).
+ * - Local mode with the placeholder in the slot also fails: there is no local
+ *   credential to serve, and the user has to sign in.
+ *
+ * Returns the slot content when the combination is consistent.
+ */
+export declare function assertHostSlotMatchesMode(input: {
+    mode: 'custody' | 'local';
+    auth: unknown;
+    provider: string;
+}): HostSlotContent;
+/** Refuse to run a local token refresh with the placeholder as the refresh token. */
+export declare function assertNotCustodyPlaceholder(refreshToken: unknown, provider: string): void;

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

@@ -0,0 +1,21 @@
+import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+import type { ClaustrumScopedClient } from './custody.js';
+export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
+export { ClaustrumUnreachableError, classifyVaultFailure, VAULT_FAILURE_CLASSES, type VaultFailureClass, } from './availability.js';
+export { ClaustrumConsumer, type ClaustrumConsumerOptions, type ClaustrumWatchState, type SendOptions, } from './consumer.js';
+export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumRosterWatch, type ClaustrumRosterWatchOptions, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, KEPT_RECEIPT_MARGIN_MS, type KeptReceiptState, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, type VaultGrantReach, type VaultGrantTuple, type VaultInventory, } from './custody.js';
+export { type ClaustrumEnrollmentClient, type ClaustrumEnrollmentConnection, type ClaustrumEnrollmentDisconnectResult, ClaustrumEnrollmentManager, type ClaustrumEnrollmentPaths, type ClaustrumEnrollmentResetResult, type ClaustrumEnrollmentStatus, classifyEnrollmentError, connectClaustrumEnrollmentClient, disconnectClaustrumEnrollment, type EnrollmentDisposition, enrollmentAuthority, enrollmentName, getClaustrumEnrollmentPaths, hostEnrollmentPaths, RETRYABLE_ENROLLMENT_CODES, readClaustrumEnrollmentStatus, readClaustrumEnrollmentToken, resetClaustrumEnrollmentState, TERMINAL_ENROLLMENT_CODES, } from './enrollment.js';
+export { ClaustrumConsumerError, type ClaustrumConsumerFailureKind, type ClaustrumLogger, } from './errors.js';
+export { assertHostSlotMatchesMode, assertNotCustodyPlaceholder, CUSTODY_PLACEHOLDER_PREFIX, classifyHostSlot, custodyPlaceholder, custodyPlaceholderKey, type HostSlotContent, isCustodyPlaceholder, isCustodyPlaceholderValue, } from './host-slot.js';
+export { acquireInsulaQuotaSource, type InsulaQuotaContext, type InsulaQuotaOptions, type InsulaQuotaSource, type InsulaUsageEntry, type InsulaUsageTransport, type InsulaUsageWatch, type InsulaUsageWindow, type InsulaWatchOptions, } from './insula.js';
+export { acceptAccount, type DeclinedAccount, declineAccount, isDeclined, } from './interlock.js';
+export { type AccountMapper, acceptVaultRoute, DEFAULT_ROUTE_PREFIX, declineVaultRoute, type MutateVaultRosterOptions, mutateVaultRoster, type ProjectionOptions, projectVaultRoster, type QuotaReceipt, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, resolveVaultPrimary, type VaultPrimary, type VaultPrimaryBinding, type VaultPrimaryUnavailableReason, type VaultRosterFile, type VaultRosterLockContext, type VaultRosterRow, vaultRoutingRows, } from './roster.js';
+export { type ChangeNotice, ChangeNoticeReader, RESUBSCRIBE_BACKOFF_MS, SAFETY_POLL_MS, ScopedRosterWatch, type ScopedRosterWatchOptions, type ScopedWatchEnd, type ScopedWatchHandle, type ScopedWatchNoticeShape, type ScopedWatchSource, WATCH_RETRY_MS, type WatchMode, } from './watch.js';
+/**
+ * Connect the client that lists and fetches this consumer's vault credentials
+ * on the request path. `connectionFile` is required: this library
+ * reads no environment, so the plugin resolves the vault's connection file.
+ */
+export declare function connectClaustrumScopedClient(options: ClaustrumClientOptions & {
+    connectionFile: string;
+}): Promise<ClaustrumScopedClient>;

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

@@ -0,0 +1,117 @@
+import type { ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+import { type WatchMode } from './watch.js';
+/** Insula's window fields are open: plugins choose which limits they understand. */
+export interface InsulaUsageWindow {
+    usedPercent: number;
+    rawUsedPercent?: number;
+    resetsAt?: string;
+    windowMinutes?: number;
+    windowKind?: string;
+    [field: string]: unknown;
+}
+export interface InsulaUsageEntry {
+    provider: string;
+    account?: string;
+    fetchedAt?: string;
+    source?: string;
+    stale?: unknown;
+    errorClass?: unknown;
+    usage?: {
+        primary?: InsulaUsageWindow;
+        secondary?: InsulaUsageWindow;
+        tertiary?: InsulaUsageWindow;
+        extraRateWindows?: Array<{
+            id?: string;
+            title?: string;
+            window?: InsulaUsageWindow;
+        }>;
+        [field: string]: unknown;
+    };
+    [field: string]: unknown;
+}
+export interface InsulaQuotaContext {
+    /** Milliseconds since the epoch, parsed from the producer's fetchedAt. */
+    fetchedAt: number;
+    source?: string;
+}
+export interface InsulaQuotaOptions<Q> {
+    provider: 'codex' | 'claude' | 'antigravity';
+    /**
+     * Set every converted window's reading time to context.fetchedAt, not poll
+     * time. Return undefined for entries the plugin cannot use. Antigravity can
+     * receive its own sidebar reading back from insula: accept it only from the
+     * vault or when fetchedAt is newer than the plugin's last reading.
+     */
+    normalize: (entry: InsulaUsageEntry, context: InsulaQuotaContext) => Q | undefined;
+}
+/**
+ * A held-open `usage.watch` stream. `closed` resolves when insula ends the
+ * stream (STREAM_END at shutdown, or a reply that ends it) or after `stop()`,
+ * and rejects with insula's refusal (an error with a `code`, such as
+ * `unknown_method` from an insula that predates the method, or
+ * `usage_watch_limit` when 64 watches are already open) or with the
+ * transport failure.
+ */
+export interface InsulaUsageWatch {
+    stop(): void;
+    readonly closed: Promise<void>;
+}
+/** Optional transport for custom scoped clients; getUsage must not retry refusals. */
+export interface InsulaUsageTransport {
+    connectionFile: string;
+    getUsage(): Promise<unknown>;
+    /**
+     * Open a `usage.watch` stream, passing each notice's raw JSON body to
+     * `onNotice`. Optional: a transport without it is polled as before.
+     */
+    watchUsage?(onNotice: (body: Uint8Array) => void): InsulaUsageWatch;
+}
+/** Constructing this transport opens no connection; getUsage opens one per call. */
+export declare function insulaUsageTransport(options: ClaustrumClientOptions & {
+    connectionFile: string;
+}): InsulaUsageTransport;
+export interface InsulaWatchOptions {
+    /**
+     * The provider this watcher reads. A notice that names only other
+     * providers then needs no read; unset means every notice does.
+     */
+    provider?: string;
+    /**
+     * setTimeout and clearTimeout for the waits before re-subscribing or retrying
+     * a watch. Defaults to the global timers; tests inject virtual ones.
+     */
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+}
+export declare class InsulaQuotaSource {
+    #private;
+    private readonly transport;
+    private readonly key;
+    constructor(transport: InsulaUsageTransport, key: string);
+    /**
+     * The background poll: at most one usage.get per minute per daemon and
+     * enrollment token. While a watch is open it reads nothing, because insula's
+     * notices announce every new reading. If insula stops announcing an account,
+     * that account's last entry grows older than the freshness limit `current()`
+     * applies, `current()` returns nothing for it, and the plugin falls back to
+     * its own provider poll for that account.
+     */
+    refresh(now: number): Promise<void>;
+    /** How this source currently learns about usage changes, for logs. */
+    watchMode(): WatchMode;
+    /**
+     * Hold a `usage.watch` open while any watcher wants it, and re-read
+     * usage.get when a notice says something changed. Watchers of one source
+     * share one watch, since insula admits only 64 per process. Returns the
+     * release; the last release closes the watch.
+     */
+    watch(options?: InsulaWatchOptions): () => void;
+    current(provider: string, accountId: string, now: number): {
+        entry: InsulaUsageEntry;
+        context: InsulaQuotaContext;
+    } | undefined;
+}
+export declare function acquireInsulaQuotaSource(transport: InsulaUsageTransport, tokenPath: string): {
+    source: InsulaQuotaSource;
+    release(): void;
+};

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

@@ -0,0 +1,27 @@
+/**
+ * The declined-account interlock: the user's "do not use this vault account",
+ * kept on the consumer side because the vault has no notion of it.
+ *
+ * A decline follows the provider account, not the vault record: an entry made
+ * while the account was known matches any credential id or alias that logs
+ * into that same account, so relabelling, adding an alias or removing and
+ * re-adding the account never lifts it. A credential id that now logs into a
+ * different known account does not match, because that account has its own
+ * policy. While either side's account is unknown the entry falls back to the
+ * credential id, so an adapter that makes no identity claim cannot slip past
+ * it. Never keyed on the record version, so a token refresh cannot lift it.
+ */
+export interface DeclinedAccount {
+    readonly credentialId: string;
+    readonly accountIdentity?: string;
+}
+export declare function isDeclined(entries: readonly DeclinedAccount[], credentialId: string, accountIdentity?: string): boolean;
+export declare function declineAccount(entries: readonly DeclinedAccount[], credentialId: string, accountIdentity?: string): DeclinedAccount[];
+/**
+ * Lift every entry that declines a row: the row's credential ids (the
+ * representative and its aliases) under the row's account. An entry for a
+ * different known account is left alone even when it names one of these
+ * credential ids, so accepting a replacement never re-enables the account the
+ * user declined.
+ */
+export declare function acceptAccount(entries: readonly DeclinedAccount[], credentialIds: readonly string[], accountIdentity?: string): DeclinedAccount[];

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

@@ -0,0 +1,221 @@
+import { type QuotaMap, type QuotaObservation } from '../quota/index.js';
+import type { RoutingRow } from '../routing/index.js';
+import type { ClaustrumScopedAttempt, ClaustrumScopedCustody, SkippedVaultRecord, VaultCredential, VaultCredentialType, VaultInventory } from './custody.js';
+import { type DeclinedAccount } from './interlock.js';
+/**
+ * One vault account as the pool sees it. It carries no bearer material: the
+ * access token is fetched from the vault for every send. Several vault
+ * records logged into the same provider account collapse into one row, so
+ * duplicate logins never count as extra quota.
+ */
+export interface VaultRosterRow {
+    routeId: string;
+    credentialId: string;
+    credentialType: VaultCredentialType;
+    accountIdentity?: string;
+    /** Other credential ids logged into the same provider account. */
+    aliases?: string[];
+    state: string;
+    label: string;
+    email?: string;
+    orgName?: string;
+    enabled: boolean;
+    addedAt: number;
+    quota?: QuotaMap;
+    /**
+     * The vault listed this record in a form this consumer could not use, so the
+     * row is the last good projection kept as it was rather than dropped.
+     */
+    stale?: true;
+    /**
+     * The vault's latest list named no account for `credentialId`, so
+     * `accountIdentity` is the last account that credential was known to log
+     * into, kept until the vault names one again. It proves neither that the
+     * credential still logs into that account nor that it changed accounts.
+     */
+    unclaimed?: true;
+}
+export interface VaultRosterFile {
+    version: 1;
+    view?: string;
+    /**
+     * False when the vault's reply carried records this consumer could not use.
+     * An incomplete reply never removes an account it may still hold: every
+     * previous member it does not account for is kept.
+     */
+    complete: boolean;
+    /** The unusable records of an incomplete reply: a safe id and a fixed reason. */
+    rejected?: SkippedVaultRecord[];
+    rows: VaultRosterRow[];
+    declined: DeclinedAccount[];
+}
+/** How a vault credential is presented in the pool. */
+export type AccountMapper = (credential: VaultCredential) => {
+    label?: string;
+};
+export interface ProjectionOptions {
+    /** Ids already used by local rows; a vault route never takes one. */
+    reservedRouteIds?: ReadonlySet<string>;
+    /** Prefix for vault route ids, so they read differently from local ids. */
+    routePrefix?: string;
+    mapAccount?: AccountMapper;
+    now?: number;
+}
+export declare const DEFAULT_ROUTE_PREFIX = "vault:";
+/**
+ * Project the vault's list onto the previous roster. Pure: callers serialize
+ * discovery and commit. Route ids, quota and the time an account was added
+ * survive for the same account; a credential that now logs into a different
+ * known account gets a new route id and no inherited quota.
+ *
+ * A record listed without an identity keeps the last account it was known to
+ * log into (the row is marked `unclaimed`). Dropping that binding would let a
+ * later different account look like an identity learned for the first time
+ * and inherit the first account's route and quota.
+ *
+ * A reply with unusable records is incomplete: a previous member it does not
+ * account for (its record was rejected, or a rejected record has no usable id
+ * and could be any of them) is kept, as an alias of its live account or as a
+ * `stale` row. Only a complete reply removes an account.
+ */
+export declare function projectVaultRoster(previous: VaultRosterFile | undefined, inventory: VaultInventory, options?: ProjectionOptions): VaultRosterFile;
+/**
+ * The rows `/routing` selects among. Only enabled, active accounts route;
+ * a declined or cold vault account stays listed for the menu but never
+ * reaches admission.
+ */
+export declare function vaultRoutingRows(roster: VaultRosterFile | undefined): RoutingRow[];
+export declare function readVaultRoster(path: string): Promise<VaultRosterFile | undefined>;
+/** The ownership assertion available to a roster mutation callback. */
+export interface VaultRosterLockContext {
+    assertOwned: () => Promise<void>;
+}
+export interface MutateVaultRosterOptions {
+    /**
+     * Runs when the new roster is fully staged on disk, immediately before the
+     * rename that publishes it, so a caller can confirm a lease of its own at
+     * the moment of publication rather than when `change` returned. If it
+     * throws, nothing is published and the staged file is removed. The
+     * roster's own write lock is reasserted right after it.
+     */
+    beforePublish?: () => Promise<void>;
+}
+/**
+ * Read, change and write the roster under its write lock. `change` returns
+ * undefined to leave the file as it is. Call `assertOwned()` immediately
+ * before any rename performed inside `change`; if it throws, do not rename.
+ */
+export declare function mutateVaultRoster<T>(path: string, change: (current: VaultRosterFile | undefined, context: VaultRosterLockContext) => Promise<{
+    next?: VaultRosterFile;
+    result: T;
+}> | {
+    next?: VaultRosterFile;
+    result: T;
+}, options?: MutateVaultRosterOptions): Promise<T>;
+/** Mark a vault account declined; it stays listed but never routes. */
+export declare function declineVaultRoute(path: string, routeId: string): Promise<undefined>;
+/** Lift the user's decline for a vault account and every alias of it. */
+export declare function acceptVaultRoute(path: string, routeId: string): Promise<undefined>;
+/**
+ * The receipt fields a quota or profile observation must carry to say which
+ * send (credential and account) it came from. Pass the
+ * `ClaustrumScopedAttempt` that send was authorized with.
+ */
+export type QuotaReceipt = Pick<ClaustrumScopedAttempt, 'credentialId' | 'accountIdentity' | 'accountIdentitySource' | 'expectedAccountIdentity'>;
+/**
+ * Merge a quota observation into a vault row through `/quota`'s merge. The
+ * write is fenced on the receipt the reading was taken with: it lands only
+ * while the row still holds that receipt's credential (as representative or
+ * alias) and account, so a slow read for a replaced account can never land on
+ * its successor. Returns whether the observation was kept.
+ */
+export declare function recordVaultQuota(path: string, input: QuotaReceipt & {
+    routeId: string;
+    observation: QuotaObservation;
+}): Promise<boolean>;
+/**
+ * Merge a quota observation that belongs to an account rather than to a
+ * served credential, such as a background reading from insula. The write
+ * lands only while the row is still bound to that exact known account, so a
+ * reading taken before a replacement never reaches the successor. Unlike
+ * `recordVaultQuota` it never binds an account: a row without a known account
+ * is refused. Returns whether the observation was kept.
+ */
+export declare function recordVaultAccountQuota(path: string, input: {
+    routeId: string;
+    accountIdentity: string;
+    observation: QuotaObservation;
+}): Promise<boolean>;
+/**
+ * Discover and commit the roster. The lease covers the list call and the
+ * commit, not just the write: an opaque view cannot tell a delayed old reply
+ * from a newer one, so a run that lost its lease is refused at commit. A
+ * failed list, or custody switching off mid-run, never writes anything; a
+ * peer holding the lease means its last committed roster is served instead.
+ */
+export declare function refreshVaultRoster(options: {
+    path: string;
+    custody: Pick<ClaustrumScopedCustody, 'discover'>;
+    isActive?: () => boolean | Promise<boolean>;
+    signal?: AbortSignal;
+    projection?: ProjectionOptions | (() => ProjectionOptions);
+}): Promise<VaultRosterFile | undefined>;
+/**
+ * A host-owned main account as last verified from the vault: the plugin's
+ * logical route, the credential that serves it and the account it logs into.
+ */
+export interface VaultPrimaryBinding {
+    routeId: string;
+    credentialId: string;
+    accountIdentity: string;
+    view: string;
+}
+export type VaultPrimaryUnavailableReason = 'malformed' | 'unclaimed' | 'incomplete' | 'identity-changed';
+export type VaultPrimary = 
+/**
+ * Main is bound. `replaced` is the previous binding when it named a
+ * different account: everything owned by that account (quota, profile,
+ * backoff, cache affinity) must be dropped, and outstanding observations
+ * for it fenced, even though the logical route stays the same.
+ */
+{
+    status: 'ready';
+    binding: VaultPrimaryBinding;
+    replaced?: VaultPrimaryBinding;
+}
+/** A complete reply lists no primary record: there is no main. */
+ | {
+    status: 'absent';
+}
+/**
+ * The reply cannot say who main is. Not the same as absent: the last
+ * verified binding is handed back untouched, and serving it still needs a
+ * fresh receipt that matches it.
+ */
+ | {
+    status: 'unavailable';
+    reason: VaultPrimaryUnavailableReason;
+    lastVerified?: VaultPrimaryBinding;
+};
+/**
+ * The seam for a plugin that keeps a main account: one fixed account the host
+ * owns under a logical route, outside the pool's rotating rows. The library
+ * has no main convention of its own: the plugin names the
+ * vault record that holds the role (`primaryCredentialId`) and its logical
+ * route. Main follows the account that record claims; another credential of
+ * that same account may serve it when the record itself is not active, but a
+ * credential of any other account is never promoted into main.
+ *
+ * Inputs are the plugin's filtered inventory, whether that inventory is
+ * complete (defaults to the reply having no unusable records; pass the
+ * roster's `complete` or false to override), the previous verified binding
+ * and, on the request path, the account the chosen request expects.
+ */
+export declare function resolveVaultPrimary(input: {
+    inventory: VaultInventory;
+    complete?: boolean;
+    previous?: VaultPrimaryBinding;
+    expectedAccountIdentity?: string;
+    primaryCredentialId: string;
+    routeId: string;
+}): VaultPrimary;