@cortexkit/antigravity-auth-core 2.2.1 → 3.0.0

package/dist/common-auth-embedded/fs/index.js

@@ -0,0 +1,6 @@
+export { writeJsonAtomic } from './atomic-write.js';
+export { WRITER_LOCK_CONSTANTS } from './lock-constants.js';
+// The try-once lock underneath withLock, for callers that hold a lock across
+// several steps or poll instead of waiting (for example a refresh lease).
+export { acquireRefreshFileLock, isLostMarkerRaceError, } from './refresh-file-lock.js';
+export { LockContentionError, LockOwnershipError, lockPathFor, withLock, } from './with-lock.js';

package/dist/common-auth-embedded/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/common-auth-embedded/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/common-auth-embedded/fs/refresh-file-lock.d.ts

@@ -0,0 +1,33 @@
+export declare function isLostMarkerRaceError(error: unknown): boolean;
+export interface LockLoss {
+    readonly reason: 'taken-over' | 'expired' | 'unreadable' | 'renewal-failed' | 'marker-lost';
+    readonly expectedOwnerId: string;
+    readonly observedOwnerId?: string;
+    readonly observedExpiresAt?: number;
+}
+export interface RefreshFileLock {
+    readonly ownerId: string;
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+    /** Resolves once on detected loss; remains pending after an owner's release. */
+    whenLost(): Promise<LockLoss>;
+    hasLost(): 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;
+    /** Notifies a live-owner refusal without awaiting; observer failures are ignored. */
+    onContended?: () => void;
+    /** Synchronous, never awaited; throws and returned promise/thenable rejections are isolated. */
+    onRenewalTimer?: (event: 'scheduled' | 'cancelled') => void;
+    onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | '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<RefreshFileLock | null>;

package/dist/common-auth-embedded/fs/refresh-file-lock.js

@@ -0,0 +1,501 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, 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 loss;
+    let resolveLoss;
+    const lostPromise = new Promise((resolve) => {
+        resolveLoss = resolve;
+    });
+    function notifyTimerStep(event) {
+        try {
+            const result = options.onRenewalTimer?.(event);
+            if (result &&
+                (typeof result === 'object' || typeof result === 'function') &&
+                'then' in result &&
+                typeof result.then === 'function') {
+                void Promise.resolve(result).catch(() => { });
+            }
+        }
+        catch {
+            // Timer observer failures must not replace the lock operation result.
+        }
+    }
+    function cancelRenewalTimer() {
+        if (!renewTimer)
+            return;
+        clearRefreshLockRenewalTimeout(renewTimer);
+        renewTimer = null;
+        notifyTimerStep('cancelled');
+    }
+    function recordLoss(reason, owner) {
+        if (loss || released)
+            return;
+        loss = Object.freeze({
+            reason,
+            expectedOwnerId: ownerId,
+            ...(typeof owner?.ownerId === 'string'
+                ? { observedOwnerId: owner.ownerId }
+                : {}),
+            ...(typeof owner?.expiresAt === 'number'
+                ? { observedExpiresAt: owner.expiresAt }
+                : {}),
+        });
+        cancelRenewalTimer();
+        resolveLoss(loss);
+    }
+    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`;
+        let handle;
+        let created = false;
+        try {
+            handle = await open(tempPath, 'wx', 0o600);
+            created = true;
+            await handle.writeFile(`${JSON.stringify({ ownerId, expiresAt: now() + options.ttlMs })}\n`, 'utf8');
+            await handle.chmod(0o600);
+            await handle.close();
+            handle = undefined;
+            await rename(tempPath, lockPath);
+            created = false;
+        }
+        finally {
+            await handle?.close().catch(() => { });
+            if (created)
+                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 another contender has taken over.
+    // Delete only a record still owned by us, so an already-installed
+    // successor is preserved. The owner read and the removal are not atomic:
+    // a successor record written between them can still be deleted.
+    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 || loss)
+            return;
+        const intervalMs = options.renewIntervalMs ?? Math.max(1_000, Math.floor(options.ttlMs / 3));
+        renewTimer = setRefreshLockRenewalTimeout(() => {
+            renewTimer = null;
+            const renewal = (async () => {
+                let shouldReschedule = !released;
+                try {
+                    const markerAcquired = await withEvictionMarker(async () => {
+                        const owner = await readOwner();
+                        const currentNow = now();
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (owner?.ownerId !== ownerId) {
+                            recordLoss('taken-over', owner);
+                            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)) {
+                            recordLoss('expired', owner);
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (options.onStep)
+                            await options.onStep('renewal-owner-confirmed');
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (!(await ownsEvictionMarker()))
+                            return;
+                        if (options.onStep)
+                            await options.onStep('renewal-write-fenced');
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (!(await ownsEvictionMarker()))
+                            return;
+                        if (options.onStep)
+                            await options.onStep('renewal-write-ready');
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        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.
+                            recordLoss('marker-lost');
+                            shouldReschedule = false;
+                            await relinquishLockAfterMarkerLoss();
+                            return;
+                        }
+                    });
+                    if (!markerAcquired && options.onStep) {
+                        await options.onStep('renewal-marker-unavailable');
+                    }
+                }
+                catch {
+                    // Retry transient failures only while the lease can still be verified.
+                    try {
+                        const owner = await readOwner();
+                        if (owner?.ownerId !== ownerId)
+                            recordLoss('taken-over', owner);
+                        else if (!(Number(owner?.expiresAt) > now()))
+                            recordLoss('expired', owner);
+                    }
+                    catch {
+                        recordLoss('renewal-failed');
+                    }
+                }
+                finally {
+                    if (options.onStep) {
+                        try {
+                            await options.onStep('renewal-finished');
+                        }
+                        catch {
+                            // Errors from the onStep observer must not reject the renewal.
+                        }
+                    }
+                    if (shouldReschedule && !released && !loss)
+                        scheduleRenewal();
+                }
+            })();
+            renewalInFlight = renewal;
+            void renewal.finally(() => {
+                if (renewalInFlight === renewal)
+                    renewalInFlight = null;
+            });
+        }, intervalMs);
+        if ('unref' in renewTimer)
+            renewTimer.unref();
+        notifyTimerStep('scheduled');
+    }
+    function contended() {
+        try {
+            const result = options.onContended?.();
+            if (result &&
+                (typeof result === 'object' || typeof result === 'function') &&
+                'then' in result &&
+                typeof result.then === 'function') {
+                void Promise.resolve(result).catch(() => { });
+            }
+        }
+        catch {
+            // Observers cannot change whether the lock is acquired.
+        }
+        return null;
+    }
+    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 contended();
+            if (options.onStep)
+                await options.onStep('stale-lock-observed');
+            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 contended();
+                // 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;
+                if (options.onStep)
+                    await options.onStep('stale-lock-removed');
+                acquired = await tryAcquire();
+                if (!acquired)
+                    return null;
+                if (options.onStep)
+                    await options.onStep('stale-lock-recreated');
+                // 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 relinquishLockAfterMarkerLoss();
+                    acquired = false;
+                    return null;
+                }
+                break;
+            }
+            finally {
+                await releaseEvictionMarker();
+            }
+        }
+    }
+    if (!acquired)
+        return null;
+    scheduleRenewal();
+    return {
+        ownerId,
+        whenLost: () => lostPromise,
+        hasLost: () => loss !== undefined,
+        assertOwned: async () => {
+            let observed;
+            try {
+                const owner = await readOwner();
+                observed = owner;
+                if (!released &&
+                    !loss &&
+                    owner?.ownerId === ownerId &&
+                    Number(owner?.expiresAt) > now())
+                    return;
+                recordLoss(owner?.ownerId !== ownerId ? 'taken-over' : 'expired', owner);
+            }
+            catch {
+                // Unreadable ownership is not evidence of a valid lease.
+                recordLoss('unreadable');
+            }
+            throw new LockOwnershipError({
+                target: options.path,
+                name: options.name,
+                expectedOwnerId: ownerId,
+                ...(typeof observed?.ownerId === 'string'
+                    ? { observedOwnerId: observed.ownerId }
+                    : {}),
+                ...(typeof observed?.expiresAt === 'number'
+                    ? { observedExpiresAt: observed.expiresAt }
+                    : {}),
+            });
+        },
+        release: async () => {
+            released = true;
+            cancelRenewalTimer();
+            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/common-auth-embedded/fs/with-lock.d.ts

@@ -0,0 +1,33 @@
+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 interface LockOwnershipDetails {
+    target: string;
+    name: string;
+    expectedOwnerId?: string;
+    observedOwnerId?: string;
+    observedExpiresAt?: number;
+}
+export declare class LockOwnershipError extends Error {
+    readonly details: LockOwnershipDetails;
+    constructor(details: LockOwnershipDetails);
+}
+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/common-auth-embedded/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/common-auth-embedded/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/common-auth-embedded/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;
+        },
+    };
+}