@cortexkit/anthropic-auth-core 1.22.0 → 2.0.0

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>;

package/dist/native-local-credential-service.d.ts

@@ -0,0 +1,76 @@
+import { type NativeLocalExternalPolicy } from './native-local-runtime-readers.ts';
+import { type NativeRefreshCoordinatorOptions, type NativeRefreshObservation, type NativeRefreshRequest, type NativeRefreshResult, type NativeRefreshSubject } from './native-refresh-coordinator.ts';
+import { type NativeLocalFailureAttribution, type NativeLocalFailurePolicy } from './native-runtime.ts';
+import type { NativePoolPaths } from './pool-paths.ts';
+/** A failure that can be recorded for a single credential. */
+export type NativeLocalAttributedFailure = Exclude<NativeLocalFailureAttribution, {
+    kind: 'none';
+}>;
+/**
+ * Everything the failure policy may use. Both values are frozen copies taken
+ * from the coordinator's report before any lock wait. They describe the
+ * credential version the failed operation used, not the pool row or runtime
+ * entry as they are now.
+ */
+export interface NativeLocalFailurePolicyInput {
+    readonly observation: NativeRefreshObservation;
+    readonly attribution: NativeLocalAttributedFailure;
+}
+export interface NativeLocalCredentialServiceOptions {
+    /** Storage resolved by resolveNativePoolPaths. The service keeps its own copy. */
+    readonly paths: NativePoolPaths;
+    /** Recheck host custody for this observation. Already consumed successors may finish their durable reconciliation; unconsumed work must still have local authority. */
+    readonly publicationGuard: (observation: NativeRefreshObservation) => Promise<boolean>;
+    /**
+     * Decide without I/O whether local OAuth mode, the account and its quota
+     * allow the operation. Credential-validation evidence is checked separately.
+     */
+    readonly externalPolicy: (subject: NativeRefreshSubject) => NativeLocalExternalPolicy;
+    /**
+     * Choose when a recorded failure was observed and when its credential may
+     * be retried. The service calls this once per attributable failure report,
+     * including each failed attempt of the coordinator's bounded retry loop.
+     *
+     * The coordinator reads the stored retry deadline again before each further
+     * attempt. A nextRetryAt later than the current clock therefore stops that
+     * loop: the next attempt is refused as 'refresh-backoff' and the result no
+     * longer carries the provider failure. Return nextRetryAt equal to checkedAt
+     * to record the failure without delaying the coordinator's own retries.
+     * The service never adds retries or a retry schedule of its own, and it does
+     * not treat an attempt number as proof that the failure is final.
+     */
+    readonly failurePolicy: (input: NativeLocalFailurePolicyInput) => NativeLocalFailurePolicy;
+    /** Clock for expiry, stored retry deadlines and pool writes; defaults to Date.now. */
+    readonly now?: () => number;
+    /** Token-exchange function; defaults to the Claude OAuth refresh endpoint. */
+    readonly refreshToken?: NativeRefreshCoordinatorOptions['refreshToken'];
+    /** Account lookup for new access; defaults to the Claude Code identity lookup. */
+    readonly resolveIdentity?: NativeRefreshCoordinatorOptions['resolveIdentity'];
+}
+/**
+ * Hosts receive an access token only after its Claude account has been checked.
+ * That check can be reused while the refresh token, access token, expiry and
+ * stored refresh timestamp have not changed.
+ */
+export interface NativeLocalCredentialService {
+    authorize(request: NativeRefreshRequest): Promise<NativeRefreshResult>;
+}
+/**
+ * Authorize local OAuth only after offline migration commits the pool as the
+ * credential authority. Creating this service neither imports credentials nor
+ * completes migration. Authority is checked before the coordinator starts and
+ * again before any access token is returned. The coordinator owns exchange,
+ * account lookup, bounded retries and the final validation check; it refuses
+ * API-key rows.
+ *
+ * Successful account checks record validation for the exact credential version.
+ * An existing runtime entry with no account UUID loses its unproven metadata,
+ * but keeps the clear timestamps that prevent older errors from returning.
+ * Known-account entries keep their metadata; a missing entry can be created
+ * only when the observation captured that absence before the provider call.
+ * Attributed failures record their credential version and caller retry policy.
+ * Writers recheck credential versions, bindings and clear timestamps under
+ * pool/runtime locks. A write fault prevents credentials from being returned,
+ * but cannot undo a token exchange or file replacement already committed.
+ */
+export declare function createNativeLocalCredentialService(options: NativeLocalCredentialServiceOptions): NativeLocalCredentialService;

package/dist/native-local-runtime-readers.d.ts

@@ -0,0 +1,22 @@
+import type { NativeRefreshHooks, NativeRefreshRestriction, NativeRefreshSubject } from './native-refresh-coordinator.ts';
+import type { NativePoolPaths } from './pool-paths.ts';
+/** Host adapters supply mode, account and quota policy for local OAuth authorization and refresh. */
+export type NativeLocalExternalPolicy = Exclude<NativeRefreshRestriction, {
+    credentialFingerprint: string;
+}>;
+export interface NativeLocalRuntimeReadersOptions {
+    paths: NativePoolPaths;
+    /**
+     * Decide whether local OAuth mode, the account and quota allow the operation
+     * without I/O. Credential-validation evidence is checked separately.
+     */
+    externalPolicy: (subject: NativeRefreshSubject) => NativeLocalExternalPolicy;
+    /** Return the current time to evaluate stored retry deadlines; tests can supply a fixed clock. */
+    now?: () => number;
+}
+/**
+ * Provide restriction and validation reads for NativeRefreshCoordinator without
+ * retrieving credentials or writing files. Host adapters separately provide
+ * runtime publication and account selection.
+ */
+export declare function createNativeLocalRuntimeReaders(options: NativeLocalRuntimeReadersOptions): Pick<NativeRefreshHooks, 'readRestrictions' | 'readAdmission'>;

package/dist/native-lock-observer.d.ts

@@ -0,0 +1,12 @@
+/** Diagnostic evidence, not an ownership assertion or a control hook. */
+export type NativeLockEvent = {
+    type: 'acquired' | 'released' | 'contended';
+    name: string;
+    path: string;
+};
+/**
+ * Diagnostics cannot decide whether a lock owner refreshes or saves a token.
+ * Consume returned rejections without awaiting: an observer may never settle.
+ * With no observer, leave the producer callback absent and allocate no wrapper.
+ */
+export declare function nativeLockObserver(observer: ((event: NativeLockEvent) => void) | undefined): ((event: NativeLockEvent) => void) | undefined;

package/dist/native-menu-executor.d.ts

@@ -0,0 +1,243 @@
+import { type NativeMenuActionId, type NativeMenuCacheMode, type NativeMenuCustodyMode, type NativeMenuHost, type NativeMenuLogLevel, type NativeMenuParameterId, type NativeMenuRefusalCode, type NativeMenuRoutingMode } from './native-menu-model.ts';
+/**
+ * Typed input checking and safety gating for native menu actions.
+ *
+ * The menu model in native-menu-model.ts only describes actions. This module
+ * checks the values a menu collected against that description and the
+ * existing command parsers' rules, applies the safety rules (headless refusal,
+ * confirmation, session requirement, cancellation before dispatch), and then
+ * hands one validated request to a host-provided capability. The capability
+ * performs the real effect; this module performs no I/O, retries, or
+ * background work, and it does not render a menu or collect input.
+ */
+/**
+ * One killswitch threshold row. The fields match the `/claude-killswitch set`
+ * entries, but `account` is taken as structured data, not command text.
+ */
+export type NativeMenuKillswitchEntry = {
+    /**
+     * An opaque account ID, passed on exactly as given, or the `main` / `all`
+     * selector. Native route IDs such as `vault:oauth:...` contain colons, so a
+     * menu that collects entries as text must keep the IDs whole rather than
+     * split them with the legacy command's `account:fh,sd` delimiters.
+     */
+    readonly account: string;
+    /** Five-hour remaining-percent threshold. */
+    readonly fh: number;
+    /** Seven-day remaining-percent threshold. */
+    readonly sd: number;
+    /** Optional model-scoped remaining-percent threshold. */
+    readonly scoped?: number;
+};
+/** Values for an action that takes no parameters: no key is accepted. */
+export type NativeMenuNoValues = {
+    readonly [key: string]: never;
+};
+/**
+ * The values each action accepts. Optional inputs may be left out or sent as
+ * `null`, which is how a menu reports an input left empty.
+ */
+export type NativeMenuActionValues = {
+    readonly enable: {
+        readonly id: string;
+    };
+    readonly disable: {
+        readonly id: string;
+    };
+    readonly remove: {
+        readonly id: string;
+    };
+    readonly 'move-up': {
+        readonly id: string;
+    };
+    readonly 'move-down': {
+        readonly id: string;
+    };
+    readonly 'reset-backoff': NativeMenuNoValues;
+    readonly 'enrollment-reset': NativeMenuNoValues;
+    readonly 'add-apikey': {
+        readonly apiKey: string;
+        readonly label?: string | null;
+        readonly baseURL?: string | null;
+        readonly authHeader?: 'authorization-bearer' | 'x-api-key' | null;
+    };
+    readonly 'add-oauth-start': NativeMenuNoValues;
+    readonly 'add-oauth-finish': {
+        readonly code: string;
+        readonly label?: string | null;
+    };
+    readonly 'custody-mode': {
+        readonly mode: NativeMenuCustodyMode;
+    };
+    readonly 'vault-disconnect': NativeMenuNoValues;
+    readonly 'quota-refresh': NativeMenuNoValues;
+    readonly 'routing-mode': {
+        readonly mode: NativeMenuRoutingMode;
+    };
+    readonly 'routing-reset': NativeMenuNoValues;
+    readonly 'killswitch-on': NativeMenuNoValues;
+    readonly 'killswitch-off': NativeMenuNoValues;
+    readonly 'killswitch-set': {
+        readonly entries: readonly NativeMenuKillswitchEntry[];
+    };
+    readonly 'cache-on': NativeMenuNoValues;
+    readonly 'cache-off': NativeMenuNoValues;
+    readonly 'cache-mode': {
+        readonly mode: NativeMenuCacheMode;
+    };
+    readonly 'cachekeep-always': NativeMenuNoValues;
+    readonly 'cachekeep-off': NativeMenuNoValues;
+    readonly 'cachekeep-window': {
+        readonly startHour: number;
+        readonly endHour: number;
+    };
+    readonly 'cachekeep-subagents': {
+        readonly enabled: 'on' | 'off';
+    };
+    readonly 'dump-on': NativeMenuNoValues;
+    readonly 'dump-off': NativeMenuNoValues;
+    readonly 'logging-level': {
+        readonly level: NativeMenuLogLevel;
+    };
+    readonly 'fast-on': NativeMenuNoValues;
+    readonly 'fast-off': NativeMenuNoValues;
+    readonly 'prime-on': NativeMenuNoValues;
+    readonly 'prime-off': NativeMenuNoValues;
+    readonly 'start-fire': NativeMenuNoValues;
+};
+/** A menu request as the shared UI hands it over, before any checking. */
+export type NativeMenuRequest = {
+    [Id in NativeMenuActionId]: NativeMenuActionValues[Id] extends NativeMenuNoValues ? {
+        readonly action: Id;
+        readonly values?: NativeMenuActionValues[Id];
+    } : {
+        readonly action: Id;
+        readonly values: NativeMenuActionValues[Id];
+    };
+}[NativeMenuActionId];
+/**
+ * Actions whose effect belongs to one conversation: routing reset clears that
+ * session's sticky assignment, lane start fires inside that session, and the
+ * OAuth start/finish pair keeps its pending sign-in state per session.
+ */
+export type NativeMenuSessionActionId = 'routing-reset' | 'start-fire' | 'add-oauth-start' | 'add-oauth-finish';
+/**
+ * Custody changes are offline setup steps, and vault disconnect goes through
+ * the host's own disconnect capability, so neither is dispatched.
+ */
+export type NativeMenuDispatchActionId = Exclude<NativeMenuActionId, 'custody-mode' | 'vault-disconnect'>;
+/** Checked values: empty optional inputs are left out instead of `null`. */
+export type NativeMenuDispatchValues<Id extends NativeMenuDispatchActionId> = {
+    readonly [Key in keyof NativeMenuActionValues[Id]]: Exclude<NativeMenuActionValues[Id][Key], null>;
+};
+/** A fully checked request, the only thing a host capability receives. */
+export type NativeMenuDispatchRequest = {
+    [Id in NativeMenuDispatchActionId]: {
+        readonly action: Id;
+        readonly values: NativeMenuDispatchValues<Id>;
+    } & (Id extends NativeMenuSessionActionId ? {
+        readonly sessionId: string;
+    } : {
+        readonly sessionId?: never;
+    });
+}[NativeMenuDispatchActionId];
+export type NativeMenuDispatchOptions = {
+    /** The caller's signal, passed on so a long capability may stop early. */
+    readonly signal?: AbortSignal;
+};
+/** What the host capability reports after it ran. */
+export type NativeMenuCapabilityOutcome = {
+    readonly ok: boolean;
+    readonly text: string;
+};
+/**
+ * The host capability that performs the real effect for a checked request.
+ * It must accept every dispatchable action; a callback written for only some
+ * actions does not satisfy this type.
+ */
+export type NativeMenuDispatch = (request: NativeMenuDispatchRequest, options: NativeMenuDispatchOptions) => Promise<NativeMenuCapabilityOutcome>;
+export type NativeMenuExecutorOptions = {
+    readonly host: NativeMenuHost;
+    readonly dispatch: NativeMenuDispatch;
+    /**
+     * Ends this host's vault enrollment. Without it the executor does not offer
+     * vault-disconnect and refuses it as unsupported.
+     */
+    readonly disconnectVault?: NativeVaultDisconnect;
+};
+/**
+ * What a host's vault disconnect reports. `disconnected`: the host is back in
+ * local custody. `idle`: no active enrollment remains; Pi's saved sign-in may
+ * still have been restored. `busy`: another process holds the enrollment lock
+ * and disconnect could not finish. `conflict`:
+ * the host's stored sign-in could not be restored without overwriting one it
+ * already has, so both were kept and the enrollment remains.
+ */
+export type NativeVaultDisconnectResult = 'disconnected' | 'idle' | 'busy' | 'conflict';
+/** The host capability that disconnects this host from the vault. */
+export type NativeVaultDisconnect = (options: NativeMenuDispatchOptions) => Promise<NativeVaultDisconnectResult>;
+/** Facts about the invocation that the safety rules depend on. */
+export type NativeMenuExecutionContext = {
+    /** False when no person can answer prompts (a headless or scripted run). */
+    readonly interactive: boolean;
+    /**
+     * The host's credential custody, read just before this request. Under
+     * claustrum custody the vault owns every account, so actions listed in
+     * NATIVE_MENU_LOCAL_CUSTODY_ACTION_IDS are refused before dispatch. Under
+     * local custody there is no enrollment to end, so vault disconnect is
+     * refused. There is no default: a context without a valid mode is refused.
+     */
+    readonly custodyMode: NativeMenuCustodyMode;
+    /** True once the person confirmed an action that requires confirmation. */
+    readonly confirmed?: boolean;
+    /** The conversation the request came from, when the host has one. */
+    readonly sessionId?: string;
+    readonly signal?: AbortSignal;
+};
+export type NativeMenuExecutorRefusalCode = NativeMenuRefusalCode | 'invalid-request' | 'invalid-context' | 'unsupported-action' | 'unknown-parameter' | 'missing-parameter' | 'invalid-parameter' | 'confirmation-required' | 'session-required' | 'aborted'
+/** The host is connected to the vault, which owns its accounts. */
+ | 'vault-managed'
+/** The host is not connected to the vault, so there is nothing to end. */
+ | 'vault-not-connected';
+export type NativeMenuExecutionResult = {
+    /** The capability ran; `ok` and `text` are what it reported. */
+    readonly status: 'executed';
+    readonly action: NativeMenuDispatchActionId;
+    readonly ok: boolean;
+    readonly text: string;
+} | {
+    /**
+     * The capability was called but threw, rejected, or returned something
+     * unreadable. Whether its effect happened is unknown.
+     */
+    readonly status: 'failed';
+    readonly action: NativeMenuDispatchActionId | 'vault-disconnect';
+    readonly code: 'execution-failed' | 'invalid-outcome';
+} | {
+    /** The host's disconnect capability ran and reported this result. */
+    readonly status: 'disconnect';
+    readonly action: 'vault-disconnect';
+    readonly result: NativeVaultDisconnectResult;
+} | {
+    /** Offline custody setup steps; nothing was changed. */
+    readonly status: 'guidance';
+    readonly action: 'custody-mode';
+    readonly mode: NativeMenuCustodyMode;
+    readonly instructions: readonly string[];
+} | {
+    /** Nothing was dispatched. */
+    readonly status: 'refused';
+    readonly code: NativeMenuExecutorRefusalCode;
+    readonly action?: NativeMenuActionId;
+    readonly parameter?: NativeMenuParameterId;
+};
+export type NativeMenuExecutor = {
+    readonly execute: (request: NativeMenuRequest, context: NativeMenuExecutionContext) => Promise<NativeMenuExecutionResult>;
+};
+/**
+ * Creates an executor for one host. The host's available actions and their
+ * safety rules come from the native menu model; `dispatch` and
+ * `disconnectVault` are captured once and called only with fully checked
+ * requests.
+ */
+export declare function createNativeMenuExecutor(options: NativeMenuExecutorOptions): NativeMenuExecutor;

package/dist/native-menu-model.d.ts

@@ -0,0 +1,142 @@
+/** Public menu metadata only; host adapters collect input and apply commands. */
+export declare const NATIVE_MENU_GROUP_IDS: readonly ["Accounts", "Quota", "Routing", "Limits", "Cache", "Diagnostics", "Extras"];
+export type NativeMenuGroupId = (typeof NATIVE_MENU_GROUP_IDS)[number];
+/** OpenCode 1 and OpenCode 2 share this action profile; host integration is separate. */
+export type NativeMenuHost = 'opencode' | 'pi';
+export type NativeMenuCommandId = 'account' | 'quota' | 'routing' | 'killswitch' | 'cache' | 'cachekeep' | 'dump' | 'logging' | 'fast' | 'prime' | 'start';
+export type NativeMenuRefusalCode = 'interactive-required' | 'offline-required';
+export type NativeMenuCustodyMode = 'local' | 'claustrum';
+export type NativeMenuRoutingMode = 'main-first' | 'fallback-first' | 'sticky-balanced';
+export type NativeMenuCacheMode = 'explicit' | 'automatic' | 'hybrid';
+export type NativeMenuLogLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+export type NativeMenuParameterId = 'id' | 'apiKey' | 'label' | 'baseURL' | 'authHeader' | 'code' | 'mode' | 'entries' | 'startHour' | 'endHour' | 'enabled' | 'level';
+export type NativeMenuChoiceParameter<Id extends NativeMenuParameterId = NativeMenuParameterId, Choice extends string = string> = {
+    readonly id: Id;
+    readonly kind: 'choice';
+    readonly required: boolean;
+    readonly choices: readonly Choice[];
+};
+/** Identifiers describe inputs, not the inputs' values or credential objects. */
+export type NativeMenuParameter = {
+    readonly id: 'id';
+    readonly kind: 'account-id';
+    readonly required: true;
+} | {
+    readonly id: 'apiKey' | 'label' | 'baseURL' | 'code';
+    readonly kind: 'text';
+    readonly required: boolean;
+    readonly protectedEntry: boolean;
+} | NativeMenuChoiceParameter<'mode', NativeMenuCustodyMode> | NativeMenuChoiceParameter<'mode', NativeMenuRoutingMode> | NativeMenuChoiceParameter<'mode', NativeMenuCacheMode> | NativeMenuChoiceParameter<'authHeader', 'authorization-bearer' | 'x-api-key'> | NativeMenuChoiceParameter<'enabled', 'on' | 'off'> | NativeMenuChoiceParameter<'level', NativeMenuLogLevel> | {
+    readonly id: 'startHour' | 'endHour';
+    readonly kind: 'number';
+    readonly required: true;
+} | {
+    readonly id: 'entries';
+    readonly kind: 'limit-entries';
+    readonly required: true;
+    readonly fields: readonly ['account', 'fh', 'sd', 'scoped?'];
+};
+export type NativeMenuActionId = 'enable' | 'disable' | 'remove' | 'move-up' | 'move-down' | 'reset-backoff' | 'enrollment-reset' | 'add-apikey' | 'add-oauth-start' | 'add-oauth-finish' | 'custody-mode' | 'vault-disconnect' | 'quota-refresh' | 'routing-mode' | 'routing-reset' | 'killswitch-on' | 'killswitch-off' | 'killswitch-set' | 'cache-on' | 'cache-off' | 'cache-mode' | 'cachekeep-always' | 'cachekeep-off' | 'cachekeep-window' | 'cachekeep-subagents' | 'dump-on' | 'dump-off' | 'logging-level' | 'fast-on' | 'fast-off' | 'prime-on' | 'prime-off' | 'start-fire';
+type DestructiveId = 'remove' | 'enrollment-reset' | 'vault-disconnect';
+type InteractiveId = 'add-apikey' | 'add-oauth-start' | 'add-oauth-finish' | 'custody-mode' | 'vault-disconnect';
+type ActionSafety<Id extends NativeMenuActionId> = (Id extends DestructiveId ? {
+    readonly destructive: true;
+    readonly confirm: string;
+} : {
+    readonly destructive: false;
+    readonly confirm?: never;
+}) & (Id extends InteractiveId ? {
+    readonly interactive: true;
+    readonly headlessRefusal: NativeMenuRefusalCode;
+} : {
+    readonly interactive: false;
+    readonly headlessRefusal?: never;
+});
+export type NativeMenuAction = {
+    [Id in NativeMenuActionId]: {
+        readonly id: Id;
+        readonly label: string;
+    } & ActionSafety<Id> & (Id extends 'custody-mode' ? {
+        readonly kind: 'setup-guidance';
+        readonly command: 'account';
+        readonly group: 'Accounts';
+        readonly parameters: readonly [
+            NativeMenuChoiceParameter<'mode', NativeMenuCustodyMode>
+        ];
+        readonly offlineRequired: true;
+        readonly setupInstructions: readonly string[];
+    } : Id extends 'vault-disconnect' ? {
+        /**
+         * Ends this host's vault enrollment through the host's own
+         * disconnect capability, never through the account dispatch.
+         */
+        readonly kind: 'vault-disconnect';
+        readonly command: 'account';
+        readonly group: 'Accounts';
+        readonly parameters: readonly [];
+    } : {
+        readonly kind: 'action';
+        readonly command: NativeMenuCommandId;
+        readonly group: NativeMenuGroupId;
+        readonly parameters: readonly NativeMenuParameter[];
+    });
+}[NativeMenuActionId];
+export type NativeMenuStatus = {
+    readonly kind: 'status';
+    readonly id: `${Exclude<NativeMenuCommandId, 'start'>}-status`;
+    readonly command: Exclude<NativeMenuCommandId, 'start'>;
+    readonly group: NativeMenuGroupId;
+    readonly label: string;
+};
+export type NativeMenuGroup = {
+    readonly id: NativeMenuGroupId;
+    readonly actions: readonly NativeMenuAction[];
+    readonly statuses: readonly NativeMenuStatus[];
+};
+export type NativeMenuModel = {
+    readonly host: NativeMenuHost;
+    readonly groups: readonly NativeMenuGroup[];
+};
+/**
+ * Actions offered only under local custody. Most write accounts or credentials
+ * held by this host: sign-in, API-key additions, removal and reordering.
+ * Enrollment reset repairs a terminal enrollment ceremony, and custody setup
+ * guidance describes connecting through offline setup; neither has a use
+ * while the host is enrolled. Under claustrum custody the vault is the only
+ * account authority, so these actions are left out of the menu and refused if
+ * a request for one still arrives. They return once the host is disconnected
+ * from the vault and back in local custody.
+ */
+export declare const NATIVE_MENU_LOCAL_CUSTODY_ACTION_IDS: readonly ["remove", "move-up", "move-down", "enrollment-reset", "add-apikey", "add-oauth-start", "add-oauth-finish", "custody-mode"];
+export type NativeMenuLocalCustodyActionId = (typeof NATIVE_MENU_LOCAL_CUSTODY_ACTION_IDS)[number];
+/** True for an action offered only while the host is in local custody. */
+export declare function isNativeMenuLocalCustodyAction(id: NativeMenuActionId): id is NativeMenuLocalCustodyActionId;
+/**
+ * When the host uses its local credential pool, hide vault-disconnect because
+ * no vault enrollment needs to end. Offer disconnect when enrollment grants
+ * this host access to the vault, or when that enrollment cannot be read so a
+ * person can recover from damaged enrollment files.
+ */
+export declare const NATIVE_MENU_VAULT_CUSTODY_ACTION_IDS: readonly ["vault-disconnect"];
+export type NativeMenuVaultCustodyActionId = (typeof NATIVE_MENU_VAULT_CUSTODY_ACTION_IDS)[number];
+/** True for actions shown when this host obtains credentials from the vault instead of its local pool. */
+export declare function isNativeMenuVaultCustodyAction(id: NativeMenuActionId): id is NativeMenuVaultCustodyActionId;
+/**
+ * Every action the host supports under either custody mode, in menu order.
+ * Request checking uses this list so it can recognise an action the current
+ * custody mode no longer offers and refuse it by name.
+ */
+export declare function listNativeMenuActions(host: NativeMenuHost): readonly NativeMenuAction[];
+/**
+ * Stable frozen metadata, with no current settings or credential material.
+ * Returns the actions the host offers under the given custody mode: local
+ * custody leaves out NATIVE_MENU_VAULT_CUSTODY_ACTION_IDS, and claustrum
+ * custody leaves out NATIVE_MENU_LOCAL_CUSTODY_ACTION_IDS. Local custody means
+ * this host keeps its own accounts; claustrum custody means the host is
+ * enrolled in the vault, which owns its accounts. The mode is required so no
+ * caller can fall back to the full action set by omission and offer local
+ * credential changes (sign-in, API keys, removal, reordering) to a host
+ * enrolled in the vault.
+ */
+export declare function getNativeMenuModel(host: NativeMenuHost, custody: NativeMenuCustodyMode): NativeMenuModel;
+export {};

package/dist/native-migration-proof.d.ts

@@ -0,0 +1,28 @@
+import type { PoolRow, StoredCredential } from "./internal-types/store/index.js";
+export declare class NativeMigrationProofError extends Error {
+    readonly code = "prepared-proof-refused";
+    constructor();
+}
+/** Credential-derived digests belong only in the owner-only migration journal. */
+export interface NativeMigrationRowProof {
+    id: string;
+    credentialEpoch: number;
+    identity: string | null;
+    stamp: 'bound';
+    credentialDigest: string;
+}
+export interface NativeMigrationPreparedProof {
+    version: 1;
+    rows: NativeMigrationRowProof[];
+    runtimeDigest: string;
+}
+export declare function requireNativeMigrationDataObject(value: unknown): asserts value is Record<string, unknown>;
+/** Copy inert JSON before decoding; never invoke a getter, proxy trap or toJSON. */
+export declare function captureNativeMigrationJson(value: unknown): unknown;
+export declare function nativeMigrationCanonicalJson(value: unknown): string;
+export declare function nativeMigrationDigest(value: unknown): string;
+/** Fixed-order, complete public descriptor; absence is different from a value. */
+export declare function nativeMigrationCredentialDigest(credential: StoredCredential): string;
+export declare function captureNativeMigrationPreparedProof(rows: readonly PoolRow[], runtimeProjection: unknown): NativeMigrationPreparedProof;
+export declare function decodeNativeMigrationPreparedProof(input: unknown): NativeMigrationPreparedProof;
+export declare function requireNativeMigrationPreparedProof(proof: NativeMigrationPreparedProof | null, rows: readonly PoolRow[], runtimeProjection: unknown): void;

package/dist/native-migration-source.d.ts

@@ -0,0 +1,47 @@
+import { type PoolCredential, type PoolRow } from "./internal-types/store/index.js";
+import { type NativeQuotaMap } from './native-quota-codec.ts';
+import type { NativeRosterSeedLegacyRow, NativeVaultRosterSeed } from './native-roster-seed.ts';
+import { type NativeRuntimeState } from './native-runtime.ts';
+import type { NativePoolPaths } from './pool-paths.ts';
+export declare class NativeMigrationProjectionError extends Error {
+    readonly code = "invalid-migration-source";
+    constructor();
+}
+export interface NativeMigrationAccount {
+    id: string;
+    enabled: boolean;
+    identity?: string;
+    label?: string;
+    credential?: PoolCredential;
+    quota?: NativeQuotaMap;
+    runtime: Record<string, unknown>;
+}
+export interface NativeMigrationProjection {
+    accounts: NativeMigrationAccount[];
+    settings: Record<string, unknown>;
+    mainRouteId: string;
+    custodyRows: NativeRosterSeedLegacyRow[];
+    custodyPrimary?: {
+        credentialId: string;
+        accountIdentity: string;
+    };
+    disabledAccountIdentities: string[];
+    relay?: {
+        token: string;
+    };
+}
+export interface NativeMigrationSourceInput {
+    host: 'opencode' | 'pi';
+    storageId: string;
+    configDigest: string | null;
+    config: unknown;
+    state: unknown;
+    hostAuth: unknown;
+}
+export declare function validateNativeMigrationSettings(settings: Record<string, unknown>): void;
+/** Deterministic projection of captured JSON, without invoking legacy loaders or callbacks. */
+export declare function projectNativeMigrationSource(input: NativeMigrationSourceInput): NativeMigrationProjection;
+/** Ignore lastRefreshedAt here: adding an OAuth row generates it, so it is not source data. */
+export declare function requireNativeMigrationSourceRows(projection: NativeMigrationProjection, rows: readonly PoolRow[], checkQuota?: boolean): void;
+/** Use row.credentialEpoch to associate imported quota and errors with the stored credentials. The store’s internal integrity hash is not a public account version. */
+export declare function projectNativeMigrationRuntime(paths: NativePoolPaths, projection: NativeMigrationProjection, rows: readonly PoolRow[], seed?: NativeVaultRosterSeed): NativeRuntimeState;

package/dist/native-migration.d.ts

@@ -0,0 +1,66 @@
+import { type PoolRow } from "./internal-types/store/index.js";
+import type { NativeCustodyInventory } from './native-custody.ts';
+import { type NativeHostAuthWriteHooks } from './native-host-auth-write.ts';
+import { type NativeRosterSeedInput, type NativeVaultRosterSeed } from './native-roster-seed.ts';
+import { type NativeRuntimeState } from './native-runtime.ts';
+import { type NativeMigrationJournal } from './pool-authority.ts';
+import { type NativePoolPaths } from './pool-paths.ts';
+import { createNativePoolStore } from './pool-store.ts';
+export declare class NativeMigrationError extends Error {
+    readonly code: 'invalid-source' | 'unsafe-source' | 'consent-required' | 'primary-unverified' | 'migration-busy' | 'ownership-lost' | 'retirement-refused';
+    constructor(code: 'invalid-source' | 'unsafe-source' | 'consent-required' | 'primary-unverified' | 'migration-busy' | 'ownership-lost' | 'retirement-refused');
+}
+export interface NativeMigrationCustody {
+    /** Use the host’s approved Claustrum token and account-list permission to discover accounts; never open the vault’s credential files. */
+    discover: () => Promise<NativeCustodyInventory>;
+    /** Use publishNativeVaultRosterSeed to verify that this controller still owns the migration journal lock before replacing the account list. */
+    publishSeed: (paths: NativePoolPaths, input: NativeRosterSeedInput, options: {
+        assertOwned: () => Promise<void>;
+    }) => Promise<NativeVaultRosterSeed>;
+    /** Use publishNativeVaultRuntimeSeed to match metadata to its vault account while holding the account-list and migration-journal locks. */
+    publishRuntimeSeed: (paths: NativePoolPaths, state: NativeRuntimeState, options: {
+        assertOwned: () => Promise<void>;
+    }) => Promise<void>;
+}
+export interface NativeMigrationOptions {
+    paths: NativePoolPaths;
+    /** Keep the configured config and state paths so the reader rejects either file if it is a symbolic link. */
+    legacyConfigPath?: string;
+    legacyStatePath?: string;
+    host: 'opencode' | 'pi';
+    hostAuthPath: string;
+    routingSourcePath: string;
+    routingDestinationPath: string;
+    env: NodeJS.ProcessEnv;
+    processFence: () => Promise<void>;
+    removePiAnthropicAuth: boolean;
+    custody?: NativeMigrationCustody;
+    preflight?: NativeMigrationPreflight;
+    /**
+     * Offline setup sets requestVaultActivation when the user explicitly chose vault custody. It
+     * applies only when no journal exists yet; it keeps the pool unauthorized
+     * after this migration commits until runNativeCustodyActivation commits.
+     */
+    requestVaultActivation?: boolean;
+}
+/** Result of read-only checks for the selected storage and host. Contains no account data or credential digests. */
+export interface NativeMigrationPreflight {
+    readonly storageId: string;
+    readonly host: 'opencode' | 'pi';
+}
+export interface NativeMigrationHooks {
+    /** Test hook for interruptions and lease loss. Receives step labels, never credentials or their digests. */
+    onStep?: (step: string) => Promise<void>;
+    hostWrite?: NativeHostAuthWriteHooks;
+    store?: Pick<Parameters<typeof createNativePoolStore>[0], 'onStep' | 'onLockStep'>;
+}
+/** Preflight is read-only so setup can validate all selected hosts before any begin. */
+export declare function prepareNativeMigration(input: NativeMigrationOptions): Promise<NativeMigrationPreflight>;
+export declare function releaseNativeMigrationPreflight(token: NativeMigrationPreflight): void;
+/**
+ * The public, secret-free state recorded alongside account credential digests for recovery checks:
+ * runtime metadata, settings, account flags and quota, and the vault roster.
+ */
+export declare function importedRuntimeProjection(paths: NativePoolPaths, store: ReturnType<typeof createNativePoolStore>, rows: PoolRow[]): Promise<unknown>;
+/** Offline, crash-forward transaction. Native serving never calls this controller. */
+export declare function runNativeMigration(input: NativeMigrationOptions, hooks?: NativeMigrationHooks): Promise<NativeMigrationJournal>;