@cortexkit/anthropic-auth-core 1.23.0 → 2.0.0

package/dist/native-account-runtime.d.ts

@@ -0,0 +1,121 @@
+import { type PoolCredential } from "./internal-types/store/index.js";
+import { type OAuthAccountProfile, type OAuthQuotaSnapshot, type PrimeUsageDelta } from './accounts.ts';
+import { type LogLevel } from './logger.ts';
+import { type NativeAccountMetadataPatch, type NativeAccountSnapshot, type NativeAccountView } from './native-account-view.ts';
+import { type NativeCustodyReceipt } from './native-custody.ts';
+import { type NativeLocalCredentialServiceOptions } from './native-local-credential-service.ts';
+import type { NativeLocalExternalPolicy } from './native-local-runtime-readers.ts';
+import type { NativeKnownCredentialSubject, NativeRefreshResult, NativeRefreshSubject } from './native-refresh-coordinator.ts';
+import { type NativeDisplayProfile, type NativeVaultRuntime, type NativeVaultRuntimeOptions } from './native-vault-runtime.ts';
+import { type NativeLocalPoolBinding } from './pool-binding.ts';
+import type { NativePoolPaths } from './pool-paths.ts';
+import type { QuotaRequestDispatch } from './quota-manager.ts';
+import type { RelayConfig } from './relay.ts';
+export type { NativeAccountMetadataPatch, NativeAccountSnapshot, NativeAccountView, } from './native-account-view.ts';
+export interface NativeAccountRuntimeOptions {
+    paths: NativePoolPaths;
+    host: 'opencode' | 'pi';
+    /** The opencode-anthropic-auth setup command rechecks that hosts are stopped before credential-file writes, so migration cannot change credentials used by a running host. */
+    beforePoolWrite?: () => Promise<void>;
+    local?: Partial<Pick<NativeLocalCredentialServiceOptions, 'refreshToken' | 'resolveIdentity' | 'failurePolicy' | 'now'>>;
+    vault?: Omit<NativeVaultRuntimeOptions, 'paths' | 'host'>;
+}
+export interface NativeLocalAuthorizeOptions {
+    intent?: 'serve' | 'refresh';
+    rejectedAccessToken?: string;
+    signal?: AbortSignal;
+    policy?: (account: NativeAccountView, snapshot: NativeAccountSnapshot) => NativeLocalExternalPolicy;
+}
+export interface NativeAccountWriteInput {
+    routeId: string;
+    credential: PoolCredential;
+    accountIdentity?: string;
+    label?: string;
+    replace?: boolean;
+}
+export interface NativeApiSubject {
+    kind: 'api';
+    binding: NativeLocalPoolBinding;
+    credentialFingerprint: string;
+    baseURL: string;
+    authHeader?: 'authorization-bearer' | 'x-api-key';
+}
+export type NativeRelayUpdate = Partial<Omit<RelayConfig, 'token'>> & {
+    token?: string | null;
+};
+export interface NativeAccountRuntime {
+    readonly vault: NativeVaultRuntime;
+    /** Fresh private relay authorization for transport only; never include it in a status snapshot. */
+    getRelayConfig(): Promise<RelayConfig | null>;
+    updateRelay(patch: NativeRelayUpdate): Promise<void>;
+    read(): Promise<NativeAccountSnapshot>;
+    authorizeLocal(routeId: string, options?: NativeLocalAuthorizeOptions): Promise<NativeRefreshResult>;
+    authorizeApi(routeId: string, signal?: AbortSignal): Promise<{
+        type: 'api';
+        apiKey: string;
+        baseURL: string;
+        authHeader?: 'authorization-bearer' | 'x-api-key';
+        subject: NativeApiSubject;
+    }>;
+    authorizeVault(routeId: string, signal?: AbortSignal): Promise<NativeCustodyReceipt>;
+    loginOAuth(input: {
+        routeId: string;
+        credential: {
+            access: string;
+            refresh: string;
+            expires: number;
+        };
+        accountIdentity?: string;
+        label?: string;
+        replace?: boolean;
+    }): Promise<NativeAccountView>;
+    putAccount(input: NativeAccountWriteInput): Promise<NativeAccountView>;
+    addApi(input: {
+        routeId?: string;
+        apiKey: string;
+        baseURL?: string;
+        authHeader?: 'authorization-bearer' | 'x-api-key';
+        label?: string;
+        replace?: boolean;
+    }): Promise<NativeAccountView>;
+    updateSettings(mutator: (settings: Record<string, unknown>) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>): Promise<{
+        settings: Record<string, unknown>;
+        outcome: 'updated' | 'unchanged';
+    }>;
+    /**
+     * Store `level` as the logging level, then make it this process's live
+     * logger level if it is not already, even when the stored value was
+     * unchanged. Nothing is applied when the write fails.
+     */
+    setLoggingLevel(level: LogLevel): Promise<void>;
+    setEnabled(routeId: string, enabled: boolean): Promise<void>;
+    remove(routeId: string): Promise<void>;
+    /**
+     * `movedRouteId` names the account the caller moved; it identifies the
+     * account in the change's INFO log and does not affect the order written.
+     */
+    reorder(routeIds: readonly string[], movedRouteId?: string): Promise<void>;
+    captureLocalSubject(routeId: string): Promise<NativeRefreshSubject>;
+    publishLocal(subject: NativeKnownCredentialSubject, patch: NativeAccountMetadataPatch): Promise<boolean>;
+    publishApi(subject: NativeApiSubject, patch: {
+        lastUsed: number;
+    }): Promise<boolean>;
+    resetBackoff(routeId: string, fence: NativeRefreshSubject | NativeCustodyReceipt, kind?: 'refresh' | 'quota' | 'all'): Promise<boolean>;
+    getOrCreateAuthLineage(routeId: string, fence: NativeKnownCredentialSubject | NativeCustodyReceipt): Promise<string | undefined>;
+    incrementPrimeUsage(routeId: string, fence: NativeKnownCredentialSubject | NativeCustodyReceipt, delta?: PrimeUsageDelta): Promise<boolean>;
+    fetchQuota(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal, dispatch?: QuotaRequestDispatch): Promise<OAuthQuotaSnapshot>;
+    fetchProfile(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<OAuthAccountProfile>;
+    /** Like fetchProfile, but returns before the profile is saved; see NativeDisplayProfile. */
+    fetchProfileForDisplay(routeId: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<NativeDisplayProfile>;
+    close(): void;
+}
+/** Host instances own leases, while stores and the vault connection live until the last release. */
+export declare function acquireNativeAccountRuntime(options: NativeAccountRuntimeOptions): NativeAccountRuntime;
+/** Evaluate quota and killswitch policy for this caller's model, outside shared credential refresh work. */
+export declare function nativeAccountPolicy(account: NativeAccountView, snapshot: NativeAccountSnapshot, modelId?: string): NativeLocalExternalPolicy;
+/** The local migration journal records completed transfer from host credentials and sidecars to the credential pool. Local use refuses without that record. Host vault enrollment instead selects independent settings and metadata, leaving local credentials, journal and metadata untouched. */
+export declare function createNativeAccountRuntime(options: NativeAccountRuntimeOptions): NativeAccountRuntime;
+export declare function primeDelta(delta: PrimeUsageDelta): {
+    inputTokens: number;
+    outputTokens: number;
+};

package/dist/native-account-view.d.ts

@@ -0,0 +1,126 @@
+import { type PoolRow } from "./internal-types/store/index.js";
+import { type AccountOperationError, type AccountStorage, type OAuthAccountProfile, type OAuthQuotaSnapshot, type PrimeUsageCounters } from './accounts.ts';
+import type { NativeVaultRosterDocument } from './native-roster-seed.ts';
+import type { NativeRuntimeEntry, NativeRuntimeState } from './native-runtime.ts';
+import type { NativeVaultRoutingSeed } from './native-vault-seed.ts';
+import { type NativeLocalPoolBinding } from './pool-binding.ts';
+import type { NativePoolPaths } from './pool-paths.ts';
+/** Display and policy metadata, not evidence that a presented token was accepted for this account. */
+export interface NativeAccountView {
+    id: string;
+    type: 'oauth' | 'api';
+    source: 'local' | 'vault';
+    enabled: boolean;
+    label?: string;
+    addedAt?: number;
+    accountIdentity?: string;
+    binding?: NativeLocalPoolBinding;
+    credentialId?: string;
+    state?: string;
+    quota?: OAuthQuotaSnapshot;
+    profile?: OAuthAccountProfile;
+    prime?: PrimeUsageCounters;
+    lastUsed?: number;
+    lastRefreshedAt?: number;
+    lastRefreshError?: AccountOperationError;
+    lastQuotaRefreshError?: AccountOperationError;
+    quotaErrorClearedAt?: number;
+    quotaErrorGeneration?: number;
+    refreshErrorClearedAt?: number;
+    baseURL?: string;
+    authHeader?: 'authorization-bearer' | 'x-api-key';
+}
+/**
+ * One-line status text for an account's state, shared by host status
+ * displays. A local account in 'unsupported-access' holds a saved access value
+ * that is not a Claude OAuth access token; it is never sent to Claude or
+ * refreshed, so the text names the remedy. Other states, such as vault
+ * credential states, are shown as recorded. Returns '' when there is no state.
+ */
+export declare function formatNativeAccountState(view: Pick<NativeAccountView, 'state'>): string;
+export interface NativeAccountSnapshot {
+    mode: 'local' | 'claustrum';
+    settings: Record<string, unknown>;
+    accounts: NativeAccountView[];
+    /** Vault session-to-account assignments use this separate file. Local mode keeps the assignment file at the destination recorded by migration. */
+    routingPath?: string;
+    routingSeed?: NativeVaultRoutingSeed;
+    /** AccountStorage-shaped input for pure policy predicates, never a credential or persistence authority. */
+    policyStorage: AccountStorage;
+}
+export interface NativeAccountMetadataPatch {
+    quota?: OAuthQuotaSnapshot;
+    profile?: OAuthAccountProfile;
+    lastUsed?: number;
+    lastQuotaRefreshError?: AccountOperationError;
+    quotaErrorClearedAt?: number;
+    quotaErrorGeneration?: number;
+    prime?: PrimeUsageCounters;
+    authLineageId?: string;
+}
+/** Copy data without invoking caller getters, proxies, serializers or callbacks. */
+export declare function captureNativePlainData(input: unknown): unknown;
+export declare function captureNativeMetadataPatch(patch: NativeAccountMetadataPatch): NativeAccountMetadataPatch;
+export declare function applyNativeMetadataPatch(entry: NativeRuntimeEntry, patch: NativeAccountMetadataPatch): NativeRuntimeEntry;
+/** Keep established retry policy without persisting provider bodies or arbitrary exception text. */
+export declare function nativeQuotaFailure(error: unknown, accountIdentity: string | undefined, checkedAt: number, previous?: AccountOperationError): AccountOperationError | undefined;
+export declare class NativeAccountReadError extends Error {
+    readonly status?: number | undefined;
+    readonly retryAfter?: number | undefined;
+    readonly code?: 'ECONNRESET' | undefined;
+    constructor(status?: number | undefined, retryAfter?: number | undefined, code?: 'ECONNRESET' | undefined);
+}
+/** Keep the HTTP status and retry classification. Omit provider error text and nested causes because they can contain credentials. */
+export declare function nativeAccountReadError(error: unknown, responseStatus?: number): NativeAccountReadError;
+export declare const NATIVE_PRIMARY_CREDENTIAL_ID = "oauth:anthropic";
+export interface NativeVaultPrimaryPin {
+    routeId: string;
+    credentialId: string;
+    accountIdentity: string;
+}
+/** Vault discovery saves the default credential ID, route ID and verified account UUID in vault settings. Readers compare that UUID to the current roster so a replaced default cannot inherit another account's metadata. */
+export declare function nativeVaultPrimaryPin(settings: Record<string, unknown>): NativeVaultPrimaryPin | undefined;
+export declare function nativeVaultPrimaryRow(roster: NativeVaultRosterDocument | undefined, pin: NativeVaultPrimaryPin | undefined): {
+    readonly routeId: string;
+    readonly credentialId: string;
+    readonly credentialType: 'oauth' | 'api_key';
+    readonly accountIdentity?: string;
+    readonly aliases?: readonly string[];
+    readonly state: string;
+    readonly label: string;
+    readonly email?: string;
+    readonly orgName?: string;
+    readonly enabled: boolean;
+    readonly addedAt: number;
+    readonly quota?: unknown;
+    readonly stale?: true;
+    readonly unclaimed?: true;
+} | undefined;
+export declare function nativeAccountSettings(settings: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Whether a local OAuth row is held back only because another writer is part
+ * way through saving it, for example a refresh that has written the state
+ * file naming the row's first account UUID but not yet the config file.
+ *
+ * True only when the row is torn and would otherwise be an enabled,
+ * coherent candidate: it holds a credential, is not disabled (including
+ * quarantine and duplicate-identity disables), staged, invalid or unbound,
+ * and its stamp is bound to that credential. Such a row is shown enabled but
+ * without a binding: it may be chosen for a request, and local authorization
+ * then waits for the write to finish before it can serve.
+ *
+ * A different stored credential epoch can belong to a replacement. Keep
+ * the existing refusal for mismatched epochs rather than use old metadata
+ * as evidence that this write only learns the account's first UUID.
+ */
+export declare function nativeLocalRowAwaitsTornWrite(paths: NativePoolPaths, row: PoolRow, stored?: NativeRuntimeEntry): boolean;
+/** `nativeLocalRowAwaitsTornWrite` for the row a route id names, mapped as the account projection maps it. */
+export declare function nativeLocalRouteAwaitsTornWrite(paths: NativePoolPaths, rows: readonly PoolRow[], settings: Record<string, unknown>, routeId: string, runtime?: NativeRuntimeState): boolean;
+/** Join quota, profile and errors only for matching storage, account and credential generation; a reused route must not expose its previous account. */
+export declare function projectNativeAccountViews(input: {
+    paths: NativePoolPaths;
+    rows: readonly PoolRow[];
+    settings: Record<string, unknown>;
+    runtime?: NativeRuntimeState;
+    roster?: NativeVaultRosterDocument;
+}): NativeAccountSnapshot;

package/dist/native-command-effects.d.ts

@@ -0,0 +1,59 @@
+import { type LogLevel } from './logger.ts';
+/**
+ * In-process effects of a committed native account or settings change.
+ *
+ * NativeAccountRuntime calls these logging and live-level helpers after its
+ * write has been committed. Account
+ * and settings effects follow only from what that write changed, so every
+ * host's /claude actions emit the same INFO records, and a refused or failed
+ * write has no effect. The one exception to "unchanged means no effect" is the
+ * explicit logging-level command (NativeAccountRuntime.setLoggingLevel): when
+ * its stored level is already the requested one, it still sets this process's
+ * live logger level if that differs. Payloads carry account ids, labels and
+ * setting values only, never credential material.
+ */
+type Settings = Record<string, unknown>;
+/** The setting values whose changes have effects, read before a settings mutator can edit its copy. */
+export interface NativeSettingsEffectFields {
+    killswitchEnabled: boolean;
+    killswitchMain: Record<string, number> | undefined;
+    killswitchAccounts: Record<string, Record<string, number>> | undefined;
+    logLevel: string | undefined;
+}
+export declare function captureNativeSettingsEffectFields(settings: Settings): NativeSettingsEffectFields;
+/**
+ * Log the killswitch and logging-level changes between the settings before a
+ * committed write and the settings that write left on disk, then apply a
+ * changed stored logging level to this process's logger. Threshold changes
+ * are compared and logged through the numeric projection only.
+ */
+export declare function applyCommittedNativeSettingsEffects(before: NativeSettingsEffectFields, committed: Settings): void;
+/**
+ * Make `level` this process's live logger level when it is not already, and
+ * record the change. The INFO record is emitted before the new level is
+ * applied, so it is filtered by the level in force until then: changing from
+ * info to warn leaves the record in the log, while changing from warn or error
+ * to info emits none. Returns whether the live level changed.
+ */
+export declare function applyNativeLogLevel(level: LogLevel): boolean;
+export type NativeAccountChange = 'account enabled' | 'account disabled' | 'account removed' | 'account reordered';
+/**
+ * Log one committed change to an account, identified by its account id and
+ * label. A reorder whose caller did not say which account it moved is logged
+ * without an id.
+ */
+export declare function logCommittedNativeAccountChange(change: NativeAccountChange, account: {
+    id?: string;
+    label?: string;
+}): void;
+/**
+ * Log an account that a committed add created. The payload holds the account
+ * id, its label and the credential kind ('apikey' or 'oauth'); it never holds
+ * the credential, its base URL or its auth header.
+ */
+export declare function logCommittedNativeAccountAdded(account: {
+    id: string;
+    label?: string;
+    type: 'oauth' | 'api';
+}): void;
+export {};

package/dist/native-credential-validation.d.ts

@@ -0,0 +1,42 @@
+import { type NativeLocalPoolBinding } from './pool-binding.ts';
+/**
+ * The access-token fingerprint, expiry and last recorded refresh time identify
+ * the captured credentials. No bearer material is stored.
+ */
+export interface NativeLocalCredentialVersion {
+    readonly accessFingerprint: string;
+    readonly expires: number;
+    readonly lastRefreshedAt?: number;
+}
+/**
+ * Positive local account evidence belongs to its own binding, not merely to
+ * the runtime entry containing it. Copying an entry must not transfer evidence
+ * to another row, storage location, credential epoch or account identity.
+ * This evidence does not establish freshness or eligibility to serve.
+ */
+export interface NativeLocalCredentialValidation {
+    readonly binding: NativeLocalPoolBinding & {
+        readonly identity: string;
+    };
+    /** Common-auth's full SHA-256 of `oauth\0` followed by the refresh token. */
+    readonly credentialFingerprint: string;
+    readonly version: NativeLocalCredentialVersion;
+}
+/**
+ * Core publishes this local input type so consumers do not need common-auth
+ * declarations.
+ */
+export interface NativeLocalCredentialMaterial {
+    readonly type: string;
+    readonly access?: string;
+    readonly refresh?: string;
+    readonly expires?: number;
+    readonly lastRefreshedAt?: number;
+}
+/** Validate the closed, token-free proof schema; no defaults or I/O are used. */
+export declare function isNativeLocalCredentialValidation(value: unknown): value is NativeLocalCredentialValidation;
+/**
+ * Match only the captured binding and exact OAuth material. Expired material
+ * can still match evidence; serving freshness is a separate decision.
+ */
+export declare function nativeLocalCredentialValidationMatches(validation: unknown, binding: NativeLocalPoolBinding, material: NativeLocalCredentialMaterial | undefined): boolean;

package/dist/native-custody-activation.d.ts

@@ -0,0 +1,45 @@
+import type { NativeCustodyInventory } from './native-custody.ts';
+import { type NativeHostAuthWriteHooks } from './native-host-auth-write.ts';
+import { type NativeMigrationJournal } from './pool-authority.ts';
+import type { NativePoolPaths } from './pool-paths.ts';
+import { createNativePoolStore } from './pool-store.ts';
+export type NativeCustodyActivationErrorCode = 'migration-required' | 'invalid-state' | 'primary-missing' | 'primary-mismatch' | 'primary-unverified' | 'primary-conflict' | 'row-unverified' | 'unenrolled-local-row' | 'vault-ambiguous' | 'roster-conflict' | 'runtime-conflict' | 'settings-conflict' | 'credential-changed' | 'host-auth-changed' | 'consent-required' | 'migration-busy' | 'ownership-lost' | 'auth-content-refused' | 'process-fence-refused' | 'migration-proof-changed';
+export declare class NativeCustodyActivationError extends Error {
+    readonly code: NativeCustodyActivationErrorCode;
+    constructor(code: NativeCustodyActivationErrorCode);
+}
+export interface NativeCustodyActivationOptions {
+    paths: NativePoolPaths;
+    host: 'opencode' | 'pi';
+    env: NodeJS.ProcessEnv;
+    /** Rejects unless every selected host is stopped and inspection succeeded. */
+    processFence: () => Promise<void>;
+    /**
+     * The user's explicit consent to delete a stored Pi Anthropic OAuth entry.
+     * It never authorizes deleting a Pi API key, which always refuses.
+     */
+    removePiAnthropicAuth: boolean;
+    /**
+     * Lists the vault accounts this host's enrollment token may read; called
+     * only while preparing the activation.
+     */
+    discover: () => Promise<NativeCustodyInventory>;
+}
+export interface NativeCustodyActivationHooks {
+    /**
+     * Test hook for simulated crashes and lease loss. Receives a label naming
+     * the activation step about to run or just finished, never account data.
+     */
+    onStep?: (step: string) => Promise<void>;
+    hostWrite?: NativeHostAuthWriteHooks;
+    store?: Pick<Parameters<typeof createNativePoolStore>[0], 'onStep' | 'onLockStep'>;
+}
+export type NativeCustodyActivationResult = {
+    status: 'already-vault';
+    journal: NativeMigrationJournal;
+} | {
+    status: 'committed';
+    journal: NativeMigrationJournal;
+};
+/** Offline, crash-forward switch of a retired local pool to vault custody. */
+export declare function runNativeCustodyActivation(options: NativeCustodyActivationOptions, hooks?: NativeCustodyActivationHooks): Promise<NativeCustodyActivationResult>;

package/dist/native-custody.d.ts

@@ -0,0 +1,114 @@
+/** Claustrum IPC operations for listing accounts, reading tokens, reporting rejection, and closing the connection. */
+export interface NativeCustodyClient {
+    listScoped: (enrollmentToken?: string) => Promise<{
+        readonly view: string;
+        readonly rows: readonly {
+            readonly id: string;
+            readonly categories: readonly string[];
+            readonly credentialType: string;
+            readonly serves: readonly string[];
+            readonly providerIds: readonly string[];
+            readonly authMethod?: 'apikey' | 'chatgpt' | 'antigravity' | 'oauth';
+            readonly refreshAdapter?: string;
+            readonly state: string;
+            readonly recordVersion: number;
+            readonly operations: readonly string[];
+            readonly createdAtMs: number | null;
+            readonly accountId?: string;
+            readonly email?: string;
+            readonly orgName?: string;
+        }[];
+    }>;
+    getScoped: (input: {
+        credentialId: string;
+        enrollmentToken?: string;
+        minTtlMs?: number;
+    }) => Promise<{
+        material: string;
+        recordVersion: number;
+        expiresAtMs: number | null;
+        credentialId?: string;
+        projectId?: string;
+        accountId?: string;
+        email?: string;
+        orgName?: string;
+    }>;
+    reportAuthFailureScoped: (input: {
+        credentialId: string;
+        enrollmentToken?: string;
+        providerStatus: number;
+        recordVersion: number;
+        reporterSource: NativeCustodyReporterSource;
+    }) => Promise<void>;
+    close: () => void;
+}
+export type NativeCustodyReporterSource = 'direct' | 'relay_status_field' | 'relay_message_parse';
+export interface NativeCustodyLogger {
+    warn: (message: string, data?: unknown) => void;
+    debug: (message: string, data?: unknown) => void;
+}
+export interface NativeCustodyOptions {
+    host: 'opencode' | 'pi';
+    connect: () => Promise<NativeCustodyClient>;
+    readToken?: () => Promise<{
+        token: string;
+        token_generation: number;
+    }>;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    logger?: NativeCustodyLogger;
+}
+export interface NativeCustodyIdentity {
+    readonly credentialId: string;
+    readonly accountIdentity: string;
+}
+/** A common-auth receipt: retain its original object identity and non-enumerable accessToken. */
+export interface NativeCustodyReceipt {
+    readonly credentialId: string;
+    readonly credentialType: 'oauth';
+    readonly accountIdentity?: string;
+    readonly accountIdentitySource: 'asserted' | 'parsed' | 'expected' | 'none';
+    readonly expectedAccountIdentity?: string;
+    readonly assertedCredentialId?: string;
+    readonly assertedAccountIdentity?: string;
+    readonly recordVersion: number;
+    readonly expiresAtMs: number | null;
+    readonly accessToken: string;
+}
+export interface NativeCustodyInventory {
+    readonly view: string;
+    readonly credentials: readonly {
+        readonly credentialId: string;
+        readonly credentialType: 'oauth' | 'api_key';
+        readonly accountIdentity?: string;
+        readonly state: string;
+        readonly email?: string;
+        readonly orgName?: string;
+    }[];
+    readonly skipped: readonly {
+        readonly credentialId?: string;
+        readonly reason: 'empty credential id' | 'duplicate credential id' | 'blank account identity' | 'empty state';
+    }[];
+}
+export type NativeCustodyErrorCode = '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 NativeCustodyError extends Error {
+    readonly code: NativeCustodyErrorCode;
+    constructor(code: NativeCustodyErrorCode);
+}
+export type NativeCustodyRetry = {
+    retry: true;
+    receipt: NativeCustodyReceipt;
+} | {
+    retry: false;
+    reason: 'reauthorize-failed' | 'credential-changed' | 'account-changed' | 'version-not-newer';
+    code?: NativeCustodyErrorCode;
+};
+export interface NativeCustody {
+    discover: (signal?: AbortSignal) => Promise<NativeCustodyInventory>;
+    authorize: (identity: NativeCustodyIdentity, signal?: AbortSignal) => Promise<NativeCustodyReceipt>;
+    reportFailure: (receipt: NativeCustodyReceipt, status: number, reporterSource: NativeCustodyReporterSource) => Promise<void>;
+    prepareRetry: (served: NativeCustodyReceipt, signal?: AbortSignal) => Promise<NativeCustodyRetry>;
+    close: () => void;
+}
+/** Share a lazy Claustrum connection; each authorize call reads a fresh enrollment token and OAuth receipt. */
+export declare function createNativeCustody(options: NativeCustodyOptions): NativeCustody;

package/dist/native-enrollment-authority.d.ts

@@ -0,0 +1,2 @@
+/** Enrollment files, not account settings, choose the host's credential source. */
+export declare function readNativeEnrollmentMode(host: 'opencode' | 'pi', env?: NodeJS.ProcessEnv): Promise<'local' | 'claustrum'>;

package/dist/native-host-auth-read.d.ts

@@ -0,0 +1,3 @@
+import { type NativeHostAuthEntryInspection } from './native-host-auth.ts';
+/** Read only the host's login classification; credentials and source fingerprints never leave this boundary. */
+export declare function readNativeHostAuthKind(host: 'opencode' | 'pi', path: string): Promise<NativeHostAuthEntryInspection['kind']>;

package/dist/native-host-auth-write.d.ts

@@ -0,0 +1,51 @@
+export interface NativeHostAuthWriteInput {
+    readonly host: 'opencode' | 'pi';
+    /**
+     * Use the configured auth path, not a symlink's target, so the source reader
+     * can reject a symlink at the auth file. Its directory must already exist.
+     */
+    readonly authPath: string;
+    readonly sourceDigest: string;
+    readonly expectedDigest: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly removePiAnthropicAuth: boolean;
+    /**
+     * Must reject if the caller no longer owns the offline operation.
+     * Awaited immediately before replacing or deleting the auth file.
+     */
+    readonly processFence: () => Promise<void>;
+}
+export interface NativeHostAuthWriteHooks {
+    readonly beforeRecheck?: () => Promise<void>;
+    readonly beforeRename?: () => Promise<void>;
+    readonly afterRename?: () => Promise<void>;
+    readonly afterUnlink?: () => Promise<void>;
+}
+export type NativeHostAuthWriteOutcome = {
+    readonly status: 'unchanged';
+} | {
+    readonly status: 'replaced' | 'created';
+} | {
+    readonly status: 'removed';
+    readonly file: 'replaced' | 'unlinked';
+};
+export declare class NativeHostAuthWriteError extends Error {
+    readonly code: 'invalid-source' | 'unsafe-source' | 'consent-required' | 'process-fence-refused' | 'write-io' | 'hook-failed';
+    /** Records the file change already completed if a later callback throws. */
+    readonly effect: NativeHostAuthWriteOutcome | undefined;
+    constructor(code: 'invalid-source' | 'unsafe-source' | 'consent-required' | 'process-fence-refused' | 'write-io' | 'hook-failed', 
+    /** Records the file change already completed if a later callback throws. */
+    effect?: NativeHostAuthWriteOutcome | undefined);
+}
+/** Match this helper's temporary filenames so crash cleanup leaves other files alone. */
+export declare function isNativeHostAuthWriteStagingName(name: string): boolean;
+/**
+ * Write only the selected host's auth file; do not advance a migration journal.
+ * The caller checks Anthropic's entry digest when resuming migration. This write
+ * also rechecks the complete file to retain other providers' current entries.
+ * There is no compare-and-swap: a host write after the final check can still be
+ * overwritten by our rename or unlink. Advisory locks do not stop that writer.
+ * Before calling, verify the selected hosts are stopped and that their auth paths
+ * match the migration's captured paths. On resume, check Anthropic's entry again.
+ */
+export declare function writeNativeHostAuth(input: NativeHostAuthWriteInput, hooks?: NativeHostAuthWriteHooks): Promise<NativeHostAuthWriteOutcome>;

package/dist/native-host-auth.d.ts

@@ -0,0 +1,12 @@
+export declare class NativeHostAuthError extends Error {
+    readonly code: 'invalid-source' | 'supervised-auth-snapshot';
+    constructor(code: 'invalid-source' | 'supervised-auth-snapshot');
+}
+export declare function hasSupervisedAuthContentSnapshot(env: NodeJS.ProcessEnv): boolean;
+export declare function requireNoSupervisedAuthContentSnapshot(env: NodeJS.ProcessEnv): void;
+export interface NativeHostAuthEntryInspection {
+    readonly kind: 'absent' | 'oauth' | 'api' | 'api_key' | 'activation';
+    readonly digest: string;
+}
+/** Inspect parsed host auth only; path safety, consent and writes belong to callers. */
+export declare function inspectNativeHostAuthEntry(host: 'opencode' | 'pi', hostAuth: unknown): Readonly<NativeHostAuthEntryInspection>;