@cortexkit/common-auth 0.6.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/identity.d.ts

@@ -22,6 +22,11 @@ export declare function countUnknownIdentityRows(rows: readonly PoolRow[]): numb
  * without an entry gets one at epoch 1. Nothing is ever deleted.
  */
 export declare function disableIn(tx: RowEditor, id: string, reason: string): void;
+/**
+ * Marks a row enabled: `enabled: true` in the roster row and no
+ * `disabledReason` in its entry. A row without an entry is not given one.
+ */
+export declare function enableIn(tx: RowEditor, id: string): void;
 /**
  * Two enabled OAuth rows with one wire identity are the same account: the
  * earlier row in roster order stays enabled and every later one is disabled