@cortexkit/common-auth 0.7.0 → 0.8.0

package/dist/logger/engine.d.ts

@@ -1,7 +1,9 @@
 import type { CaptureSink } from './capture-sink.js';
 import { type RedactionOptions } from './redact.js';
 export type Level = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/** A logger that writes to a file, and to a capture sink when one is given. */
 export interface InitLoggerOptions extends RedactionOptions {
+    /** Receives every emitted record, scrubbed, alongside the file. */
     captureSink?: CaptureSink;
     /**
      * Path of the file lines are appended to, or a function returning it.
@@ -15,6 +17,25 @@ export interface InitLoggerOptions extends RedactionOptions {
     /** Level floor applied when no `setLogLevel` call has overridden it. */
     level?: Level | (() => Level | undefined);
 }
+/**
+ * A logger with no file: the capture sink is its only destination. Nothing
+ * is written to disk or printed, for a host that forwards records to its own
+ * log.
+ */
+export interface SinkOnlyLoggerOptions extends RedactionOptions {
+    /** Receives every emitted record, scrubbed. */
+    captureSink: CaptureSink;
+    file?: undefined;
+    /** Level floor applied when no `setLogLevel` call has overridden it. */
+    level?: Level | (() => Level | undefined);
+}
+/**
+ * What a logger is configured with: a file (`InitLoggerOptions`, the shape
+ * every release before this one accepted, kept as its own interface so a
+ * caller deriving a type from it with `Pick` or `extends` keeps compiling) or
+ * a capture sink alone.
+ */
+export type LoggerOptions = InitLoggerOptions | SinkOnlyLoggerOptions;
 export interface ChannelLogger {
     error(message: string, data?: unknown): void;
     warn(message: string, data?: unknown): void;
@@ -37,7 +58,7 @@ export interface LoggerInstance {
      * alone, because it is the operator's explicit choice and outranks the
      * floor a host computed at start-up.
      */
-    configure(options: InitLoggerOptions): void;
+    configure(options: LoggerOptions): void;
     /** Operator override of the level floor; undefined removes it. */
     setLogLevel(level: Level | undefined): void;
     /**
@@ -53,14 +74,14 @@ export interface LoggerInstance {
  * uses this instead of `initLogger`, so neither replaces the other's file,
  * level, redaction or capture sink.
  */
-export declare function createLoggerInstance(options: InitLoggerOptions): LoggerInstance;
+export declare function createLoggerInstance(options: LoggerOptions): LoggerInstance;
 /**
  * Point the module's default logger at a host's file and level, and return
  * it. Idempotent: calling it again replaces both. A runtime level installed
  * by `setLogLevel` is deliberately left alone, because it is the operator's
  * explicit choice and outranks the floor a host computed at start-up.
  */
-export declare function initLogger(options: InitLoggerOptions): LoggerInstance;
+export declare function initLogger(options: LoggerOptions): LoggerInstance;
 export declare function setLogLevel(l: Level | undefined): void;
 /**
  * Write whatever the default logger has buffered. Safe to call synchronously

package/dist/logger/engine.js

@@ -126,7 +126,8 @@ function createEngine(options) {
             }, 500);
     }
     function emit(channel, level, message, data) {
-        if (logFileSource === undefined)
+        // Unconfigured (neither a file nor a sink) stays a silent no-op.
+        if (logFileSource === undefined && captureSink === undefined)
             return;
         try {
             if (ORDER[level] > ORDER[configuredLevel()])
@@ -152,6 +153,9 @@ function createEngine(options) {
                 });
             }
             catch { }
+            // A sink-only logger has no file to buffer lines for.
+            if (logFileSource === undefined)
+                return;
             buffer.push(line);
             if (buffer.length >= 50)
                 flushLogs();

package/dist/logger/index.d.ts

@@ -1,6 +1,6 @@
 export type { CaptureSink, LogTestRecord } from './capture-sink.js';
 export { createCaptureSink } from './capture-sink.js';
-export type { ChannelLogger, InitLoggerOptions, Level, LoggerInstance, } from './engine.js';
+export type { ChannelLogger, InitLoggerOptions, Level, LoggerInstance, LoggerOptions, SinkOnlyLoggerOptions, } from './engine.js';
 export { createLogger, createLoggerInstance, flushForTest, flushLogs, initLogger, resetLoggerForTest, setLogLevel, } from './engine.js';
 export type { RedactionOptions, Redactor } from './redact.js';
 export { createRedactor, redact, redactStrings } from './redact.js';

package/dist/rpc/notifications.d.ts

@@ -35,6 +35,24 @@ export interface NotificationScope {
      * session, which plugins that drain from one process-wide TUI rely on.
      */
     requireSession?: boolean;
+    /**
+     * What a drain with no session id returns, and what it acknowledges.
+     *
+     * - `'all'` (default): every queued notification, broadcasts and every
+     *   session's targeted ones; a sessionless acknowledgement removes
+     *   nothing. A plugin that drains from one process-wide TUI relies on this.
+     * - `'broadcast-only'`: broadcasts only (notifications pushed without a
+     *   session), never a session's targeted ones, for a TUI that polls before
+     *   it knows its session. A sessionless acknowledgement removes the
+     *   acknowledged broadcasts and leaves every targeted notification queued.
+     *   It also answers `isTuiConnected(scope, undefined)`: true while any
+     *   drain on the queue, with or without a session, happened within the
+     *   connection window.
+     *
+     * The option governs each call made with this scope; it does not split the
+     * queue, so a push through a scope without it lands in the same queue.
+     */
+    sessionlessDrain?: 'all' | 'broadcast-only';
 }
 /** A strict notification scope was used without a session id. */
 export declare class RpcSessionRequiredError extends Error {
@@ -45,5 +63,11 @@ export declare class RpcSessionRequiredError extends Error {
 export declare function isSessionId(value: unknown): value is string;
 export declare function pushNotification(scope: NotificationScope, payload: OpenDialogPayload, sessionId?: string): void;
 export declare function drainNotifications(scope: NotificationScope, lastReceivedId?: number, sessionId?: string): RpcNotification[];
-export declare function isTuiConnected(scope: NotificationScope, sessionId: string): boolean;
+/**
+ * True when a TUI drained within the last 3000 ms. With a session id, that
+ * session drained. Without one, a broadcast-only scope answers whether any
+ * drain happened; a default scope answers false, since it only tracks
+ * sessions.
+ */
+export declare function isTuiConnected(scope: NotificationScope, sessionId: string | undefined): boolean;
 export declare function resetNotificationsForTest(scope: NotificationScope): void;

package/dist/rpc/notifications.js

@@ -21,7 +21,12 @@ function state(scope) {
     ]);
     let value = queues.get(key);
     if (!value) {
-        value = { queue: [], nextId: 1, lastDrainAtBySession: new Map() };
+        value = {
+            queue: [],
+            nextId: 1,
+            lastDrainAtBySession: new Map(),
+            lastDrainAtAny: 0,
+        };
         queues.set(key, value);
     }
     return value;
@@ -49,25 +54,41 @@ export function drainNotifications(scope, lastReceivedId = 0, sessionId) {
         throw new RpcSessionRequiredError('drain');
     const value = state(scope);
     const now = Date.now();
+    value.lastDrainAtAny = now;
     if (sessionId !== undefined)
         value.lastDrainAtBySession.set(sessionId, now);
-    const matches = (n) => sessionId === undefined ||
-        n.sessionId === undefined ||
-        n.sessionId === sessionId;
+    const broadcastOnly = scope.sessionlessDrain === 'broadcast-only';
+    const matches = (n) => sessionId === undefined
+        ? !broadcastOnly || n.sessionId === undefined
+        : n.sessionId === undefined || n.sessionId === sessionId;
     if (lastReceivedId > 0) {
         value.queue = value.queue.filter((n) => {
             if (n.id > lastReceivedId)
                 return true;
+            // A sessionless ack in broadcast-only mode consumes the broadcasts it
+            // was shown; in the default mode it consumes nothing, since it was
+            // shown targeted notifications other sessions still have to receive.
             if (sessionId === undefined)
-                return true;
+                return !broadcastOnly || n.sessionId !== undefined;
             return n.sessionId !== sessionId;
         });
     }
     return value.queue.filter((n) => n.id > lastReceivedId && matches(n));
 }
+/**
+ * True when a TUI drained within the last 3000 ms. With a session id, that
+ * session drained. Without one, a broadcast-only scope answers whether any
+ * drain happened; a default scope answers false, since it only tracks
+ * sessions.
+ */
 export function isTuiConnected(scope, sessionId) {
     const now = Date.now();
-    const at = state(scope).lastDrainAtBySession.get(sessionId) ?? 0;
+    const value = state(scope);
+    const at = sessionId !== undefined
+        ? (value.lastDrainAtBySession.get(sessionId) ?? 0)
+        : scope.sessionlessDrain === 'broadcast-only'
+            ? value.lastDrainAtAny
+            : 0;
     return at > 0 && now - at < TUI_CONNECTED_WINDOW_MS;
 }
 export function resetNotificationsForTest(scope) {
@@ -75,4 +96,5 @@ export function resetNotificationsForTest(scope) {
     value.queue = [];
     value.nextId = 1;
     value.lastDrainAtBySession.clear();
+    value.lastDrainAtAny = 0;
 }

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

@@ -17,4 +17,13 @@ export declare function writePortFile(dir: string, entry: {
     beforeWrite?: () => void | Promise<void>;
 }): Promise<string>;
 export declare function sweepRpcState(root: string, activeDir: string, isManagedDir: (name: string) => boolean, log?: RpcLogChannel): Promise<void>;
-export declare function discoverPortFile(dir: string, expectedPid?: number): Promise<PortFileEntry | null>;
+export interface DiscoverPortFileOptions {
+    /**
+     * Return only the expected PID's entry, or null; never fall back to
+     * another live server. Without an expected PID nothing matches, so the
+     * result is null. Off by default, when a missing or unmatched expected PID
+     * falls back to the newest live entry.
+     */
+    exactPid?: boolean;
+}
+export declare function discoverPortFile(dir: string, expectedPid?: number, options?: DiscoverPortFileOptions): Promise<PortFileEntry | null>;

package/dist/rpc/port-file.js

@@ -1,7 +1,17 @@
 import { createHash } from 'node:crypto';
 import { chmod, mkdir, readdir, readFile, rename, rmdir, unlink, writeFile, } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+/**
+ * A PID a liveness probe may address. `process.kill(0 | negative, 0)` signals
+ * a process group rather than a process, and an unsafe integer cannot name a
+ * real process, so neither is ever probed.
+ */
+function isProbeablePid(pid) {
+    return typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0;
+}
 function pidAlive(pid) {
+    if (!isProbeablePid(pid))
+        return false;
     try {
         process.kill(pid, 0);
         return true;
@@ -23,14 +33,29 @@ export function getRpcDir(rpcRoot, directoryPrefix, projectDirectory) {
     return join(rpcRoot, directoryPrefix +
         createHash('sha256').update(projectDirectory).digest('hex').slice(0, 16));
 }
-function isUsablePortFileEntry(value) {
-    return (value !== null &&
-        typeof value === 'object' &&
-        !Array.isArray(value) &&
-        typeof value.pid === 'number' &&
-        Number.isFinite(value.pid) &&
-        typeof value.port === 'number' &&
-        Number.isFinite(value.port));
+/** The PID a port file's name claims, or undefined for a malformed name. */
+function filenamePid(name) {
+    const match = /^port-(\d+)\.json$/.exec(name);
+    return match ? Number(match[1]) : undefined;
+}
+/**
+ * An entry a client may connect to: its PID is probeable and matches the PID
+ * in its file name (a mismatch means the file was not written by the server
+ * it names), its port is a real TCP port, and its token is non-empty (an
+ * absent token would otherwise be sent as `Bearer undefined`).
+ */
+function isUsablePortFileEntry(value, name) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const { pid, port, token } = value;
+    return (isProbeablePid(pid) &&
+        filenamePid(name) === pid &&
+        typeof port === 'number' &&
+        Number.isInteger(port) &&
+        port >= 1 &&
+        port <= 65_535 &&
+        typeof token === 'string' &&
+        token.length > 0);
 }
 async function removeCorruptPortFile(portFile, log) {
     log?.debug('rpc corrupt port file', { pid: process.pid, portFile });
@@ -53,11 +78,18 @@ export async function writePortFile(dir, entry, options = {}) {
         const full = { ...entry, startedAt: Date.now() };
         const target = join(dir, `port-${entry.pid}.json`);
         const tmp = `${target}.${process.pid}.tmp`;
-        await writeFile(tmp, JSON.stringify(full), {
-            encoding: 'utf8',
-            mode: 0o600,
-        });
-        await rename(tmp, target);
+        try {
+            await writeFile(tmp, JSON.stringify(full), {
+                encoding: 'utf8',
+                mode: 0o600,
+            });
+            await rename(tmp, target);
+        }
+        catch (error) {
+            // The staged file carries the server token; never leave it behind.
+            await unlink(tmp).catch(() => { });
+            throw error;
+        }
         return target;
     };
     try {
@@ -116,7 +148,7 @@ export async function sweepRpcState(root, activeDir, isManagedDir, log) {
                 await removeCorruptPortFile(portFile, log);
                 continue;
             }
-            if (!isUsablePortFileEntry(parsed)) {
+            if (!isUsablePortFileEntry(parsed, name)) {
                 await removeCorruptPortFile(portFile, log);
                 continue;
             }
@@ -128,7 +160,7 @@ export async function sweepRpcState(root, activeDir, isManagedDir, log) {
             await rmdir(dir).catch(() => { });
     }
 }
-export async function discoverPortFile(dir, expectedPid) {
+export async function discoverPortFile(dir, expectedPid, options = {}) {
     let names;
     try {
         names = await readdir(dir);
@@ -142,7 +174,7 @@ export async function discoverPortFile(dir, expectedPid) {
             continue;
         try {
             const parsed = JSON.parse(await readFile(join(dir, name), 'utf8'));
-            if (isUsablePortFileEntry(parsed)) {
+            if (isUsablePortFileEntry(parsed, name)) {
                 if (pidAlive(parsed.pid))
                     live.push(parsed);
                 else
@@ -156,6 +188,8 @@ export async function discoverPortFile(dir, expectedPid) {
     const candidates = expectedPid !== undefined && expectedPid >= 1
         ? live.filter((entry) => entry.pid === expectedPid)
         : [];
+    if (options.exactPid === true && candidates.length === 0)
+        return null;
     const entries = candidates.length > 0 ? candidates : live;
     const sortTime = (entry) => typeof entry.startedAt === 'number' && Number.isFinite(entry.startedAt)
         ? entry.startedAt

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

@@ -1,8 +1,25 @@
 import type { ApplyRequest, ApplyResult, RpcNotification } from './notifications.js';
-import { type PortFileEntry } from './port-file.js';
+import { type DiscoverPortFileOptions, type PortFileEntry } from './port-file.js';
 export interface RpcClient {
     pending: (lastReceivedId: number, sessionId?: string) => Promise<RpcNotification[]>;
     apply: (request: ApplyRequest, timeoutMs?: number) => Promise<ApplyResult>;
 }
 export declare const DEFAULT_RPC_TIMEOUT_MS = 2000;
-export declare function createRpcClient(dir: string, expectedPid?: number, onSelected?: (entry: PortFileEntry | null) => void): RpcClient;
+/**
+ * `exactPid`: every call goes only to the expected PID's server. With no
+ * such server (or no expected PID) a call returns its fallback without
+ * opening a socket, on every call. Off by default, when a call falls back to
+ * the newest live server.
+ */
+export type RpcClientOptions = DiscoverPortFileOptions;
+/**
+ * A client for the server in `dir`, preferring `expectedPid`'s.
+ *
+ * `onSelected` reports the first selection: it is told which entry (or null)
+ * discovery chose, until one call of it returns normally. It is a report, not
+ * 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 }`.
+ */
+export declare function createRpcClient(dir: string, expectedPid?: number, onSelected?: (entry: PortFileEntry | null) => void, options?: RpcClientOptions): RpcClient;

package/dist/rpc/rpc-client.js

@@ -1,7 +1,7 @@
-import { discoverPortFile } from './port-file.js';
+import { discoverPortFile, } from './port-file.js';
 export const DEFAULT_RPC_TIMEOUT_MS = 2_000;
-async function call(dir, expectedPid, onSelected, method, params, timeoutMs = DEFAULT_RPC_TIMEOUT_MS) {
-    const entry = await discoverPortFile(dir, expectedPid);
+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)
         return null;
@@ -28,21 +28,36 @@ async function call(dir, expectedPid, onSelected, method, params, timeoutMs = DE
         clearTimeout(timer);
     }
 }
-export function createRpcClient(dir, expectedPid, onSelected) {
+/**
+ * A client for the server in `dir`, preferring `expectedPid`'s.
+ *
+ * `onSelected` reports the first selection: it is told which entry (or null)
+ * discovery chose, until one call of it returns normally. It is a report, not
+ * 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 }`.
+ */
+export function createRpcClient(dir, expectedPid, onSelected, options = {}) {
+    const discoverOptions = {
+        exactPid: options.exactPid,
+    };
     let reportedSelection = false;
     const reportSelected = (entry) => {
         if (reportedSelection)
             return;
-        reportedSelection = true;
         onSelected?.(entry);
+        // Counted only after the observer returns, so a throwing one is not
+        // silently skipped on later calls.
+        reportedSelection = true;
     };
     return {
         async pending(lastReceivedId, sessionId) {
-            const out = await call(dir, expectedPid, reportSelected, 'pending-notifications', { lastReceivedId, sessionId });
+            const out = await call(dir, expectedPid, discoverOptions, reportSelected, 'pending-notifications', { lastReceivedId, sessionId });
             return out?.messages ?? [];
         },
         async apply(request, timeoutMs) {
-            const out = await call(dir, expectedPid, reportSelected, 'apply', {
+            const out = await call(dir, expectedPid, discoverOptions, reportSelected, 'apply', {
                 ...request,
             }, timeoutMs);
             return out ?? { text: 'apply failed', knobs: {} };

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

@@ -23,5 +23,23 @@ export interface RpcServerOptions {
     requireSession?: boolean;
     timeoutMs?: number;
     receiptTimeoutMs?: number;
+    /**
+     * Answer an `apply` call whose handler is still running after this many
+     * milliseconds with 504 `{error: 'handler deadline exceeded'}`. The handler
+     * is not cancelled; its eventual result is discarded. Unset by default,
+     * when only the socket inactivity timeout (`timeoutMs`) bounds a handler,
+     * by destroying the socket.
+     */
+    applyDeadlineMs?: number;
+}
+/**
+ * Thrown by an `apply` or `drain` handler to refuse a request with a 4xx
+ * status. Its message is sent on the wire as `{error: message}`, so it must
+ * be written for the client and never quote a credential. Any other error a
+ * handler throws answers 500 with a fixed code.
+ */
+export declare class RpcRequestError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
 }
 export declare function startRpcServer(options: RpcServerOptions): Promise<RpcServerHandle>;

package/dist/rpc/rpc-server.js

@@ -4,15 +4,47 @@ import { createServer, } from 'node:http';
 import { join } from 'node:path';
 import { isSessionId, } from './notifications.js';
 import { sweepRpcState, writePortFile } from './port-file.js';
+/**
+ * Thrown by an `apply` or `drain` handler to refuse a request with a 4xx
+ * status. Its message is sent on the wire as `{error: message}`, so it must
+ * be written for the client and never quote a credential. Any other error a
+ * handler throws answers 500 with a fixed code.
+ */
+export class RpcRequestError extends Error {
+    status;
+    constructor(status, message) {
+        if (!Number.isInteger(status) || status < 400 || status > 499)
+            throw new RangeError(`RpcRequestError status must be 4xx, got ${status}`);
+        super(message);
+        this.name = 'RpcRequestError';
+        this.status = status;
+    }
+}
+const MAX_BODY_BYTES = 1_000_000;
+/** The request body exceeded the cap; answered 413. */
+class BodyTooLargeError extends Error {
+}
 function readBody(req) {
     return new Promise((resolve, reject) => {
+        const tooLarge = () => {
+            // Keep reading and discarding the rest, so the client finishes sending
+            // and can read the 413 instead of seeing a reset connection.
+            req.removeAllListeners('data');
+            req.on('data', () => { });
+            req.resume();
+            reject(new BodyTooLargeError('body too large'));
+        };
+        const declared = Number(req.headers['content-length']);
+        if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+            tooLarge();
+            return;
+        }
         const chunks = [];
         let size = 0;
         req.on('data', (chunk) => {
             size += chunk.length;
-            if (size > 1_000_000) {
-                req.destroy();
-                reject(new Error('body too large'));
+            if (size > MAX_BODY_BYTES) {
+                tooLarge();
                 return;
             }
             chunks.push(chunk);
@@ -21,6 +53,23 @@ function readBody(req) {
         req.on('error', reject);
     });
 }
+class ApplyDeadlineError extends Error {
+}
+/** Settle with `work`, or reject at `ms` while `work` keeps running. */
+async function withDeadline(work, ms) {
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new ApplyDeadlineError('apply deadline exceeded')), ms);
+    });
+    // A handler that fails after its deadline has nobody left to answer.
+    work.catch(() => { });
+    try {
+        return await Promise.race([work, deadline]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 function tokenOk(header, token) {
     if (!header?.startsWith('Bearer '))
         return false;
@@ -45,25 +94,43 @@ export async function startRpcServer(options) {
     server.requestTimeout = receiptTimeoutMs;
     server.headersTimeout = receiptTimeoutMs;
     async function dispatch(req, res) {
-        const json = (status, value) => {
-            // Guard against writing to a socket that was destroyed (e.g. when
-            // readBody rejected after req.destroy() on an oversized body).
+        const json = (status, value, headers = {}) => {
+            // Guard against writing to a socket that is already gone (the
+            // inactivity timeout destroys it).
             if (res.headersSent || res.writableEnded || res.destroyed)
                 return;
-            res.writeHead(status, { 'content-type': 'application/json' });
+            res.writeHead(status, { 'content-type': 'application/json', ...headers });
             res.end(JSON.stringify(value));
         };
         try {
-            const url = req.url ?? '';
-            if (req.method === 'GET' && url === '/health')
+            // Route on the pathname alone, so a query string does not turn a known
+            // method into a 404.
+            const path = new URL(req.url ?? '/', 'http://127.0.0.1').pathname;
+            if (req.method === 'GET' && path === '/health')
                 return json(200, { ok: true });
-            if (req.method !== 'POST' || !url.startsWith('/rpc/'))
+            if (req.method !== 'POST' || !path.startsWith('/rpc/'))
                 return json(404, { error: 'not found' });
             if (!tokenOk(req.headers.authorization, token))
                 return json(401, { error: 'unauthorized' });
-            const method = url.slice('/rpc/'.length);
-            const body = await readBody(req);
-            const params = JSON.parse(body || '{}');
+            const method = path.slice('/rpc/'.length);
+            let body;
+            try {
+                body = await readBody(req);
+            }
+            catch (error) {
+                if (!(error instanceof BodyTooLargeError))
+                    throw error;
+                // Close the connection after answering: the rest of the oversized
+                // body is not worth keeping the socket for.
+                return json(413, { error: 'body too large' }, { connection: 'close' });
+            }
+            let params;
+            try {
+                params = JSON.parse(body || '{}');
+            }
+            catch {
+                return json(400, { error: 'invalid json' });
+            }
             if (method === 'pending-notifications') {
                 if (options.requireSession === true && !isSessionId(params.sessionId))
                     return json(400, { error: 'session required' });
@@ -78,12 +145,29 @@ export async function startRpcServer(options) {
                 return json(200, { messages });
             }
             if (method === 'apply') {
-                const result = await options.apply(params);
+                const work = Promise.resolve(options.apply(params));
+                const result = options.applyDeadlineMs === undefined
+                    ? await work
+                    : await withDeadline(work, options.applyDeadlineMs);
                 return json(200, result);
             }
             return json(404, { error: 'unknown method' });
         }
         catch (error) {
+            if (error instanceof RpcRequestError) {
+                log.debug('rpc request refused', {
+                    pid: process.pid,
+                    status: error.status,
+                });
+                return json(error.status, { error: error.message });
+            }
+            if (error instanceof ApplyDeadlineError) {
+                log.warn('rpc apply deadline exceeded', {
+                    pid: process.pid,
+                    deadlineMs: options.applyDeadlineMs,
+                });
+                return json(504, { error: 'handler deadline exceeded' });
+            }
             // A handler's exception can quote a request or a credential, so its
             // text goes to the plugin's log channel only; the wire gets a fixed code.
             log.warn('rpc request failed', {

package/dist/sidebar-file/sidebar-file.d.ts

@@ -68,6 +68,16 @@ export interface SidebarFileOptions<T> {
      * that the lock was lost. Without it such a write is only reported.
      */
     repair?: SidebarRepair<T>;
+    /**
+     * Name of the lock writers coordinate on, as `<path>.<lockName>.lock`.
+     * Defaults to `'sidebar-write'`. It names both the lock a write takes and
+     * the lock whose ownership is checked before the rename, so a takeover of
+     * this name refuses the write. A plugin keeping an existing writer's lock
+     * identity passes that writer's name; mutual exclusion with that writer is
+     * promised only while it holds a live lease of the same name in the same
+     * lock-file format, not for its stale-lock reclamation or renewal.
+     */
+    lockName?: string;
 }
 export interface SidebarFile<T> {
     read(): Promise<T>;

package/dist/sidebar-file/sidebar-file.js

@@ -43,6 +43,7 @@ export function createSidebarFile(options) {
     };
     const lockOptions = {
         ...WRITER_LOCK_CONSTANTS.sidebar,
+        name: options.lockName ?? WRITER_LOCK_CONSTANTS.sidebar.name,
         timeoutMs: options.timeoutMs ?? WRITER_LOCK_CONSTANTS.sidebar.timeoutMs,
     };
     /**

package/dist/store/attribution.d.ts

@@ -2,8 +2,19 @@ import { type StoreRuntime } from './runtime.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
- * this credential epoch and this recorded identity; a replaced credential bumps the epoch, so work issued
- * for the old one is discarded.
+ * this credential epoch and this recorded identity; a replaced credential
+ * bumps the epoch, so work issued for the old one is discarded.
+ *
+ * The epoch names one credential lineage of the row: a credential given by
+ * `add` or `replace`, through every refresh and `rotate` of it, which keep
+ * the epoch. Since 0.8.0 that holds across removal too: a row added under an
+ * id the pool held before starts past every epoch that id held (the store
+ * records them when it drops a row, in the config file, so every process
+ * sees it), so an attribution taken for a removed row is refused once the id
+ * is added again, even with the same identity. Writers older than 0.8.0
+ * start a re-added id at epoch 1 again, and a writer that does not know the
+ * pool can remove and re-add a row without the store seeing it; work
+ * attributed across either may still apply to the new credential.
  */
 export interface Attribution {
     credentialEpoch: number;

package/dist/store/mutate.d.ts

@@ -118,7 +118,11 @@ export declare class Transaction {
      * Writes the config: legacy `version: 1` and the legacy roster beside
      * `commonAuthPool`, every other top-level key and every unrecognised pool
      * key untouched. Entries for ids no longer in the roster are dropped here,
-     * and remembered so the id is not reused in this process.
+     * and remembered so the id is not reused in this process. Every id the
+     * write drops (a roster row the files held when the transaction read them,
+     * or an entry left without one) has its epoch recorded in the config (see
+     * `retireEpochsIn`), which is what keeps a later `add` of the id, from any
+     * process, past every epoch an attribution could name.
      */
     commitConfig(options?: {
         counted?: boolean;

package/dist/store/mutate.js

@@ -4,7 +4,7 @@ import { LockContentionError, LockOwnershipError } from '../fs/with-lock.js';
 import { PoolOperationError, } from './errors.js';
 import { callFailureHook } from './hooks.js';
 import { LockStack, } from './refresh-lock.js';
-import { classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, rosterRowIn, setEntryIn, } from './schema.js';
+import { classifyConfig, classifyState, ensureEntries, entryIn, isRecord, LEGACY_STORE_VERSION, POOL_KEY, POOL_ROWS_KEY, POOL_SCHEMA_VERSION, retireEpochsIn, rosterOf, rosterRowIn, setEntryIn, } from './schema.js';
 import { completeTornRows, loadRows } from './torn.js';
 async function readJson(path) {
     let text;
@@ -169,7 +169,11 @@ export class Transaction {
      * Writes the config: legacy `version: 1` and the legacy roster beside
      * `commonAuthPool`, every other top-level key and every unrecognised pool
      * key untouched. Entries for ids no longer in the roster are dropped here,
-     * and remembered so the id is not reused in this process.
+     * and remembered so the id is not reused in this process. Every id the
+     * write drops (a roster row the files held when the transaction read them,
+     * or an entry left without one) has its epoch recorded in the config (see
+     * `retireEpochsIn`), which is what keeps a later `add` of the id, from any
+     * process, past every epoch an attribution could name.
      */
     async commitConfig(options = {}) {
         const roster = this.roster();
@@ -177,6 +181,14 @@ export class Transaction {
         for (const raw of roster)
             if (isRecord(raw) && typeof raw.id === 'string')
                 rosterIds.add(raw.id);
+        const dropped = new Set();
+        for (const raw of rosterOf(this.snapshot.config))
+            if (isRecord(raw) && typeof raw.id === 'string' && !rosterIds.has(raw.id))
+                dropped.add(raw.id);
+        for (const id of Object.keys(this.entries()))
+            if (!rosterIds.has(id))
+                dropped.add(id);
+        retireEpochsIn(this.config, dropped);
         const entries = this.entries();
         const kept = {};
         for (const [id, entry] of Object.entries(entries)) {

package/dist/store/pool.d.ts

@@ -88,6 +88,13 @@ export interface PoolStore {
     }): Promise<{
         status: InitializeOutcome;
     }>;
+    /**
+     * Adds a row, or completes or rotates the row already holding the id or
+     * the secret. A new row starts at credential epoch 1; since 0.8.0 one
+     * whose id the pool held before starts one past the highest epoch that id
+     * held (see `Attribution`), and an id that held `Number.MAX_SAFE_INTEGER`
+     * refuses (`id-removed`) before writing.
+     */
     add(input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
     /**
      * Gives a row a new credential and a new credential epoch. Since 0.6.0 the

package/dist/store/rows.d.ts

@@ -192,7 +192,9 @@ export declare function enableRow(rt: StoreRuntime, id: string, options?: RowTra
  * between the two leaves a row every reader already sees as removed, with
  * only an orphaned state entry that no reader loads; calling `remove` again
  * drops that entry (`completed`). As with every id the store drops, the id is
- * not reused by `add` in this process.
+ * not reused by `add` in this process, and the config write records the
+ * row's credential epoch, so an `add` of the id in any other process starts
+ * past it (see `nextAddEpochIn`).
  */
 export declare function removeRow(rt: StoreRuntime, id: string, options?: RemoveOptions): Promise<RemoveResult>;
 /**

package/dist/store/rows.js

@@ -5,7 +5,7 @@ import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, enable
 import { notReadyError, readPool, runOperation, withTransaction, } from './mutate.js';
 import { acceptProviderState, mergedProviderState, planProviderStateIn, providerStateCoverage, replacementProviderState, } from './provider-state.js';
 import { readRow, refusal, requireBound, rowLockSpec, unknownRow, } from './runtime.js';
-import { boundProviderStateDigest, CREDENTIAL_STAMP_KEY, credentialProblem, fingerprintOf, idProblem, isCredentialEpoch, isRecord, PROVIDER_STATE_KEY, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.js';
+import { boundProviderStateDigest, CREDENTIAL_STAMP_KEY, credentialProblem, fingerprintOf, idProblem, isCredentialEpoch, isRecord, nextAddEpochIn, PROVIDER_STATE_KEY, rosterRowFor, rotationStamp, rowLockKey, stampFor, stateFieldsFor, storedCredential, } from './schema.js';
 import { applyTransition, bindReplacement, TRANSITION_STAMP_KEY, } from './torn.js';
 /** Fields of a state entry that belong to the credential it replaces. */
 const CREDENTIAL_STATE_FIELDS = [
@@ -259,6 +259,12 @@ export async function addRow(rt, input, options = {}) {
                     await tx.commitConfig();
                 return { id, outcome: 'completed', credential: stored };
             }
+            // An id the pool held before starts past every epoch it held, so
+            // work attributed to the earlier row's credential, from this
+            // process or another, never matches the new one.
+            const credentialEpoch = nextAddEpochIn(tx.config, id);
+            if (!isCredentialEpoch(credentialEpoch))
+                throw refusal('add', id, 'id-removed', `id ${id} has held every credential epoch and is not reused; add the credential under another id`);
             tx.roster().push(rosterRowFor({
                 id,
                 credential,
@@ -267,7 +273,7 @@ export async function addRow(rt, input, options = {}) {
                 addedAt: ctx.now(),
             }));
             tx.setEntry(id, {
-                credentialEpoch: 1,
+                credentialEpoch,
                 needsFirstReading: credential.type === 'oauth',
             });
             let outcome = 'added';
@@ -577,7 +583,9 @@ export function enableRow(rt, id, options = {}) {
  * between the two leaves a row every reader already sees as removed, with
  * only an orphaned state entry that no reader loads; calling `remove` again
  * drops that entry (`completed`). As with every id the store drops, the id is
- * not reused by `add` in this process.
+ * not reused by `add` in this process, and the config write records the
+ * row's credential epoch, so an `add` of the id in any other process starts
+ * past it (see `nextAddEpochIn`).
  */
 export async function removeRow(rt, id, options = {}) {
     assertNotInsideHook('remove');

package/dist/store/schema.d.ts

@@ -4,6 +4,15 @@ export declare const POOL_KEY = "commonAuthPool";
 export declare const POOL_SCHEMA_VERSION = 1;
 /** Property of `commonAuthPool` holding the per-row entries, keyed by local id. */
 export declare const POOL_ROWS_KEY = "rows";
+/**
+ * Property of `commonAuthPool` (since 0.8.0) holding, per id, the highest
+ * credential epoch a row with that id held when the store last dropped it
+ * from the pool. A row added later under the same id starts past it (see
+ * `nextAddEpochIn`), so an attribution taken for the dropped row never
+ * matches the new one. Older readers ignore it, and older writers keep it
+ * as they keep every pool key they do not know.
+ */
+export declare const POOL_RETIRED_EPOCHS_KEY = "retiredEpochs";
 /** The `version` older readers of the same files expect at the top level. */
 export declare const LEGACY_STORE_VERSION = 1;
 /**
@@ -348,6 +357,37 @@ export declare function ensureEntries(config: Record<string, unknown>): Record<s
 export declare function entryIn(config: Record<string, unknown>, id: string): Record<string, unknown> | undefined;
 /** Sets an entry as an own property, so an id such as `toString` is safe. */
 export declare function setEntryIn(config: Record<string, unknown>, id: string, entry: Record<string, unknown>): void;
+/**
+ * The credential epoch recorded for a dropped id (see
+ * `POOL_RETIRED_EPOCHS_KEY`), or undefined when none is. A value that is not
+ * a credential epoch counts as none.
+ */
+export declare function retiredEpochIn(config: Record<string, unknown>, id: string): number | undefined;
+/**
+ * The credential epoch `add` gives a new row with this id: one past the
+ * highest epoch the id is known to have held, which is the epoch recorded
+ * when the store dropped it, or the epoch of an entry left behind by a writer
+ * that removed only its roster row; 1 for an id the pool never held.
+ *
+ * An attribution names a row by id and credential epoch (and identity), and
+ * an id is chosen by the plugin, so it is often the same one again (`main`).
+ * Were a re-added row to start at epoch 1 again, an attribution taken for the
+ * removed row's credential would match the new credential exactly, in this
+ * process or any other. Starting past every earlier epoch makes such an
+ * attribution fail as it does after a `replace`. The result may lie past the
+ * safe integers (an id whose last row was at `Number.MAX_SAFE_INTEGER`);
+ * `add` refuses such an id.
+ */
+export declare function nextAddEpochIn(config: Record<string, unknown>, id: string): number;
+/**
+ * Records, in a config being written, the epochs of the ids it drops: for
+ * each, the epoch its entry claims (1 for a row without one, the epoch such a
+ * row is at), kept only when above what is already recorded, so the record
+ * for an id never goes down. Valid recorded values of other ids are kept; a
+ * record that is not an object, or a value in it that is not an epoch, says
+ * nothing and is replaced. An entry whose epoch cannot be read records 1.
+ */
+export declare function retireEpochsIn(config: Record<string, unknown>, dropped: Iterable<string>): void;
 /**
  * Builds the rows of a ready pool from the files exactly as they are, without
  * looking at credential stamps (see `loadRows` for the rows every reader

package/dist/store/schema.js

@@ -5,6 +5,15 @@ export const POOL_KEY = 'commonAuthPool';
 export const POOL_SCHEMA_VERSION = 1;
 /** Property of `commonAuthPool` holding the per-row entries, keyed by local id. */
 export const POOL_ROWS_KEY = 'rows';
+/**
+ * Property of `commonAuthPool` (since 0.8.0) holding, per id, the highest
+ * credential epoch a row with that id held when the store last dropped it
+ * from the pool. A row added later under the same id starts past it (see
+ * `nextAddEpochIn`), so an attribution taken for the dropped row never
+ * matches the new one. Older readers ignore it, and older writers keep it
+ * as they keep every pool key they do not know.
+ */
+export const POOL_RETIRED_EPOCHS_KEY = 'retiredEpochs';
 /** The `version` older readers of the same files expect at the top level. */
 export const LEGACY_STORE_VERSION = 1;
 /**
@@ -410,11 +419,15 @@ function credentialFor(raw, stateEntry) {
 export function rosterRowIn(config, id) {
     return rosterOf(config).find((raw) => isRecord(raw) && raw.id === id);
 }
-/** The per-row entries of a config, created (empty) when absent. */
-export function ensureEntries(config) {
+/** The pool object of a config, created (empty) when absent. */
+function ensurePool(config) {
     if (!isRecord(config[POOL_KEY]))
         config[POOL_KEY] = {};
-    const pool = config[POOL_KEY];
+    return config[POOL_KEY];
+}
+/** The per-row entries of a config, created (empty) when absent. */
+export function ensureEntries(config) {
+    const pool = ensurePool(config);
     if (!isRecord(pool[POOL_ROWS_KEY]))
         pool[POOL_ROWS_KEY] = {};
     return pool[POOL_ROWS_KEY];
@@ -433,6 +446,77 @@ export function setEntryIn(config, id, entry) {
         configurable: true,
     });
 }
+/**
+ * The credential epoch recorded for a dropped id (see
+ * `POOL_RETIRED_EPOCHS_KEY`), or undefined when none is. A value that is not
+ * a credential epoch counts as none.
+ */
+export function retiredEpochIn(config, id) {
+    const pool = config[POOL_KEY];
+    if (!isRecord(pool))
+        return undefined;
+    const retired = pool[POOL_RETIRED_EPOCHS_KEY];
+    if (!isRecord(retired) || !Object.hasOwn(retired, id))
+        return undefined;
+    const epoch = retired[id];
+    return isCredentialEpoch(epoch) ? epoch : undefined;
+}
+/**
+ * The epoch a per-row entry claims, read without validating the rest of the
+ * entry, or undefined when it names none a reader would accept.
+ */
+function entryEpochIn(config, id) {
+    const epoch = entryIn(config, id)?.credentialEpoch;
+    return isCredentialEpoch(epoch) ? epoch : undefined;
+}
+/**
+ * The credential epoch `add` gives a new row with this id: one past the
+ * highest epoch the id is known to have held, which is the epoch recorded
+ * when the store dropped it, or the epoch of an entry left behind by a writer
+ * that removed only its roster row; 1 for an id the pool never held.
+ *
+ * An attribution names a row by id and credential epoch (and identity), and
+ * an id is chosen by the plugin, so it is often the same one again (`main`).
+ * Were a re-added row to start at epoch 1 again, an attribution taken for the
+ * removed row's credential would match the new credential exactly, in this
+ * process or any other. Starting past every earlier epoch makes such an
+ * attribution fail as it does after a `replace`. The result may lie past the
+ * safe integers (an id whose last row was at `Number.MAX_SAFE_INTEGER`);
+ * `add` refuses such an id.
+ */
+export function nextAddEpochIn(config, id) {
+    return (Math.max(retiredEpochIn(config, id) ?? 0, entryEpochIn(config, id) ?? 0) + 1);
+}
+/**
+ * Records, in a config being written, the epochs of the ids it drops: for
+ * each, the epoch its entry claims (1 for a row without one, the epoch such a
+ * row is at), kept only when above what is already recorded, so the record
+ * for an id never goes down. Valid recorded values of other ids are kept; a
+ * record that is not an object, or a value in it that is not an epoch, says
+ * nothing and is replaced. An entry whose epoch cannot be read records 1.
+ */
+export function retireEpochsIn(config, dropped) {
+    const ids = [...dropped];
+    if (ids.length === 0)
+        return;
+    const pool = ensurePool(config);
+    const previous = isRecord(pool[POOL_RETIRED_EPOCHS_KEY])
+        ? pool[POOL_RETIRED_EPOCHS_KEY]
+        : {};
+    const next = {};
+    const define = (id, epoch) => Object.defineProperty(next, id, {
+        value: epoch,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+    for (const [id, epoch] of Object.entries(previous))
+        if (isCredentialEpoch(epoch))
+            define(id, epoch);
+    for (const id of ids)
+        define(id, Math.max(retiredEpochIn(config, id) ?? 0, entryEpochIn(config, id) ?? 1));
+    pool[POOL_RETIRED_EPOCHS_KEY] = next;
+}
 /**
  * Builds the rows of a ready pool from the files exactly as they are, without
  * looking at credential stamps (see `loadRows` for the rows every reader

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/common-auth",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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": {