@cortexkit/common-auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ex Machina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,10 @@
+# common-auth
+
+Shared libraries for the CortexKit auth plugins for OpenCode and Pi: openai-auth, anthropic-auth and antigravity-auth. Nothing is published yet.
+
+`research/` holds the spike reports that inform the design:
+
+- [OpenCode 2 transport spike](research/opencode2-transport/REPORT.md): can a plugin own the transport on OpenCode 2?
+- [OpenCode 2 native-driver spike](research/opencode2-thin/REPORT.md): multi-account support through hooks on OpenCode 2's built-in OpenAI driver.
+
+Licensed under MIT; see [LICENSE](LICENSE).

package/dist/fs/atomic-write.d.ts

@@ -0,0 +1,5 @@
+export interface AtomicWriteOptions {
+    serialize?: (value: unknown) => string;
+    beforeRename?: () => Promise<void>;
+}
+export declare function writeJsonAtomic(path: string, value: unknown, options?: AtomicWriteOptions): Promise<void>;

package/dist/fs/atomic-write.js

@@ -0,0 +1,22 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export async function writeJsonAtomic(path, value, options = {}) {
+    await mkdir(dirname(path), { recursive: true });
+    const tempPath = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(tempPath, options.serialize
+            ? options.serialize(value)
+            : `${JSON.stringify(value, null, 2)}\n`, {
+            encoding: 'utf8',
+            mode: 0o600,
+        });
+        await options.beforeRename?.();
+        await rename(tempPath, path);
+    }
+    catch (error) {
+        // A failed write can leave partial staging bytes just like a failed rename.
+        await rm(tempPath, { force: true }).catch(() => { });
+        throw error;
+    }
+}

package/dist/fs/index.d.ts

@@ -0,0 +1,5 @@
+export type { AtomicWriteOptions } from './atomic-write.js';
+export { writeJsonAtomic } from './atomic-write.js';
+export { WRITER_LOCK_CONSTANTS } from './lock-constants.js';
+export type { LockOptions } from './with-lock.js';
+export { LockContentionError, LockOwnershipError, lockPathFor, withLock, } from './with-lock.js';

package/dist/fs/index.js

@@ -0,0 +1,3 @@
+export { writeJsonAtomic } from './atomic-write.js';
+export { WRITER_LOCK_CONSTANTS } from './lock-constants.js';
+export { LockContentionError, LockOwnershipError, lockPathFor, withLock, } from './with-lock.js';

package/dist/fs/lock-constants.d.ts

@@ -0,0 +1,14 @@
+export declare const WRITER_LOCK_CONSTANTS: Readonly<{
+    sidebar: Readonly<{
+        name: "sidebar-write";
+        ttlMs: 10000;
+        timeoutMs: 15000;
+        renew: true;
+    }>;
+    preferences: Readonly<{
+        name: "preferences";
+        ttlMs: 10000;
+        timeoutMs: 2000;
+        renew: true;
+    }>;
+}>;

package/dist/fs/lock-constants.js

@@ -0,0 +1,14 @@
+export const WRITER_LOCK_CONSTANTS = Object.freeze({
+    sidebar: Object.freeze({
+        name: 'sidebar-write',
+        ttlMs: 10_000,
+        timeoutMs: 15_000,
+        renew: true,
+    }),
+    preferences: Object.freeze({
+        name: 'preferences',
+        ttlMs: 10_000,
+        timeoutMs: 2_000,
+        renew: true,
+    }),
+});

package/dist/fs/refresh-file-lock.d.ts

@@ -0,0 +1,18 @@
+export declare function isLostMarkerRaceError(error: unknown): boolean;
+export declare function acquireRefreshFileLock(options: {
+    name: string;
+    ttlMs: number;
+    /**
+     * File the lock is named after. Required: the lock and the write it guards
+     * must target the same file, and a default resolved in here could only ever
+     * be one host's path.
+     */
+    path: string;
+    now?: () => number;
+    renew?: boolean;
+    renewIntervalMs?: number;
+    onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-confirmed' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
+}): Promise<{
+    release: () => Promise<void>;
+    assertOwned: () => Promise<void>;
+} | null>;

package/dist/fs/refresh-file-lock.js

@@ -0,0 +1,392 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { LockOwnershipError, lockPathFor } from './with-lock.js';
+const setRefreshLockRenewalTimeout = globalThis.setTimeout.bind(globalThis);
+const clearRefreshLockRenewalTimeout = globalThis.clearTimeout.bind(globalThis);
+// A concurrent contender renaming the freshly-created eviction-marker directory
+// away surfaces the vanished parent differently per platform: ENOENT on Linux,
+// EINVAL or ENOTDIR on macOS/APFS. All three mean the marker is no longer ours
+// to hold — a lost race the caller should retry, not a fatal lock error.
+export function isLostMarkerRaceError(error) {
+    const code = error?.code;
+    return code === 'ENOENT' || code === 'EINVAL' || code === 'ENOTDIR';
+}
+export async function acquireRefreshFileLock(options) {
+    const lockPath = lockPathFor(options.path, options.name);
+    const legacyOwnerPath = join(lockPath, 'owner.json');
+    const ownerId = randomUUID();
+    const now = options.now ?? Date.now;
+    let renewTimer = null;
+    let released = false;
+    let renewalInFlight = null;
+    // Only the owner of this exclusively-created marker may remove or renew a
+    // lock. A contender recovering a stale marker can accidentally rename a newer
+    // marker instead; checking its owner file before each mutation prevents the
+    // displaced owner from continuing to act on the lock.
+    const evictPath = `${lockPath}.evicting`;
+    const evictOwnerPath = join(evictPath, 'owner.json');
+    const evictOwnerId = randomUUID();
+    const EVICT_TTL = 5_000;
+    const MAX_STEAL_ATTEMPTS = 8;
+    async function readOwner() {
+        try {
+            return JSON.parse(await readFile(lockPath, 'utf8'));
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EISDIR')
+                throw error;
+            return JSON.parse(await readFile(legacyOwnerPath, 'utf8'));
+        }
+    }
+    async function writeOwner() {
+        // Readers must see a complete lease, even while renewal is writing.
+        const tempPath = `${lockPath}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(tempPath, `${JSON.stringify({ ownerId, expiresAt: now() + options.ttlMs })}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+            await rename(tempPath, lockPath);
+        }
+        finally {
+            await rm(tempPath, { force: true }).catch(() => { });
+        }
+    }
+    async function tryAcquire() {
+        try {
+            await writeFile(lockPath, `${JSON.stringify({ ownerId, expiresAt: now() + options.ttlMs })}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+            return true;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === 'EEXIST' || code === 'EISDIR')
+                return false;
+            if (code === 'ENOENT') {
+                // Reboots can clear runtime temp directories before the next lock acquisition.
+                await mkdir(dirname(lockPath), { recursive: true });
+                try {
+                    await writeFile(lockPath, `${JSON.stringify({ ownerId, expiresAt: now() + options.ttlMs })}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+                    return true;
+                }
+                catch (retryError) {
+                    const retryCode = retryError.code;
+                    if (retryCode === 'EEXIST' || retryCode === 'EISDIR')
+                        return false;
+                    throw retryError;
+                }
+            }
+            throw error;
+        }
+    }
+    async function backoff() {
+        await new Promise((resolve) => setTimeout(resolve, Math.floor(Math.random() * 4)));
+    }
+    async function lockIsLive() {
+        try {
+            const currentOwner = await readOwner();
+            return Number(currentOwner?.expiresAt) > now();
+        }
+        catch {
+            try {
+                const current = await stat(lockPath);
+                return current.mtimeMs + options.ttlMs > now();
+            }
+            catch {
+                // Lock doesn't exist — safe to acquire.
+                return false;
+            }
+        }
+    }
+    // Fail-closed: any read error means we do NOT own the marker.
+    async function ownsEvictionMarker() {
+        try {
+            const owner = JSON.parse(await readFile(evictOwnerPath, 'utf8'));
+            return owner?.ownerId === evictOwnerId;
+        }
+        catch {
+            return false;
+        }
+    }
+    async function releaseEvictionMarker() {
+        if (await ownsEvictionMarker()) {
+            await rm(evictPath, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+    async function tryAcquireEvictionMarker() {
+        await mkdir(evictPath);
+        try {
+            await writeFile(evictOwnerPath, `${JSON.stringify({ ownerId: evictOwnerId, createdAt: now() })}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        }
+        catch (error) {
+            // A competing contender can rename our just-created marker directory
+            // away between the mkdir above and this write (the stale-marker steal
+            // path below does exactly that). That is a lost race, not a failure, so
+            // report it as such and let the caller back off and retry rather than
+            // failing the whole lock acquisition.
+            if (isLostMarkerRaceError(error))
+                return false;
+            await releaseEvictionMarker();
+            throw error;
+        }
+        if (options.onStep)
+            await options.onStep('eviction-marker-acquired');
+        return true;
+    }
+    async function recoverStaleEvictionMarker() {
+        let evictStat;
+        try {
+            evictStat = await stat(evictPath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return 'missing';
+            throw error;
+        }
+        if (evictStat.mtimeMs + EVICT_TTL > now())
+            return 'fresh';
+        if (options.onStep)
+            await options.onStep('stale-marker-stat');
+        const claimedPath = `${evictPath}.${randomUUID()}`;
+        try {
+            await rename(evictPath, claimedPath);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return 'missing';
+            throw error;
+        }
+        if (options.onStep)
+            await options.onStep('stale-marker-claimed');
+        await rm(claimedPath, { recursive: true, force: true }).catch(() => { });
+        return 'recovered';
+    }
+    async function withEvictionMarker(action) {
+        try {
+            if (!(await tryAcquireEvictionMarker()))
+                return false;
+        }
+        catch (error) {
+            if (error.code === 'EEXIST')
+                return false;
+            throw error;
+        }
+        try {
+            await action();
+        }
+        finally {
+            await releaseEvictionMarker();
+        }
+        return true;
+    }
+    // Marker loss after a write may mean our record replaced a successor's.
+    // Delete only a record still owned by us; a concurrent successor write can
+    // then yield zero winners, never two.
+    async function relinquishLockAfterMarkerLoss() {
+        for (let attempt = 0; attempt < MAX_STEAL_ATTEMPTS; attempt++) {
+            if (options.onStep)
+                await options.onStep('relinquish-read');
+            let owner;
+            try {
+                owner = await readOwner();
+            }
+            catch {
+                return;
+            }
+            if (owner?.ownerId !== ownerId)
+                return;
+            try {
+                await rm(lockPath, { recursive: true, force: true });
+                return;
+            }
+            catch {
+                await backoff();
+            }
+        }
+    }
+    function scheduleRenewal() {
+        if (!options.renew || released)
+            return;
+        const intervalMs = options.renewIntervalMs ?? Math.max(1_000, Math.floor(options.ttlMs / 3));
+        renewTimer = setRefreshLockRenewalTimeout(() => {
+            const renewal = (async () => {
+                let shouldReschedule = !released;
+                try {
+                    const markerAcquired = await withEvictionMarker(async () => {
+                        const owner = await readOwner();
+                        const currentNow = now();
+                        if (released || owner?.ownerId !== ownerId) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        // An expired lease is no longer ours to extend; a contender may
+                        // already be eligible to acquire it.
+                        if (Number(owner?.expiresAt) <= currentNow) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (options.onStep)
+                            await options.onStep('renewal-owner-confirmed');
+                        if (released) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (!(await ownsEvictionMarker()))
+                            return;
+                        if (options.onStep)
+                            await options.onStep('renewal-write-fenced');
+                        if (released) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (!(await ownsEvictionMarker()))
+                            return;
+                        if (options.onStep)
+                            await options.onStep('renewal-write-ready');
+                        await writeOwner();
+                        if (!(await ownsEvictionMarker())) {
+                            // If marker ownership cannot be read, stop claiming the lease
+                            // and remove only a record that still carries our owner id.
+                            shouldReschedule = false;
+                            await relinquishLockAfterMarkerLoss();
+                            return;
+                        }
+                    });
+                    if (!markerAcquired && options.onStep) {
+                        await options.onStep('renewal-marker-unavailable');
+                    }
+                }
+                catch {
+                    // Transient marker and filesystem failures retry on the next interval.
+                }
+                finally {
+                    if (options.onStep) {
+                        try {
+                            await options.onStep('renewal-finished');
+                        }
+                        catch {
+                            // Errors from the onStep observer must not reject the renewal.
+                        }
+                    }
+                    if (shouldReschedule && !released)
+                        scheduleRenewal();
+                }
+            })();
+            renewalInFlight = renewal;
+            void renewal.finally(() => {
+                if (renewalInFlight === renewal)
+                    renewalInFlight = null;
+            });
+        }, intervalMs);
+        if ('unref' in renewTimer)
+            renewTimer.unref();
+    }
+    let acquired = await tryAcquire();
+    if (!acquired) {
+        for (let attempt = 0; attempt < MAX_STEAL_ATTEMPTS; attempt++) {
+            acquired = await tryAcquire();
+            if (acquired)
+                break;
+            if (await lockIsLive())
+                return null;
+            try {
+                if (!(await tryAcquireEvictionMarker())) {
+                    await backoff();
+                    continue;
+                }
+            }
+            catch (evictError) {
+                const code = evictError.code;
+                if (code !== 'EEXIST')
+                    throw evictError;
+                const recovered = await recoverStaleEvictionMarker();
+                if (recovered === 'fresh')
+                    return null;
+                await backoff();
+                continue;
+            }
+            try {
+                if (await lockIsLive())
+                    return null;
+                // Verify marker ownership before removing a lock found not live.
+                if (!(await ownsEvictionMarker()))
+                    return null;
+                if (options.onStep)
+                    await options.onStep('stale-lock-confirmed');
+                // The onStep callback can pause while another contender renames
+                // our marker, so verify ownership again after the callback.
+                if (!(await ownsEvictionMarker()))
+                    return null;
+                await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                // Fence check 3: re-verify ownership after removing the stale lock.
+                if (!(await ownsEvictionMarker()))
+                    return null;
+                acquired = await tryAcquire();
+                if (!acquired)
+                    return null;
+                // Fence check 4: re-verify ownership after acquiring the lock. If the
+                // marker was stolen between tryAcquire and this check, release the
+                // just-acquired lock and return null (fail-closed).
+                if (!(await ownsEvictionMarker())) {
+                    await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                    acquired = false;
+                    return null;
+                }
+                break;
+            }
+            finally {
+                await releaseEvictionMarker();
+            }
+        }
+    }
+    if (!acquired)
+        return null;
+    scheduleRenewal();
+    return {
+        assertOwned: async () => {
+            try {
+                const owner = await readOwner();
+                if (!released &&
+                    owner?.ownerId === ownerId &&
+                    Number(owner?.expiresAt) > now())
+                    return;
+            }
+            catch {
+                // Unreadable ownership is not evidence of a valid lease.
+            }
+            throw new LockOwnershipError({
+                target: options.path,
+                name: options.name,
+            });
+        },
+        release: async () => {
+            released = true;
+            if (renewTimer) {
+                clearRefreshLockRenewalTimeout(renewTimer);
+                renewTimer = null;
+            }
+            await renewalInFlight;
+            for (let attempt = 0; attempt < MAX_STEAL_ATTEMPTS; attempt++) {
+                try {
+                    const markerAcquired = await withEvictionMarker(async () => {
+                        const owner = await readOwner();
+                        if (owner?.ownerId !== ownerId)
+                            return;
+                        if (options.onStep)
+                            await options.onStep('release-owner-confirmed');
+                        if (!(await ownsEvictionMarker()))
+                            return;
+                        await rm(lockPath, { recursive: true, force: true }).catch(() => { });
+                    });
+                    if (markerAcquired)
+                        return;
+                    await recoverStaleEvictionMarker();
+                }
+                catch {
+                    return;
+                }
+                await backoff();
+            }
+            // Do not delete by pathname without the marker: bounded retries leave the
+            // lease to expire rather than risking removal of a successor's lock.
+        },
+    };
+}

package/dist/fs/with-lock.d.ts

@@ -0,0 +1,32 @@
+export declare function lockPathFor(target: string, name: string): string;
+export declare class LockContentionError extends Error {
+    readonly details: {
+        target: string;
+        name: string;
+        timeoutMs: number;
+    };
+    constructor(details: {
+        target: string;
+        name: string;
+        timeoutMs: number;
+    });
+}
+export declare class LockOwnershipError extends Error {
+    readonly details: {
+        target: string;
+        name: string;
+    };
+    constructor(details: {
+        target: string;
+        name: string;
+    });
+}
+export interface LockOptions {
+    name: string;
+    ttlMs: number;
+    timeoutMs: number;
+    renew?: boolean;
+}
+export declare function withLock<T>(target: string, options: LockOptions, fn: (lock: {
+    assertOwned(): Promise<void>;
+}) => Promise<T>): Promise<T>;

package/dist/fs/with-lock.js

@@ -0,0 +1,48 @@
+import { acquireRefreshFileLock } from './refresh-file-lock.js';
+export function lockPathFor(target, name) {
+    return `${target}.${name}.lock`;
+}
+export class LockContentionError extends Error {
+    details;
+    constructor(details) {
+        super(`Timed out acquiring ${details.name} lock for ${details.target}`);
+        this.name = 'LockContentionError';
+        this.details = details;
+    }
+}
+export class LockOwnershipError extends Error {
+    details;
+    constructor(details) {
+        super(`Lost ${details.name} lock for ${details.target}`);
+        this.name = 'LockOwnershipError';
+        this.details = details;
+    }
+}
+export async function withLock(target, options, fn) {
+    const started = performance.now();
+    for (;;) {
+        const lock = await acquireRefreshFileLock({
+            path: target,
+            name: options.name,
+            ttlMs: options.ttlMs,
+            renew: options.renew ?? false,
+        });
+        if (lock) {
+            try {
+                return await fn(lock);
+            }
+            finally {
+                await lock.release();
+            }
+        }
+        const remaining = options.timeoutMs - (performance.now() - started);
+        if (remaining <= 0) {
+            throw new LockContentionError({
+                target,
+                name: options.name,
+                timeoutMs: options.timeoutMs,
+            });
+        }
+        await new Promise((resolve) => setTimeout(resolve, Math.min(25, Math.ceil(remaining))));
+    }
+}

package/dist/logger/capture-sink.d.ts

@@ -0,0 +1,14 @@
+import type { Level } from './engine.js';
+export interface LogTestRecord {
+    channel: string;
+    level: Level;
+    message: string;
+    data?: unknown;
+}
+/** The engine delivers scrubbed records only; this sink never sees raw credentials. */
+export type CaptureSink = (record: LogTestRecord) => void;
+export declare function createCaptureSink(): {
+    records: LogTestRecord[];
+    sink: CaptureSink;
+    clear: () => void;
+};

package/dist/logger/capture-sink.js

@@ -0,0 +1,13 @@
+export function createCaptureSink() {
+    const records = [];
+    const sink = (record) => {
+        records.push(record);
+    };
+    return {
+        records,
+        sink,
+        clear: () => {
+            records.length = 0;
+        },
+    };
+}

package/dist/logger/engine.d.ts

@@ -0,0 +1,44 @@
+import type { CaptureSink } from './capture-sink.js';
+import { type RedactionOptions } from './redact.js';
+export type Level = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+export interface InitLoggerOptions extends RedactionOptions {
+    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);
+}
+/**
+ * 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 declare function initLogger(options: InitLoggerOptions): void;
+export declare function setLogLevel(l: 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.
+ */
+export declare function flushLogs(): void;
+export declare function createLogger(channel: string): {
+    error: (m: string, d?: unknown) => void;
+    warn: (m: string, d?: unknown) => void;
+    info: (m: string, d?: unknown) => void;
+    debug: (m: string, d?: unknown) => void;
+    trace: (m: string, d?: unknown) => void;
+};
+export declare function flushForTest(): Promise<void>;
+/**
+ * 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 declare function resetLoggerForTest(): void;