@cortexkit/antigravity-auth-core 2.2.1 → 3.0.0

package/dist/common-auth-embedded/logger/engine.d.ts

@@ -0,0 +1,100 @@
+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.
+     *
+     * A function is what a host passes when its destination can move while the
+     * process runs — an operator or a test changing the variable that names the
+     * log file expects the next line to land in the new file, and a value
+     * captured once at init would keep writing to the old one.
+     */
+    file: string | (() => string);
+    /** 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;
+    info(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+    trace(message: string, data?: unknown): void;
+}
+/**
+ * A logger with its own file, level, redaction, capture sink and buffer.
+ * Two instances in one process never touch each other's settings or lines,
+ * so two plugins that load one shared copy of this module each keep their own
+ * log by holding their own instance.
+ */
+export interface LoggerInstance {
+    /** A logger whose lines carry `channel` and go to this instance's file. */
+    createLogger(channel: string): ChannelLogger;
+    /**
+     * Point this instance at a host's file and level. Idempotent: calling it
+     * again replaces both. A runtime level installed by `setLogLevel` is left
+     * alone, because it is the operator's explicit choice and outranks the
+     * floor a host computed at start-up.
+     */
+    configure(options: LoggerOptions): void;
+    /** Operator override of the level floor; undefined removes it. */
+    setLogLevel(level: Level | undefined): void;
+    /**
+     * Write whatever is buffered. Safe to call synchronously from a
+     * process-exit handler, which is how each host drains the buffer on
+     * shutdown.
+     */
+    flushLogs(): void;
+}
+/**
+ * A logger instance of its own, configured with `options`. A plugin whose
+ * copy of this module may be shared with another plugin in the same process
+ * uses this instead of `initLogger`, so neither replaces the other's file,
+ * level, redaction or capture sink.
+ */
+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: LoggerOptions): LoggerInstance;
+export declare function setLogLevel(l: Level | undefined): void;
+/**
+ * Write whatever the default logger has buffered. Safe to call synchronously
+ * from a process-exit handler, which is how each host drains the buffer on
+ * shutdown.
+ */
+export declare function flushLogs(): void;
+export declare function createLogger(channel: string): ChannelLogger;
+export declare function flushForTest(): Promise<void>;
+/**
+ * Return the default 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 declare function resetLoggerForTest(): void;

package/dist/common-auth-embedded/logger/engine.js

@@ -0,0 +1,246 @@
+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;
+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 */
+    }
+}
+function safeSerialize(data) {
+    try {
+        return ` ${JSON.stringify(data)}`;
+    }
+    catch {
+        return ' [unserializable]';
+    }
+}
+/**
+ * One logger's settings and buffer.
+ *
+ * Where lines are written and the level floor start unset unless `options`
+ * supplies them. A host decides where its log lives (that decision reads host
+ * environment variables and host directories, neither of which belongs in
+ * shared code) and configures the logger 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 a configuration that may never arrive.
+ */
+function createEngine(options) {
+    let logFileSource;
+    let initLevelSource;
+    let runtimeLevel;
+    let redactor = createRedactor();
+    let captureSink;
+    let buffer = [];
+    let timer;
+    function configure(next) {
+        logFileSource = next.file;
+        initLevelSource = next.level;
+        redactor = createRedactor(next);
+        captureSink = next.captureSink;
+    }
+    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';
+    }
+    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 emit(channel, level, message, data) {
+        // Unconfigured (neither a file nor a sink) stays a silent no-op.
+        if (logFileSource === undefined && captureSink === 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 { }
+            // A sink-only logger has no file to buffer lines for.
+            if (logFileSource === undefined)
+                return;
+            buffer.push(line);
+            if (buffer.length >= 50)
+                flushLogs();
+            else
+                schedule();
+        }
+        catch {
+            // Provider and redaction failures must never turn diagnostics into a host crash.
+        }
+    }
+    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),
+        };
+    }
+    function reset() {
+        buffer = [];
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        logFileSource = undefined;
+        initLevelSource = undefined;
+        runtimeLevel = undefined;
+        redactor = createRedactor();
+        captureSink = undefined;
+    }
+    if (options)
+        configure(options);
+    return { configure, createLogger, setLogLevel, flushLogs, reset };
+}
+/**
+ * A logger instance of its own, configured with `options`. A plugin whose
+ * copy of this module may be shared with another plugin in the same process
+ * uses this instead of `initLogger`, so neither replaces the other's file,
+ * level, redaction or capture sink.
+ */
+export function createLoggerInstance(options) {
+    const { configure, createLogger, setLogLevel, flushLogs } = createEngine(options);
+    return { configure, createLogger, setLogLevel, flushLogs };
+}
+/**
+ * The instance behind the module-level functions below, which keep the
+ * single-plugin API: one plugin per copy of this module calls `initLogger`
+ * and `createLogger` without holding an instance.
+ */
+const defaultEngine = createEngine();
+/**
+ * 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 function initLogger(options) {
+    defaultEngine.configure(options);
+    const { configure, createLogger, setLogLevel, flushLogs } = defaultEngine;
+    return { configure, createLogger, setLogLevel, flushLogs };
+}
+export function setLogLevel(l) {
+    defaultEngine.setLogLevel(l);
+}
+/**
+ * Write whatever the default logger has buffered. Safe to call synchronously
+ * from a process-exit handler, which is how each host drains the buffer on
+ * shutdown.
+ */
+export function flushLogs() {
+    defaultEngine.flushLogs();
+}
+export function createLogger(channel) {
+    return defaultEngine.createLogger(channel);
+}
+export async function flushForTest() {
+    defaultEngine.flushLogs();
+}
+/**
+ * Return the default 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() {
+    defaultEngine.reset();
+}

package/dist/common-auth-embedded/logger/index.d.ts

@@ -0,0 +1,6 @@
+export type { CaptureSink, LogTestRecord } from './capture-sink.js';
+export { createCaptureSink } from './capture-sink.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/common-auth-embedded/logger/index.js

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

package/dist/common-auth-embedded/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/common-auth-embedded/logger/redact.js

@@ -0,0 +1,83 @@
+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***';
+// How many errors deep a cause chain is followed. A chain this long is
+// already unreadable in a log line, and an unbounded one (each cause a fresh
+// object, so the cycle check never trips) must not grow the line forever.
+const MAX_ERROR_DEPTH = 8;
+// Error's own fields are non-enumerable, so a plain entry walk renders an
+// Error as `{}` and the name, message and stack a plugin logged are lost.
+// The tag check also recognises an Error from another realm (a worker or a
+// vm context), whose prototype is not this realm's Error.
+function isError(value) {
+    return (value instanceof Error ||
+        Object.prototype.toString.call(value) === '[object Error]');
+}
+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));
+    }
+    // The fields every log reader wants first, then whatever else the error
+    // carries as its own enumerable properties (which is all an Error rendered
+    // as before). Every entry goes through the same key and string scrubbing as
+    // any other object, so a token in a message or stack is still masked.
+    function errorEntries(error) {
+        const fields = error;
+        const entries = [
+            ['name', error.name],
+            ['message', error.message],
+            ['stack', error.stack],
+        ];
+        for (const key of ['code', 'status', 'cause'])
+            if (fields[key] !== undefined)
+                entries.push([key, fields[key]]);
+        const listed = new Set(entries.map(([key]) => key));
+        for (const entry of Object.entries(error))
+            if (!listed.has(entry[0]))
+                entries.push(entry);
+        return entries;
+    }
+    function walk(value, keys, seen, errorDepth = 0) {
+        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, errorDepth));
+            const error = isError(value);
+            if (error && errorDepth >= MAX_ERROR_DEPTH)
+                return '[Truncated]';
+            const childDepth = error ? errorDepth + 1 : errorDepth;
+            // Define own properties so a diagnostic __proto__ key cannot change the output prototype.
+            return Object.fromEntries((error ? errorEntries(value) : Object.entries(value)).map(([key, item]) => [
+                key,
+                keys && isSecretKey(key)
+                    ? MASK
+                    : walk(item, keys, seen, childDepth),
+            ]));
+        }
+        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/common-auth-embedded/pi-slot/index.d.ts

@@ -0,0 +1,3 @@
+/** Move a Pi provider slot aside without changing provider or model identifiers. */
+export type { PiSlot, PiSlotErrorCode, PiSlotInspection, PiSlotOptions, } from './slot.js';
+export { openPiSlot, PiSlotError } from './slot.js';

package/dist/common-auth-embedded/pi-slot/index.js

@@ -0,0 +1,2 @@
+/** Move a Pi provider slot aside without changing provider or model identifiers. */
+export { openPiSlot, PiSlotError } from './slot.js';

package/dist/common-auth-embedded/pi-slot/lock.js

@@ -0,0 +1,212 @@
+import { rmdirSync, statSync } from 'node:fs';
+import { mkdir, rmdir, stat, utimes } from 'node:fs/promises';
+// Protocol source: proper-lockfile 4.1.2 lib/lockfile.js and lib/mtime-precision.js;
+// line-level citations and the Pi lock options are recorded in docs/sources.md.
+// Pi's async acquireLockAsync uses stale=30s (update=15s). Keep takeover at 30s
+// so a live async writer's lock cannot be reclaimed between its renewals.
+const STALE = 30_000;
+// Pi's sync acquireLockSyncWithRetry uses proper-lockfile defaults: stale=10s,
+// update=5s. Renew every 3s for margin and stop retrying failed renewals after 10s.
+const RENEWAL_STALE = 10_000;
+const UPDATE = 3_000;
+let precision;
+/** Held locks, with the time each last renewed, for cleanup at process exit. */
+const active = new Map();
+process.once('exit', () => {
+    for (const [path, identity] of active) {
+        try {
+            // Pi's synchronous auth.json writer treats a lock whose mtime has not
+            // been refreshed for 10s as abandoned and may take it over. A lease that
+            // went 10s without renewing may therefore already be that writer's, so
+            // it is left in place; whoever next needs the lock clears it as stale.
+            if (identity.renewedAt + RENEWAL_STALE < Date.now())
+                continue;
+            const observed = statSync(path);
+            if (sameDirectory(observed, identity) &&
+                observed.mtime.getTime() === identity.mtime)
+                rmdirSync(path);
+        }
+        catch {
+            /* A compromised or already removed lock is not ours to clean up. */
+        }
+    }
+});
+function sameDirectory(observed, identity) {
+    return observed.dev === identity.dev && observed.ino === identity.ino;
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? error.code
+        : undefined;
+}
+function held() {
+    return Object.assign(new Error('Pi auth lock held'), { code: 'ELOCKED' });
+}
+async function remove(path) {
+    try {
+        await rmdir(path);
+    }
+    catch (error) {
+        if (errorCode(error) !== 'ENOENT')
+            throw error;
+    }
+}
+async function acquire(path, stale) {
+    try {
+        await mkdir(path);
+    }
+    catch (error) {
+        if (errorCode(error) !== 'EEXIST')
+            throw error;
+        if (stale <= 0)
+            throw held();
+        let mtime;
+        try {
+            mtime = (await stat(path)).mtime.getTime();
+        }
+        catch (error) {
+            if (errorCode(error) === 'ENOENT')
+                return acquire(path, 0);
+            throw error;
+        }
+        if (!(mtime < Date.now() - stale))
+            throw held();
+        // Match upstream: rmdir (ignore ENOENT), then one mkdir attempt without another stale check.
+        await remove(path);
+        return acquire(path, 0);
+    }
+    try {
+        if (!precision) {
+            const probe = new Date(Math.ceil(Date.now() / 1_000) * 1_000 + 5);
+            await utimes(path, probe, probe);
+        }
+        const observed = await stat(path);
+        const mtime = observed.mtime.getTime();
+        precision ??= mtime % 1_000 === 0 ? 's' : 'ms';
+        return { dev: observed.dev, ino: observed.ino, mtime };
+    }
+    catch (error) {
+        await remove(path).catch(() => { });
+        throw error;
+    }
+}
+/** The same mkdir/mtime/rmdir protocol as Pi's proper-lockfile, with realpath disabled. */
+export async function acquirePiLock(authPath, onCompromised, onRenew) {
+    const path = `${authPath}.lock`;
+    const identity = await acquire(path, STALE);
+    let mtime = identity.mtime;
+    let lastUpdate = Date.now();
+    let released = false;
+    let timer;
+    active.set(path, { ...identity, renewedAt: lastUpdate });
+    function compromise() {
+        released = true;
+        if (timer)
+            clearTimeout(timer);
+        active.delete(path);
+        onCompromised();
+    }
+    function assertFresh() {
+        // A sync writer may already have reclaimed an unrenewed lock after 10s,
+        // even if the directory still matches. Never revive that expired lease.
+        if (!released && lastUpdate + RENEWAL_STALE < Date.now())
+            compromise();
+    }
+    function schedule(delay = UPDATE) {
+        if (released)
+            return;
+        timer = setTimeout(() => {
+            void update();
+        }, delay);
+        timer.unref();
+    }
+    function retry(error) {
+        if (released)
+            return;
+        if (errorCode(error) === 'ENOENT' ||
+            lastUpdate + RENEWAL_STALE < Date.now())
+            compromise();
+        else
+            schedule(1_000);
+    }
+    async function update() {
+        assertFresh();
+        if (released)
+            return;
+        let observed;
+        try {
+            observed = await stat(path);
+        }
+        catch (error) {
+            retry(error);
+            return;
+        }
+        assertFresh();
+        if (released)
+            return;
+        if (!sameDirectory(observed, identity) ||
+            observed.mtime.getTime() !== mtime) {
+            compromise();
+            return;
+        }
+        const next = new Date(precision === 's' ? Math.ceil(Date.now() / 1_000) * 1_000 : Date.now());
+        try {
+            await utimes(path, next, next);
+        }
+        catch (error) {
+            retry(error);
+            return;
+        }
+        if (released)
+            return;
+        mtime = next.getTime();
+        lastUpdate = Date.now();
+        active.set(path, { ...identity, mtime, renewedAt: lastUpdate });
+        schedule();
+    }
+    // Tests can resume a paused renewal without waiting for the production timer.
+    onRenew?.(async () => {
+        if (timer)
+            clearTimeout(timer);
+        await update();
+    });
+    schedule();
+    return {
+        assertFresh,
+        async release() {
+            if (released)
+                return;
+            released = true;
+            if (timer)
+                clearTimeout(timer);
+            active.delete(path);
+            // An expired lease is never removed, even when the directory still
+            // matches. Pi's synchronous auth.json writer may take over a lock that
+            // went 10s without an mtime refresh, so after 10s without renewing the
+            // directory may be that writer's. Whoever next needs the lock clears it
+            // as stale.
+            const expired = () => lastUpdate + RENEWAL_STALE < Date.now();
+            if (expired()) {
+                compromise();
+                return;
+            }
+            let observed;
+            try {
+                observed = await stat(path);
+            }
+            catch (error) {
+                if (errorCode(error) !== 'ENOENT')
+                    throw error;
+                compromise();
+                return;
+            }
+            if (expired() ||
+                !sameDirectory(observed, identity) ||
+                mtime !== observed.mtime.getTime()) {
+                compromise();
+                return;
+            }
+            await remove(path);
+        },
+    };
+}