@cortexkit/anthropic-auth-core 2.4.0 → 2.4.2

package/dist/holder-registry.d.ts

@@ -1,6 +1,8 @@
 import { type NativeLockEvent } from './native-lock-observer.ts';
-import type { NativePoolPaths } from './pool-paths.ts';
+import { type OwnerOnlyOptions } from './owner-only.ts';
+import { type NativePoolPaths } from './pool-paths.ts';
 import { RelocatedError } from './relocation-guard.ts';
+import { StateLayoutRefusalError } from './state-layout-errors.ts';
 /** The file, beside a dataset's files, that lists the processes using them. */
 export declare const HOLDER_FILE_NAME = "anthropic-auth-holders.json";
 /** Lock name on the holder file: lock file `<holder file>.holders.lock`. */
@@ -90,7 +92,14 @@ export declare const HOLDER_REGISTRATION_ERROR_MESSAGES: readonly string[];
  * roster operations wrap what their hooks throw in their own error, which
  * keeps the original as its `cause`, so the chain is followed a few levels.
  */
-export declare function stateRefusalCause(error: unknown): RelocatedError | HolderRegistrationError | undefined;
+export declare function stateRefusalCause(error: unknown): RelocatedError | HolderRegistrationError | StateLayoutRefusalError | undefined;
+/**
+ * The fixed message, naming no file or folder, to show for the relocation,
+ * registration or layout refusal behind `error`, or undefined when there is
+ * none. Hosts show it where their output may be shared; the refusal's own
+ * message and the log name the files.
+ */
+export declare function stateRefusalPublicMessage(error: unknown): string | undefined;
 /** How liveness is read; tests replace it. */
 export interface HolderLiveness {
     pidAlive(pid: number): boolean;
@@ -106,6 +115,28 @@ export declare function processIncarnation(pid: number): Promise<string | null>;
  * So pid reuse can keep a stale entry, but never clears a live one.
  */
 export declare function holderEntryIsLive(entry: Pick<HolderEntry, 'pid' | 'incarnation'>, liveness?: HolderLiveness): Promise<boolean>;
+export interface HolderFileContents {
+    /** Entries as found, including any this version doesn't understand. */
+    entries: unknown[];
+}
+/** An entry's pid and incarnation when it has a usable shape. */
+export declare function holderEntryLiveness(value: unknown): Pick<HolderEntry, 'pid' | 'incarnation'> | undefined;
+/**
+ * Read a holder file. Undefined when it is absent. A file that exists but
+ * doesn't parse throws: rewriting it would erase other processes' entries.
+ */
+export declare function readHolderFile(path: string): Promise<HolderFileContents | undefined>;
+/**
+ * Refuse dataset paths a caller chose itself, rather than the layout
+ * decision, when they reach into the state folder: paths resolved in the
+ * state-home layout, or with any dataset file in a folder anthropic-auth
+ * manages (holding `config-dir.json` or `layout.json`) or in a
+ * destination-shaped folder. Serving such files needs the decision's
+ * admission under the holder lock, which checks the move record; registering
+ * them as an ordinary `legacy` dataset would skip it. Throws
+ * `HolderRegistrationError('managed-folder')`, whose message is fixed.
+ */
+export declare function assertUnmanagedInjectedPaths(paths: NativePoolPaths): Promise<void>;
 export interface RegisterNativePoolHolderOptions {
     paths: NativePoolPaths;
     role: HolderRole;
@@ -118,6 +149,18 @@ export interface RegisterNativePoolHolderOptions {
     retryIntervalMs?: number;
     liveness?: HolderLiveness;
     now?: () => number;
+    /** How a missing folder is made owner-only; tests simulate Windows here. */
+    ownerOnly?: OwnerOnlyOptions;
+    /**
+     * `mandatory`: the entry is published in every holder file before the
+     * process serves, even before any dataset file exists there, and any
+     * failure to publish refuses with `HolderRegistrationError`. The layout
+     * decision passes it once moving is enabled (`unmovedRegistrationPolicy`).
+     * Without it, a failed write refuses only for an `explicit` or `pi`
+     * dataset with a file in a destination-shaped folder; every other failure
+     * is retried in the background.
+     */
+    policy?: 'mandatory';
 }
 /** The outcome of a registration that did not refuse. */
 export interface NativeHolderRegistration {
@@ -132,6 +175,34 @@ export interface NativeHolderRegistration {
     /** Stop retrying. Published entries stay; later writers prune them once the pid is dead. */
     close(): void;
 }
+/**
+ * Create `dir` for a holder file when it is missing, readable by its owner
+ * only: `0700` on POSIX, and on Windows a protected owner-only DACL set by
+ * the native helper as the folder is created, along with any missing parent.
+ * An existing folder is left exactly as it is: it may be the user's own
+ * config folder, shared on purpose. On Windows a folder that another process
+ * created first is adopted only if it is owner-only; otherwise this throws.
+ */
+export declare function ensureHolderDirectory(dir: string, ownerOnly?: OwnerOnlyOptions): Promise<void>;
+/**
+ * Add `entry` to `holderFile`, pruning entries of dead processes, while the
+ * caller holds that file's `holders` lock. Writes nothing when a live entry
+ * for this process, kind and files is already there. A holder file that
+ * doesn't parse throws and is never overwritten.
+ */
+export declare function publishHolderEntryLocked(holderFile: string, entry: HolderEntry, options: {
+    liveness?: HolderLiveness;
+    assertOwned(): Promise<void>;
+}): Promise<void>;
+/** A holder entry for this process. */
+export declare function buildHolderEntry(input: {
+    role: HolderRole;
+    kind: HolderKind;
+    identity: string | null;
+    files: readonly string[];
+    liveness?: HolderLiveness;
+    now?: () => number;
+}): Promise<HolderEntry>;
 /**
  * Record, beside a dataset's files, that this process uses them, before the
  * process's first pool I/O for that dataset. A later release reads these
@@ -142,7 +213,9 @@ export interface NativeHolderRegistration {
  * dataset lies in a folder anthropic-auth manages (`HolderRegistrationError`
  * with `managed-folder`).
  *
- * A failed write is handled by kind:
+ * A failed write is handled by `options.policy`. With `mandatory` the call
+ * throws `HolderRegistrationError` and the process must not serve. Without
+ * it, by kind:
  * - An `explicit` or `pi` dataset with a file in a destination-shaped folder
  *   (see `isDestinationShapedDirectory`) must be registered there, so the
  *   call throws `HolderRegistrationError` and the process must not serve it.
@@ -155,5 +228,17 @@ export interface NativeHolderRegistration {
  * for data locks.
  */
 export declare function registerNativePoolHolder(options: RegisterNativePoolHolderOptions): Promise<NativeHolderRegistration>;
+/**
+ * Hand a registration that already failed once to the ordinary policy's
+ * background retry, for a caller that tried to publish `options`'s entry
+ * itself and may serve without it: log the failure at WARN (once per folder
+ * and process) and retry at most once a minute until it succeeds or `close()`
+ * is called. A retry that finds a relocation tombstone or a managed folder
+ * stops retrying; the relocation guards then refuse every later write.
+ */
+export declare function deferNativePoolHolderRegistration(options: RegisterNativePoolHolderOptions, failure: {
+    readonly directory: string;
+    readonly error: unknown;
+}): NativeHolderRegistration;
 /** Forget what this process has published; tests only. */
 export declare function resetNativeHolderRegistryForTests(): void;

package/dist/index.d.ts

@@ -89,7 +89,10 @@ export * from './routing.ts';
 export type { SseEvent, SseFramer, SseFramerOptions } from './sse.ts';
 export { createSseFramer, DEFAULT_SSE_MAX_FRAME_BYTES, decodeSseFrame, isSseCandidateFrame, isTerminatedSseFrame, parseSseFrame, SseFrameTooLargeError, } from './sse.ts';
 export * from './start.ts';
+export * from './state-layout-decision.ts';
+export * from './state-layout-errors.ts';
 export * from './state-layout-paths.ts';
+export * from './state-layout-restore.ts';
 export * from './sticky-routing.ts';
 export * from './thinking-binding.ts';
 export * from './turn-end-note.ts';