@cortexkit/common-auth 0.1.0

package/dist/logger/engine.js

@@ -0,0 +1,199 @@
+import { appendFileSync, chmodSync, existsSync, renameSync, statSync, } from 'node:fs';
+import { createRedactor } from './redact.js';
+const ORDER = {
+    error: 0,
+    warn: 1,
+    info: 2,
+    debug: 3,
+    trace: 4,
+};
+const MAX_BYTES = 5 * 1024 * 1024;
+/**
+ * Where lines are written, and the level floor, as the host supplied them.
+ *
+ * Both start unset. A host decides where its log lives — that decision reads
+ * host environment variables and host directories, neither of which belongs in
+ * shared code — and calls `initLogger` before it runs any command. Until then
+ * every `log.*` call is a silent no-op: throwing would turn the first command a
+ * host forgot to wire into a crash, and buffering would hold credential-bearing
+ * lines for an init that may never arrive.
+ */
+let logFileSource;
+let initLevelSource;
+let runtimeLevel;
+let redactor = createRedactor();
+let captureSink;
+/**
+ * Point the logger at a host's file and level. 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 function initLogger(options) {
+    logFileSource = options.file;
+    initLevelSource = options.level;
+    redactor = createRedactor(options);
+    captureSink = options.captureSink;
+}
+export function setLogLevel(l) {
+    if (l === undefined || l in ORDER)
+        runtimeLevel = l;
+}
+function logFilePath() {
+    if (logFileSource === undefined)
+        return undefined;
+    const resolved = typeof logFileSource === 'function' ? logFileSource() : logFileSource;
+    return resolved || undefined;
+}
+function configuredLevel() {
+    if (runtimeLevel)
+        return runtimeLevel;
+    const floor = typeof initLevelSource === 'function' ? initLevelSource() : initLevelSource;
+    if (floor && floor in ORDER)
+        return floor;
+    return 'info';
+}
+let buffer = [];
+let timer;
+const ROTATE_KEEP = 3;
+function chmodPrivate(path) {
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        /* never throw */
+    }
+}
+function rotateIfNeeded(f) {
+    try {
+        if (!(existsSync(f) && statSync(f).size >= MAX_BYTES))
+            return;
+        for (let i = ROTATE_KEEP - 1; i >= 1; i--) {
+            if (existsSync(`${f}.${i}`)) {
+                const rotated = `${f}.${i + 1}`;
+                renameSync(`${f}.${i}`, rotated);
+                chmodPrivate(rotated);
+            }
+        }
+        const rotated = `${f}.1`;
+        renameSync(f, rotated);
+        chmodPrivate(rotated);
+    }
+    catch {
+        /* never throw */
+    }
+}
+/**
+ * Write whatever is buffered. Safe to call synchronously from a process-exit
+ * handler, which is how each host drains the buffer on shutdown.
+ */
+export function flushLogs() {
+    if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+    }
+    if (!buffer.length)
+        return;
+    let file;
+    try {
+        file = logFilePath();
+    }
+    catch {
+        buffer = [];
+        return;
+    }
+    const text = buffer.join('');
+    buffer = [];
+    if (!file)
+        return;
+    try {
+        rotateIfNeeded(file);
+        if (existsSync(file))
+            chmodPrivate(file);
+        appendFileSync(file, text, { encoding: 'utf8', mode: 0o600 });
+    }
+    catch {
+        /* never throw */
+    }
+}
+function schedule() {
+    if (!timer)
+        timer = setTimeout(() => {
+            timer = undefined;
+            flushLogs();
+        }, 500);
+}
+function safeSerialize(data) {
+    try {
+        return ` ${JSON.stringify(data)}`;
+    }
+    catch {
+        return ' [unserializable]';
+    }
+}
+function emit(channel, level, message, data) {
+    if (logFileSource === undefined)
+        return;
+    try {
+        if (ORDER[level] > ORDER[configuredLevel()])
+            return;
+        const scrubbedMessage = redactor.redactStrings(message);
+        let scrubbedData;
+        try {
+            scrubbedData = redactor.redact(data);
+        }
+        catch {
+            scrubbedData = '[unserializable]';
+        }
+        const line = `[${new Date().toISOString()}] ${level.toUpperCase()} [${channel}] ${scrubbedMessage}` +
+            (data === undefined ? '' : safeSerialize(scrubbedData)) +
+            '\n';
+        // A failing observer must not prevent file logging or escape into the host.
+        try {
+            captureSink?.({
+                channel,
+                level,
+                message: scrubbedMessage,
+                data: scrubbedData,
+            });
+        }
+        catch { }
+        buffer.push(line);
+        if (buffer.length >= 50)
+            flushLogs();
+        else
+            schedule();
+    }
+    catch {
+        // Provider and redaction failures must never turn diagnostics into a host crash.
+    }
+}
+export function createLogger(channel) {
+    return {
+        error: (m, d) => emit(channel, 'error', m, d),
+        warn: (m, d) => emit(channel, 'warn', m, d),
+        info: (m, d) => emit(channel, 'info', m, d),
+        debug: (m, d) => emit(channel, 'debug', m, d),
+        trace: (m, d) => emit(channel, 'trace', m, d),
+    };
+}
+export async function flushForTest() {
+    flushLogs();
+}
+/**
+ * Return the logger to its uninitialised state. Only a test needs this: a
+ * single process runs every test file, so a file path left over from one test
+ * would keep a later "logger was never initialised" case writing lines.
+ */
+export function resetLoggerForTest() {
+    buffer = [];
+    if (timer) {
+        clearTimeout(timer);
+        timer = undefined;
+    }
+    logFileSource = undefined;
+    initLevelSource = undefined;
+    runtimeLevel = undefined;
+    redactor = createRedactor();
+    captureSink = undefined;
+}

package/dist/logger/index.d.ts

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

package/dist/logger/index.js

@@ -0,0 +1,3 @@
+export { createCaptureSink } from './capture-sink.js';
+export { createLogger, flushForTest, flushLogs, initLogger, resetLoggerForTest, setLogLevel, } from './engine.js';
+export { createRedactor, redact, redactStrings } from './redact.js';

package/dist/logger/redact.d.ts

@@ -0,0 +1,11 @@
+export interface RedactionOptions {
+    extraSecretKeys?: (normalizedKey: string) => boolean;
+    extraValuePatterns?: RegExp[];
+}
+export declare function createRedactor(options?: RedactionOptions): {
+    redact: (value: unknown) => unknown;
+    redactStrings: (value: unknown) => unknown;
+};
+export type Redactor = ReturnType<typeof createRedactor>;
+export declare const redact: (value: unknown) => unknown;
+export declare const redactStrings: (value: unknown) => unknown;

package/dist/logger/redact.js

@@ -0,0 +1,45 @@
+const SECRET_KEY_EXACT = /^(authorization|x-api-key|cookie|set-cookie|refresh|access|token)$/i;
+const TOKEN_VALUE = /\b(Bearer\s+[\w.-]+|sk-[\w-]+|eyJ[\w.-]+)\b|ckh_[A-Za-z0-9_-]{20,}/g;
+const MASK = '***REDACTED***';
+export function createRedactor(options = {}) {
+    const patterns = [TOKEN_VALUE, ...(options.extraValuePatterns ?? [])].map((pattern) => new RegExp(pattern.source, pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`));
+    function isSecretKey(key) {
+        const normalized = key.toLowerCase().replace(/[-_]/g, '');
+        return (SECRET_KEY_EXACT.test(key) ||
+            normalized.includes('apikey') ||
+            normalized.endsWith('secret') ||
+            normalized.endsWith('password') ||
+            (normalized.endsWith('token') && !normalized.endsWith('tokens')) ||
+            !!options.extraSecretKeys?.(normalized));
+    }
+    function walk(value, keys, seen) {
+        if (typeof value === 'string') {
+            return patterns.reduce((text, pattern) => text.replace(pattern, MASK), value);
+        }
+        if (!value || typeof value !== 'object')
+            return value;
+        if (seen.has(value))
+            return '[Circular]';
+        seen.add(value);
+        try {
+            if (Array.isArray(value))
+                return value.map((item) => walk(item, keys, seen));
+            // Define own properties so a diagnostic __proto__ key cannot change the output prototype.
+            return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+                key,
+                keys && isSecretKey(key) ? MASK : walk(item, keys, seen),
+            ]));
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    return {
+        redact: (value) => walk(value, true, new WeakSet()),
+        // Schema keys describe arguments, not credentials; only their string values are scrubbed.
+        redactStrings: (value) => walk(value, false, new WeakSet()),
+    };
+}
+const defaultRedactor = createRedactor();
+export const redact = defaultRedactor.redact;
+export const redactStrings = defaultRedactor.redactStrings;

package/dist/rpc/index.d.ts

@@ -0,0 +1,10 @@
+export * from './notifications.js';
+export * from './port-file.js';
+export * from './rpc-client.js';
+export * from './rpc-server.js';
+export * from './server-registry.js';
+/** Pass methods bound to the caller’s logger channel; RPC uses no-op methods when no logger is supplied. */
+export interface RpcLogChannel {
+    warn(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+}

package/dist/rpc/index.js

@@ -0,0 +1,5 @@
+export * from './notifications.js';
+export * from './port-file.js';
+export * from './rpc-client.js';
+export * from './rpc-server.js';
+export * from './server-registry.js';

package/dist/rpc/notifications.d.ts

@@ -0,0 +1,29 @@
+export interface ApplyRequest {
+    command: string;
+    arguments: string;
+    sessionId?: string;
+}
+export interface ApplyResult {
+    text: string;
+    knobs: Record<string, unknown>;
+}
+export interface OpenDialogPayload {
+    command: string;
+    text: string;
+    knobs: Record<string, unknown>;
+}
+export interface RpcNotification {
+    id: number;
+    type: 'open-dialog';
+    payload: OpenDialogPayload;
+    sessionId?: string;
+}
+export interface NotificationScope {
+    rpcRoot: string;
+    directoryPrefix: string;
+    registrationSessionId: 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;
+export declare function resetNotificationsForTest(scope: NotificationScope): void;

package/dist/rpc/notifications.js

@@ -0,0 +1,57 @@
+const queues = new Map();
+function state(scope) {
+    const key = JSON.stringify([
+        scope.rpcRoot,
+        scope.directoryPrefix,
+        scope.registrationSessionId,
+    ]);
+    let value = queues.get(key);
+    if (!value) {
+        value = { queue: [], nextId: 1, lastDrainAtBySession: new Map() };
+        queues.set(key, value);
+    }
+    return value;
+}
+const QUEUE_CAP = 100;
+const TUI_CONNECTED_WINDOW_MS = 3_000;
+export function pushNotification(scope, payload, sessionId) {
+    const value = state(scope);
+    value.queue.push({
+        id: value.nextId++,
+        type: 'open-dialog',
+        payload,
+        sessionId,
+    });
+    if (value.queue.length > QUEUE_CAP)
+        value.queue = value.queue.slice(-QUEUE_CAP);
+}
+export function drainNotifications(scope, lastReceivedId = 0, sessionId) {
+    const value = state(scope);
+    const now = Date.now();
+    if (sessionId !== undefined)
+        value.lastDrainAtBySession.set(sessionId, now);
+    const matches = (n) => sessionId === undefined ||
+        n.sessionId === undefined ||
+        n.sessionId === sessionId;
+    if (lastReceivedId > 0) {
+        value.queue = value.queue.filter((n) => {
+            if (n.id > lastReceivedId)
+                return true;
+            if (sessionId === undefined)
+                return true;
+            return n.sessionId !== sessionId;
+        });
+    }
+    return value.queue.filter((n) => n.id > lastReceivedId && matches(n));
+}
+export function isTuiConnected(scope, sessionId) {
+    const now = Date.now();
+    const at = state(scope).lastDrainAtBySession.get(sessionId) ?? 0;
+    return at > 0 && now - at < TUI_CONNECTED_WINDOW_MS;
+}
+export function resetNotificationsForTest(scope) {
+    const value = state(scope);
+    value.queue = [];
+    value.nextId = 1;
+    value.lastDrainAtBySession.clear();
+}

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

@@ -0,0 +1,20 @@
+import type { RpcLogChannel } from './index.js';
+export interface PortFileEntry {
+    port: number;
+    token: string;
+    pid: number;
+    startedAt: number;
+}
+export declare function createManagedRpcStateDirPredicate(directoryPrefix: string): (name: string) => boolean;
+export declare function isManagedRpcStateDir(name: string, directoryPrefix: string): boolean;
+export declare function getRpcDir(rpcRoot: string, directoryPrefix: string, projectDirectory: string): string;
+export declare function writePortFile(dir: string, entry: {
+    port: number;
+    token: string;
+    pid: number;
+}, options?: {
+    secureDir?: boolean;
+    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>;

package/dist/rpc/port-file.js

@@ -0,0 +1,164 @@
+import { createHash } from 'node:crypto';
+import { chmod, mkdir, readdir, readFile, rename, rmdir, unlink, writeFile, } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+export function createManagedRpcStateDirPredicate(directoryPrefix) {
+    return (name) => isManagedRpcStateDir(name, directoryPrefix);
+}
+export function isManagedRpcStateDir(name, directoryPrefix) {
+    if (/^[0-9a-f]{16}$/.test(name))
+        return true;
+    return (name.startsWith(directoryPrefix) &&
+        /^[0-9a-f]{16}$/.test(name.slice(directoryPrefix.length)));
+}
+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));
+}
+async function removeCorruptPortFile(portFile, log) {
+    log?.debug('rpc corrupt port file', { pid: process.pid, portFile });
+    await unlink(portFile).catch(() => { });
+}
+export async function writePortFile(dir, entry, options = {}) {
+    // The directory can be removed by another project's sweep between our
+    // mkdir and the first writeFile/rename, so the whole create-then-rename
+    // unit is retried once on ENOENT. The retry recreates the directory; a
+    // persistent ENOENT (e.g. permission, read-only parent) will surface on
+    // the second attempt — failing fast beats an unbounded loop.
+    const writeOnce = async () => {
+        await mkdir(dir, {
+            recursive: true,
+            mode: options.secureDir ? 0o700 : undefined,
+        });
+        if (options.secureDir)
+            await chmod(dir, 0o700);
+        await options.beforeWrite?.();
+        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);
+        return target;
+    };
+    try {
+        return await writeOnce();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return await writeOnce();
+        }
+        throw error;
+    }
+}
+export async function sweepRpcState(root, activeDir, isManagedDir, log) {
+    let projectDirs;
+    try {
+        projectDirs = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const active = resolve(activeDir);
+    for (const projectDir of projectDirs) {
+        if (!projectDir.isDirectory() || !isManagedDir(projectDir.name)) {
+            continue;
+        }
+        const dir = join(root, projectDir.name);
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        for (const name of names) {
+            if (!name.startsWith('port-') || !name.endsWith('.json'))
+                continue;
+            const portFile = join(dir, name);
+            let raw;
+            try {
+                raw = await readFile(portFile, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            if (raw === undefined)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                await removeCorruptPortFile(portFile, log);
+                continue;
+            }
+            if (!isUsablePortFileEntry(parsed)) {
+                await removeCorruptPortFile(portFile, log);
+                continue;
+            }
+            const entry = parsed;
+            if (!pidAlive(entry.pid))
+                await unlink(portFile).catch(() => { });
+        }
+        if (resolve(dir) !== active)
+            await rmdir(dir).catch(() => { });
+    }
+}
+export async function discoverPortFile(dir, expectedPid) {
+    let names;
+    try {
+        names = await readdir(dir);
+    }
+    catch {
+        return null;
+    }
+    const live = [];
+    for (const name of names) {
+        if (!name.startsWith('port-') || !name.endsWith('.json'))
+            continue;
+        try {
+            const parsed = JSON.parse(await readFile(join(dir, name), 'utf8'));
+            if (isUsablePortFileEntry(parsed)) {
+                if (pidAlive(parsed.pid))
+                    live.push(parsed);
+                else
+                    await unlink(join(dir, name)).catch(() => { });
+            }
+        }
+        catch { }
+    }
+    if (live.length === 0)
+        return null;
+    const candidates = expectedPid !== undefined && expectedPid >= 1
+        ? live.filter((entry) => entry.pid === expectedPid)
+        : [];
+    const entries = candidates.length > 0 ? candidates : live;
+    const sortTime = (entry) => typeof entry.startedAt === 'number' && Number.isFinite(entry.startedAt)
+        ? entry.startedAt
+        : -Infinity;
+    return entries.sort((a, b) => sortTime(b) - sortTime(a))[0] ?? null;
+}

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

@@ -0,0 +1,8 @@
+import type { ApplyRequest, ApplyResult, RpcNotification } from './notifications.js';
+import { 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;

package/dist/rpc/rpc-client.js

@@ -0,0 +1,51 @@
+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);
+    onSelected?.(entry);
+    if (!entry)
+        return null;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`http://127.0.0.1:${entry.port}/rpc/${method}`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${entry.token}`,
+            },
+            body: JSON.stringify(params),
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function createRpcClient(dir, expectedPid, onSelected) {
+    let reportedSelection = false;
+    const reportSelected = (entry) => {
+        if (reportedSelection)
+            return;
+        reportedSelection = true;
+        onSelected?.(entry);
+    };
+    return {
+        async pending(lastReceivedId, sessionId) {
+            const out = await call(dir, expectedPid, reportSelected, 'pending-notifications', { lastReceivedId, sessionId });
+            return out?.messages ?? [];
+        },
+        async apply(request, timeoutMs) {
+            const out = await call(dir, expectedPid, reportSelected, 'apply', {
+                ...request,
+            }, timeoutMs);
+            return out ?? { text: 'apply failed', knobs: {} };
+        },
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { RpcLogChannel } from './index.js';
+import type { ApplyRequest, ApplyResult, RpcNotification } from './notifications.js';
+export interface RpcServerHandle {
+    port: number;
+    token: string;
+    stop: () => Promise<void>;
+}
+export interface RpcServerOptions {
+    dir: string;
+    log?: RpcLogChannel;
+    isManagedDir: (name: string) => boolean;
+    secureDir?: boolean;
+    sweepRoot?: string;
+    drain: (lastReceivedId: number, sessionId?: string) => RpcNotification[];
+    apply: (request: ApplyRequest) => Promise<ApplyResult>;
+    timeoutMs?: number;
+    receiptTimeoutMs?: number;
+}
+export declare function startRpcServer(options: RpcServerOptions): Promise<RpcServerHandle>;