@cortexkit/common-auth 0.1.3 → 0.2.1

package/dist/store/rows.js

@@ -0,0 +1,250 @@
+import { assertNotInsideHook } from './hooks.js';
+import { DUPLICATE_IDENTITY_REASON, disableIdentityDuplicates, disableIn, recordIdentityIn, } from './identity.js';
+import { runOperation, withTransaction } from './mutate.js';
+import { readRow, refusal, rowLockSpec, unknownRow, } from './runtime.js';
+import { credentialProblem, fingerprintOf, idProblem, isRecord, rosterRowFor, rotationStamp, rowLockKey, stateFieldsFor, storedCredential, } from './schema.js';
+/** Fields of a state entry that belong to the credential it replaces. */
+const CREDENTIAL_STATE_FIELDS = [
+    'access',
+    'refresh',
+    'expires',
+    'lastRefreshedAt',
+    'apiKey',
+];
+/**
+ * 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 async function rotateIn(rt, tx, id, credential, extra = {}) {
+    const prior = tx.stateAccount(id);
+    const priorStamp = typeof prior?.lastRefreshedAt === 'number'
+        ? prior.lastRefreshedAt
+        : undefined;
+    const stamp = credential.type === 'oauth'
+        ? (extra.stamp ?? rotationStamp(priorStamp, rt.ctx.now()))
+        : undefined;
+    const kept = { ...(prior ?? {}) };
+    for (const field of CREDENTIAL_STATE_FIELDS)
+        delete kept[field];
+    if (extra.clearErrors) {
+        delete kept.lastRefreshError;
+        delete kept.lastQuotaRefreshError;
+        delete kept.quota;
+    }
+    const raw = tx.rosterRow(id);
+    const stored = credential.type === 'api' && isRecord(raw)
+        ? storedCredential({
+            ...credential,
+            baseURL: String(raw.baseURL ?? credential.baseURL),
+            ...(raw.authHeader === 'x-api-key' ||
+                raw.authHeader === 'authorization-bearer'
+                ? { authHeader: raw.authHeader }
+                : {}),
+        }, stamp)
+        : storedCredential(credential, stamp);
+    tx.setStateAccount(id, { ...kept, ...stateFieldsFor(credential, stamp) });
+    await tx.commitState(stored);
+    return stored;
+}
+function checkInput(operation, id, credential) {
+    const idIssue = operation === 'add' ? idProblem(id) : undefined;
+    if (idIssue)
+        throw refusal(operation, id, 'invalid-input', idIssue);
+    const credentialIssue = credentialProblem(credential);
+    if (credentialIssue)
+        throw refusal(operation, id, 'invalid-input', credentialIssue);
+}
+function requireUsableRow(operation, id, row, credential) {
+    if (!row)
+        throw unknownRow(operation, id);
+    if (row.invalid)
+        throw refusal(operation, id, 'invalid-row', `row ${id} failed validation`);
+    if (credential && credential.type !== row.type)
+        throw refusal(operation, id, 'type-mismatch', `row ${id} holds a ${row.type} credential`);
+    return row;
+}
+/** Keying changed between the unlocked read and the locked one: retry. */
+function keyChanged(operation, id) {
+    return refusal(operation, id, 'row-key-changed', `row ${id}'s wire identity changed while its lock was being taken`, true);
+}
+export async function addRow(rt, input, options = {}) {
+    assertNotInsideHook('add');
+    const { ctx } = rt;
+    const { id, credential, identity, label } = input;
+    const result = await runOperation(ctx, 'add', id, options.onFailure, async (locks, progress) => {
+        checkInput('add', id, credential);
+        if (ctx.removedIds.has(id))
+            throw refusal('add', id, 'id-removed', `id ${id} was removed from the roster in this process and is not reused`);
+        await locks.acquire(rowLockSpec(rt, { id, identity }));
+        if (credential.type === 'oauth')
+            await locks.acquire(options.providerLock ?? rt.providerLock);
+        return withTransaction(ctx, locks, progress, { operation: 'add', rowId: id }, async (tx) => {
+            const rows = tx.rows();
+            const fingerprint = fingerprintOf(credential);
+            const same = rows.find((row) => row.invalid === undefined && row.fingerprint === fingerprint);
+            if (same) {
+                const stored = await rotateIn(rt, tx, same.id, credential);
+                return { id: same.id, outcome: 'rotated', credential: stored };
+            }
+            const existing = rows.find((row) => row.id === id);
+            if (existing) {
+                if (existing.invalid)
+                    throw refusal('add', id, 'invalid-row', `row ${id} is invalid`);
+                if (existing.credential)
+                    throw refusal('add', id, 'id-exists', `row ${id} already holds a credential`);
+                if (existing.type !== credential.type)
+                    throw refusal('add', id, 'type-mismatch', `row ${id} is a ${existing.type} row`);
+                // An earlier add wrote this row's config and stopped before the
+                // state write; writing the credential now completes it at epoch 1.
+                if (!existing.hasEntry) {
+                    tx.setEntry(id, {
+                        credentialEpoch: 1,
+                        needsFirstReading: credential.type === 'oauth',
+                    });
+                    await tx.commitConfig();
+                }
+                const stored = await rotateIn(rt, tx, id, credential, {
+                    clearErrors: true,
+                });
+                return { id, outcome: 'completed', credential: stored };
+            }
+            tx.roster().push(rosterRowFor({
+                id,
+                credential,
+                ...(identity !== undefined ? { identity } : {}),
+                ...(label !== undefined ? { label } : {}),
+                addedAt: ctx.now(),
+            }));
+            tx.setEntry(id, {
+                credentialEpoch: 1,
+                needsFirstReading: credential.type === 'oauth',
+            });
+            let outcome = 'added';
+            if (identity !== undefined && credential.type === 'oauth') {
+                // Same account, different credential: kept on disk, disabled.
+                const holder = rows.find((row) => row.invalid === undefined &&
+                    row.type === 'oauth' &&
+                    row.enabled &&
+                    row.identity === identity);
+                if (holder) {
+                    disableIn(tx, id, DUPLICATE_IDENTITY_REASON);
+                    outcome = 'added-disabled';
+                }
+            }
+            await tx.commitConfig();
+            const stored = await rotateIn(rt, tx, id, credential);
+            return { id, outcome, credential: stored };
+        });
+    });
+    if (credential.type === 'oauth' &&
+        (result.outcome === 'added' || result.outcome === 'completed'))
+        rt.firePull(result.id, 'add');
+    return result;
+}
+export async function replaceRow(rt, id, credential, input = {}, options = {}) {
+    assertNotInsideHook('replace');
+    const { ctx } = rt;
+    const result = await runOperation(ctx, 'replace', id, options.onFailure, async (locks, progress) => {
+        checkInput('replace', id, credential);
+        const { row: seen } = await readRow(rt, 'replace', id);
+        await locks.acquire(rowLockSpec(rt, seen));
+        if (credential.type === 'oauth')
+            await locks.acquire(options.providerLock ?? rt.providerLock);
+        return withTransaction(ctx, locks, progress, { operation: 'replace', rowId: id }, async (tx) => {
+            const row = requireUsableRow('replace', id, tx.row(id), credential);
+            if (rowLockKey(row) !== rowLockKey(seen))
+                throw keyChanged('replace', id);
+            const entry = tx.entry(id) ?? {};
+            const priorEpoch = typeof entry.credentialEpoch === 'number'
+                ? entry.credentialEpoch
+                : 1;
+            const credentialEpoch = priorEpoch + 1;
+            const nextEntry = {
+                ...entry,
+                credentialEpoch,
+                needsFirstReading: true,
+            };
+            delete nextEntry.quota;
+            tx.setEntry(id, nextEntry);
+            const raw = tx.rosterRow(id);
+            if (input.identity !== undefined)
+                raw.accountId = input.identity;
+            else
+                delete raw.accountId;
+            if (credential.type === 'api') {
+                raw.baseURL = credential.baseURL.trim();
+                raw.authHeader = credential.authHeader ?? 'authorization-bearer';
+            }
+            if (input.identity !== undefined)
+                disableIdentityDuplicates(tx, input.identity);
+            await tx.commitConfig();
+            const stored = await rotateIn(rt, tx, id, credential, {
+                clearErrors: true,
+            });
+            return { id, credential: stored, credentialEpoch };
+        });
+    });
+    if (credential.type === 'oauth')
+        rt.firePull(id, 'replace');
+    return result;
+}
+export async function rotateRow(rt, id, credential, input = {}, options = {}) {
+    assertNotInsideHook('rotate');
+    const { ctx } = rt;
+    return runOperation(ctx, 'rotate', id, options.onFailure, async (locks, progress) => {
+        checkInput('rotate', id, credential);
+        const { row: seen } = await readRow(rt, 'rotate', id);
+        await locks.acquire(rowLockSpec(rt, seen));
+        if (input.identity !== undefined && credential.type === 'oauth')
+            await locks.acquire(options.providerLock ?? rt.providerLock);
+        return withTransaction(ctx, locks, progress, { operation: 'rotate', rowId: id }, async (tx) => {
+            const row = requireUsableRow('rotate', id, tx.row(id), credential);
+            if (rowLockKey(row) !== rowLockKey(seen))
+                throw keyChanged('rotate', id);
+            const stored = await rotateIn(rt, tx, id, credential);
+            let configChanged = false;
+            if (!row.hasEntry) {
+                tx.setEntry(id, {
+                    credentialEpoch: 1,
+                    needsFirstReading: row.type === 'oauth',
+                });
+                configChanged = true;
+            }
+            if (input.identity !== undefined && row.identity !== input.identity) {
+                recordIdentityIn(tx, id, input.identity);
+                configChanged = true;
+            }
+            if (configChanged)
+                await tx.commitConfig();
+            return { id, credential: stored };
+        });
+    });
+}
+export async function disableRow(rt, id, reason, options = {}) {
+    assertNotInsideHook('disable');
+    return runOperation(rt.ctx, 'disable', id, options.onFailure, async (locks, progress) => withTransaction(rt.ctx, locks, progress, { operation: 'disable', rowId: id }, async (tx) => {
+        if (!tx.rosterRow(id))
+            throw unknownRow('disable', id);
+        disableIn(tx, id, reason);
+        await tx.commitConfig();
+        return { id };
+    }));
+}
+export async function recordRowIdentity(rt, id, identity, options = {}) {
+    assertNotInsideHook('recordIdentity');
+    return runOperation(rt.ctx, 'recordIdentity', id, options.onFailure, async (locks, progress) => {
+        if (typeof identity !== 'string' || identity.length === 0)
+            throw refusal('recordIdentity', id, 'invalid-input', 'identity must be non-empty');
+        const { row: seen } = await readRow(rt, 'recordIdentity', id);
+        await locks.acquire(rowLockSpec(rt, seen));
+        await locks.acquire(options.providerLock ?? rt.providerLock);
+        return withTransaction(rt.ctx, locks, progress, { operation: 'recordIdentity', rowId: id }, async (tx) => {
+            const row = requireUsableRow('recordIdentity', id, tx.row(id));
+            if (rowLockKey(row) !== rowLockKey(seen))
+                throw keyChanged('recordIdentity', id);
+            const disabled = recordIdentityIn(tx, id, identity);
+            await tx.commitConfig();
+            return { id, disabled };
+        });
+    });
+}

package/dist/store/runtime.d.ts

@@ -0,0 +1,28 @@
+import { type PoolOperation, PoolOperationError } from './errors.js';
+import { type ReadResult, type StoreContext } from './mutate.js';
+import type { PoolLockOptions, PoolLockSpec } from './refresh-lock.js';
+import { type PoolRow } from './schema.js';
+/** Where a pull was fired from; `load` fires at most once per process per row. */
+export type PullReason = 'load' | 'add' | 'replace' | 'admission';
+/** What every operation module shares. */
+export interface StoreRuntime {
+    ctx: StoreContext;
+    providerLock: PoolLockSpec;
+    rowLockOptions: Partial<PoolLockOptions>;
+    firePull(id: string, reason: PullReason): void;
+}
+/**
+ * The row lock's (name, path): keyed by the row's recorded wire identity when
+ * known, else its local id, beside the state file. The key is prefixed and
+ * URL-encoded so it can never name a store lock or leave the directory.
+ */
+export declare function rowLockSpec(rt: StoreRuntime, row: Pick<PoolRow, 'id' | 'identity'>): PoolLockSpec;
+/** An unlocked read that must find a ready pool holding the row. */
+export declare function readRow(rt: StoreRuntime, operation: PoolOperation, id: string): Promise<{
+    result: Extract<ReadResult, {
+        status: 'ready';
+    }>;
+    row: PoolRow;
+}>;
+export declare function unknownRow(operation: PoolOperation, id: string): PoolOperationError;
+export declare function refusal(operation: PoolOperation, id: string, kind: PoolOperationError['kind'], message: string, retryable?: boolean): PoolOperationError;

package/dist/store/runtime.js

@@ -0,0 +1,45 @@
+import { PoolOperationError } from './errors.js';
+import { notReadyError, readPool, } from './mutate.js';
+import { rowLockKey } from './schema.js';
+/**
+ * The row lock's (name, path): keyed by the row's recorded wire identity when
+ * known, else its local id, beside the state file. The key is prefixed and
+ * URL-encoded so it can never name a store lock or leave the directory.
+ */
+export function rowLockSpec(rt, row) {
+    return {
+        ...rt.rowLockOptions,
+        name: `row-${encodeURIComponent(rowLockKey(row))}`,
+        path: rt.ctx.statePath,
+    };
+}
+/** An unlocked read that must find a ready pool holding the row. */
+export async function readRow(rt, operation, id) {
+    const result = await readPool(rt.ctx);
+    if (result.status !== 'ready')
+        throw notReadyError(result, operation, id);
+    const row = result.rows.find((candidate) => candidate.id === id);
+    if (!row)
+        throw unknownRow(operation, id);
+    return { result, row };
+}
+export function unknownRow(operation, id) {
+    return new PoolOperationError({
+        operation,
+        rowId: id,
+        phase: operation === 'pull' ? 'pull' : 'before-first-write',
+        retryable: false,
+        kind: 'unknown-row',
+        message: `no row ${id} in the pool`,
+    });
+}
+export function refusal(operation, id, kind, message, retryable = false) {
+    return new PoolOperationError({
+        operation,
+        rowId: id,
+        phase: operation === 'pull' ? 'pull' : 'before-first-write',
+        retryable,
+        kind,
+        message,
+    });
+}

package/dist/store/schema.d.ts

@@ -0,0 +1,133 @@
+/** Top-level key of the config file that holds everything the pool adds. */
+export declare const POOL_KEY = "commonAuthPool";
+/** The pool schema this library reads and writes. */
+export declare const POOL_SCHEMA_VERSION = 1;
+/** Property of `commonAuthPool` holding the per-row entries, keyed by local id. */
+export declare const POOL_ROWS_KEY = "rows";
+/** The `version` older readers of the same files expect at the top level. */
+export declare const LEGACY_STORE_VERSION = 1;
+/**
+ * How far ahead of the clock a stored `lastRefreshedAt` may sit and still be
+ * trusted. Older readers of the state file apply the same bound, and a stamp
+ * strictly above it counts as absent when they compare two copies of a token.
+ */
+export declare const REFRESH_STAMP_TOLERANCE_MS: number;
+export type OAuthCredential = {
+    type: 'oauth';
+    access?: string;
+    refresh: string;
+    expires?: number;
+};
+export type ApiKeyCredential = {
+    type: 'api';
+    apiKey: string;
+    baseURL: string;
+    authHeader?: 'authorization-bearer' | 'x-api-key';
+};
+export type PoolCredential = OAuthCredential | ApiKeyCredential;
+/** A credential as stored: an OAuth credential also carries its refresh stamp. */
+export type StoredCredential = (OAuthCredential & {
+    lastRefreshedAt?: number;
+}) | ApiKeyCredential;
+/** Quota codec supplied by `/quota`: the store never interprets the map itself. */
+export interface QuotaCodec {
+    validate(value: unknown): boolean;
+    merge(stored: unknown | undefined, observation: unknown): unknown;
+}
+/** One row of the pool as loaded. */
+export interface PoolRow {
+    id: string;
+    type: 'oauth' | 'api';
+    label?: string;
+    enabled: boolean;
+    addedAt?: number;
+    /** Recorded wire identity (the roster row's `accountId`), when known. */
+    identity?: string;
+    /** Undefined when the state file holds no usable credential for the row. */
+    credential?: StoredCredential;
+    /** Stable hash of the credential's secret material; never persisted. */
+    fingerprint?: string;
+    /** Undefined when the row has no per-row entry yet. */
+    credentialEpoch?: number;
+    needsFirstReading: boolean;
+    disabledReason?: string;
+    /** The opaque quota map, as validated by the codec. */
+    quota?: unknown;
+    hasEntry: boolean;
+    /** A row that may be refreshed, pulled for, or admitted. */
+    candidate: boolean;
+    /** Set when the roster row or the per-row entry failed validation. */
+    invalid?: 'roster' | 'entry';
+}
+export type ConfigClassification = {
+    status: 'ready';
+    exists: boolean;
+    config: Record<string, unknown>;
+} | {
+    status: 'pending-migration';
+    config: Record<string, unknown>;
+} | {
+    status: 'error';
+    reason: string;
+};
+export type StateClassification = {
+    status: 'ready';
+    exists: boolean;
+    state: Record<string, unknown>;
+} | {
+    status: 'error';
+    reason: string;
+};
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Ids are stored exactly as given. Older readers trim ids, so an id with
+ * surrounding whitespace would be renamed by them; such ids, empty ids and
+ * prototype keys are refused instead of being rewritten.
+ */
+export declare function idProblem(id: unknown): string | undefined;
+/** Same URL rule the older readers apply to an API-key row's `baseURL`. */
+export declare function isValidBaseURL(value: unknown): boolean;
+export declare function fingerprintOf(credential: PoolCredential | StoredCredential): string;
+/** A parsed file, or the reason it could not be parsed. */
+export type FileRead = {
+    exists: false;
+} | {
+    exists: true;
+    value: unknown;
+} | {
+    exists: true;
+    parseError: unknown;
+};
+export declare function classifyConfig(read: FileRead): ConfigClassification;
+export declare function classifyState(read: FileRead): StateClassification;
+export declare function rosterOf(config: Record<string, unknown>): unknown[];
+export declare function entriesOf(config: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Builds the rows of a ready pool. A roster row the older readers would
+ * reject, a duplicate id, or a malformed per-row entry makes that one row
+ * invalid (never a candidate) and blocks nothing else.
+ */
+export declare function buildRows(config: Record<string, unknown>, state: Record<string, unknown>, codec: QuotaCodec): PoolRow[];
+/** The row-lock key: recorded wire identity when known, else the local id. */
+export declare function rowLockKey(row: Pick<PoolRow, 'id' | 'identity'>): string;
+/**
+ * The refresh stamp a write persists: the clock, raised to one past a prior
+ * stamp that is still trusted, so a stale copy of the previous token can never
+ * compare newer than the rotation. A prior stamp beyond the trust bound says
+ * nothing and is ignored.
+ */
+export declare function rotationStamp(prior: number | undefined, now: number): number;
+/** True when a rotation stamped now would itself be past the trust bound. */
+export declare function rotationStampUntrusted(prior: number | undefined, now: number): boolean;
+/** The legacy-shaped roster row for a new row. */
+export declare function rosterRowFor(input: {
+    id: string;
+    credential: PoolCredential;
+    identity?: string;
+    label?: string;
+    addedAt: number;
+}): Record<string, unknown>;
+/** The state-file fields a credential occupies, in the older readers' names. */
+export declare function stateFieldsFor(credential: PoolCredential, lastRefreshedAt: number | undefined): Record<string, unknown>;
+export declare function storedCredential(credential: PoolCredential, lastRefreshedAt: number | undefined): StoredCredential;
+export declare function credentialProblem(credential: unknown): string | undefined;