@cortexkit/common-auth 0.1.2 → 0.2.0

package/dist/store/pull.js

@@ -0,0 +1,129 @@
+import { recordQuota } from './attribution.js';
+import { PoolOperationError } from './errors.js';
+import { toFailure, withTransaction } from './mutate.js';
+import { LockStack } from './refresh-lock.js';
+/**
+ * Fires quota pulls without ever making a caller wait for one. A pull first
+ * gives a row without a per-row entry its entry at epoch 1 (its own locked
+ * config write), then captures the credential and the attribution tuple in
+ * one locked read, requests the observation, and records it only if
+ * attribution still holds. Failures go to the store's pull failure hook.
+ */
+export class PullScheduler {
+    rt;
+    hook;
+    onFailure;
+    firedAtLoad;
+    logger;
+    inflight = new Set();
+    constructor(rt, hook, onFailure, 
+    /** Rows a load-time pull has fired for in this process. */
+    firedAtLoad, logger) {
+        this.rt = rt;
+        this.hook = hook;
+        this.onFailure = onFailure;
+        this.firedAtLoad = firedAtLoad;
+        this.logger = logger;
+    }
+    fire(id, reason) {
+        if (!this.hook)
+            return;
+        if (reason === 'load') {
+            if (this.firedAtLoad.has(id))
+                return;
+            this.firedAtLoad.add(id);
+        }
+        const run = this.run(id, reason);
+        this.inflight.add(run);
+        void run.finally(() => this.inflight.delete(run));
+    }
+    /** Resolves once every pull fired so far has settled. */
+    async settled() {
+        while (this.inflight.size > 0)
+            await Promise.allSettled([...this.inflight]);
+    }
+    async run(id, reason) {
+        const rt = this.rt();
+        const { ctx } = rt;
+        const locks = new LockStack(ctx.lockDefaults, ctx.lockEnv);
+        const progress = { writes: 0 };
+        try {
+            const request = await withTransaction(ctx, locks, progress, { operation: 'pull', rowId: id }, async (tx) => {
+                const row = tx.row(id);
+                // Disabled, API-key and credential-less rows never pull.
+                if (!row?.candidate || row.type !== 'oauth')
+                    return undefined;
+                if (!row.hasEntry) {
+                    tx.setEntry(id, { credentialEpoch: 1, needsFirstReading: true });
+                    await tx.commitConfig();
+                }
+                const current = tx.row(id);
+                if (!current?.credential || current.credentialEpoch === undefined)
+                    return undefined;
+                return {
+                    id,
+                    credential: current.credential,
+                    credentialEpoch: current.credentialEpoch,
+                    ...(current.identity !== undefined
+                        ? { identity: current.identity }
+                        : {}),
+                    reason,
+                };
+            });
+            await locks.releaseAll();
+            if (!request) {
+                this.firedAtLoad.delete(id);
+                return;
+            }
+            await ctx.hold?.('pull-before-request', id);
+            let observation;
+            try {
+                observation = await this.hook?.(request);
+            }
+            catch (cause) {
+                throw new PoolOperationError({
+                    operation: 'pull',
+                    rowId: id,
+                    phase: 'pull',
+                    retryable: true,
+                    kind: 'pull',
+                    message: 'the quota pull rejected',
+                    cause,
+                });
+            }
+            await recordQuota(rt, id, {
+                credentialEpoch: request.credentialEpoch,
+                ...(request.identity !== undefined
+                    ? { identity: request.identity }
+                    : {}),
+            }, observation);
+        }
+        catch (error) {
+            // Needs-first-reading stays set; a later load may fire again.
+            this.firedAtLoad.delete(id);
+            const failure = toFailure(error, 'pull', id, progress);
+            if (this.onFailure) {
+                try {
+                    await this.onFailure(id, failure);
+                }
+                catch (hookError) {
+                    this.logger?.warn('pull failure hook threw', {
+                        rowId: id,
+                        error: hookError instanceof Error
+                            ? hookError.message
+                            : String(hookError),
+                    });
+                }
+            }
+            else {
+                this.logger?.warn('quota pull failed', {
+                    rowId: id,
+                    kind: failure.kind,
+                });
+            }
+        }
+        finally {
+            await locks.releaseAll();
+        }
+    }
+}

package/dist/store/refresh-lock.d.ts

@@ -0,0 +1,63 @@
+import { acquireRefreshFileLock } from '../fs/refresh-file-lock.js';
+type LockStep = NonNullable<Parameters<typeof acquireRefreshFileLock>[0]['onStep']> extends (step: infer S) => unknown ? S : never;
+/** Tuning shared by every lock the store takes; each field is overridable. */
+export interface PoolLockOptions {
+    ttlMs: number;
+    timeoutMs: number;
+    retryMs: number;
+    renew: boolean;
+    renewIntervalMs?: number;
+}
+/** A lock: the (name, path) pair naming its file plus optional tuning. */
+export interface PoolLockSpec extends Partial<PoolLockOptions> {
+    name: string;
+    path: string;
+}
+/**
+ * Store lock defaults: a 15 000 ms bounded wait retried every 50 ms plus
+ * jitter, and a renewed 10 000 ms lease.
+ */
+export declare const POOL_LOCK_DEFAULTS: Readonly<PoolLockOptions>;
+export type LockEvent = {
+    type: 'acquired' | 'released';
+    name: string;
+    path: string;
+};
+export interface LockEnvironment {
+    now: () => number;
+    onLockEvent?: (event: LockEvent) => void;
+    onLockStep?: (lock: {
+        name: string;
+        path: string;
+    }, step: LockStep) => void | Promise<void>;
+}
+export interface HeldLock {
+    readonly name: string;
+    readonly path: string;
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+}
+/**
+ * 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 declare function acquirePoolLock(spec: PoolLockSpec, defaults: PoolLockOptions, env: LockEnvironment): Promise<HeldLock>;
+/**
+ * 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 declare class LockStack {
+    private readonly defaults;
+    private readonly env;
+    readonly held: HeldLock[];
+    constructor(defaults: PoolLockOptions, env: LockEnvironment);
+    acquire(spec: PoolLockSpec): Promise<HeldLock>;
+    assertAll(): Promise<void>;
+    /** Releases every lock taken after `mark` (a length of `held`), newest first. */
+    releaseTo(mark: number): Promise<void>;
+    releaseAll(): Promise<void>;
+}
+export {};

package/dist/store/refresh-lock.js

@@ -0,0 +1,125 @@
+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 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,
+            ...(options.renewIntervalMs !== undefined
+                ? { renewIntervalMs: options.renewIntervalMs }
+                : {}),
+            ...(env.onLockStep
+                ? {
+                    onStep: (step) => env.onLockStep?.({ name: spec.name, path: spec.path }, step),
+                }
+                : {}),
+        });
+        if (lock) {
+            env.onLockEvent?.({
+                type: 'acquired',
+                name: spec.name,
+                path: spec.path,
+            });
+            const held = {
+                name: spec.name,
+                path: spec.path,
+                assertOwned: () => lock.assertOwned(),
+                release: async () => {
+                    await lock.release();
+                    env.onLockEvent?.({
+                        type: 'released',
+                        name: spec.name,
+                        path: spec.path,
+                    });
+                },
+            };
+            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/store/refresh.d.ts

@@ -0,0 +1,48 @@
+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;
+}
+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 the rotation is persisted and the store locks released. */
+    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;
+} | {
+    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/store/refresh.js

@@ -0,0 +1,169 @@
+import { PoolOperationError } from './errors.js';
+import { assertNotInsideHook, runInsideHook } from './hooks.js';
+import { recordIdentityIn } from './identity.js';
+import { runOperation, withTransaction } from './mutate.js';
+import { rotateIn } from './rows.js';
+import { readRow, refusal, rowLockSpec } from './runtime.js';
+import { rotationStamp, rotationStampUntrusted, rowLockKey, } from './schema.js';
+function requireRefreshable(id, row) {
+    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));
+                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 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`,
+                });
+            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 stored = await rotateIn(rt, tx, id, credential, {
+                stamp: rotationStamp(prior, now),
+            });
+            let identity = current.identity;
+            if (current.identity === undefined && result.identity) {
+                recordIdentityIn(tx, id, result.identity);
+                identity = result.identity;
+                await tx.commitConfig();
+            }
+            return { stored, identity, refused: undefined };
+        });
+        if (commit.refused !== undefined)
+            return { status: 'refused', rowId: id, reason: commit.refused };
+        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/store/rows.d.ts

@@ -0,0 +1,53 @@
+import type { PoolOperationError } from './errors.js';
+import { type Transaction } from './mutate.js';
+import type { PoolLockSpec } from './refresh-lock.js';
+import { type StoreRuntime } from './runtime.js';
+import { type PoolCredential, type StoredCredential } from './schema.js';
+export type FailureHook = (rowId: string, error: PoolOperationError) => void | Promise<void>;
+export interface RowOperationOptions {
+    /** Called once, awaited, on every non-success path, before locks release. */
+    onFailure?: FailureHook;
+    /** The provider-wide lock, when an operation may change identity keying. */
+    providerLock?: PoolLockSpec;
+}
+export interface AddInput {
+    id: string;
+    credential: PoolCredential;
+    identity?: string;
+    label?: string;
+}
+export type AddResult = {
+    /** The row holding the credential; an existing row's id on a re-add. */
+    id: string;
+    outcome: 'added' | 'added-disabled' | 'completed' | 'rotated';
+    credential: StoredCredential;
+};
+/**
+ * Writes a rotated credential into the state file (one write). A rotation is
+ * the same lineage: no epoch bump, no identity or quota change.
+ */
+export declare function rotateIn(rt: StoreRuntime, tx: Transaction, id: string, credential: PoolCredential, extra?: {
+    stamp?: number;
+    clearErrors?: boolean;
+}): Promise<StoredCredential>;
+export declare function addRow(rt: StoreRuntime, input: AddInput, options?: RowOperationOptions): Promise<AddResult>;
+export declare function replaceRow(rt: StoreRuntime, id: string, credential: PoolCredential, input?: {
+    identity?: string;
+}, options?: RowOperationOptions): Promise<{
+    id: string;
+    credential: StoredCredential;
+    credentialEpoch: number;
+}>;
+export declare function rotateRow(rt: StoreRuntime, id: string, credential: PoolCredential, input?: {
+    identity?: string;
+}, options?: RowOperationOptions): Promise<{
+    id: string;
+    credential: StoredCredential;
+}>;
+export declare function disableRow(rt: StoreRuntime, id: string, reason: string, options?: Pick<RowOperationOptions, 'onFailure'>): Promise<{
+    id: string;
+}>;
+export declare function recordRowIdentity(rt: StoreRuntime, id: string, identity: string, options?: RowOperationOptions): Promise<{
+    id: string;
+    disabled: string[];
+}>;