@cortexkit/antigravity-auth-core 2.2.1 → 3.0.0

package/dist/common-auth-embedded/auth-menu/select.js

@@ -0,0 +1,159 @@
+import { ANSI, parseKeys, truncateAnsi } from './ansi.js';
+import { isInteractive } from './terminal.js';
+/** How long a lone Escape byte waits for the rest of an arrow-key sequence. */
+const ESCAPE_TIMEOUT_MS = 50;
+function colorCode(color) {
+    if (color === 'red')
+        return ANSI.red;
+    if (color === 'cyan')
+        return ANSI.cyan;
+    return '';
+}
+/**
+ * Render a bounded, keyboard-only terminal selector without a prompt
+ * dependency. Resolves the chosen value, or null on Escape, Ctrl-C, a signal,
+ * or a terminal that refuses raw mode.
+ */
+export async function select(terminal, items, options) {
+    if (!isInteractive(terminal))
+        throw new Error('Interactive select requires a TTY terminal');
+    if (items.length === 0)
+        throw new Error('No menu items provided');
+    const { input: stdin, output: stdout, signals } = terminal;
+    let cursor = 0;
+    let escapeTimeout = null;
+    let cleaned = false;
+    let renderedLines = 0;
+    const render = () => {
+        const columns = stdout.columns ?? 80;
+        const rows = stdout.rows ?? 24;
+        const previousLines = renderedLines;
+        if (options.clearScreen) {
+            stdout.write(ANSI.clearScreen + ANSI.moveTo(1, 1));
+        }
+        else if (previousLines > 0) {
+            stdout.write(ANSI.up(previousLines));
+        }
+        let lines = 0;
+        const writeLine = (line) => {
+            stdout.write(`${ANSI.clearLine}${line}\n`);
+            lines += 1;
+        };
+        const extraLines = options.lines ?? [];
+        const headerLines = 1 +
+            (options.subtitle ? 3 : 0) +
+            extraLines.length +
+            (extraLines.length ? 1 : 0);
+        const maxVisible = Math.max(1, Math.min(items.length, rows - headerLines - 2 - 1));
+        const windowStart = Math.max(0, Math.min(cursor - Math.floor(maxVisible / 2), Math.max(0, items.length - maxVisible)));
+        const visibleItems = items.slice(windowStart, windowStart + maxVisible);
+        writeLine(`${ANSI.dim}┌  ${ANSI.reset}${truncateAnsi(options.message, Math.max(1, columns - 4))}`);
+        if (options.subtitle) {
+            writeLine(`${ANSI.dim}│${ANSI.reset}`);
+            writeLine(`${ANSI.cyan}◆${ANSI.reset}  ${truncateAnsi(options.subtitle, Math.max(1, columns - 4))}`);
+            writeLine('');
+        }
+        for (const line of extraLines) {
+            writeLine(`${ANSI.cyan}│${ANSI.reset}  ${truncateAnsi(line, Math.max(1, columns - 4))}`);
+        }
+        if (extraLines.length)
+            writeLine(`${ANSI.cyan}│${ANSI.reset}`);
+        for (let offset = 0; offset < visibleItems.length; offset++) {
+            const item = visibleItems[offset];
+            if (!item)
+                continue;
+            const selected = windowStart + offset === cursor;
+            const color = colorCode(item.color);
+            let label = color
+                ? `${selected ? '' : ANSI.dim}${color}${item.label}${ANSI.reset}`
+                : selected
+                    ? item.label
+                    : `${ANSI.dim}${item.label}${ANSI.reset}`;
+            if (item.hint)
+                label += ` ${ANSI.dim}${item.hint}${ANSI.reset}`;
+            label = truncateAnsi(label, Math.max(1, columns - 8));
+            writeLine(selected
+                ? `${ANSI.cyan}│${ANSI.reset}  ${ANSI.green}●${ANSI.reset} ${label}`
+                : `${ANSI.cyan}│${ANSI.reset}  ${ANSI.dim}○${ANSI.reset} ${label}`);
+        }
+        const windowHint = visibleItems.length < items.length
+            ? ` (${windowStart + 1}-${windowStart + visibleItems.length}/${items.length})`
+            : '';
+        writeLine(`${ANSI.cyan}│${ANSI.reset}  ${ANSI.dim}${truncateAnsi(`Up/Down to select | Enter: confirm | Esc: back${windowHint}`, Math.max(1, columns - 6))}${ANSI.reset}`);
+        writeLine(`${ANSI.cyan}└${ANSI.reset}`);
+        for (let extra = lines; extra < previousLines; extra++)
+            writeLine('');
+        renderedLines = lines;
+    };
+    return new Promise((resolve) => {
+        const wasRaw = stdin.isRaw ?? false;
+        const cleanup = () => {
+            if (cleaned)
+                return;
+            cleaned = true;
+            if (escapeTimeout)
+                clearTimeout(escapeTimeout);
+            stdin.removeListener('data', onKey);
+            try {
+                stdin.setRawMode(wasRaw);
+                stdin.pause();
+                stdout.write(ANSI.show);
+            }
+            catch { }
+            signals?.removeListener('SIGINT', onSignal);
+            signals?.removeListener('SIGTERM', onSignal);
+        };
+        const finish = (value) => {
+            cleanup();
+            resolve(value);
+        };
+        const onSignal = () => finish(null);
+        const onKey = (data) => {
+            for (const key of parseKeys(data)) {
+                if (cleaned)
+                    break;
+                if (escapeTimeout) {
+                    clearTimeout(escapeTimeout);
+                    escapeTimeout = null;
+                }
+                switch (key) {
+                    case 'up':
+                        cursor = (cursor - 1 + items.length) % items.length;
+                        render();
+                        break;
+                    case 'down':
+                        cursor = (cursor + 1) % items.length;
+                        render();
+                        break;
+                    case 'enter':
+                        finish(items[cursor]?.value ?? null);
+                        break;
+                    case 'escape':
+                        finish(null);
+                        break;
+                    case 'escape-start':
+                        // A bare Escape byte is also the start of an arrow-key sequence
+                        // that may arrive split across reads; only a lone one cancels.
+                        escapeTimeout = setTimeout(() => finish(null), ESCAPE_TIMEOUT_MS);
+                        break;
+                    default:
+                        break;
+                }
+            }
+        };
+        signals?.once('SIGINT', onSignal);
+        signals?.once('SIGTERM', onSignal);
+        try {
+            stdin.setRawMode(true);
+        }
+        catch {
+            cleanup();
+            resolve(null);
+            return;
+        }
+        stdin.resume();
+        stdout.write(ANSI.hide);
+        render();
+        stdin.on('data', onKey);
+    });
+}

package/dist/common-auth-embedded/auth-menu/terminal.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The terminal the menu draws on and reads keys from. The process's own
+ * stdin and stdout satisfy it; tests pass a scripted stand-in, so the full
+ * key-in, frame-out path runs without a real TTY.
+ */
+export interface MenuTerminal {
+    input: MenuInput;
+    output: MenuOutput;
+    /**
+     * Where SIGINT and SIGTERM are heard while a selector holds raw mode, so a
+     * kill restores the terminal. Defaults to nothing: raw mode turns Ctrl-C
+     * into a key the selector already handles.
+     */
+    signals?: MenuSignals;
+}
+export interface MenuInput {
+    /** True only on an interactive terminal; anything else gets a plain list. */
+    readonly isTTY?: boolean;
+    readonly isRaw?: boolean;
+    setRawMode(mode: boolean): unknown;
+    resume(): unknown;
+    pause(): unknown;
+    on(event: 'data', listener: (data: Buffer | string) => void): unknown;
+    removeListener(event: 'data', listener: (data: Buffer | string) => void): unknown;
+}
+export interface MenuOutput {
+    write(text: string): unknown;
+    readonly columns?: number;
+    readonly rows?: number;
+}
+export interface MenuSignals {
+    once(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    removeListener(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+/** The current process's terminal, with its signals. */
+export declare function processTerminal(): MenuTerminal;
+/**
+ * Whether keys can be read one at a time. Only the input is checked, as the
+ * plugins' menus always did: output piped to a file still gets the menu.
+ */
+export declare function isInteractive(terminal: MenuTerminal): boolean;
+/** Writes one line of plain output below the menu. */
+export declare function printLine(terminal: MenuTerminal, line?: string): void;

package/dist/common-auth-embedded/auth-menu/terminal.js

@@ -0,0 +1,19 @@
+/** The current process's terminal, with its signals. */
+export function processTerminal() {
+    return {
+        input: process.stdin,
+        output: process.stdout,
+        signals: process,
+    };
+}
+/**
+ * Whether keys can be read one at a time. Only the input is checked, as the
+ * plugins' menus always did: output piped to a file still gets the menu.
+ */
+export function isInteractive(terminal) {
+    return terminal.input.isTTY === true;
+}
+/** Writes one line of plain output below the menu. */
+export function printLine(terminal, line = '') {
+    terminal.output.write(`${line}\n`);
+}

package/dist/common-auth-embedded/claustrum/consumer.d.ts

@@ -0,0 +1,102 @@
+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 QuotaReceipt, 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;
+    /**
+     * Issue a receipt only when the vault's served reply itself names the
+     * credential id and the roster's account identity (see
+     * `ClaustrumScopedCustody`). Set it for providers whose tokens do not reveal
+     * their account; leave it unset to accept a reply that asserts no identity.
+     */
+    requireAssertion?: boolean;
+    /**
+     * 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 or profile observation for a vault route. The receipt the
+     * reading was taken with is required: the observation lands only while the
+     * route still holds the credential and account that receipt was served for
+     * (see `recordVaultQuota`), so a reading for a replaced account is dropped.
+     */
+    recordQuota(routeId: string, observation: QuotaObservation, attempt: QuotaReceipt): Promise<boolean>;
+    close(): void;
+}

package/dist/common-auth-embedded/claustrum/consumer.js

@@ -0,0 +1,298 @@
+import { createLogger } from '../logger/index.js';
+import { combineAbortSignals } from '../util/any-signal.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 = combineAbortSignals([
+            this.#shutdown.signal,
+            ...(signal ? [signal] : []),
+        ]);
+        return new Promise((resolve, reject) => {
+            const cleanup = () => {
+                combined.signal.removeEventListener('abort', abort);
+                combined.dispose();
+            };
+            const abort = () => {
+                cleanup();
+                reject(combined.signal.reason);
+            };
+            combined.signal.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.signal.aborted)
+                    reject(combined.signal.reason);
+                else
+                    resolve(value);
+            }, (error) => {
+                cleanup();
+                reject(error);
+            });
+            if (combined.signal.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,
+                    requireAssertion: this.#options.requireAssertion,
+                    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');
+        const custody = await this.#wait(this.#getCustody(), signal);
+        const combined = combineAbortSignals([
+            this.#shutdown.signal,
+            ...(signal ? [signal] : []),
+        ]);
+        try {
+            return await custody.authorize({
+                credentialId: configured.credentialId,
+                credentialType: configured.credentialType,
+                ...(configured.accountIdentity !== undefined && {
+                    accountIdentity: configured.accountIdentity,
+                }),
+            }, combined.signal);
+        }
+        finally {
+            combined.dispose();
+        }
+    }
+    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 or profile observation for a vault route. The receipt the
+     * reading was taken with is required: the observation lands only while the
+     * route still holds the credential and account that receipt was served for
+     * (see `recordVaultQuota`), so a reading for a replaced account is dropped.
+     */
+    async recordQuota(routeId, observation, attempt) {
+        this.#assertOpen();
+        const kept = await recordVaultQuota(this.#options.rosterPath, {
+            routeId,
+            observation,
+            credentialId: attempt.credentialId,
+            accountIdentitySource: attempt.accountIdentitySource,
+            ...(attempt.accountIdentity !== undefined && {
+                accountIdentity: attempt.accountIdentity,
+            }),
+            ...(attempt.expectedAccountIdentity !== undefined && {
+                expectedAccountIdentity: attempt.expectedAccountIdentity,
+            }),
+        });
+        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;
+    }
+}