@cortexkit/anthropic-auth-core 2.0.1 → 2.0.3

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/consumer.d.ts

@@ -0,0 +1,132 @@
+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 } 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';
+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;
+    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>;
+}
+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;
+    /** Rows for `/routing`, from the last committed roster. */
+    routingRows(): RoutingRow[];
+    refresh(): Promise<VaultRosterFile | undefined>;
+    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,178 @@
+import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
+import { type ClaustrumLogger } from './errors.js';
+import type { InsulaUsageTransport } from './insula.js';
+export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'> & {
+    insula?: InsulaUsageTransport;
+};
+/** 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;
+}
+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[];
+}
+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;
+}
+/** 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;
+/**
+ * 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.
+ */
+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;
+    });
+    /**
+     * 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>;
+    /**
+     * 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.
+     */
+    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal): 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>;
+    close(): void;
+}

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,16 @@
+/**
+ * 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 {
+    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,19 @@
+import { type ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+import type { ClaustrumScopedClient } from './custody.js';
+export { ClaustrumCredentialError, type ClaustrumReporterSource, type EnrollmentTokenFile, } from '@cortexkit/claustrum-client';
+export { ClaustrumConsumer, type ClaustrumConsumerOptions, type SendOptions, } from './consumer.js';
+export { type AccountIdentitySource, type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, ClaustrumScopedCustody, type ClaustrumScopedIdentity, decideScopedRetryAfter401, type IdentityParser, isScopedCredentialRotation, type ScopedRetryReason, SERVING_MARGIN_MS, type SkippedVaultReason, type SkippedVaultRecord, type VaultCredential, type VaultCredentialType, 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 type { InsulaQuotaContext, InsulaQuotaOptions, InsulaUsageEntry, InsulaUsageTransport, InsulaUsageWindow, } 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';
+/**
+ * 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,69 @@
+import type { ClaustrumClientOptions } from '@cortexkit/claustrum-client';
+/** 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;
+}
+/** Optional transport for custom scoped clients; getUsage must not retry refusals. */
+export interface InsulaUsageTransport {
+    connectionFile: string;
+    getUsage(): Promise<unknown>;
+}
+/** Constructing this transport opens no connection; getUsage opens one per call. */
+export declare function insulaUsageTransport(options: ClaustrumClientOptions & {
+    connectionFile: string;
+}): InsulaUsageTransport;
+export declare class InsulaQuotaSource {
+    #private;
+    private readonly transport;
+    private readonly key;
+    constructor(transport: InsulaUsageTransport, key: string);
+    refresh(now: number): Promise<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;
+};