@cortexkit/anthropic-auth-core 2.2.8 → 2.4.0

package/dist/internal-types/store/attribution.d.ts

@@ -1,4 +1,6 @@
+import { type StoreContext } from './mutate.js';
 import { type StoreRuntime } from './runtime.js';
+import { type PoolRow } from './schema.js';
 /**
  * What a pull or refresh captured about its row (named by id alongside) when
  * it was issued. A result applies only while the row with that id still has
@@ -20,6 +22,9 @@ export interface Attribution {
     credentialEpoch: number;
     identity?: string;
 }
+export declare function assertQuotaEpoch(id: string, attribution: Attribution): void;
+export declare function assertQuotaRow(id: string, attribution: Attribution, row: PoolRow | undefined): asserts row is PoolRow;
+export declare function mergedQuota(ctx: StoreContext, id: string, stored: unknown, observation: unknown): unknown;
 /**
  * Merges a quota observation into a row's stored map under the store locks,
  * after attribution passes. Needs no row lock, so it is permitted from

package/dist/internal-types/store/mutate.d.ts

@@ -52,6 +52,8 @@ export type ReadResult = ({
     kind?: 'snapshot-contended';
     retryable?: true;
 };
+/** Settings need only the config classification, not a joined roster snapshot. */
+export declare function readPoolConfig(path: string): Promise<import("./schema.js").ConfigClassification>;
 /**
  * Validate config/state/config bytes without locks. Roster replacement writes
  * config before deleting old state credentials. Re-read a changed config so an

package/dist/internal-types/store/pool.d.ts

@@ -1,3 +1,4 @@
+import type { QuotaCommitTimer } from '../quota/commit-interval.js';
 import { type Attribution } from './attribution.js';
 import type { PoolOperationError } from './errors.js';
 import type { PoolLogger } from './hooks.js';
@@ -16,6 +17,23 @@ export interface OpenPoolStoreOptions {
     configPath: string;
     statePath: string;
     quota: QuotaCodec;
+    /**
+     * Opt in to detached, coalesced quota publication, with any `quota` codec.
+     * Each accepted observation is queued whole for its row and binding, and
+     * the queue is applied in arrival order through `quota.merge` under the
+     * store locks, so the codec's own merge decides which fields a newer or
+     * older reading replaces. Accepted readings appear in read/load
+     * immediately, merged the same way; the returned promise still rejects
+     * current-row refusals before queueing. Await dispose or close at shutdown
+     * to attempt a bounded drain; readings still pending at its timeout are
+     * discarded. Normal quota commits are at least 30 seconds apart; a full
+     * queue commits early so response handling never waits for that interval.
+     */
+    coalesceQuota?: boolean;
+    /** Bounded quota drain on close/dispose, in milliseconds; defaults to 1,000. */
+    quotaDrainTimeoutMs?: number;
+    /** Monotonic clock and scheduling seam for detached quota commits. */
+    quotaCommitTimer?: QuotaCommitTimer;
     /**
      * The codec of the provider state kept beside each row's credential (see
      * `ProviderStateCodec`). Without it no row shows a provider state, and
@@ -189,6 +207,10 @@ export interface PoolStore {
     }>;
     refresh(id: string, provider: ProviderRefresh, options?: RefreshOptions): Promise<RefreshOutcome>;
     recordQuota(id: string, attribution: Attribution, observation: unknown): Promise<void>;
+    /** Drain opted-in quota publication; subsequent coalesced readings refuse. Idempotent. */
+    close(): Promise<void>;
+    /** Same bounded quota drain as close(). Does not wait for provider pull hooks. */
+    dispose(): Promise<void>;
     /** Fires a pull for a row admission refused for want of a reading. */
     requestReading(id: string): void;
     /** Resolves once every pull fired so far has settled. */

package/dist/internal-types/store/runtime.d.ts

@@ -1,3 +1,4 @@
+import type { Attribution } from './attribution.js';
 import { type PoolOperation, PoolOperationError } from './errors.js';
 import { type ReadResult, type StoreContext } from './mutate.js';
 import type { PoolLockOptions, PoolLockSpec } from './refresh-lock.js';
@@ -10,6 +11,7 @@ export interface StoreRuntime {
     providerLock: PoolLockSpec;
     rowLockOptions: Partial<PoolLockOptions>;
     firePull(id: string, reason: PullReason): void;
+    publishQuota?: (id: string, attribution: Attribution, observation: unknown) => Promise<void>;
 }
 /**
  * The row lock's (name, path): keyed by the row's recorded wire identity when

package/dist/internal-types/store/settings.d.ts

@@ -50,7 +50,7 @@ export type UpdateSettingsResult = {
     /** `unchanged` when the mutator left the settings as they were; nothing was written. */
     outcome: 'updated' | 'unchanged';
 };
-/** Reads the settings without taking a lock or writing anything. */
+/** Reads only the config's settings, without taking a lock or writing anything. */
 export declare function readPoolSettings(rt: StoreRuntime): Promise<SettingsRead>;
 /**
  * One locked read-modify-write of the plugin's settings in the config file

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

@@ -13,6 +13,7 @@ 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';
+import { type RelocationGuard } from './relocation-guard.ts';
 export type { NativeAccountMetadataPatch, NativeAccountSnapshot, NativeAccountView, } from './native-account-view.ts';
 export interface NativeAccountRuntimeOptions {
     paths: NativePoolPaths;
@@ -47,8 +48,15 @@ export type NativeRelayUpdate = Partial<Omit<RelayConfig, 'token'>> & {
 };
 export interface NativeAccountRuntime {
     readonly onLockEvent?: (event: NativeLockEvent) => void;
+    /**
+     * Refuses once a newer version has moved this runtime's files. Hosts pass
+     * it to the routing stores they create, so their writes check it under
+     * the routing file's lock.
+     */
+    readonly relocationGuard?: RelocationGuard;
     readonly vault: NativeVaultRuntime;
     readonly quotaObservations: NativeQuotaObservations;
+    /** Waits for pending quota observations, quota submissions, and runtime metadata writes. An accepted pool quota update may not yet be on disk; close() drains the pool's pending quota writes. */
     drainQuotaPublications(): Promise<void>;
     drainRoutingPublications(): Promise<void>;
     /** Fresh private relay authorization for transport only; never include it in a status snapshot. */

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

@@ -1,5 +1,7 @@
 import { enrollmentAuthority, readClaustrumEnrollmentStatus } from "./internal-types/claustrum/index.js";
 import { NativeCustodyError } from './native-custody.ts';
+/** Test-only reset for the once-per-process enrollment mode log. */
+export declare function __resetEnrollmentModeLogForTests(): void;
 /**
  * Shown instead of `Native custody refused: invalid-token` when the
  * enrollment files could not be read because the private-files backend did

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

@@ -9,11 +9,11 @@ export declare function nativeRuntimeStorageKey(options: {
 export declare function nativeRuntimeConnectionFile(host: 'opencode' | 'pi', env: NodeJS.ProcessEnv): string;
 /** A release applies to the runtime entry acquired earlier, not to a later entry created with the same key. */
 export declare class NativeRuntimeRegistry<T extends {
-    close(): void;
+    close(): void | Promise<void>;
 }> {
     private readonly entries;
     acquire(key: string, create: () => T): {
         use: () => T;
-        close: () => void;
+        close: () => void | Promise<void>;
     };
 }

package/dist/native-vault-paths.d.ts

@@ -1,4 +1,5 @@
 import type { NativePoolPaths } from './pool-paths.ts';
+import { type StateLayout } from './state-layout-paths.ts';
 /** Vault files have no migration journal: enrollment alone authorizes their use. */
 export interface NativeVaultPaths {
     config: string;
@@ -9,5 +10,13 @@ export interface NativeVaultPaths {
     storageId: string;
     legacySeedConfig: string;
 }
-/** Keep vault settings, metadata and affinity outside every local recovery file. */
-export declare function nativeVaultPaths(local: NativePoolPaths): NativeVaultPaths;
+/**
+ * Keep vault settings, metadata and affinity outside every local recovery file.
+ *
+ * `layout` must be the one `local` was resolved in: the local paths don't say
+ * where the vault's state files are. It defaults to this process's layout
+ * decision. Vault settings stay beside the account file in every layout, and
+ * the storage id is always computed from the vault store state's
+ * legacy-layout path.
+ */
+export declare function nativeVaultPaths(local: NativePoolPaths, layout?: StateLayout): NativeVaultPaths;

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

@@ -116,7 +116,7 @@ export interface NativeVaultRuntime {
     resetBackoff(receipt: NativeCustodyReceipt, kind?: 'refresh' | 'quota' | 'all'): Promise<boolean>;
     getOrCreateAuthLineage(receipt: NativeCustodyReceipt): Promise<string | undefined>;
     incrementPrimeUsage(receipt: NativeCustodyReceipt, delta?: PrimeUsageDelta): Promise<boolean>;
-    close(): void;
+    close(): void | Promise<void>;
 }
 /** Publish the initial roster from validated account inventory. A caller importing captured state must fence that state through assertOwned, which runs again at the roster's actual publication. */
 export declare function publishNativeVaultRosterSeed(paths: Pick<NativeVaultPaths, 'roster'>, input: NativeRosterSeedInput, options?: {
@@ -136,4 +136,4 @@ export declare function nativeVaultRuntimeKey(options: NativeVaultRuntimeOptions
 /** Each handle owns one reference; disposing it cannot close another host session. */
 export declare function acquireNativeVaultRuntime(options: NativeVaultRuntimeOptions): NativeVaultRuntime;
 /** Each account lease wraps the shared vault runtime and tracks its own subscriptions, so releasing the lease removes those subscriptions. */
-export declare function leaseNativeVaultRuntime(use: () => NativeVaultRuntime, close: () => void): NativeVaultRuntime;
+export declare function leaseNativeVaultRuntime(use: () => NativeVaultRuntime, close: () => void | Promise<void>): NativeVaultRuntime;

package/dist/pool-paths.d.ts

@@ -1,3 +1,4 @@
+import { type StateLayout } from './state-layout-paths.ts';
 export interface NativePoolPaths {
     legacyConfig: string;
     legacyState: string;
@@ -19,5 +20,11 @@ export declare function canonicalPath(path: string): Promise<string>;
 /**
  * Separate runtime authority from import inputs so a stale legacy writer cannot
  * rewrite a stamped credential. Both independently configured paths matter.
+ *
+ * `layout` places the pool state, runtime, journal and custody roster; the pool
+ * config stays beside the account file in every layout. It defaults to this
+ * process's layout decision, so a re-resolution matches the first resolution.
+ * The storage id is always computed from the pool state's legacy-layout path,
+ * so moving files between layouts never changes it.
  */
-export declare function resolveNativePoolPaths(legacyConfig?: string, legacyState?: string): Promise<NativePoolPaths>;
+export declare function resolveNativePoolPaths(legacyConfig?: string, legacyState?: string, layout?: StateLayout): Promise<NativePoolPaths>;

package/dist/relocation-guard.d.ts

@@ -0,0 +1,48 @@
+import type { NativePoolPaths } from './pool-paths.ts';
+import { type RelocationPointer } from './state-layout-paths.ts';
+/**
+ * Fixed text of the refusal a process gives once a newer version has moved
+ * the state files it uses. It names no path, because hosts show it on screen
+ * and in their own logs; the log line written with it names the folders.
+ */
+export declare const RELOCATED_MESSAGE = "Anthropic account state was moved to a new folder by a newer anthropic-auth version. Update anthropic-auth in every OpenCode and Pi that uses this folder, then restart them.";
+/**
+ * A runtime file this process uses has been replaced by a relocation
+ * tombstone: a newer version moved the dataset elsewhere, and this version
+ * can't follow it. Every later use of the old files is refused, so this
+ * process never writes beside state it no longer owns.
+ */
+export declare class RelocatedError extends Error {
+    readonly code = "relocated";
+    /** The old runtime path that holds the tombstone. */
+    readonly runtimePath: string;
+    /** Where the tombstone says the state went. */
+    readonly relocatedTo: string;
+    constructor(runtimePath: string, pointer: RelocationPointer);
+}
+/**
+ * Checks whether a dataset has been moved, by looking for a relocation
+ * tombstone over its legacy runtime files. It takes no lock: callers run it
+ * inside a callback that already holds the lock a mover must hold to install
+ * the tombstone, so the check sees either no move or the tombstone.
+ */
+export interface RelocationGuard {
+    /** Throws `RelocatedError` when either runtime file is a tombstone. */
+    assertNotRelocated(): Promise<void>;
+    /** True when either runtime file is a tombstone; never throws for it. */
+    isRelocated(): Promise<boolean>;
+}
+/** The first tombstone among `runtimePaths`, with the path that holds it. */
+export declare function findRelocationTombstone(runtimePaths: readonly string[]): Promise<{
+    path: string;
+    pointer: RelocationPointer;
+} | undefined>;
+/** A guard over the given legacy runtime files. */
+export declare function createRelocationGuard(runtimePaths: readonly string[]): RelocationGuard;
+/**
+ * The legacy runtime files of a dataset: its local runtime and its vault
+ * runtime. A move replaces both with tombstones before it commits.
+ */
+export declare function nativeRelocationRuntimePaths(paths: NativePoolPaths): [string, string];
+/** A guard over a dataset's two legacy runtime files. */
+export declare function nativeRelocationGuard(paths: NativePoolPaths): RelocationGuard;

package/dist/state-layout-paths.d.ts

@@ -0,0 +1,193 @@
+import * as nodePath from 'node:path';
+/**
+ * Where a dataset's machine-written files live.
+ *
+ * - `legacy`: beside the account files in OpenCode's config folder, as in every
+ *   release so far.
+ * - `state-home`: in `dir`, the config folder's own subfolder of the CortexKit
+ *   state root. `dir` must be absolute and canonical (no symlinked component),
+ *   because vault paths are derived from it without another realpath pass.
+ *
+ * The layout decides only where files are. Storage ids never depend on it: they
+ * are always computed from where the files would be in the legacy layout, so a
+ * file copied between layouts keeps the id it was written with.
+ */
+export type StateLayout = {
+    readonly kind: 'legacy';
+} | {
+    readonly kind: 'state-home';
+    readonly dir: string;
+};
+export declare const LEGACY_STATE_LAYOUT: StateLayout;
+/**
+ * The layout a resolver uses when its caller passes none. A process decides it
+ * once, before it resolves any pool path, and never switches: every
+ * re-resolution must use the same layout as the first, or comparisons between
+ * them fail. No process can choose the state-home layout yet, so this is
+ * always the legacy layout.
+ */
+export declare function processStateLayout(): StateLayout;
+/** The `node:path` functions the pure helpers use; tests pass `path.win32`. */
+export type StatePathApi = Pick<typeof nodePath, 'join' | 'isAbsolute'>;
+export interface StateRootInputs {
+    /** `XDG_STATE_HOME` exactly as read; undefined or empty means unset. */
+    xdgStateHome: string | undefined;
+    /** Home directory used when `XDG_STATE_HOME` is unset or not usable. */
+    home: string;
+    /**
+     * Use a relative `XDG_STATE_HOME` as given. The XDG base-directory rules say
+     * a relative value is invalid and must be ignored, which is the default and
+     * what the CLI diagnostics folder has always done. Host enrollment files and
+     * the RPC folder have always accepted a relative value, so they keep doing
+     * so: changing it would hide an existing enrollment.
+     */
+    acceptRelative?: boolean;
+}
+/**
+ * The CortexKit state root of anthropic-auth:
+ * `<XDG_STATE_HOME or ~/.local/state>/cortexkit/anthropic-auth`. Enrollment
+ * files, RPC port files, CLI diagnostics and relocated pool state all live
+ * under it.
+ */
+export declare function anthropicAuthStateRoot(inputs: StateRootInputs, pathApi?: StatePathApi): string;
+/**
+ * The identity of a config folder: `realpathSync.native` of it, compared and
+ * hashed exactly as returned, with no case folding on any OS. A folder that
+ * doesn't exist has no identity, and its dataset stays in the legacy layout.
+ */
+export declare function configFolderIdentity(configDir?: string): string | undefined;
+/** OpenCode's config folder when nothing in the environment overrides it. */
+export declare function homeDefaultConfigDir(home?: string, pathApi?: StatePathApi): string;
+/**
+ * The state-root subfolder of a config folder. Only the home directory's
+ * default folder gets the plain `opencode` name. That folder is derived from
+ * the home directory and never from `XDG_CONFIG_HOME`, so two environments
+ * with different `XDG_CONFIG_HOME` values can't both claim `opencode`. Every
+ * other folder gets `opencode-<first 16 hex digits of sha256(identity)>`.
+ */
+export declare function stateSubfolderName(identity: string, homeDefaultIdentity: string | undefined): string;
+export interface StateHomeTarget {
+    /** The config folder's identity (see `configFolderIdentity`). */
+    identity: string;
+    /** The state root this process uses. */
+    stateRoot: string;
+    /**
+     * The config folder's subfolder of `stateRoot`. It may not exist yet, so it
+     * is not canonicalized here.
+     */
+    dir: string;
+}
+/**
+ * Where this process would keep the state of OpenCode's config folder in the
+ * state-home layout, or undefined when the config folder has no identity.
+ * `XDG_STATE_HOME` must be absolute to count; a relative value is ignored.
+ */
+export declare function resolveStateHomeTarget(options?: {
+    env?: NodeJS.ProcessEnv;
+    home?: string;
+}): StateHomeTarget | undefined;
+/**
+ * Names of the files kept in a state-home subfolder. Data files keep their
+ * default legacy names so the folder stays readable for manual recovery.
+ */
+export declare const STATE_HOME_FILE_NAMES: Readonly<{
+    localPoolState: "anthropic-auth-pool-state.json";
+    localRuntime: "anthropic-auth-native-state.json";
+    journal: "anthropic-auth-migration.json";
+    localRoster: "anthropic-auth-custody-roster.json";
+    vaultStoreState: "anthropic-auth-vault-store-state.json";
+    vaultRuntime: "anthropic-auth-vault-state.json";
+    vaultRoster: "anthropic-auth-vault-roster.json";
+    vaultRouting: "anthropic-auth-vault-routing-state.json";
+    requestGzip: "anthropic-auth-request-gzip.json";
+    configDirMarker: "config-dir.json";
+    layoutMarker: "layout.json";
+}>;
+export type StateHomeFilePaths = {
+    readonly [K in keyof typeof STATE_HOME_FILE_NAMES]: string;
+};
+/**
+ * Every file of a state-home subfolder. The account files
+ * (`anthropic-auth.json`, `anthropic-auth-state.json`), the pool settings
+ * (`anthropic-auth-pool.json`), the vault settings
+ * (`anthropic-auth-vault-settings.json`), the local routing file and the TUI
+ * preferences stay in the config folder in both layouts and are not listed.
+ */
+export declare function stateHomeFilePaths(dir: string, pathApi?: StatePathApi): StateHomeFilePaths;
+/**
+ * Files of the state-home layout for a dataset given by its canonical legacy
+ * account files. Only the default dataset of a config folder can use that
+ * layout: custom file names or a state file away from the config file mean an
+ * explicit override, which keeps every file beside the named files.
+ */
+export declare function stateHomeDatasetFiles(layout: Extract<StateLayout, {
+    kind: 'state-home';
+}>, legacyConfig: string, legacyState: string): StateHomeFilePaths;
+export type StateLayoutFileErrorCode = 'unreadable' | 'invalid';
+/** A state-layout file exists but can't be read or doesn't parse. */
+export declare class StateLayoutFileError extends Error {
+    readonly code: StateLayoutFileErrorCode;
+    readonly path: string;
+    constructor(code: StateLayoutFileErrorCode, path: string, cause?: unknown);
+}
+/** `config-dir.json`: names the config folder a state-home subfolder belongs to. */
+export interface ConfigDirMarker {
+    readonly version: 1;
+    readonly identity: string;
+}
+/**
+ * Read `<dir>/config-dir.json`. Undefined only when the file is absent; any
+ * other read error, or content that doesn't parse, throws
+ * `StateLayoutFileError`.
+ */
+export declare function readConfigDirMarker(dir: string): Promise<ConfigDirMarker | undefined>;
+export declare const STATE_LAYOUT_PHASES: readonly ['preparing', 'committed', 'rolled-back', 'restoring', 'restore-staged', 'restored'];
+export type StateLayoutPhase = (typeof STATE_LAYOUT_PHASES)[number];
+declare const CLEANUP_STATES: readonly ['pending', 'done', 'kept'];
+declare const RESTORE_CLEANUP_STATES: readonly ['pending', 'done'];
+/** The fields of `layout.json` that decide whether a process may use a layout. */
+export interface StateLayoutMarker {
+    readonly version: 1;
+    readonly phase: StateLayoutPhase;
+    readonly attempt: string;
+    readonly identity: string;
+    readonly stateRoot: string;
+    readonly sub: string;
+    readonly oldDir: string;
+    readonly storageIds: {
+        readonly local: string;
+        readonly vault: string;
+    };
+    /** Present once a move has committed. */
+    readonly cleanup?: (typeof CLEANUP_STATES)[number];
+    /** Present while a restore to the legacy layout is under way or finished. */
+    readonly restore?: {
+        readonly cleanup?: (typeof RESTORE_CLEANUP_STATES)[number];
+    };
+}
+/**
+ * Read `<dir>/layout.json`. Undefined only when the file is absent. Any other
+ * read error, or content that doesn't parse, throws `StateLayoutFileError`:
+ * an unreadable marker must never be taken as "no move" or as a finished one.
+ */
+export declare function readStateLayoutMarker(dir: string): Promise<StateLayoutMarker | undefined>;
+/**
+ * What a relocation tombstone over an old runtime path says. A move replaces
+ * each legacy runtime file with one, so older versions refuse the legacy copy
+ * and newer ones can name where the state went.
+ */
+export interface RelocationPointer {
+    readonly relocatedTo: string;
+    readonly stateRoot: string;
+    readonly identity: string;
+    readonly attempt: string;
+    readonly by: string;
+}
+/**
+ * Read a legacy runtime path as a relocation tombstone. Undefined when the
+ * file is absent, isn't a small regular file, or doesn't parse as a
+ * tombstone: such a file is an ordinary runtime, valid or not, and its own
+ * reader decides. Read errors other than absence are thrown.
+ */
+export declare function readRelocationPointer(runtimePath: string): Promise<RelocationPointer | undefined>;
+export {};

package/dist/sticky-routing.d.ts

@@ -111,6 +111,14 @@ export declare class StickySessionRouter {
         vaultSeed?: NativeVaultRoutingSeed;
         localRecoveryPath?: string;
         onLockEvent?: (event: NativeLockEvent) => void;
+        /**
+         * Refuses once a newer version has moved the dataset this routing
+         * file belongs to. Every write runs it under the routing file's lock,
+         * before any temporary file is created.
+         */
+        relocationGuard?: {
+            assertNotRelocated(): Promise<void>;
+        };
     });
     private now;
     private readState;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/anthropic-auth-core",
-  "version": "2.2.8",
+  "version": "2.4.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@cortexkit/common-auth": "0.25.0"
+    "@cortexkit/common-auth": "0.28.0"
   },
   "dependencies": {
     "@cortexkit/claustrum-client": "0.12.0",