@cortexkit/common-auth 0.2.5 → 0.2.7

package/dist/claustrum/consumer.d.ts

@@ -0,0 +1,93 @@
+import type { ClaustrumReporterSource } from '@cortexkit/claustrum-client';
+import type { QuotaObservation } from '../quota/index.js';
+import type { RoutingRow } from '../routing/index.js';
+import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser } from './custody.js';
+import { type ClaustrumLogger } from './errors.js';
+import { type AccountMapper, type VaultRosterFile } from './roster.js';
+export interface ClaustrumConsumerOptions {
+    /**
+     * The roster file: one row per vault account (route id, credential id,
+     * account identity, state, quota), plus the accounts the user declined. It
+     * never holds a token.
+     */
+    rosterPath: string;
+    /** This host's enrollment token, written by setup. */
+    tokenPath: string;
+    family: ClaustrumFamily;
+    connect: () => Promise<ClaustrumScopedClient>;
+    /**
+     * Whether the plugin currently takes its accounts from the vault (custody
+     * mode) rather than from local logins. Checked before every discovery,
+     * commit and dispatch; false closes the vault connection and refuses sends.
+     */
+    isCustodyActive?: () => boolean | Promise<boolean>;
+    /** Ids of the plugin's local pool rows; no vault route id may equal one. */
+    reservedRouteIds?: () => Iterable<string>;
+    routePrefix?: string;
+    mapAccount?: AccountMapper;
+    parseIdentity?: IdentityParser;
+    /**
+     * Fired once per change of the vault's view cursor, including the first
+     * roster. A poll that sees the same view does not fire, and neither does a
+     * routine token refresh, which never moves the view.
+     */
+    onRoster?: (roster: VaultRosterFile) => void;
+    onError?: (error: unknown) => void;
+    pollIntervalMs?: number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    now?: () => number;
+    logger?: ClaustrumLogger;
+}
+export interface SendOptions {
+    /**
+     * What kind of request this is (for example `model`, `quota`, `profile`),
+     * recorded in the 401 retry log line so a retry can be traced to its caller.
+     */
+    site: string;
+    signal?: AbortSignal;
+    reporterSource?: ClaustrumReporterSource;
+}
+/**
+ * One plugin host's view of its vault accounts. It turns vault credentials
+ * into rows for `/routing`, authorizes each physical send with the vault, and
+ * reports a 401 against the exact record version that send used. Metadata
+ * (the connection and discovery) is shared and coalesced; credential reads
+ * never are. It never enrolls: a missing token is an error here, and setup
+ * is where enrollment happens.
+ */
+export declare class ClaustrumConsumer {
+    #private;
+    constructor(options: ClaustrumConsumerOptions);
+    /** The last committed roster this instance saw, without any I/O. */
+    snapshot(): VaultRosterFile | undefined;
+    /** Rows for `/routing`, from the last committed roster. */
+    routingRows(): RoutingRow[];
+    refresh(): Promise<VaultRosterFile | undefined>;
+    start(): void;
+    /**
+     * Authorize one physical send on a vault route. The roster file is re-read
+     * first, so a decline committed by another process applies before the next
+     * poll, and a route whose credential or account changed is refused.
+     */
+    authorize(routeId: string, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
+    reportFailure(attempt: ClaustrumScopedAttempt, status: number, source: ClaustrumReporterSource): Promise<void>;
+    /**
+     * Send on a vault route. `dispatch` builds and sends the request with the
+     * receipt's token and may be called twice, so it must be able to rebuild
+     * its body. A 401 is retried once, and only when the vault now serves a new
+     * record version of the same credential and account; the final 401 is
+     * reported against the version that send actually used. Each call to
+     * `dispatch` gets its own receipt.
+     */
+    send(routeId: string, dispatch: (attempt: ClaustrumScopedAttempt, signal?: AbortSignal) => Promise<Response>, options: SendOptions): Promise<Response>;
+    /** Decline a vault account: it stays listed and never routes until accepted. */
+    decline(routeId: string): Promise<void>;
+    accept(routeId: string): Promise<void>;
+    /**
+     * Store a quota observation for a vault route. Pass the receipt the reading
+     * was taken with, so an observation for a replaced account is dropped.
+     */
+    recordQuota(routeId: string, observation: QuotaObservation, attempt?: Pick<ClaustrumScopedAttempt, 'accountIdentity'>): Promise<boolean>;
+    close(): void;
+}

package/dist/claustrum/consumer.js

@@ -0,0 +1,276 @@
+import { createLogger } from '../logger/index.js';
+import { ClaustrumScopedCustody, decideScopedRetryAfter401, } from './custody.js';
+import { ClaustrumConsumerError } from './errors.js';
+import { acceptVaultRoute, declineVaultRoute, readVaultRoster, recordVaultQuota, refreshVaultRoster, vaultRoutingRows, } from './roster.js';
+/**
+ * One plugin host's view of its vault accounts. It turns vault credentials
+ * into rows for `/routing`, authorizes each physical send with the vault, and
+ * reports a 401 against the exact record version that send used. Metadata
+ * (the connection and discovery) is shared and coalesced; credential reads
+ * never are. It never enrolls: a missing token is an error here, and setup
+ * is where enrollment happens.
+ */
+export class ClaustrumConsumer {
+    #options;
+    #shutdown = new AbortController();
+    #logger;
+    #custody;
+    #connecting;
+    #refreshing;
+    #roster;
+    #timer;
+    #started = false;
+    constructor(options) {
+        this.#options = options;
+        this.#logger = options.logger ?? createLogger('claustrum');
+    }
+    #assertOpen(signal) {
+        this.#shutdown.signal.throwIfAborted();
+        signal?.throwIfAborted();
+    }
+    async #active() {
+        return (await this.#options.isCustodyActive?.()) ?? true;
+    }
+    #wait(pending, signal) {
+        const combined = AbortSignal.any([
+            this.#shutdown.signal,
+            ...(signal ? [signal] : []),
+        ]);
+        return new Promise((resolve, reject) => {
+            const cleanup = () => combined.removeEventListener('abort', abort);
+            const abort = () => {
+                cleanup();
+                reject(combined.reason);
+            };
+            combined.addEventListener('abort', abort, { once: true });
+            // Observe the operation even after cancellation: shared metadata work may
+            // finish for other callers, and a late connection must still be closed.
+            pending.then((value) => {
+                cleanup();
+                if (combined.aborted)
+                    reject(combined.reason);
+                else
+                    resolve(value);
+            }, (error) => {
+                cleanup();
+                reject(error);
+            });
+            if (combined.aborted)
+                abort();
+        });
+    }
+    async #getCustody() {
+        this.#assertOpen();
+        if (this.#custody)
+            return this.#custody;
+        if (!this.#connecting) {
+            this.#connecting = this.#options
+                .connect()
+                .then((client) => {
+                if (this.#shutdown.signal.aborted) {
+                    client.close();
+                    this.#assertOpen();
+                }
+                this.#custody = new ClaustrumScopedCustody({
+                    client,
+                    family: this.#options.family,
+                    tokenPath: this.#options.tokenPath,
+                    parseIdentity: this.#options.parseIdentity,
+                    now: this.#options.now,
+                    logger: this.#logger,
+                });
+                return this.#custody;
+            })
+                .finally(() => {
+                this.#connecting = undefined;
+            });
+        }
+        return this.#wait(this.#connecting);
+    }
+    /** The last committed roster this instance saw, without any I/O. */
+    snapshot() {
+        return this.#roster;
+    }
+    /** Rows for `/routing`, from the last committed roster. */
+    routingRows() {
+        return vaultRoutingRows(this.#roster);
+    }
+    refresh() {
+        this.#assertOpen();
+        if (this.#refreshing)
+            return this.#refreshing;
+        this.#refreshing = (async () => {
+            if (!(await this.#active())) {
+                this.#roster = undefined;
+                this.#custody?.close();
+                this.#custody = undefined;
+                return undefined;
+            }
+            const custody = await this.#getCustody();
+            const roster = await refreshVaultRoster({
+                path: this.#options.rosterPath,
+                custody,
+                isActive: () => this.#active(),
+                signal: this.#shutdown.signal,
+                projection: () => ({
+                    reservedRouteIds: new Set(this.#options.reservedRouteIds?.() ?? []),
+                    routePrefix: this.#options.routePrefix,
+                    mapAccount: this.#options.mapAccount,
+                    now: (this.#options.now ?? Date.now)(),
+                }),
+            });
+            this.#assertOpen();
+            const changed = roster?.view !== this.#roster?.view;
+            this.#roster = roster;
+            // Notify on view changes only: subscribers rewrite shared state on each
+            // notification, and the poll runs every few seconds.
+            if (roster && changed)
+                this.#options.onRoster?.(roster);
+            return roster;
+        })().finally(() => {
+            this.#refreshing = undefined;
+        });
+        return this.#refreshing;
+    }
+    start() {
+        if (this.#started)
+            return;
+        this.#assertOpen();
+        this.#started = true;
+        const tick = async () => {
+            try {
+                await this.refresh();
+            }
+            catch (error) {
+                if (!this.#shutdown.signal.aborted)
+                    this.#options.onError?.(error);
+            }
+            if (this.#shutdown.signal.aborted)
+                return;
+            const delay = this.#options.pollIntervalMs ?? 5_000;
+            if (delay <= 0)
+                return;
+            this.#timer = (this.#options.setTimeoutImpl ?? setTimeout)(() => {
+                this.#timer = undefined;
+                void tick();
+            }, delay);
+            this.#timer.unref?.();
+        };
+        void tick();
+    }
+    /**
+     * Authorize one physical send on a vault route. The roster file is re-read
+     * first, so a decline committed by another process applies before the next
+     * poll, and a route whose credential or account changed is refused.
+     */
+    async authorize(routeId, signal) {
+        this.#assertOpen(signal);
+        const roster = this.#roster ?? (await this.#wait(this.refresh(), signal));
+        if (!roster || !(await this.#active()))
+            throw new ClaustrumConsumerError('not-active', 'Claustrum scoped custody is not active');
+        const current = await readVaultRoster(this.#options.rosterPath);
+        this.#assertOpen(signal);
+        const observed = roster.rows.find((row) => row.routeId === routeId);
+        const configured = current?.rows.find((row) => row.routeId === routeId);
+        if (configured && !configured.enabled)
+            throw new ClaustrumConsumerError('route-declined', 'Claustrum route is disabled');
+        if (!observed ||
+            !configured ||
+            configured.state !== 'active' ||
+            configured.credentialId !== observed.credentialId ||
+            configured.accountIdentity !== observed.accountIdentity)
+            throw new ClaustrumConsumerError('route-unavailable', 'Claustrum route is disabled, removed or changed');
+        return (await this.#wait(this.#getCustody(), signal)).authorize({
+            credentialId: configured.credentialId,
+            credentialType: configured.credentialType,
+            ...(configured.accountIdentity !== undefined && {
+                accountIdentity: configured.accountIdentity,
+            }),
+        }, AbortSignal.any([this.#shutdown.signal, ...(signal ? [signal] : [])]));
+    }
+    async reportFailure(attempt, status, source) {
+        this.#assertOpen();
+        if (!this.#custody)
+            throw new ClaustrumConsumerError('no-receipt', 'Claustrum dispatch receipt has no active owner');
+        await this.#custody.reportFailure(attempt, status, source);
+    }
+    /**
+     * Send on a vault route. `dispatch` builds and sends the request with the
+     * receipt's token and may be called twice, so it must be able to rebuild
+     * its body. A 401 is retried once, and only when the vault now serves a new
+     * record version of the same credential and account; the final 401 is
+     * reported against the version that send actually used. Each call to
+     * `dispatch` gets its own receipt.
+     */
+    async send(routeId, dispatch, options) {
+        const signal = options.signal;
+        let served = await this.authorize(routeId, signal);
+        let response = await dispatch(served, signal);
+        if (response.status === 401 && !signal?.aborted) {
+            let current;
+            try {
+                current = await this.authorize(routeId, signal);
+            }
+            catch {
+                // Re-authorization failed: keep this 401 and report it against the
+                // receipt (served record version) this request was sent with.
+            }
+            if (decideScopedRetryAfter401(options.site, served, current, this.#logger)) {
+                await response.body?.cancel().catch(() => { });
+                served = current;
+                response = await dispatch(current, signal);
+            }
+        }
+        if (response.status === 401) {
+            await this.reportFailure(served, 401, options.reporterSource ?? 'direct').catch((error) => this.#options.onError?.(error));
+            // After the report the vault may mark the account as needing a new
+            // login; refresh now so routing drops it without waiting for the next poll. Deferred so a consumer closed in
+            // the meantime reports to onError instead of throwing from this send.
+            Promise.resolve()
+                .then(() => this.refresh())
+                .catch((error) => {
+                if (!this.#shutdown.signal.aborted)
+                    this.#options.onError?.(error);
+            });
+        }
+        return response;
+    }
+    /** Decline a vault account: it stays listed and never routes until accepted. */
+    async decline(routeId) {
+        this.#assertOpen();
+        await declineVaultRoute(this.#options.rosterPath, routeId);
+        this.#roster = await readVaultRoster(this.#options.rosterPath);
+    }
+    async accept(routeId) {
+        this.#assertOpen();
+        await acceptVaultRoute(this.#options.rosterPath, routeId);
+        this.#roster = await readVaultRoster(this.#options.rosterPath);
+    }
+    /**
+     * Store a quota observation for a vault route. Pass the receipt the reading
+     * was taken with, so an observation for a replaced account is dropped.
+     */
+    async recordQuota(routeId, observation, attempt) {
+        this.#assertOpen();
+        const kept = await recordVaultQuota(this.#options.rosterPath, {
+            routeId,
+            observation,
+            ...(attempt?.accountIdentity !== undefined && {
+                accountIdentity: attempt.accountIdentity,
+            }),
+        });
+        if (kept)
+            this.#roster = await readVaultRoster(this.#options.rosterPath);
+        return kept;
+    }
+    close() {
+        if (this.#shutdown.signal.aborted)
+            return;
+        this.#shutdown.abort(new ClaustrumConsumerError('closed', 'Claustrum consumer is closed'));
+        if (this.#timer)
+            (this.#options.clearTimeoutImpl ?? clearTimeout)(this.#timer);
+        this.#timer = undefined;
+        this.#custody?.close();
+        this.#roster = undefined;
+    }
+}

package/dist/claustrum/custody.d.ts

@@ -0,0 +1,128 @@
+import { type ClaustrumClient, type ClaustrumReporterSource, type EnrollmentTokenFile } from '@cortexkit/claustrum-client';
+import { type ClaustrumLogger } from './errors.js';
+export type ClaustrumScopedClient = Pick<ClaustrumClient, 'listScoped' | 'getScoped' | 'reportAuthFailureScoped' | 'close'>;
+/** The two credential types a plugin's family can hold; routing differs by type. */
+export type VaultCredentialType = 'oauth' | 'api_key';
+/**
+ * Which vault rows belong to this plugin. `refreshAdapter` classifies an OAuth
+ * row by the protocol it speaks; `category` is the grant that authorizes this
+ * consumer to read it. Static API keys carry no refresh adapter, so they are
+ * admitted only when `apiKeys` is set and only by category.
+ */
+export interface ClaustrumFamily {
+    refreshAdapter: string;
+    category: string;
+    apiKeys?: boolean;
+}
+/** One vault credential this consumer may serve. Never carries bearer material. */
+export interface VaultCredential {
+    readonly credentialId: string;
+    readonly credentialType: VaultCredentialType;
+    /**
+     * The provider account the credential logs into, when the vault's adapter
+     * claims one. Absent means the adapter makes no claim, not a mismatch.
+     */
+    readonly accountIdentity?: string;
+    readonly state: string;
+    readonly email?: string;
+    readonly orgName?: string;
+}
+/** A vault record this consumer could not use, kept for the warning it raises. */
+export interface SkippedVaultRecord {
+    readonly credentialId?: string;
+    readonly reason: string;
+}
+export interface VaultInventory {
+    /**
+     * The vault's change cursor: a digest over exactly what this consumer can see
+     * (ids, grants, state, identity), never over record versions, so a routine
+     * token refresh does not move it. Only equality is meaningful.
+     */
+    readonly view: string;
+    readonly credentials: readonly VaultCredential[];
+    readonly skipped: readonly SkippedVaultRecord[];
+}
+export interface ClaustrumScopedIdentity {
+    readonly credentialId: string;
+    readonly credentialType: VaultCredentialType;
+    readonly accountIdentity?: string;
+}
+/**
+ * A receipt: what the vault served for one physical send. Each attempt gets
+ * its own. It records the exact record version served, because a 401 for
+ * this send is reported to the vault against that version.
+ */
+export interface ClaustrumScopedAttempt {
+    readonly credentialId: string;
+    readonly credentialType: VaultCredentialType;
+    readonly accountIdentity?: string;
+    /**
+     * Kept in memory only and hidden from JSON.stringify and object spreads, so
+     * logging a receipt never leaks it. Authorize again for every dispatch and retry.
+     */
+    readonly accessToken: string;
+    readonly recordVersion: number;
+    readonly expiresAtMs: number | null;
+}
+/** Reads the provider identity a served token executes under, when the plugin can tell. */
+export type IdentityParser = (accessToken: string) => string | undefined;
+/** Only a new version of the same account may replace an in-flight 401. */
+export declare function isScopedCredentialRotation(served: ClaustrumScopedAttempt, current: ClaustrumScopedAttempt | undefined): current is ClaustrumScopedAttempt;
+/** Why a scoped 401 did or did not retry. Never carries credential material. */
+export type ScopedRetryReason = 'rotated' | 'reauthorize-failed' | 'credential-changed' | 'account-changed' | 'version-unchanged';
+/**
+ * Decide whether a request that got a 401 should retry with the freshly
+ * re-authorized receipt, and log the decision. The vault can refresh a
+ * credential between the send and the 401; the log line lets that refresh be
+ * matched against the consumer's retry. `site` names the kind of request.
+ */
+export declare function decideScopedRetryAfter401(site: string, served: ClaustrumScopedAttempt, current: ClaustrumScopedAttempt | undefined, logger?: ClaustrumLogger): current is ClaustrumScopedAttempt;
+/**
+ * How long a served OAuth token must stay valid after the vault hands it out,
+ * so it cannot expire while a long request is still using it.
+ */
+export declare const SERVING_MARGIN_MS = 300000;
+/**
+ * Reads this consumer's vault credentials (list, fetch, 401 report), with the
+ * enrollment token as authorization. Used by every host of a plugin. There is
+ * deliberately no credential cache and no single-flight of credential reads:
+ * each physical send is authorized by the vault, so a revoked enrollment or a
+ * changed record takes effect on the next send. The enrollment token is
+ * re-read per operation so an operator's reissue on disk is picked up.
+ */
+export declare class ClaustrumScopedCustody {
+    #private;
+    constructor(options: {
+        client: ClaustrumScopedClient;
+        family: ClaustrumFamily;
+        tokenPath?: string;
+        readToken?: () => Promise<EnrollmentTokenFile>;
+        parseIdentity?: IdentityParser;
+        now?: () => number;
+        logger?: ClaustrumLogger;
+    });
+    /**
+     * List this consumer's credentials. A record that cannot be used is skipped
+     * and warned about rather than failing the whole list, so one bad record
+     * never hides every other account. Records outside the family are not
+     * skipped records: they simply are not this consumer's.
+     */
+    discover(signal?: AbortSignal): Promise<VaultInventory>;
+    /**
+     * Fetch the credential for one physical send and wrap it in a fresh receipt.
+     * Identity is checked only where both sides assert one: the vault's served
+     * identity (or, without one, the plugin's parse of the token) must equal the
+     * roster's when both are present; absence on either side proves nothing and
+     * does not refuse.
+     */
+    authorize(identity: ClaustrumScopedIdentity, signal?: AbortSignal): Promise<ClaustrumScopedAttempt>;
+    /**
+     * Report that a send this consumer actually made was rejected. Only a 401
+     * is reported (the vault refuses 429, 402 and 5xx reports), addressed by
+     * credential id with the exact record version that send was served, and
+     * signed with the enrollment token that authorized it. A receipt this
+     * custody did not issue is refused rather than reported.
+     */
+    reportFailure(attempt: ClaustrumScopedAttempt, status: number, reporterSource: ClaustrumReporterSource): Promise<void>;
+    close(): void;
+}