@cortexkit/common-auth 0.1.2 → 0.2.0

package/dist/quota/codec.d.ts

@@ -0,0 +1,11 @@
+export interface QuotaCodec {
+    readonly validate: (value: unknown) => boolean;
+    readonly merge: (stored: unknown, observation: unknown) => unknown;
+}
+/**
+ * The quota codec the account-pool store (the `/store` subpath) takes when it
+ * is opened: `validate` checks a stored per-row quota map and `merge` applies
+ * an observation to one, so the store persists the map without interpreting
+ * it.
+ */
+export declare const quotaCodec: QuotaCodec;

package/dist/quota/codec.js

@@ -0,0 +1,12 @@
+import { isQuotaMap } from './map.js';
+import { mergeQuotaObservation } from './merge.js';
+/**
+ * The quota codec the account-pool store (the `/store` subpath) takes when it
+ * is opened: `validate` checks a stored per-row quota map and `merge` applies
+ * an observation to one, so the store persists the map without interpreting
+ * it.
+ */
+export const quotaCodec = Object.freeze({
+    validate: isQuotaMap,
+    merge: mergeQuotaObservation,
+});

package/dist/quota/index.d.ts

@@ -0,0 +1,8 @@
+export type { QuotaCodec } from './codec.js';
+export { quotaCodec } from './codec.js';
+export type { CreditBudgetCleared, CreditBudgetEntry, CreditBudgetReading, QuotaAbsentEntry, QuotaEntry, QuotaMap, QuotaReadingEntry, QuotaRetiredEntry, } from './map.js';
+export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, emptyQuotaMap, isQuotaMap, } from './map.js';
+export type { ObservedBudget, ObservedPair, ObservedReading, QuotaObservation, } from './merge.js';
+export { isQuotaObservation, mergeQuotaObservation, QuotaCodecError, } from './merge.js';
+export type { ExhaustionReset, ProjectedBudget, ProjectedLimit, ProjectedQuota, } from './projection.js';
+export { budgetExhaustedResetAt, futureResetAt, projectQuota, readsExhausted, } from './projection.js';

package/dist/quota/index.js

@@ -0,0 +1,4 @@
+export { quotaCodec } from './codec.js';
+export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, emptyQuotaMap, isQuotaMap, } from './map.js';
+export { isQuotaObservation, mergeQuotaObservation, QuotaCodecError, } from './merge.js';
+export { budgetExhaustedResetAt, futureResetAt, projectQuota, readsExhausted, } from './projection.js';

package/dist/quota/map.d.ts

@@ -0,0 +1,63 @@
+/** The scope of a limit that binds every request regardless of model. */
+export declare const ALL_SCOPE = "all";
+/** The window label required when an admission call supplies none. */
+export declare const DEFAULT_REQUIRED_LABELS: readonly string[];
+export interface QuotaReadingEntry {
+    scope: string;
+    label: string;
+    kind: 'reading';
+    checkedAt: number;
+    usedPercent: number;
+    /** ISO timestamp at which the window resets, as the provider reported it. */
+    resetsAt?: string;
+    /** Window length in minutes, when the provider reported one. */
+    windowMinutes?: number;
+}
+export interface QuotaRetiredEntry {
+    scope: string;
+    label: string;
+    kind: 'retired';
+    retiredAt: number;
+}
+export interface QuotaAbsentEntry {
+    scope: string;
+    label: string;
+    kind: 'absent';
+    checkedAt: number;
+}
+export type QuotaEntry = QuotaReadingEntry | QuotaRetiredEntry | QuotaAbsentEntry;
+export interface CreditBudgetReading {
+    kind: 'reading';
+    checkedAt: number;
+    /** The provider's own verdict that the budget is spent. */
+    reached: boolean;
+    remainingPercent?: number;
+    usedPercent?: number;
+    resetsAt?: string;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+    unit?: string;
+}
+export interface CreditBudgetCleared {
+    kind: 'cleared';
+    checkedAt: number;
+}
+export type CreditBudgetEntry = CreditBudgetReading | CreditBudgetCleared;
+export interface QuotaMap {
+    limits: QuotaEntry[];
+    /** Absent means no observation has reported on the budget yet. */
+    budget?: CreditBudgetEntry;
+}
+export declare function emptyQuotaMap(): QuotaMap;
+/** The time an entry speaks for: its reading, retirement or absence time. */
+export declare function entryTime(entry: QuotaEntry): number;
+export declare function limitKey(scope: string, label: string): string;
+export declare function isCreditBudgetEntry(value: unknown): value is CreditBudgetEntry;
+/**
+ * True when `value` is a well-formed quota map. Unrecognised top-level keys
+ * are tolerated (and preserved by merge) so a newer writer's additions
+ * survive; a malformed entry, a duplicated (scope, label) key or a malformed
+ * budget makes the whole map invalid.
+ */
+export declare function isQuotaMap(value: unknown): value is QuotaMap;

package/dist/quota/map.js

@@ -0,0 +1,105 @@
+// The per-row quota map: what the pool knows about one row's limits.
+//
+// A row's quota is a set of keyed limits. Each key is a (scope, window label)
+// pair: the scope is `all` for a limit that binds every request, or a model
+// family name for a limit that binds only that family; the label names the
+// window the provider reports (for example `primary` or `secondary`). Each key
+// holds one entry, which is either a reading, a retirement tombstone (the key
+// held a reading until an authoritative observation stopped reporting it), or
+// an absence record (an authoritative observation reported the key as having
+// no limit before any reading was seen). Tombstones and absence records are
+// evidence that the key is known to be unlimited; a missing key is unknown.
+//
+// Beside the limits sits the credit budget, a third pressure axis with its own
+// reset clock. It is a tri-state: absent (never reported), a reading, or
+// cleared (the provider reported that no budget exists).
+//
+// The map is plain JSON so the store can persist it without interpreting it.
+/** The scope of a limit that binds every request regardless of model. */
+export const ALL_SCOPE = 'all';
+/** The window label required when an admission call supplies none. */
+export const DEFAULT_REQUIRED_LABELS = Object.freeze([
+    'primary',
+]);
+export function emptyQuotaMap() {
+    return { limits: [] };
+}
+/** The time an entry speaks for: its reading, retirement or absence time. */
+export function entryTime(entry) {
+    return entry.kind === 'retired' ? entry.retiredAt : entry.checkedAt;
+}
+export function limitKey(scope, label) {
+    // JSON-encoding the pair keeps keys unambiguous for any scope or label text.
+    return JSON.stringify([scope, label]);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isName(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function optional(record, key, check) {
+    return record[key] === undefined || check(record[key]);
+}
+function isPositiveFinite(value) {
+    return isFiniteNumber(value) && value > 0;
+}
+function isString(value) {
+    return typeof value === 'string';
+}
+function isQuotaEntry(value) {
+    if (!isRecord(value) || !isName(value.scope) || !isName(value.label)) {
+        return false;
+    }
+    switch (value.kind) {
+        case 'reading':
+            return (isFiniteNumber(value.checkedAt) &&
+                isFiniteNumber(value.usedPercent) &&
+                optional(value, 'resetsAt', isString) &&
+                optional(value, 'windowMinutes', isPositiveFinite));
+        case 'retired':
+            return isFiniteNumber(value.retiredAt);
+        case 'absent':
+            return isFiniteNumber(value.checkedAt);
+        default:
+            return false;
+    }
+}
+export function isCreditBudgetEntry(value) {
+    if (!isRecord(value) || !isFiniteNumber(value.checkedAt))
+        return false;
+    if (value.kind === 'cleared')
+        return true;
+    return (value.kind === 'reading' &&
+        typeof value.reached === 'boolean' &&
+        optional(value, 'remainingPercent', isFiniteNumber) &&
+        optional(value, 'usedPercent', isFiniteNumber) &&
+        optional(value, 'resetsAt', isString) &&
+        optional(value, 'limit', isFiniteNumber) &&
+        optional(value, 'used', isFiniteNumber) &&
+        optional(value, 'remaining', isFiniteNumber) &&
+        optional(value, 'unit', isString));
+}
+/**
+ * True when `value` is a well-formed quota map. Unrecognised top-level keys
+ * are tolerated (and preserved by merge) so a newer writer's additions
+ * survive; a malformed entry, a duplicated (scope, label) key or a malformed
+ * budget makes the whole map invalid.
+ */
+export function isQuotaMap(value) {
+    if (!isRecord(value) || !Array.isArray(value.limits))
+        return false;
+    const seen = new Set();
+    for (const entry of value.limits) {
+        if (!isQuotaEntry(entry))
+            return false;
+        const key = limitKey(entry.scope, entry.label);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+    }
+    return optional(value, 'budget', isCreditBudgetEntry);
+}

package/dist/quota/merge.d.ts

@@ -0,0 +1,48 @@
+import { type QuotaMap } from './map.js';
+export interface ObservedReading {
+    /** Defaults to `all`. */
+    scope?: string;
+    label: string;
+    usedPercent: number;
+    resetsAt?: string;
+    windowMinutes?: number;
+}
+export interface ObservedPair {
+    /** Defaults to `all`. */
+    scope?: string;
+    label: string;
+}
+export type ObservedBudget = {
+    kind: 'reading';
+    reached: boolean;
+    remainingPercent?: number;
+    usedPercent?: number;
+    resetsAt?: string;
+    limit?: number;
+    used?: number;
+    remaining?: number;
+    unit?: string;
+} | {
+    kind: 'cleared';
+};
+export interface QuotaObservation {
+    checkedAt: number;
+    readings?: ObservedReading[];
+    /** Pairs reported on with authority besides the ones carrying a reading. */
+    coverage?: ObservedPair[];
+    /** Absent means the observation says nothing about the budget. */
+    budget?: ObservedBudget;
+}
+/** Thrown by `mergeQuotaObservation` when either argument is malformed. */
+export declare class QuotaCodecError extends TypeError {
+    constructor(message: string);
+}
+/** True when `value` is a well-formed observation; a pair read twice is not. */
+export declare function isQuotaObservation(value: unknown): value is QuotaObservation;
+/**
+ * Applies `observation` to `stored` (undefined for a row with no map yet) and
+ * returns the new map. Pure: neither argument is modified. Throws
+ * `QuotaCodecError` when either argument is malformed, so a store refuses the
+ * write rather than persisting a map it could not read back.
+ */
+export declare function mergeQuotaObservation(stored: unknown, observation: unknown): QuotaMap;

package/dist/quota/merge.js

@@ -0,0 +1,162 @@
+// Merging one observation into a stored quota map.
+//
+// One freshness rule applies everywhere: an observation applies to a key when
+// it is not older than what the key holds, so an equal time applies and the
+// observation applied last wins, as openai-auth's `freshestWindow` does.
+//
+// An observation carries readings plus a coverage list: the (scope, label)
+// pairs it speaks for with authority. Every reading is implicitly covered. A
+// covered pair the observation carries no reading for is reported as having
+// no limit: an existing reading becomes a retirement tombstone, and a key with
+// no entry gets an absence record. A pair outside the coverage is never
+// touched, so a header-shaped partial observation (which covers only what it
+// carries) cannot erase a family limit or the budget.
+import { ALL_SCOPE, entryTime, isQuotaMap, limitKey, } from './map.js';
+/** Thrown by `mergeQuotaObservation` when either argument is malformed. */
+export class QuotaCodecError extends TypeError {
+    constructor(message) {
+        super(message);
+        this.name = 'QuotaCodecError';
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+function isScope(value) {
+    return value === undefined || (typeof value === 'string' && value !== '');
+}
+function isLabel(value) {
+    return typeof value === 'string' && value !== '';
+}
+function optionalFinite(record, key) {
+    return record[key] === undefined || isFiniteNumber(record[key]);
+}
+function optionalString(record, key) {
+    return record[key] === undefined || typeof record[key] === 'string';
+}
+function isObservedReading(value) {
+    return (isRecord(value) &&
+        isScope(value.scope) &&
+        isLabel(value.label) &&
+        isFiniteNumber(value.usedPercent) &&
+        optionalString(value, 'resetsAt') &&
+        (value.windowMinutes === undefined ||
+            (isFiniteNumber(value.windowMinutes) && value.windowMinutes > 0)));
+}
+function isObservedPair(value) {
+    return isRecord(value) && isScope(value.scope) && isLabel(value.label);
+}
+function isObservedBudget(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.kind === 'cleared')
+        return true;
+    return (value.kind === 'reading' &&
+        typeof value.reached === 'boolean' &&
+        optionalFinite(value, 'remainingPercent') &&
+        optionalFinite(value, 'usedPercent') &&
+        optionalString(value, 'resetsAt') &&
+        optionalFinite(value, 'limit') &&
+        optionalFinite(value, 'used') &&
+        optionalFinite(value, 'remaining') &&
+        optionalString(value, 'unit'));
+}
+/** True when `value` is a well-formed observation; a pair read twice is not. */
+export function isQuotaObservation(value) {
+    if (!isRecord(value) || !isFiniteNumber(value.checkedAt))
+        return false;
+    const readings = value.readings ?? [];
+    const coverage = value.coverage ?? [];
+    if (!Array.isArray(readings) || !Array.isArray(coverage))
+        return false;
+    const read = new Set();
+    for (const reading of readings) {
+        if (!isObservedReading(reading))
+            return false;
+        const key = limitKey(reading.scope ?? ALL_SCOPE, reading.label);
+        if (read.has(key))
+            return false;
+        read.add(key);
+    }
+    if (!coverage.every(isObservedPair))
+        return false;
+    return value.budget === undefined || isObservedBudget(value.budget);
+}
+function compareEntries(left, right) {
+    if (left.scope !== right.scope)
+        return left.scope < right.scope ? -1 : 1;
+    if (left.label !== right.label)
+        return left.label < right.label ? -1 : 1;
+    return 0;
+}
+function mergeBudget(stored, observed, checkedAt) {
+    if (observed === undefined)
+        return stored;
+    if (stored !== undefined && checkedAt < stored.checkedAt)
+        return stored;
+    return { ...observed, checkedAt };
+}
+/**
+ * Applies `observation` to `stored` (undefined for a row with no map yet) and
+ * returns the new map. Pure: neither argument is modified. Throws
+ * `QuotaCodecError` when either argument is malformed, so a store refuses the
+ * write rather than persisting a map it could not read back.
+ */
+export function mergeQuotaObservation(stored, observation) {
+    if (stored !== undefined && !isQuotaMap(stored)) {
+        throw new QuotaCodecError('stored quota map is malformed');
+    }
+    if (!isQuotaObservation(observation)) {
+        throw new QuotaCodecError('quota observation is malformed');
+    }
+    const base = stored ?? { limits: [] };
+    const at = observation.checkedAt;
+    const entries = new Map();
+    for (const entry of base.limits) {
+        entries.set(limitKey(entry.scope, entry.label), entry);
+    }
+    const applies = (key) => {
+        const existing = entries.get(key);
+        return existing === undefined || at >= entryTime(existing);
+    };
+    const carried = new Set();
+    for (const reading of observation.readings ?? []) {
+        const scope = reading.scope ?? ALL_SCOPE;
+        const key = limitKey(scope, reading.label);
+        carried.add(key);
+        if (!applies(key))
+            continue;
+        entries.set(key, {
+            scope,
+            label: reading.label,
+            kind: 'reading',
+            checkedAt: at,
+            usedPercent: reading.usedPercent,
+            ...(reading.resetsAt === undefined ? {} : { resetsAt: reading.resetsAt }),
+            ...(reading.windowMinutes === undefined
+                ? {}
+                : { windowMinutes: reading.windowMinutes }),
+        });
+    }
+    for (const pair of observation.coverage ?? []) {
+        const scope = pair.scope ?? ALL_SCOPE;
+        const key = limitKey(scope, pair.label);
+        if (carried.has(key) || !applies(key))
+            continue;
+        const existing = entries.get(key);
+        entries.set(key, existing === undefined || existing.kind === 'absent'
+            ? { scope, label: pair.label, kind: 'absent', checkedAt: at }
+            : { scope, label: pair.label, kind: 'retired', retiredAt: at });
+    }
+    // Keys this module does not recognise are carried over untouched.
+    const { limits: _limits, budget: _budget, ...unknownKeys } = base;
+    const budget = mergeBudget(base.budget, observation.budget, at);
+    return {
+        ...unknownKeys,
+        limits: [...entries.values()].sort(compareEntries),
+        ...(budget === undefined ? {} : { budget }),
+    };
+}

package/dist/quota/projection.d.ts

@@ -0,0 +1,57 @@
+import { type QuotaMap } from './map.js';
+export interface ProjectedLimit {
+    scope: string;
+    label: string;
+    kind: 'reading' | 'retired' | 'absent';
+    /** The reading, retirement or absence time. */
+    checkedAt: number;
+    /** The stored window length; undefined when the provider reported none. */
+    windowMinutes?: number;
+    /** Present on readings only. */
+    usedPercent?: number;
+    /** Present on readings only: `100 - usedPercent`. */
+    remainingPercent?: number;
+    resetsAt?: string;
+}
+export interface ProjectedBudget {
+    checkedAt: number;
+    reached: boolean;
+    remainingPercent?: number;
+    resetsAt?: string;
+}
+export interface ProjectedQuota {
+    scope: string;
+    /** One entry per label: longest known window first, unknown lengths last. */
+    limits: readonly ProjectedLimit[];
+    /**
+     * The oldest reading time among the limits (or, with no reading, the oldest
+     * evidence time), so a projection is only as fresh as its stalest limit.
+     */
+    checkedAt?: number;
+    /** Present only when the stored budget is a reading, not cleared. */
+    budget?: ProjectedBudget;
+}
+/**
+ * Resolves `map` for a request in `scope` (`all` or a model family). A family
+ * request sees only its own family's keys and the `all` keys. Per label, a
+ * family reading shadows the `all` entry; a family tombstone or absence
+ * record says only that no family-specific limit exists, so it does not hide
+ * an `all` entry for the same label and is used only when there is none.
+ */
+export declare function projectQuota(map: QuotaMap | undefined, scope?: string): ProjectedQuota;
+export interface ExhaustionReset {
+    resetsAt: string;
+    resetAtMs: number;
+}
+/**
+ * The credit budget's own exhaustion signal. Admission and the sticky
+ * routing decision to move a session off its pinned row both use it, so the
+ * two agree on what "spent" means. `reached` is the provider's
+ * verdict (the percentage is only a display value), and the check fails open
+ * on a missing, unparsable or already-passed reset.
+ */
+export declare function budgetExhaustedResetAt(quota: Pick<ProjectedQuota, 'budget'> | null | undefined, now: number): ExhaustionReset | undefined;
+/** True for a reading at or beyond its whole window. */
+export declare function readsExhausted(limit: ProjectedLimit): boolean;
+/** The reset time of a limit when it parses and lies after `now`. */
+export declare function futureResetAt(limit: ProjectedLimit, now: number): number | undefined;

package/dist/quota/projection.js

@@ -0,0 +1,127 @@
+// Projection of a keyed quota map onto one request scope.
+//
+// The selection primitives carried from openai-auth judge an account by a
+// short list of windows; the keyed map can hold many (scope, label) keys. The
+// projection resolves exactly one entry per window label for the request's
+// scope, orders the result the way the primitives expect, and carries each
+// entry's (scope, label) so a decision names the limit it judged rather than
+// the position it occupied.
+import { ALL_SCOPE, } from './map.js';
+function project(entry) {
+    if (entry.kind === 'retired') {
+        return {
+            scope: entry.scope,
+            label: entry.label,
+            kind: 'retired',
+            checkedAt: entry.retiredAt,
+        };
+    }
+    if (entry.kind === 'absent') {
+        return {
+            scope: entry.scope,
+            label: entry.label,
+            kind: 'absent',
+            checkedAt: entry.checkedAt,
+        };
+    }
+    return {
+        scope: entry.scope,
+        label: entry.label,
+        kind: 'reading',
+        checkedAt: entry.checkedAt,
+        usedPercent: entry.usedPercent,
+        remainingPercent: 100 - entry.usedPercent,
+        ...(entry.windowMinutes === undefined
+            ? {}
+            : { windowMinutes: entry.windowMinutes }),
+        ...(entry.resetsAt === undefined ? {} : { resetsAt: entry.resetsAt }),
+    };
+}
+function compareLimits(left, right) {
+    const leftKnown = left.windowMinutes !== undefined;
+    const rightKnown = right.windowMinutes !== undefined;
+    if (leftKnown !== rightKnown)
+        return leftKnown ? -1 : 1;
+    if (leftKnown && rightKnown && left.windowMinutes !== right.windowMinutes) {
+        return (right.windowMinutes ?? 0) - (left.windowMinutes ?? 0);
+    }
+    if (left.label !== right.label)
+        return left.label < right.label ? -1 : 1;
+    return 0;
+}
+function projectBudget(budget) {
+    return {
+        checkedAt: budget.checkedAt,
+        reached: budget.reached,
+        ...(budget.remainingPercent === undefined
+            ? {}
+            : { remainingPercent: budget.remainingPercent }),
+        ...(budget.resetsAt === undefined ? {} : { resetsAt: budget.resetsAt }),
+    };
+}
+/**
+ * Resolves `map` for a request in `scope` (`all` or a model family). A family
+ * request sees only its own family's keys and the `all` keys. Per label, a
+ * family reading shadows the `all` entry; a family tombstone or absence
+ * record says only that no family-specific limit exists, so it does not hide
+ * an `all` entry for the same label and is used only when there is none.
+ */
+export function projectQuota(map, scope = ALL_SCOPE) {
+    const byLabel = new Map();
+    for (const entry of map?.limits ?? []) {
+        if (entry.scope !== scope && entry.scope !== ALL_SCOPE)
+            continue;
+        const current = byLabel.get(entry.label);
+        if (current === undefined) {
+            byLabel.set(entry.label, entry);
+            continue;
+        }
+        const family = entry.scope === ALL_SCOPE ? current : entry;
+        const general = entry.scope === ALL_SCOPE ? entry : current;
+        byLabel.set(entry.label, family.kind === 'reading' ? family : general);
+    }
+    const limits = [...byLabel.values()].map(project).sort(compareLimits);
+    const readings = limits.filter((limit) => limit.kind === 'reading');
+    const stamped = readings.length > 0 ? readings : limits;
+    const checkedAt = stamped.length > 0
+        ? Math.min(...stamped.map((limit) => limit.checkedAt))
+        : undefined;
+    const budget = map?.budget?.kind === 'reading' ? projectBudget(map.budget) : undefined;
+    return {
+        scope,
+        limits,
+        ...(checkedAt === undefined ? {} : { checkedAt }),
+        ...(budget === undefined ? {} : { budget }),
+    };
+}
+/**
+ * The credit budget's own exhaustion signal. Admission and the sticky
+ * routing decision to move a session off its pinned row both use it, so the
+ * two agree on what "spent" means. `reached` is the provider's
+ * verdict (the percentage is only a display value), and the check fails open
+ * on a missing, unparsable or already-passed reset.
+ */
+export function budgetExhaustedResetAt(quota, now) {
+    const budget = quota?.budget;
+    if (budget?.reached !== true || typeof budget.resetsAt !== 'string') {
+        return undefined;
+    }
+    const resetAtMs = Date.parse(budget.resetsAt);
+    if (!Number.isFinite(resetAtMs) || resetAtMs <= now)
+        return undefined;
+    return { resetsAt: budget.resetsAt, resetAtMs };
+}
+/** True for a reading at or beyond its whole window. */
+export function readsExhausted(limit) {
+    return (limit.kind === 'reading' &&
+        typeof limit.usedPercent === 'number' &&
+        Number.isFinite(limit.usedPercent) &&
+        limit.usedPercent >= 100);
+}
+/** The reset time of a limit when it parses and lies after `now`. */
+export function futureResetAt(limit, now) {
+    if (typeof limit.resetsAt !== 'string')
+        return undefined;
+    const resetAtMs = Date.parse(limit.resetsAt);
+    return Number.isFinite(resetAtMs) && resetAtMs > now ? resetAtMs : undefined;
+}