@cortexkit/anthropic-auth-core 2.3.0 → 2.4.0

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

@@ -107,6 +107,15 @@ export interface EnrollmentAncestorOptions {
  * sticky ancestors are accepted. Windows uses the shared safe-parent policy.
  */
 export declare function refuseWritableAncestor(parent: string, options?: EnrollmentAncestorOptions): Promise<void>;
+/**
+ * Create `directory` owner-only, or make an existing one owner-only. POSIX:
+ * every component it creates gets mode 0700, a directory another user owns is
+ * refused, and one that group or others can reach is tightened to 0700.
+ * Windows: private-files creates missing components owner-only and verifies
+ * existing ones without modifying them. `what` names the directory in the
+ * ownership refusal.
+ */
+export declare function ensureClaustrumPrivateDirectory(directory: string, options?: EnrollmentAncestorOptions, what?: string): 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

package/dist/internal-types/setup/flags.d.ts

@@ -0,0 +1,50 @@
+import type { OpenCodeGeneration, SetupHost } from './types.js';
+export declare const UNAVAILABLE_HOST_MESSAGE = "Requested setup host is unknown or unavailable. Use --host=opencode or --host=pi with a detected host.";
+type SwitchKey = 'yes' | 'dryRun' | 'claustrum' | 'noClaustrum' | 'login' | 'enrollOnly';
+/**
+ * One flag the shared setup parser accepts. A switch sets `key` to true; a
+ * value flag takes one of `values` as `--name=value`, and also as the next
+ * argument (`--name value`) when `spaceForm` is set. `invalid` replaces the
+ * unknown-argument refusal when a value flag gets a value it does not accept.
+ */
+export type SetupFlag = {
+    name: string;
+    key: SwitchKey;
+    description: string;
+} | {
+    name: string;
+    key: 'hosts' | 'opencode';
+    values: readonly string[];
+    spaceForm?: boolean;
+    invalid?: string;
+    description: string;
+};
+/**
+ * Every flag `runSetup` accepts. The parser and `setupUsage` both read this
+ * table, so the help a plugin prints cannot list a flag the parser refuses or
+ * leave out one it accepts.
+ */
+export declare const SETUP_FLAGS: readonly SetupFlag[];
+export interface SetupFlags {
+    yes: boolean;
+    dryRun: boolean;
+    claustrum: boolean;
+    noClaustrum: boolean;
+    login: boolean;
+    enrollOnly: boolean;
+    hosts: SetupHost[];
+    opencode: OpenCodeGeneration | undefined;
+}
+/** Parse setup's arguments against `SETUP_FLAGS`, refusing anything else. */
+export declare function parseSetupFlags(argv: readonly string[]): SetupFlags;
+/**
+ * The flags `runSetup` accepts, one per line, for a plugin's `setup --help`.
+ * The shared parser has no `--help` of its own: the plugin's bin checks for
+ * `--help` or `-h` before calling `runSetup`, prints this text and any lines of
+ * its own, and exits 0. With `command` the text starts with a usage line, such
+ * as `Usage: example-auth setup [flags]`.
+ */
+export declare function setupUsage(options?: {
+    command?: string;
+}): string;
+export {};

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

@@ -2,6 +2,7 @@ export { AMBIGUOUS_OPENCODE_MESSAGE, runSetup } from './command.js';
 export { SetupCommandError, setupEnrollment } from './command-error.js';
 export { detectHosts, detectOpenCodeGeneration, findExecutableOnPath, openCodeDesktopMarkers, } from './detect.js';
 export { ENROLLMENT_WAIT_MS, HostNotEnrolledError, type HostNotEnrolledReason, UNSUPPORTED_VAULT_MESSAGE, } from './enroll.js';
+export { setupUsage } from './flags.js';
 export { assertHostsStopped, createProcessFence, listSetupProcesses, ProcessFenceViolationError, ProcessInspectionError, type ProcessInspectionStep, } from './process-fence.js';
 export { type PlannedWrite, planOpenCodeRegistration, registerOpenCode, registerPi, updatePluginConfig, } from './register.js';
 export type { CommandResult, CommandRunner, HostDetection, OpenCodeGeneration, ProcessFence, SetupCallbackContext, SetupDetection, SetupEnrollmentOutcome, SetupEnvironment, SetupFileSystem, SetupHost, SetupHostEnrollment, SetupIO, SetupPlugin, SetupResult, } from './types.js';

package/dist/internal-types/setup/types.d.ts

@@ -61,7 +61,13 @@ export interface SetupPlugin {
      */
     beforeSignIn?(host: SetupHost, context: SetupCallbackContext): Promise<void>;
     signInLocal(host: SetupHost, context: SetupCallbackContext): Promise<void>;
-    migrate(host: SetupHost, context: SetupCallbackContext): Promise<void>;
+    /**
+     * Moves the host's existing provider credentials into place after the host
+     * is registered. Optional: a plugin with nothing to migrate (one that only
+     * reads credentials from the vault) leaves it out, and setup then neither
+     * calls it nor mentions migration in its dry-run plan.
+     */
+    migrate?(host: SetupHost, context: SetupCallbackContext): Promise<void>;
     /** Reject mixed local/vault credentials and activate provider-specific vault access before registration. */
     beforeRegister?(host: SetupHost, mode: 'local' | 'claustrum', context: SetupCallbackContext): Promise<void>;
 }

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,6 +48,12 @@ 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. */

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/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.3.0",
+  "version": "2.4.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -30,7 +30,7 @@
     "prepublishOnly": "bun run build"
   },
   "devDependencies": {
-    "@cortexkit/common-auth": "0.27.1"
+    "@cortexkit/common-auth": "0.28.0"
   },
   "dependencies": {
     "@cortexkit/claustrum-client": "0.12.0",