@cortexkit/antigravity-auth-core 2.2.1 → 3.0.0

package/dist/common-auth-embedded/store/refresh-lock.js

@@ -0,0 +1,136 @@
+import { acquireRefreshFileLock } from '../fs/refresh-file-lock.js';
+import { LockContentionError } from '../fs/with-lock.js';
+/**
+ * Store lock defaults: a 15 000 ms bounded wait retried every 50 ms plus
+ * jitter, and a renewed 10 000 ms lease.
+ */
+export const POOL_LOCK_DEFAULTS = Object.freeze({
+    ttlMs: 10_000,
+    timeoutMs: 15_000,
+    retryMs: 50,
+    renew: true,
+});
+/**
+ * Takes one lock, retrying while a live holder has it until `timeoutMs` has
+ * passed on the real clock, then throws `LockContentionError`. The lease is
+ * asserted as owned once acquired, so a caller never proceeds on a lease that
+ * expired during the wait.
+ */
+export async function acquirePoolLock(spec, defaults, env) {
+    const emit = (type) => {
+        try {
+            const result = env.onLockEvent?.({
+                type,
+                name: spec.name,
+                path: spec.path,
+            });
+            if (result &&
+                (typeof result === 'object' || typeof result === 'function') &&
+                'then' in result &&
+                typeof result.then === 'function') {
+                void Promise.resolve(result).catch(() => { });
+            }
+        }
+        catch {
+            // Lock observers must not affect acquisition or release.
+        }
+    };
+    const options = { ...defaults, ...definedOnly(spec) };
+    const started = performance.now();
+    for (;;) {
+        const lock = await acquireRefreshFileLock({
+            name: spec.name,
+            path: spec.path,
+            ttlMs: options.ttlMs,
+            now: env.now,
+            renew: options.renew,
+            onContended: () => emit('contended'),
+            ...(options.renewIntervalMs !== undefined
+                ? { renewIntervalMs: options.renewIntervalMs }
+                : {}),
+            ...(env.onLockStep
+                ? {
+                    onStep: (step) => env.onLockStep?.({ name: spec.name, path: spec.path }, step),
+                }
+                : {}),
+        });
+        if (lock) {
+            emit('acquired');
+            const held = {
+                name: spec.name,
+                path: spec.path,
+                assertOwned: () => lock.assertOwned(),
+                release: async () => {
+                    await lock.release();
+                    emit('released');
+                },
+            };
+            try {
+                await held.assertOwned();
+            }
+            catch (error) {
+                await held.release();
+                throw error;
+            }
+            return held;
+        }
+        const remaining = options.timeoutMs - (performance.now() - started);
+        if (remaining <= 0) {
+            throw new LockContentionError({
+                target: spec.path,
+                name: spec.name,
+                timeoutMs: options.timeoutMs,
+            });
+        }
+        const jitter = Math.floor(Math.random() * (options.retryMs + 1));
+        await new Promise((resolve) => setTimeout(resolve, Math.min(options.retryMs + jitter, remaining)));
+    }
+}
+function definedOnly(spec) {
+    const out = {};
+    if (spec.ttlMs !== undefined)
+        out.ttlMs = spec.ttlMs;
+    if (spec.timeoutMs !== undefined)
+        out.timeoutMs = spec.timeoutMs;
+    if (spec.retryMs !== undefined)
+        out.retryMs = spec.retryMs;
+    if (spec.renew !== undefined)
+        out.renew = spec.renew;
+    if (spec.renewIntervalMs !== undefined)
+        out.renewIntervalMs = spec.renewIntervalMs;
+    return out;
+}
+/**
+ * Locks taken in order and released in reverse. Every acquisition re-asserts
+ * the leases already held, because a wait is exactly when an earlier lease
+ * can expire unnoticed.
+ */
+export class LockStack {
+    defaults;
+    env;
+    held = [];
+    constructor(defaults, env) {
+        this.defaults = defaults;
+        this.env = env;
+    }
+    async acquire(spec) {
+        const lock = await acquirePoolLock(spec, this.defaults, this.env);
+        this.held.push(lock);
+        await this.assertAll();
+        return lock;
+    }
+    async assertAll() {
+        for (const lock of this.held)
+            await lock.assertOwned();
+    }
+    /** Releases every lock taken after `mark` (a length of `held`), newest first. */
+    async releaseTo(mark) {
+        while (this.held.length > mark) {
+            const lock = this.held.pop();
+            await lock?.release().catch(() => { });
+        }
+    }
+    async releaseAll() {
+        await this.releaseTo(0);
+    }
+}

package/dist/common-auth-embedded/store/refresh.d.ts

@@ -0,0 +1,72 @@
+import type { PoolLockSpec } from './refresh-lock.js';
+import { type FailureHook } from './rows.js';
+import { type StoreRuntime } from './runtime.js';
+import { type OAuthCredential, type PoolRow, type StoredCredential } from './schema.js';
+/** What the injected provider refresh function returns. */
+export interface ProviderRefreshResult {
+    access: string;
+    refresh: string;
+    expires: number;
+    expiresIn?: number;
+    /** The account's wire identity, when the provider reports one. */
+    identity?: string;
+    /**
+     * Provider state that changes with the new token (needs the store's
+     * provider-state codec). It is merged with the row's value on disk
+     * (`ProviderStateCodec.merge`) and written in the same state write as the
+     * rotated credential, under the same commit fence. Left out, the row keeps
+     * its value.
+     */
+    providerState?: unknown;
+}
+export type ProviderRefresh = (credential: OAuthCredential & {
+    lastRefreshedAt?: number;
+}, row: PoolRow) => Promise<ProviderRefreshResult>;
+export interface RefreshOptions {
+    /** The one provider-wide lock serialising every provider call. */
+    providerLock?: PoolLockSpec;
+    /** Taken after the provider-wide lock in this order, released in reverse. */
+    extraLocks?: readonly PoolLockSpec[];
+    /**
+     * Awaited once an ordinary rotation is persisted and the store locks released.
+     * Never called for `identity-contradicted`: its credential must not propagate
+     * as the row's recorded account.
+     */
+    onPersisted?: (rowId: string, credential: StoredCredential) => void | Promise<void>;
+    onFailure?: FailureHook;
+    /**
+     * Awaited before any lock is taken, on the locked re-read, and at commit
+     * time under the store locks; a reason refuses the refresh there, leaving
+     * the stored credential untouched and discarding any rotated material.
+     */
+    refuse?: (row: PoolRow) => string | undefined | Promise<string | undefined>;
+}
+export type RefreshOutcome = {
+    status: 'rotated';
+    rowId: string;
+    credential: StoredCredential;
+    identity?: string;
+}
+/**
+ * The provider's successor credential is stored bound to expectedIdentity,
+ * not returnedIdentity. The row stays disabled until the adapter supplies
+ * an identity-validated replacement credential through replace.
+ */
+ | {
+    status: 'identity-contradicted';
+    rowId: string;
+    expectedIdentity: string;
+    returnedIdentity: string;
+    credential: StoredCredential;
+} | {
+    status: 'refused';
+    rowId: string;
+    reason: string;
+};
+/**
+ * Refreshes one OAuth row. Locks are taken in the fixed order row lock,
+ * provider-wide lock, extra locks, and the store locks only around the
+ * capture and the commit; ownership of every held lease is asserted after
+ * each wait, immediately before the provider call and before each write.
+ */
+export declare function refreshRow(rt: StoreRuntime, id: string, provider: ProviderRefresh, options?: RefreshOptions): Promise<RefreshOutcome>;

package/dist/common-auth-embedded/store/refresh.js

@@ -0,0 +1,225 @@
+import { randomUUID } from 'node:crypto';
+import { PoolOperationError } from './errors.js';
+import { assertNotInsideHook, runInsideHook } from './hooks.js';
+import { IDENTITY_CONTRADICTED_REASON_PREFIX, recordIdentityIn, } from './identity.js';
+import { runOperation, withTransaction } from './mutate.js';
+import { acceptProviderState, mergedProviderState } from './provider-state.js';
+import { assertNotReserved } from './reserved.js';
+import { rotateIn } from './rows.js';
+import { readRow, refusal, requireBound, rowLockSpec, } from './runtime.js';
+import { rotationStamp, rotationStampUntrusted, rowLockKey, } from './schema.js';
+import { applyTransition } from './torn.js';
+function requireRefreshable(id, row) {
+    assertNotReserved('refresh', id, row?.staged);
+    if (!row)
+        throw refusal('refresh', id, 'unknown-row', `no row ${id} in the pool`);
+    if (row.invalid)
+        throw refusal('refresh', id, 'invalid-row', `row ${id} is invalid`);
+    if (row.type !== 'oauth' || row.credential?.type !== 'oauth')
+        throw refusal('refresh', id, 'no-credential', `row ${id} holds no OAuth credential`);
+    if (!row.enabled)
+        throw refusal('refresh', id, 'row-disabled', `row ${id} is disabled`);
+    return row;
+}
+function stampAhead(id) {
+    return refusal('refresh', id, 'refresh-stamp-ahead', `row ${id}'s stored refresh stamp is ahead of the clock; a rotation now could not be stamped newer within the trust bound`, true);
+}
+/**
+ * Refreshes one OAuth row. Locks are taken in the fixed order row lock,
+ * provider-wide lock, extra locks, and the store locks only around the
+ * capture and the commit; ownership of every held lease is asserted after
+ * each wait, immediately before the provider call and before each write.
+ */
+export async function refreshRow(rt, id, provider, options = {}) {
+    assertNotInsideHook('refresh');
+    const { ctx } = rt;
+    return runOperation(ctx, 'refresh', id, options.onFailure, async (locks, progress) => {
+        const { row: seen } = await readRow(rt, 'refresh', id);
+        requireRefreshable(id, seen);
+        const early = await options.refuse?.(seen);
+        if (early !== undefined)
+            return { status: 'refused', rowId: id, reason: early };
+        let key = rowLockKey(seen);
+        let captured;
+        for (let attempt = 0;; attempt++) {
+            await locks.acquire(rowLockSpec(rt, { id, identity: key === id ? undefined : key }));
+            await locks.acquire(options.providerLock ?? rt.providerLock);
+            for (const extra of options.extraLocks ?? [])
+                await locks.acquire(extra);
+            // The capture may write the config once, to give a row its per-row
+            // entry. That write is setup, not the rotation, so it is counted apart
+            // and never makes a later failure report `after-first-write`.
+            const captureProgress = { writes: 0 };
+            const read = await withTransaction(ctx, locks, captureProgress, { operation: 'refresh', rowId: id }, async (tx) => {
+                let row = requireRefreshable(id, tx.row(id));
+                requireBound('refresh', row);
+                if (!row.hasEntry) {
+                    tx.setEntry(id, { credentialEpoch: 1, needsFirstReading: true });
+                    await tx.commitConfig();
+                    row = requireRefreshable(id, tx.row(id));
+                }
+                if (rowLockKey(row) !== key)
+                    return { keyNow: rowLockKey(row) };
+                const reason = await options.refuse?.(row);
+                if (reason !== undefined)
+                    return { refused: reason };
+                return {
+                    row,
+                    credential: row.credential,
+                    credentialEpoch: row.credentialEpoch,
+                    identity: row.identity,
+                };
+            });
+            if ('refused' in read)
+                return { status: 'refused', rowId: id, reason: read.refused };
+            if ('keyNow' in read) {
+                await locks.releaseAll();
+                if (attempt >= 1)
+                    throw refusal('refresh', id, 'row-key-changed', `row ${id}'s wire identity changed twice while its lock was held`, true);
+                key = read.keyNow;
+                continue;
+            }
+            captured = read;
+            break;
+        }
+        if (rotationStampUntrusted(captured.credential.lastRefreshedAt, ctx.now()))
+            throw stampAhead(id);
+        await ctx.hold?.('refresh-before-provider', id);
+        await locks.assertAll();
+        let result;
+        try {
+            result = await provider(captured.credential, captured.row);
+        }
+        catch (cause) {
+            throw new PoolOperationError({
+                operation: 'refresh',
+                rowId: id,
+                phase: 'before-first-write',
+                retryable: true,
+                kind: 'provider',
+                message: 'the provider refresh failed',
+                cause,
+            });
+        }
+        if (typeof result?.refresh !== 'string' || !result.refresh.trim())
+            throw refusal('refresh', id, 'provider', 'the provider returned no refresh token', true);
+        const incoming = result.providerState === undefined
+            ? undefined
+            : acceptProviderState(ctx.providerState, 'refresh', id, result.providerState, 'the provider state the provider returned');
+        const commit = await withTransaction(ctx, locks, progress, { operation: 'refresh', rowId: id }, async (tx) => {
+            const current = tx.row(id);
+            const entry = tx.entry(id);
+            if (!current ||
+                current.invalid ||
+                !entry ||
+                entry.credentialEpoch !== captured.credentialEpoch ||
+                current.identity !== captured.identity)
+                throw new PoolOperationError({
+                    operation: 'refresh',
+                    rowId: id,
+                    phase: 'before-first-write',
+                    retryable: true,
+                    kind: 'attribution',
+                    message: `row ${id} changed credential while its refresh was in flight; the rotation is discarded`,
+                });
+            // The epoch fence above does not see a credential another writer
+            // swapped in under the same epoch; the stamp does, and committing
+            // the rotation would stamp the swapped row as bound.
+            requireBound('refresh', current);
+            const reason = await options.refuse?.(current);
+            if (reason !== undefined)
+                return { refused: reason };
+            const now = ctx.now();
+            const prior = current.credential?.type === 'oauth'
+                ? current.credential.lastRefreshedAt
+                : undefined;
+            if (rotationStampUntrusted(prior, now))
+                throw stampAhead(id);
+            const credential = {
+                type: 'oauth',
+                access: result.access,
+                refresh: result.refresh,
+                expires: result.expires,
+            };
+            const contradiction = current.identity !== undefined &&
+                result.identity !== undefined &&
+                current.identity !== result.identity
+                ? {
+                    expectedIdentity: current.identity,
+                    returnedIdentity: result.identity,
+                }
+                : undefined;
+            const transition = contradiction
+                ? {
+                    mark: randomUUID(),
+                    enabled: false,
+                    reason: `${IDENTITY_CONTRADICTED_REASON_PREFIX}${JSON.stringify(contradiction)}`,
+                }
+                : undefined;
+            const learnt = current.identity === undefined && result.identity
+                ? result.identity
+                : undefined;
+            // The rotated credential's stamp names a learnt identity before the
+            // config records it, so a crash between the two writes is completed
+            // forward rather than leaving an identity no stamp proves.
+            const stored = await rotateIn(rt, tx, id, credential, {
+                stamp: rotationStamp(prior, now),
+                // Write state first with the disable marker, then config below.
+                // Once the successor is durable, recovery projects the disable even
+                // if config has not landed. A crash before the first rename still
+                // loses an in-memory provider reply, as in any ordinary refresh.
+                transition,
+                identity: learnt,
+                ...(incoming !== undefined
+                    ? {
+                        providerState: mergedProviderState(ctx.providerState, 'refresh', id, current.providerState, incoming),
+                    }
+                    : {}),
+            });
+            if (transition !== undefined) {
+                applyTransition(tx, id, transition);
+                await tx.commitConfig();
+            }
+            let identity = current.identity;
+            if (learnt !== undefined) {
+                recordIdentityIn(tx, id, learnt);
+                identity = learnt;
+                await tx.commitConfig();
+            }
+            return { stored, identity, contradiction, refused: undefined };
+        });
+        if (commit.refused !== undefined)
+            return { status: 'refused', rowId: id, reason: commit.refused };
+        if (commit.contradiction !== undefined)
+            return {
+                status: 'identity-contradicted',
+                rowId: id,
+                ...commit.contradiction,
+                credential: commit.stored,
+            };
+        if (options.onPersisted) {
+            try {
+                const persisted = options.onPersisted;
+                await runInsideHook('refresh', () => persisted(id, commit.stored));
+            }
+            catch (cause) {
+                throw new PoolOperationError({
+                    operation: 'refresh',
+                    rowId: id,
+                    phase: 'after-first-write',
+                    retryable: false,
+                    kind: 'after-persist-hook',
+                    committed: commit.stored,
+                    message: 'the after-persist hook threw; the rotation stays committed',
+                    cause,
+                });
+            }
+        }
+        return {
+            status: 'rotated',
+            rowId: id,
+            credential: commit.stored,
+            ...(commit.identity !== undefined ? { identity: commit.identity } : {}),
+        };
+    });
+}

package/dist/common-auth-embedded/store/reserved.js

@@ -0,0 +1,13 @@
+import { PoolOperationError } from './errors.js';
+/** A stored marker reserves the row even when the rest of its entry is invalid. */
+export function assertNotReserved(operation, id, reservation) {
+    if (reservation !== undefined)
+        throw new PoolOperationError({
+            operation,
+            rowId: id,
+            kind: 'row-staged',
+            phase: operation === 'pull' ? 'pull' : 'before-first-write',
+            retryable: false,
+            message: `row ${id} is reserved for roster publication`,
+        });
+}