@cortexkit/anthropic-auth-core 2.1.1 → 2.1.2

package/dist/internal-types/fs/atomic-write.d.ts

@@ -0,0 +1,25 @@
+import { type PrivateWriteOutcome } from './private-files.js';
+export interface AtomicWriteOptions {
+    serialize?: (value: unknown) => string;
+    beforeRename?: () => Promise<void>;
+    /** Test seam for forcing staging-name collisions; defaults to randomUUID. */
+    stageName?: () => string;
+    /** Sync the staged file and, after rename, its parent directory. Opt-in. */
+    durable?: boolean;
+    /** Windows opt-in: flush file bytes, without promising directory metadata durability. */
+    durability?: 'file-only-on-windows';
+    /** Reports Windows rename success, file/directory durability, retry counts and error codes, never file bytes. */
+    onOutcome?: (outcome: PrivateWriteOutcome) => void;
+}
+/** Internal classification of fsync failures, including a failure after rename. */
+export declare class AtomicSyncError extends Error {
+    constructor(cause: unknown);
+}
+export declare function writeJsonAtomic(path: string, value: unknown, options?: AtomicWriteOptions): Promise<void>;
+/**
+ * Notify internal callers at the rename. The store records committed writes
+ * and removed ids here, because a later directory sync cannot undo the rename.
+ */
+export declare function writeJsonAtomicTracked(path: string, value: unknown, options: AtomicWriteOptions, onRenamed?: () => void): Promise<void>;
+/** Make an already renamed file and its directory durable without rewriting bytes. */
+export declare function syncJsonFile(path: string): Promise<void>;

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

@@ -0,0 +1,9 @@
+export type { AtomicWriteOptions } from './atomic-write.js';
+export { writeJsonAtomic } from './atomic-write.js';
+export { WRITER_LOCK_CONSTANTS } from './lock-constants.js';
+export type { PrivateWriteOutcome } from './private-files.js';
+export { PrivateFileError } from './private-files.js';
+export type { LockLoss, RefreshFileLock } from './refresh-file-lock.js';
+export { acquireRefreshFileLock, isLostMarkerRaceError, } from './refresh-file-lock.js';
+export type { LockOptions, LockOwnershipDetails } from './with-lock.js';
+export { LockContentionError, LockOwnershipError, lockPathFor, withLock, } from './with-lock.js';

package/dist/internal-types/fs/lock-constants.d.ts

@@ -0,0 +1,14 @@
+export declare const WRITER_LOCK_CONSTANTS: Readonly<{
+    sidebar: Readonly<{
+        name: "sidebar-write";
+        ttlMs: 10000;
+        timeoutMs: 15000;
+        renew: true;
+    }>;
+    preferences: Readonly<{
+        name: "preferences";
+        ttlMs: 10000;
+        timeoutMs: 2000;
+        renew: true;
+    }>;
+}>;

package/dist/internal-types/fs/private-files.d.ts

@@ -0,0 +1,66 @@
+import { rename } from 'node:fs/promises';
+import type { PosixOwnerOnlyPathAsyncOptions } from '@cortexkit/private-files';
+export declare const windowsPrivateFiles: boolean;
+type Backend = typeof import('@cortexkit/private-files');
+type Kind = 'file' | 'directory';
+/** Tests inject a backend here; production always imports the private-files package. */
+export declare function setPrivateFilesBackendForTest(api?: Backend): void;
+export declare class PrivateFileError extends Error {
+    readonly path: string;
+    readonly stage: string;
+    readonly code: string;
+    readonly win32Code?: number;
+    readonly reason?: string;
+    published: boolean;
+    durabilityConfirmed: boolean;
+    fileDurable: boolean;
+    attempts: number;
+    elapsedMs: number;
+    orphanPath?: string;
+    constructor(path: string, stage: string, cause: unknown);
+}
+export declare function privateOperation<T>(path: string, stage: string, operation: () => Promise<T>): Promise<T>;
+/** Tests only: policy options used by safe-parent checks that pass none. */
+export declare function setSafeParentOptionsForTest(options?: PosixOwnerOnlyPathAsyncOptions): void;
+/** Existing containing directories use the shared entry-integrity policy, not secret-file permissions. */
+export declare function verifySafeDirectory(path: string, options?: PosixOwnerOnlyPathAsyncOptions): Promise<void>;
+/** Repair only the specific owned secret file supplied by a caller, never an existing directory tree. */
+export declare function verifyPrivate(path: string, kind: Kind, migrate?: boolean): Promise<void>;
+/** Create missing components privately; inspect existing ancestors without modifying them. */
+export declare function ensurePrivateDirectory(path: string, _migrate?: boolean, options?: PosixOwnerOnlyPathAsyncOptions): Promise<void>;
+export declare function readPrivateText(path: string, migrate?: boolean): Promise<string>;
+export declare function readPrivateBuffer(path: string, migrate?: boolean): Promise<Buffer>;
+export declare function createPrivateBytes(path: string, bytes: string): Promise<void>;
+export declare function createPrivateDirectoryExclusive(path: string): Promise<void>;
+export interface ReplaceOptions {
+    beforeRename?: () => Promise<void>;
+    /** Absolute monotonic deadline, for an expiring lease. */
+    deadline?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    rename?: typeof rename;
+}
+/** Retry Windows rename sharing/access errors within a budget; they never prove lease contention. */
+export declare function replaceWindowsFile(from: string, to: string, options?: ReplaceOptions): Promise<{
+    attempts: number;
+    elapsedMs: number;
+}>;
+export interface PrivateWriteOutcome {
+    path: string;
+    stage: string;
+    published: boolean;
+    fileDurable: boolean;
+    durabilityConfirmed: boolean;
+    attempts: number;
+    elapsedMs: number;
+    code?: string;
+    win32Code?: number;
+}
+export declare function writePrivateAtomic(path: string, bytes: string, options?: ReplaceOptions & {
+    stagePath?: string;
+    onRenamed?: () => void;
+    durable?: boolean;
+    durability?: 'file-only-on-windows';
+    onOutcome?: (outcome: PrivateWriteOutcome) => void;
+}): Promise<void>;
+export {};

package/dist/internal-types/fs/with-lock.d.ts

@@ -0,0 +1,36 @@
+import { acquireRefreshFileLock } from './refresh-file-lock.js';
+export declare function lockPathFor(target: string, name: string): string;
+export declare class LockContentionError extends Error {
+    readonly details: {
+        target: string;
+        name: string;
+        timeoutMs: number;
+    };
+    constructor(details: {
+        target: string;
+        name: string;
+        timeoutMs: number;
+    });
+}
+export interface LockOwnershipDetails {
+    target: string;
+    name: string;
+    expectedOwnerId?: string;
+    observedOwnerId?: string;
+    observedExpiresAt?: number;
+}
+export declare class LockOwnershipError extends Error {
+    readonly details: LockOwnershipDetails;
+    constructor(details: LockOwnershipDetails);
+}
+export interface LockOptions {
+    name: string;
+    ttlMs: number;
+    timeoutMs: number;
+    renew?: boolean;
+    onStep?: Parameters<typeof acquireRefreshFileLock>[0]['onStep'];
+    onRenewalTimer?: Parameters<typeof acquireRefreshFileLock>[0]['onRenewalTimer'];
+}
+export declare function withLock<T>(target: string, options: LockOptions, fn: (lock: {
+    assertOwned(): Promise<void>;
+}) => Promise<T>): Promise<T>;

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

@@ -5,6 +5,7 @@ import { type NativeAccountMetadataPatch, type NativeAccountSnapshot, type Nativ
 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 NativeLockEvent } from './native-lock-observer.ts';
 import { type NativeQuotaObservations } from './native-quota-observations.ts';
 import type { NativeKnownCredentialSubject, NativeRefreshResult, NativeRefreshSubject } from './native-refresh-coordinator.ts';
 import { type NativeDisplayProfile, type NativeVaultQuotaPurpose, type NativeVaultRuntime, type NativeVaultRuntimeOptions } from './native-vault-runtime.ts';
@@ -18,7 +19,7 @@ export interface NativeAccountRuntimeOptions {
     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'>>;
+    local?: Partial<Pick<NativeLocalCredentialServiceOptions, 'refreshToken' | 'resolveIdentity' | 'failurePolicy' | 'now' | 'onLockEvent'>>;
     vault?: Omit<NativeVaultRuntimeOptions, 'paths' | 'host'>;
 }
 export interface NativeLocalAuthorizeOptions {
@@ -45,9 +46,11 @@ export type NativeRelayUpdate = Partial<Omit<RelayConfig, 'token'>> & {
     token?: string | null;
 };
 export interface NativeAccountRuntime {
+    readonly onLockEvent?: (event: NativeLockEvent) => void;
     readonly vault: NativeVaultRuntime;
     readonly quotaObservations: NativeQuotaObservations;
     drainQuotaPublications(): Promise<void>;
+    drainRoutingPublications(): Promise<void>;
     /** Fresh private relay authorization for transport only; never include it in a status snapshot. */
     getRelayConfig(): Promise<RelayConfig | null>;
     updateRelay(patch: NativeRelayUpdate): Promise<void>;
@@ -111,7 +114,7 @@ export interface NativeAccountRuntime {
     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;
+    close(): void | Promise<void>;
     getSettingsPath(): Promise<string>;
 }
 /** Host instances own leases, while stores and the vault connection live until the last release. */

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

@@ -1,4 +1,5 @@
 import { type NativeLocalExternalPolicy } from './native-local-runtime-readers.ts';
+import type { NativeLockEvent } from './native-lock-observer.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';
@@ -46,6 +47,7 @@ export interface NativeLocalCredentialServiceOptions {
     readonly refreshToken?: NativeRefreshCoordinatorOptions['refreshToken'];
     /** Account lookup for new access; defaults to the Claude Code identity lookup. */
     readonly resolveIdentity?: NativeRefreshCoordinatorOptions['resolveIdentity'];
+    readonly onLockEvent?: (event: NativeLockEvent) => void;
 }
 /**
  * Hosts receive an access token only after its Claude account has been checked.

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

@@ -1,6 +1,11 @@
+import { withLock } from "./internal-types/fs/index.js";
+/** Mark work as background-origin without changing how it acquires or releases locks. */
+export declare function withDetachedNativeLocks<T>(work: () => Promise<T>): Promise<T>;
 /** Diagnostic evidence, not an ownership assertion or a control hook. */
 export type NativeLockEvent = {
-    type: 'acquired' | 'released' | 'contended';
+    type: 'acquiring' | 'acquired' | 'released' | 'contended';
+    /** Marks background-origin work; callers may still await the same shared refresh. */
+    detached?: boolean;
     name: string;
     path: string;
 };
@@ -10,3 +15,13 @@ export type NativeLockEvent = {
  * 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;
+/** Observe the real lease without changing acquisition, ownership or release. */
+export declare function withNativeLock<T>(path: string, options: Parameters<typeof withLock>[1] & {
+    onLockEvent?: (event: NativeLockEvent) => void;
+}, run: (lease: {
+    assertOwned(): Promise<void>;
+}) => Promise<T>, acquire?: typeof withLock): Promise<T>;
+/** Resolve the supplied acquisition function for each operation. */
+export declare function observeNativeLocks(acquire: () => typeof withLock, observer?: (event: NativeLockEvent) => void): <T>(path: string, options: Parameters<typeof withNativeLock>[1], run: (lease: {
+    assertOwned(): Promise<void>;
+}) => Promise<T>) => Promise<T>;

package/dist/native-runtime.d.ts

@@ -1,5 +1,6 @@
 import type { AccountOperationError, OAuthAccountProfile, PrimeUsageCounters } from './accounts.ts';
 import { type NativeLocalCredentialValidation } from './native-credential-validation.ts';
+import { type NativeLockEvent } from './native-lock-observer.ts';
 import { type NativeQuotaMap } from './native-quota-codec.ts';
 import type { NativeRefreshObservation, NativeRefreshSubject } from './native-refresh-coordinator.ts';
 import { type OwnerOnlyOptions } from './owner-only.ts';
@@ -72,6 +73,8 @@ export interface NativeRuntimeState {
     relay?: {
         token: string;
     };
+    /** Binds the private relay token (including its removal) to relay settings. */
+    relayGeneration?: string;
 }
 export type NativeRuntimeRead = {
     status: 'missing';
@@ -80,13 +83,16 @@ export type NativeRuntimeRead = {
     state: NativeRuntimeState;
 };
 export declare class NativeRuntimeError extends Error {
-    readonly code: 'invalid-runtime' | 'unsafe-runtime' | 'runtime-io' | 'runtime-conflict' | 'publication-refused';
-    constructor(code: 'invalid-runtime' | 'unsafe-runtime' | 'runtime-io' | 'runtime-conflict' | 'publication-refused');
+    readonly code: 'invalid-runtime' | 'unsafe-runtime' | 'runtime-io' | 'runtime-conflict' | 'publication-refused' | 'relay-inconsistent';
+    readonly status?: 400;
+    readonly retryable?: false;
+    constructor(code: 'invalid-runtime' | 'unsafe-runtime' | 'runtime-io' | 'runtime-conflict' | 'publication-refused' | 'relay-inconsistent');
 }
 /** Validate structure and internal identifier consistency. The publisher separately checks these identifiers against the current pool or vault roster. */
 export declare function decodeNativeRuntime(value: unknown, storageId: string): NativeRuntimeState;
 export declare function readNativeRuntime(path: string, storageId: string, ownership?: OwnerOnlyOptions): Promise<NativeRuntimeRead>;
 export interface NativeRuntimeWriteHooks {
+    onLockEvent?: (event: NativeLockEvent) => void;
     publication?: PublicationOptions;
     /** Verify that the observed account still matches the current pool record or vault roster and that the caller still owns the locks protecting those records. */
     beforeRename?: () => Promise<void>;
@@ -115,6 +121,7 @@ export type NativeRuntimeOptionalPublication = {
     status: 'skipped';
 };
 export interface NativeRuntimeOptionalWriteHooks {
+    onLockEvent?: (event: NativeLockEvent) => void;
     publication?: PublicationOptions;
     /**
      * Same checks as NativeRuntimeWriteHooks.beforeRename, run at the same
@@ -136,14 +143,14 @@ export declare function updateNativeRuntimeOptional(path: string, storageId: str
  * account permission to make another model request; admission checks still apply.
  * No caller mutator or publication callback can widen this transition.
  */
-export declare function publishNativeLocalFirstIdentity(paths: NativePoolPaths, observation: NativeRefreshObservation, hooks?: Pick<NativeRuntimeWriteHooks, 'beforePublish'>): Promise<NativeRuntimeState>;
+export declare function publishNativeLocalFirstIdentity(paths: NativePoolPaths, observation: NativeRefreshObservation, hooks?: Pick<NativeRuntimeWriteHooks, 'beforePublish' | 'onLockEvent'>): Promise<NativeRuntimeState>;
 /**
  * Record successful credential validation for a local account with a known UUID.
  * Bootstrap must provide the state captured before its request and the exact
  * credentials it checked. An unidentified entry requires first-identity publication.
  * Recording validation for a disabled entry does not enable it or permit serving.
  */
-export declare function publishNativeLocalCredentialValidation(paths: NativePoolPaths, observation: NativeRefreshObservation, hooks?: Pick<NativeRuntimeWriteHooks, 'beforePublish'>): Promise<NativeRuntimeState>;
+export declare function publishNativeLocalCredentialValidation(paths: NativePoolPaths, observation: NativeRefreshObservation, hooks?: Pick<NativeRuntimeWriteHooks, 'beforePublish' | 'onLockEvent'>): Promise<NativeRuntimeState>;
 export interface NativeLocalFailurePolicy {
     readonly checkedAt: number;
     /** A nextRetryAt equal to checkedAt adds no delay beyond the recorded failure time. */
@@ -205,4 +212,4 @@ export declare function classifyNativeLocalFailure(observation: NativeRefreshObs
  * This does not validate credentials or repair their account identity. Credentials
  * are saved separately; a metadata write failure cannot undo a token exchange.
  */
-export declare function publishNativeLocalRefreshFailure(paths: NativePoolPaths, observation: NativeRefreshObservation, policy: NativeLocalFailurePolicy, hooks?: Pick<NativeRuntimeWriteHooks, 'beforePublish'>): Promise<NativeLocalFailurePublication>;
+export declare function publishNativeLocalRefreshFailure(paths: NativePoolPaths, observation: NativeRefreshObservation, policy: NativeLocalFailurePolicy, hooks?: Pick<NativeRuntimeWriteHooks, 'beforePublish' | 'onLockEvent'>): Promise<NativeLocalFailurePublication>;

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

@@ -1,3 +1,4 @@
+import { type NativeLockEvent } from './native-lock-observer.ts';
 import { type NativePoolStorePaths } from './pool-store.ts';
 /**
  * A local account could not be authorized because another writer was part
@@ -34,4 +35,4 @@ export declare function isNativeTransientAccountError(value: unknown): value is
  * every attempt too, so a cancelled caller never takes a lock. All pool
  * leases use wall time, independently of logical observation timestamps.
  */
-export declare function joinNativePoolWrite(paths: NativePoolStorePaths, signals: readonly AbortSignal[], check: () => void): Promise<'joined' | 'deadline'>;
+export declare function joinNativePoolWrite(paths: NativePoolStorePaths, signals: readonly AbortSignal[], check: () => void, onLockEvent?: (event: NativeLockEvent) => void): Promise<'joined' | 'deadline'>;

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

@@ -2,6 +2,7 @@ import type { ClaustrumClientOptions } from '@cortexkit/claustrum-client';
 import { type OAuthAccountProfile, type OAuthQuotaSnapshot, type PrimeUsageDelta } from './accounts.ts';
 import { type NativeAccountMetadataPatch } from './native-account-view.ts';
 import { type NativeCustodyClient, type NativeCustodyInventory, type NativeCustodyReceipt, type NativeCustodyReporterSource, type NativeCustodyRetry } from './native-custody.ts';
+import { type NativeLockEvent } from './native-lock-observer.ts';
 import { NativeQuotaObservations } from './native-quota-observations.ts';
 import { type NativeRosterSeedInput, type NativeVaultRosterDocument, type NativeVaultRosterSeed } from './native-roster-seed.ts';
 import { type NativeRuntimeState } from './native-runtime.ts';
@@ -21,6 +22,7 @@ export interface NativeVaultRuntimeOptions {
     }>;
     env?: NodeJS.ProcessEnv;
     now?: () => number;
+    onLockEvent?: (event: NativeLockEvent) => void;
     /**
      * Timer functions for the vault custody's outage probe and roster watch
      * retries. Defaults to the global ones; tests pass their own.

package/dist/sticky-routing.d.ts

@@ -1,4 +1,5 @@
 import { type AccountOperationError, type AccountStorage, type OAuthQuotaSnapshot } from './accounts.ts';
+import { type NativeLockEvent } from './native-lock-observer.ts';
 import type { NativeVaultRosterDocument } from './native-roster-seed.ts';
 import { type NativeVaultRoutingSeed } from './native-vault-seed.ts';
 export declare const STICKY_ROUTING_MAIN_ACCOUNT_ID = "main";
@@ -99,7 +100,9 @@ export declare class StickySessionRouter {
     private loaded;
     private state;
     private stateMtimeNs;
-    private touchChain;
+    private publicationChain;
+    private seedPublication;
+    private readonly changes;
     private seedFinalized;
     constructor(options: {
         path: string;
@@ -107,6 +110,7 @@ export declare class StickySessionRouter {
         assignmentTtlMs?: number;
         vaultSeed?: NativeVaultRoutingSeed;
         localRecoveryPath?: string;
+        onLockEvent?: (event: NativeLockEvent) => void;
     });
     private now;
     private readState;
@@ -119,11 +123,17 @@ export declare class StickySessionRouter {
     private prune;
     private writeState;
     private writeResolutionState;
-    /** Import legacy session pins only after vault account discovery produces a complete verified roster. No empty routing file is published while that roster is incomplete. */
+    /** Queue legacy-pin import in the background; take its writer lease only after verifying a complete roster. */
     prepareLegacySeed(knownRoster?: NativeVaultRosterDocument | null): Promise<void>;
     private logicalAccountId;
     setVaultSeed(seed: NativeVaultRoutingSeed | undefined): void;
     private scheduleTouch;
+    private overlayChanges;
+    private enqueuePublication;
+    private scheduleChange;
+    private retryChange;
+    /** Wait for owned background publications during host disposal or fixture cleanup. */
+    drain(): Promise<void>;
     private selectCandidate;
     resolve(input: {
         sessionId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/anthropic-auth-core",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "type": "module",
   "repository": {
     "type": "git",