@cortexkit/common-auth 0.11.3 → 0.11.4

package/README.md

@@ -11,14 +11,14 @@ Shared libraries for the CortexKit auth plugins for OpenCode and Pi: openai-auth
 
 A passing safety test proves little until it has been seen to fail. [`mutations.toml`](mutations.toml) is the checked-in catalogue: each row deliberately breaks one guard in `src/` (or a CI scan script) and names the Bun test that must fail because of it, so a guard cannot silently stop guarding. A row earns its place by guarding a silent, costly failure: lock exclusion, crash safety, credential loss or leakage, a single-use token used twice, misattributed quota, a wire contract, data loss. Style and cosmetics do not.
 
-The pinned [`ck-mutate`](https://github.com/cortexkit/commons/tree/7d08e73722fa3e79bbcc2607753978ab768f1c6b/crates/cortexkit-mutate) runner replays it from a clean tree. It installs and builds first (fixtures import `dist/`), checks each named test passes, applies the break, rebuilds, requires the test to fail, and restores the source byte for byte:
+The pinned [`ckdev-mutate`](https://github.com/cortexkit/commons/tree/46cc166b0df2edcfd14b3eb54ed6eeac588fed69/crates/cortexkit-mutate) runner replays it from a clean tree. It installs and builds first (fixtures import `dist/`), checks each named test passes, applies the break, rebuilds, requires the test to fail, and restores the source byte for byte:
 
 ```sh
-cargo install --locked --git https://github.com/cortexkit/commons --rev 7d08e73722fa3e79bbcc2607753978ab768f1c6b cortexkit-mutate
-ck-mutate check
-ck-mutate run --all
-ck-mutate run --diff origin/main
-ck-mutate run --only fs-lock-try-once-refuses-held-lock
+cargo install --locked --git https://github.com/cortexkit/commons --rev 46cc166b0df2edcfd14b3eb54ed6eeac588fed69 cortexkit-mutate
+ckdev-mutate check
+ckdev-mutate run --all
+ckdev-mutate run --diff origin/main
+ckdev-mutate run --only fs-lock-try-once-refuses-held-lock
 ```
 
 Every row must report CAUGHT. Replay with the Bun version CI pins (1.3.14): the row `rpc-declared-oversize-413-half-closes` guards the RPC server's workaround for Bun 1.3.14 reusing a connection the server refused with 413. Bun 1.4.2 never reuses it, so that row survives there. Rows are command rows: `{test}` is a Bun `-t` filter, a regular expression over the full test name (describe names and test name joined by spaces), so ids are anchored, escaped, and spell each space `\s`. CI replays the rows a pull request's diff selects, the full catalogue on every push to main, and the full catalogue with `--broad` nightly. Never `git checkout` a file while a replay runs: it removes the mutation and fakes a survivor.

package/dist/rpc/port-file.d.ts

@@ -28,4 +28,6 @@ export interface DiscoverPortFileOptions {
      */
     exactPid?: boolean;
 }
+/** Internal cache validation: probe only the selected file and its PID. */
+export declare function portFileIdentity(dir: string, entry: PortFileEntry): Promise<string | null>;
 export declare function discoverPortFile(dir: string, expectedPid?: number, options?: DiscoverPortFileOptions): Promise<PortFileEntry | null>;

package/dist/rpc/port-file.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { chmod, mkdir, open, readdir, readFile, rename, rmdir, unlink, } from 'node:fs/promises';
+import { chmod, mkdir, open, readdir, readFile, rename, rmdir, stat, unlink, } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 /**
  * A PID a liveness probe may address. `process.kill(0 | negative, 0)` signals
@@ -166,6 +166,19 @@ export async function sweepRpcState(root, activeDir, isManagedDir, log) {
             await rmdir(dir).catch(() => { });
     }
 }
+/** Internal cache validation: probe only the selected file and its PID. */
+export async function portFileIdentity(dir, entry) {
+    if (!pidAlive(entry.pid))
+        return null;
+    const path = join(resolve(dir), `port-${entry.pid}.json`);
+    try {
+        const info = await stat(path);
+        return `${path}:${info.dev}:${info.ino}:${info.mtimeMs}:${info.size}`;
+    }
+    catch {
+        return null;
+    }
+}
 export async function discoverPortFile(dir, expectedPid, options = {}) {
     let names;
     try {

package/dist/rpc/rpc-client.d.ts

@@ -1,5 +1,5 @@
 import type { ApplyRequest, ApplyResult, RpcNotification } from './notifications.js';
-import { type DiscoverPortFileOptions, type PortFileEntry } from './port-file.js';
+import { type DiscoverPortFileOptions, discoverPortFile, type PortFileEntry } from './port-file.js';
 export interface RpcClient {
     pending: (lastReceivedId: number, sessionId?: string, timeoutMs?: number) => Promise<RpcNotification[]>;
     apply: (request: ApplyRequest, timeoutMs?: number) => Promise<ApplyResult>;
@@ -11,7 +11,10 @@ export declare const DEFAULT_RPC_TIMEOUT_MS = 2000;
  * opening a socket, on every call. Off by default, when a call falls back to
  * the newest live server.
  */
-export type RpcClientOptions = DiscoverPortFileOptions;
+export type RpcClientOptions = DiscoverPortFileOptions & {
+    /** Internal discovery-count seam. */
+    discover?: typeof discoverPortFile;
+};
 /**
  * A client for the server in `dir`, preferring `expectedPid`'s.
  *
@@ -20,6 +23,8 @@ export type RpcClientOptions = DiscoverPortFileOptions;
  * a gate: an observer that throws rejects that call before any request is
  * sent and is asked again on the next call, but nothing stops a later call
  * once an observer has returned. A caller that must never reach another
- * server passes `{ exactPid: true }`.
+ * server passes `{ exactPid: true }`. Validated selections are shared by
+ * directory, expected PID and exactPid until their file identity changes or a
+ * connect/auth/stale-server failure triggers one rediscovery in the same call.
  */
 export declare function createRpcClient(dir: string, expectedPid?: number, onSelected?: (entry: PortFileEntry | null) => void, options?: RpcClientOptions): RpcClient;

package/dist/rpc/rpc-client.js

@@ -1,30 +1,87 @@
+import { open } from 'node:fs/promises';
 import { connect } from 'node:net';
-import { discoverPortFile, } from './port-file.js';
+import { join, resolve } from 'node:path';
+import { discoverPortFile, portFileIdentity, } from './port-file.js';
 export const DEFAULT_RPC_TIMEOUT_MS = 2_000;
-async function call(dir, expectedPid, discoverOptions, onSelected, method, params, timeoutMs = DEFAULT_RPC_TIMEOUT_MS) {
-    const entry = await discoverPortFile(dir, expectedPid, discoverOptions);
-    onSelected?.(entry);
-    if (!entry)
+const selections = new Map();
+const discoveries = new Map();
+// The identity a cached selection is checked against must belong to the bytes
+// that named this server. Statting the path after discovery is not enough: the
+// file can be replaced in between, which would pin the old server to the new
+// file's identity. So read and fstat one open descriptor, and bind only when
+// those bytes still name the discovered entry.
+async function boundIdentity(dir, entry) {
+    const path = join(resolve(dir), `port-${entry.pid}.json`);
+    let handle;
+    try {
+        handle = await open(path, 'r');
+        const info = await handle.stat();
+        const current = JSON.parse(await handle.readFile('utf8'));
+        if (current.pid !== entry.pid ||
+            current.port !== entry.port ||
+            current.token !== entry.token)
+            return null;
+        return `${path}:${info.dev}:${info.ino}:${info.mtimeMs}:${info.size}`;
+    }
+    catch {
         return null;
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}
+async function select(key, dir, expectedPid, options) {
+    const cached = selections.get(key);
+    if (cached && (await portFileIdentity(dir, cached.entry)) === cached.identity)
+        return cached;
+    selections.delete(key);
+    const pending = discoveries.get(key);
+    if (pending)
+        return pending;
+    const discovery = (async () => {
+        const entry = await (options.discover ?? discoverPortFile)(dir, expectedPid, options);
+        if (!entry)
+            return null;
+        const identity = await boundIdentity(dir, entry);
+        // The file changed under discovery: use what was discovered for this
+        // call, as an uncached selection, so the next call discovers again.
+        if (!identity)
+            return { entry, identity: '' };
+        const selected = { entry, identity };
+        selections.set(key, selected);
+        return selected;
+    })();
+    discoveries.set(key, discovery);
+    try {
+        return await discovery;
+    }
+    finally {
+        if (discoveries.get(key) === discovery)
+            discoveries.delete(key);
+    }
+}
+async function request(entry, method, params, timeoutMs = DEFAULT_RPC_TIMEOUT_MS) {
     // A raw loopback socket never consults runtime HTTP proxy settings, which
     // otherwise can expose the bearer token to a configured proxy. timeoutMs is
     // a total deadline for connect, request and the full response, not idle time.
     return new Promise((resolve) => {
         let socket;
         let settled = false;
-        const done = (value) => {
+        let connected = false;
+        const done = (value, stale = false) => {
             if (settled)
                 return;
             settled = true;
             clearTimeout(timer);
             socket?.destroy();
-            resolve(value);
+            resolve({ value, stale });
         };
         const timer = setTimeout(() => done(null), timeoutMs);
         try {
             const body = JSON.stringify(params);
             socket = connect({ host: '127.0.0.1', port: entry.port });
             socket.on('connect', () => {
+                connected = true;
                 // HTTP/1.0 avoids chunked responses; explicitly request connection close
                 // because older Bun servers can keep delayed HTTP/1.0 replies open.
                 socket?.write(`POST /rpc/${method} HTTP/1.0\r\n` +
@@ -69,8 +126,15 @@ async function call(dir, expectedPid, discoverOptions, onSelected, method, param
                             .toString('latin1')
                             .split('\r\n');
                         const status = /^HTTP\/1\.[01] (\d{3})(?: |$)/.exec(headers[0] ?? '');
-                        if (!status || Number(status[1]) < 200 || Number(status[1]) >= 300)
+                        if (!status)
                             return done(null);
+                        const code = Number(status[1]);
+                        if (code < 200 || code >= 300)
+                            // Only statuses meaning "this is not the server you meant" may
+                            // rediscover and resend. A 504 is this server's apply deadline:
+                            // the handler can still be running, so resending it to another
+                            // server could run the command twice. 5xx is never retried.
+                            return done(null, [401, 403, 404, 410].includes(code));
                         for (const header of headers.slice(1)) {
                             const colon = header.indexOf(':');
                             const name = header.slice(0, colon).toLowerCase();
@@ -107,14 +171,47 @@ async function call(dir, expectedPid, discoverOptions, onSelected, method, param
                     return done(null);
                 finishBody();
             });
-            socket.on('error', () => done(null));
+            socket.on('error', () => done(null, !connected));
             socket.on('close', () => done(null));
         }
         catch {
-            done(null);
+            done(null, !connected);
         }
     });
 }
+async function call(dir, expectedPid, options, onSelected, method, params, timeoutMs = DEFAULT_RPC_TIMEOUT_MS) {
+    const key = JSON.stringify([
+        resolve(dir),
+        expectedPid ?? null,
+        options.exactPid === true,
+    ]);
+    const selected = await select(key, dir, expectedPid, options);
+    onSelected(selected?.entry ?? null);
+    if (!selected)
+        return null;
+    const deadline = Date.now() + timeoutMs;
+    const out = await request(selected.entry, method, params, timeoutMs);
+    if (!out.stale)
+        return out.value;
+    if (selections.get(key) === selected)
+        selections.delete(key);
+    // Retry only definite pre-dispatch/stale-server failures, never an ambiguous
+    // response or timeout that could replay an already executed apply command.
+    const replacement = await select(key, dir, expectedPid, options);
+    if (!replacement || Date.now() >= deadline)
+        return null;
+    if (replacement.entry.port === selected.entry.port &&
+        replacement.entry.pid === selected.entry.pid &&
+        replacement.entry.token === selected.entry.token) {
+        if (selections.get(key) === replacement)
+            selections.delete(key);
+        return null;
+    }
+    const retry = await request(replacement.entry, method, params, deadline - Date.now());
+    if (retry.stale && selections.get(key) === replacement)
+        selections.delete(key);
+    return retry.value;
+}
 /**
  * A client for the server in `dir`, preferring `expectedPid`'s.
  *
@@ -123,11 +220,14 @@ async function call(dir, expectedPid, discoverOptions, onSelected, method, param
  * a gate: an observer that throws rejects that call before any request is
  * sent and is asked again on the next call, but nothing stops a later call
  * once an observer has returned. A caller that must never reach another
- * server passes `{ exactPid: true }`.
+ * server passes `{ exactPid: true }`. Validated selections are shared by
+ * directory, expected PID and exactPid until their file identity changes or a
+ * connect/auth/stale-server failure triggers one rediscovery in the same call.
  */
 export function createRpcClient(dir, expectedPid, onSelected, options = {}) {
     const discoverOptions = {
         exactPid: options.exactPid,
+        discover: options.discover,
     };
     let reportedSelection = false;
     const reportSelected = (entry) => {

package/dist/tui-prefs/watcher.d.ts

@@ -1,6 +1,22 @@
-import { watch } from 'node:fs';
+import { type Stats, watch } from 'node:fs';
+type Metadata = Pick<Stats, 'mtimeMs' | 'size' | 'ino' | 'dev'>;
 export interface TuiPreferencesWatchOptions {
     watchDirectory?: typeof watch;
+    /** Internal filesystem seam; the first subscriber supplies a shared watcher's I/O. */
+    fs?: {
+        readFileSync?: (file: string) => string;
+        readFile?: (file: string) => Promise<string>;
+        statSync?: (file: string) => Metadata;
+        stat?: (file: string) => Promise<Metadata>;
+    };
 }
-/** Watch the directory so atomic file replacement does not detach the watcher. */
+/**
+ * Share one directory watcher and metadata poll per canonical path, including
+ * across bundled copies. Native events use a 150 ms debounce; missed events
+ * recover through a 1,000 ms stat probe (formerly a 100 ms full-file poll).
+ * Watching the directory preserves atomic replacement and missing-file recovery.
+ * Only changed raw text notifies; each subscriber is isolated and independently
+ * disposable. The last unsubscribe stops both the native watcher and the poll.
+ */
 export declare function watchTuiPreferences(file: string, onChange: () => void, options?: TuiPreferencesWatchOptions): () => void;
+export {};

package/dist/tui-prefs/watcher.js

@@ -1,38 +1,111 @@
-import { readFileSync, watch } from 'node:fs';
-import { readFile } from 'node:fs/promises';
-import { basename, dirname } from 'node:path';
+import { readFileSync, realpathSync, statSync, watch, } from 'node:fs';
+import { readFile, stat } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
 import { clearTimeout, setTimeout } from 'node:timers';
-/** Watch the directory so atomic file replacement does not detach the watcher. */
+function canonicalPath(file) {
+    const path = resolve(file);
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        // Resolve existing ancestors even when the preferences file is not yet present.
+        const parent = dirname(path);
+        return parent === path ? path : join(canonicalPath(parent), basename(path));
+    }
+}
+function identity(info) {
+    return info && `${info.dev}:${info.ino}:${info.mtimeMs}:${info.size}`;
+}
+/**
+ * Share one directory watcher and metadata poll per canonical path, including
+ * across bundled copies. Native events use a 150 ms debounce; missed events
+ * recover through a 1,000 ms stat probe (formerly a 100 ms full-file poll).
+ * Watching the directory preserves atomic replacement and missing-file recovery.
+ * Only changed raw text notifies; each subscriber is isolated and independently
+ * disposable. The last unsubscribe stops both the native watcher and the poll.
+ */
 export function watchTuiPreferences(file, onChange, options = {}) {
-    const name = basename(file);
+    const globals = globalThis;
+    const key = Symbol.for('cortexkit.common-auth.tui-prefs.watchers.v1');
+    const registry = globals[key] ?? new Map();
+    globals[key] = registry;
+    const path = canonicalPath(file);
+    const shared = registry.get(path);
+    if (shared)
+        return shared.subscribe(onChange);
+    const name = basename(path);
+    const read = options.fs?.readFile ?? ((file) => readFile(file, 'utf8'));
+    const probe = options.fs?.stat ?? stat;
     let timer = null;
-    // An asynchronous seed could absorb a write made immediately after returning.
+    let pollTimer = null;
+    let lastMetadata = null;
     let lastSeen = null;
+    // Seed synchronously so an immediate write cannot be absorbed as the baseline.
+    // The metadata is recorded only together with contents that were read, as in
+    // the probe below: if the first read fails, the probe keeps trying.
     try {
-        lastSeen = readFileSync(file, 'utf8');
+        const metadata = identity((options.fs?.statSync ?? statSync)(path));
+        lastSeen = (options.fs?.readFileSync ?? ((file) => readFileSync(file, 'utf8')))(path);
+        lastMetadata = metadata;
     }
     catch {
-        // Missing files can be created later.
+        // Missing or unreadable files are picked up by the probe later.
     }
     let disposed = false;
-    const checkForChange = async () => {
-        const text = await readFile(file, 'utf8').catch(() => null);
-        if (disposed || text === null || text === lastSeen)
-            return;
-        lastSeen = text;
-        onChange();
+    const subscribers = new Set();
+    let checking = Promise.resolve();
+    const checkForChange = (native) => {
+        // Serialize native and poll checks so an older read cannot roll back state.
+        checking = checking.then(async () => {
+            if (disposed)
+                return;
+            const metadata = identity(await probe(path).catch(() => null));
+            if (!native && metadata === lastMetadata)
+                return;
+            // A missing file has nothing to read; remember that so the probe stays
+            // quiet until it reappears.
+            if (metadata === null) {
+                lastMetadata = null;
+                return;
+            }
+            const text = await read(path).catch(() => null);
+            if (disposed)
+                return;
+            // Record the metadata only once its contents were read. A failed read
+            // leaves the old value, so the next probe sees a change and retries
+            // instead of skipping a file whose new contents were never observed.
+            if (text === null)
+                return;
+            lastMetadata = metadata;
+            if (text === lastSeen)
+                return;
+            lastSeen = text;
+            for (const subscriber of [...subscribers]) {
+                if (!subscribers.has(subscriber))
+                    continue;
+                try {
+                    subscriber.notify();
+                }
+                catch {
+                    // A broken subscriber must not prevent the others from observing a change.
+                }
+            }
+        });
+        return checking;
     };
     const scheduleCheck = () => {
+        if (disposed)
+            return;
         if (timer)
             clearTimeout(timer);
         timer = setTimeout(() => {
             timer = null;
-            void checkForChange();
+            void checkForChange(true);
         }, 150);
     };
     let watcher = null;
     try {
-        watcher = (options.watchDirectory ?? watch)(dirname(file), (_event, filename) => {
+        watcher = (options.watchDirectory ?? watch)(dirname(path), (_event, filename) => {
             const eventName = filename?.toString();
             const isOurs = eventName === name ||
                 (eventName?.startsWith(`${name}.`) && eventName.endsWith('.tmp'));
@@ -43,14 +116,12 @@ export function watchTuiPreferences(file, onChange, options = {}) {
         watcher.on('error', () => {
             // Polling continues if the native watcher fails after construction.
             watcher?.close();
+            watcher = null;
         });
     }
     catch {
-        if (lastSeen === null)
-            return () => { };
+        // The probe still recovers a later creation, even with no native watcher.
     }
-    // Poll independently: directory watchers can miss rename events.
-    let pollTimer = null;
     const schedulePoll = () => {
         if (disposed || pollTimer)
             return;
@@ -58,17 +129,29 @@ export function watchTuiPreferences(file, onChange, options = {}) {
             pollTimer = null;
             if (disposed)
                 return;
-            void checkForChange().finally(schedulePoll);
-        }, 100);
+            void checkForChange(false).finally(schedulePoll);
+        }, 1_000);
         pollTimer.unref();
     };
-    schedulePoll();
-    return () => {
-        disposed = true;
-        if (timer)
-            clearTimeout(timer);
-        if (pollTimer)
-            clearTimeout(pollTimer);
-        watcher?.close();
+    const entry = {
+        subscribe: (notify) => {
+            const subscriber = { notify };
+            subscribers.add(subscriber);
+            return () => {
+                if (!subscribers.delete(subscriber) || subscribers.size > 0)
+                    return;
+                disposed = true;
+                if (timer)
+                    clearTimeout(timer);
+                if (pollTimer)
+                    clearTimeout(pollTimer);
+                watcher?.close();
+                if (registry.get(path) === entry)
+                    registry.delete(path);
+            };
+        },
     };
+    registry.set(path, entry);
+    schedulePoll();
+    return entry.subscribe(onChange);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.11.3",
+  "version": "0.11.4",
   "description": "Shared code for the CortexKit auth plugins: account pool, quota and routing, commands and auth menu, OpenCode 2 hooks, Claustrum custody, and plumbing (loopback RPC, file locks, logger, sidebar state, TUI preferences and build).",
   "license": "MIT",
   "repository": {