firedrill-run 2.2.4 → 3.0.0

package/dist/cli/src/auth.js

@@ -0,0 +1,465 @@
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { randomUUID } from 'node:crypto';
+import { CliError, endpoint, jsonRequest, responseError, WORKOS_ORIGIN } from './http.js';
+import { credentialLock, loadCredentials, removeCredentials, saveCredentials, loadPendingDevice, savePendingDevice, removePendingDevice, credentialMode, isCredentialCompanion, eraseVolatileCredentials, volatileCredentialSummary } from './credentials.js';
+import { credentialStoreStatus } from './credential-mode.js';
+import { companionRequest, startCompanionServer } from './native/companion-ipc.js';
+import { chooseLoginOrganization, loginOrganizationIdentifier } from './login-organizations.js';
+import { nativeSessionMatches, nativeMembershipSyncMatches, nativeWorkspacesMatch, nativeRevokedMatches, nativeOrganizationsMatch } from '../../contracts/native-identity-contracts.js';
+async function configuration(signal) {
+    const result = await jsonRequest(endpoint('/api/auth/cli/config'), { signal });
+    if (result.status !== 200)
+        throw responseError(result.body, result.status);
+    const value = result.body;
+    try {
+        const origin = new URL(value.verification_origin);
+        if (value.schema !== 'firedrill.cli-auth.v1' || !/^client_[A-Za-z0-9]{1,120}$/.test(value.client_id)
+            || origin.protocol !== 'https:' || origin.origin !== value.verification_origin || origin.username || origin.password
+            || value.device_authorization_endpoint !== WORKOS_ORIGIN + '/user_management/authorize/device'
+            || value.token_endpoint !== WORKOS_ORIGIN + '/user_management/authenticate')
+            throw new Error();
+    }
+    catch {
+        throw new CliError('auth_configuration_invalid', 'Terminal sign-in configuration is unavailable.');
+    }
+    return value;
+}
+function organizationClaim(accessToken) {
+    const claims = JSON.parse(Buffer.from(accessToken.split('.')[1], 'base64url').toString('utf8'));
+    if (claims.org_id !== undefined && claims.org_id !== null && (typeof claims.org_id !== 'string' || !/^org_[A-Za-z0-9]{1,120}$/.test(claims.org_id)))
+        throw new Error();
+    return claims.org_id ?? undefined;
+}
+function credentials(body, config, previous, selectedOrganization) {
+    try {
+        const value = body;
+        if (typeof value.access_token !== 'string' || value.access_token.length > 16384 || typeof value.refresh_token !== 'string'
+            || !value.refresh_token || value.refresh_token.length > 16384)
+            throw new Error();
+        // Expiry/identity here only organize local storage. The API independently
+        // verifies signature/issuer/client/session and current membership.
+        const claims = JSON.parse(Buffer.from(value.access_token.split('.')[1], 'base64url').toString('utf8'));
+        if (!/^user_[A-Za-z0-9]{1,120}$/.test(claims.sub) || !/^session_[A-Za-z0-9]{1,120}$/.test(claims.sid)
+            || !Number.isSafeInteger(claims.exp) || claims.exp <= Date.now() / 1000
+            || value.user?.id && value.user.id !== claims.sub
+            || previous && (previous.subject !== claims.sub || previous.sid !== claims.sid || previous.client_id !== config.client_id))
+            throw new Error();
+        const organization = organizationClaim(value.access_token);
+        if (selectedOrganization !== undefined ? organization !== selectedOrganization
+            : previous && organization !== organizationClaim(previous.access_token))
+            throw new Error();
+        return { schema: 'firedrill.native-credentials.v1', state: 'ready', client_id: config.client_id,
+            access_token: value.access_token, refresh_token: value.refresh_token, subject: claims.sub, sid: claims.sid, expires_at: claims.exp };
+    }
+    catch {
+        throw new CliError('auth_response_invalid', 'Sign-in returned an incomplete response. Start sign-in again.');
+    }
+}
+export function openBrowser(url) {
+    return new Promise(resolve => {
+        const platform = process.platform;
+        const command = platform === 'darwin' ? '/usr/bin/open' : platform === 'win32' ? 'rundll32.exe' : 'xdg-open';
+        const args = platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
+        const child = spawn(command, args, { shell: false, stdio: 'ignore', windowsHide: true });
+        child.once('error', () => resolve(false));
+        child.once('exit', code => resolve(code === 0));
+    });
+}
+async function tokenRequest(config, body, signal) {
+    return jsonRequest(new URL(config.token_endpoint), { method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ ...body, client_id: config.client_id }), signal });
+}
+/** Terminal (CLI) device authorization only. Remote MCP OAuth and agent registration are separate flows. */
+export async function login(options) {
+    loginOrganizationIdentifier(options.organization);
+    const session = credentialMode() === 'session';
+    if (session && !isCredentialCompanion())
+        throw new CliError('session_login_requires_companion', 'Session-only sign-in happens inside the companion process. Run `firedrill init --session-only` and keep it running. No sign-in was started.', 2);
+    if (!session) {
+        // Report supported remediation before any browser ceremony. Never a file fallback.
+        const store = await credentialStoreStatus({ verifyWrite: true, signal: options.signal });
+        if (!store.available)
+            throw new CliError('credential_store_unavailable', `${store.remediation} No sign-in was started.`, 2);
+    }
+    const launchBrowser = options.open && (!options.json || options.explicitOpen === true);
+    return credentialLock(async (active) => {
+        options = { ...options, signal: AbortSignal.any([options.signal, active]) };
+        // Loading the native binding first refuses a missing store before asking
+        // the user to authorize. Actual read/write failures remain explicit.
+        const previous = await loadCredentials();
+        let pending = await loadPendingDevice();
+        options.signal.throwIfAborted();
+        const config = await configuration(options.signal);
+        async function finishAuthorization(value) {
+            let saved = value;
+            const organization = await chooseLoginOrganization(async (query, page, selected = '') => {
+                const params = new URLSearchParams({ q: query, page: String(page), ...(selected ? { organization_id: selected } : {}) });
+                const choices = await authorized('/api/auth/native/organizations?' + params, { signal: options.signal }, saved.access_token);
+                if (!nativeOrganizationsMatch(choices, saved.subject, query, page, selected))
+                    throw new CliError('organization_unconfirmed', 'Organization access could not be confirmed. No workspace was selected.', 2);
+                return choices;
+            }, options);
+            if (organization && organization !== organizationClaim(saved.access_token)) {
+                await saveCredentials({ ...saved, state: 'refresh_pending' }, options.signal);
+                const switched = await tokenRequest(config, { grant_type: 'refresh_token', refresh_token: saved.refresh_token,
+                    organization_id: organization }, options.signal);
+                if (switched.status !== 200)
+                    throw new CliError('organization_authorization_required', 'The selected organization was not authorized. Complete its browser sign-in before trying again. No workspace access was granted.', 2);
+                saved = credentials(switched.body, config, saved, organization);
+            }
+            await saveCredentials({ ...saved, state: 'ready' }, options.signal);
+            return authorized('/api/auth/native/register', { method: 'POST', body: { label: 'Terminal' }, signal: options.signal }, saved.access_token);
+        }
+        if (previous?.state === 'organization_selection_pending' && previous.client_id === config.client_id && previous.expires_at > Date.now() / 1000 + 60) {
+            // The single-use exchange already returned and its exact credentials are
+            // retained. Resume organization selection, not a new device exchange.
+            await removePendingDevice(options.signal);
+            return finishAuthorization(previous);
+        }
+        if (pending && pending.expires_at <= Date.now() / 1000) {
+            if (pending.state === 'polling')
+                throw new CliError('authorization_exchange_uncertain', 'The previous authorization exchange was not confirmed. Review Account access in the browser. Use logout --local-only to clear its local attempt before starting another; this does not revoke an unknown cloud credential.', 2);
+            await removePendingDevice(options.signal);
+            pending = null;
+        }
+        if (pending && (pending.client_id !== config.client_id || new URL(pending.verification_url).origin !== config.verification_origin
+            || pending.organization_hint !== (options.organization ?? null)))
+            throw new CliError('authorization_intent_changed', 'An original authorization is pending for different settings. Resume it with its original options or clear it with logout --local-only. No replacement was created.', 2);
+        if (pending?.state === 'polling')
+            throw new CliError('authorization_exchange_uncertain', 'The original token exchange was interrupted and cannot be safely repeated. Review Account access in the browser. Clear the local attempt with logout --local-only before starting another.', 2);
+        if (!pending) {
+            const grant = await jsonRequest(new URL(config.device_authorization_endpoint), { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ client_id: config.client_id }), signal: options.signal });
+            if (grant.status !== 200)
+                throw new CliError('device_authorization_failed', 'Browser sign-in could not be started.');
+            const value = grant.body;
+            let link;
+            try {
+                const base = new URL(value.verification_uri);
+                link = new URL(value.verification_uri_complete ?? value.verification_uri);
+                if (base.origin !== config.verification_origin || link.origin !== config.verification_origin || base.pathname !== '/device'
+                    || link.pathname !== '/device' || link.username || link.password || link.hash || base.search || base.hash
+                    || typeof value.device_code !== 'string' || !value.device_code || value.device_code.length > 16384
+                    || !/^[A-Z0-9-]{4,64}$/.test(value.user_code) || !Number.isInteger(value.expires_in) || value.expires_in < 1 || value.expires_in > 3600
+                    || value.interval !== undefined && (!Number.isInteger(value.interval) || value.interval < 1 || value.interval > 300)
+                    || [...link.searchParams.keys()].some(key => key !== 'user_code')
+                    || link.search && link.searchParams.get('user_code') !== value.user_code)
+                    throw new Error();
+            }
+            catch {
+                throw new CliError('device_authorization_invalid', 'The browser sign-in response was not accepted.');
+            }
+            const interval = value.interval ?? 5;
+            pending = { schema: 'firedrill.device-authorization.v1', id: randomUUID(), state: 'waiting', client_id: config.client_id,
+                organization_hint: options.organization ?? null, device_code: value.device_code, user_code: value.user_code,
+                verification_url: link.href, expires_at: Math.floor(Date.now() / 1000) + value.expires_in,
+                interval, next_poll_at: Date.now() + interval * 1000 };
+            await savePendingDevice(pending, options.signal);
+        }
+        const instruction = { type: 'authorization_required', authorization_id: pending.id, verification_url: pending.verification_url,
+            user_code: pending.user_code, expires_in: Math.max(0, pending.expires_at - Math.floor(Date.now() / 1000)), payment_required: false };
+        if (options.json)
+            process.stdout.write(JSON.stringify({ ...instruction, credential_mode: session ? 'session' : 'persistent' }) + '\n');
+        else
+            process.stderr.write(`Open ${pending.verification_url}\nCode: ${pending.user_code}\nNo credit card required. ${session
+                ? 'Session-only: this sign-in stays in memory and ends when this companion stops; if interrupted, start sign-in again.'
+                : 'Run the same command to resume if interrupted.'}\n`);
+        if (launchBrowser)
+            await openBrowser(pending.verification_url);
+        while (Date.now() < pending.expires_at * 1000) {
+            await sleep(Math.min(Math.max(0, pending.next_poll_at - Date.now()), Math.max(0, pending.expires_at * 1000 - Date.now())), undefined, { signal: options.signal });
+            options.signal.throwIfAborted();
+            if (Date.now() >= pending.expires_at * 1000)
+                break;
+            pending = { ...pending, state: 'polling' };
+            await savePendingDevice(pending, options.signal);
+            const result = await tokenRequest(config, { grant_type: 'urn:ietf:params:oauth:grant-type:device_code', device_code: pending.device_code }, options.signal);
+            if (result.status === 200) {
+                const saved = credentials(result.body, config);
+                await saveCredentials({ ...saved, state: 'organization_selection_pending' }, options.signal);
+                await removePendingDevice(options.signal);
+                // A lost registration reply is recoverable with this same retained
+                // provider session. Never exchange the single-use device code again.
+                return finishAuthorization(saved);
+            }
+            const error = result.body && typeof result.body === 'object' ? result.body.error : undefined;
+            if (error === 'authorization_pending' || error === 'slow_down') {
+                // RFC 8628: slow_down permanently adds 5 seconds to the polling interval.
+                const interval = error === 'slow_down' ? Math.min(3600, pending.interval + 5) : pending.interval;
+                pending = { ...pending, state: 'waiting', interval, next_poll_at: Date.now() + interval * 1000 };
+                await savePendingDevice(pending, options.signal);
+                continue;
+            }
+            // A definitive provider answer: the device code is spent or refused.
+            await removePendingDevice(options.signal);
+            if (error === 'access_denied')
+                throw new CliError('authorization_denied', 'Browser authorization was declined. No terminal access was granted.', 2);
+            if (error === 'expired_token')
+                throw new CliError('authorization_expired', 'Browser sign-in expired before it was approved. Run firedrill login again. No terminal access was granted.', 2);
+            throw new CliError('authorization_ended', 'Browser authorization ended. Start sign-in again. No terminal access was granted.', 2);
+        }
+        await removePendingDevice(options.signal);
+        throw new CliError('authorization_expired', 'Browser sign-in expired. Run firedrill login again.', 2);
+    });
+}
+async function authorized(path, options, accessToken) {
+    if (options.bodyJson !== undefined && (typeof options.bodyJson !== 'string' || options.body !== undefined
+        || Buffer.byteLength(options.bodyJson) > 8 * 1024 * 1024 + 65536)) {
+        throw new CliError('request_body_invalid', 'Provide one bounded JSON request body. Nothing was submitted.', 2);
+    }
+    if (options.idempotencyKey !== undefined && (typeof options.idempotencyKey !== 'string'
+        || !/^[\x21-\x7e]{1,128}$/.test(options.idempotencyKey)))
+        throw new CliError('request_key_invalid', 'Use the saved request identifier.');
+    const route = endpoint(path), method = (options.method ?? 'GET').toUpperCase();
+    const uuid = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+    // Preserve the existing reviewed package pre-effect capacity exception;
+    // the broader projection-unavailable recovery below applies only to GET.
+    const packageOriginal = method === 'POST' && !route.search && (new RegExp(`^/api/workspaces/${uuid}/tools/package-requests$`).test(route.pathname)
+        && typeof options.idempotencyKey === 'string' && new RegExp(`^${uuid}$`).test(options.idempotencyKey)
+        || new RegExp(`^/api/workspaces/${uuid}/tools/package-requests/${uuid}/(?:upload-access|complete)$`).test(route.pathname));
+    const request = { method,
+        headers: { Authorization: `Bearer ${accessToken}`, ...(options.actor ? { 'X-Firedrill-Actor': options.actor } : {}),
+            ...(options.workspace ? { 'X-Firedrill-Workspace': options.workspace } : {}),
+            ...(options.idempotencyKey ? { 'Idempotency-Key': options.idempotencyKey } : {}),
+            ...(options.body === undefined && options.bodyJson === undefined ? {} : { 'Content-Type': 'application/json' }) },
+        body: options.bodyJson ?? (options.body === undefined ? undefined : JSON.stringify(options.body)), signal: options.signal };
+    // Projection refresh is asynchronous and can briefly outlast its freshness
+    // window. Repeat only an answered GET refusal, with exactly the same token,
+    // actor/workspace and path. No new write or credential-exchange retry scope.
+    let recoveryDeadline = performance.now() + 25_000;
+    const readSignal = method === 'GET'
+        ? AbortSignal.any([...(options.signal ? [options.signal] : []), AbortSignal.timeout(25_000)])
+        : options.signal;
+    let result = await jsonRequest(route, { ...request, signal: readSignal }, options.maximumResponseBytes);
+    if (method !== 'GET')
+        recoveryDeadline = performance.now() + 10_000;
+    for (let attempt = 1; attempt < (method === 'GET' ? 9 : 3)
+        && (method === 'GET' || method === 'HEAD' || packageOriginal); attempt += 1) {
+        if (result.status !== 503 || !(method === 'GET'
+            ? ['identity_service_unavailable', 'identity_refresh_capacity', 'native_authorization_refresh_pending'] : ['identity_refresh_capacity'])
+            .includes(responseError(result.body, result.status).code))
+            break;
+        const wait = Math.max(result.retryAfterMs ?? 0, method === 'GET' ? Math.min(4_000, 500 * 2 ** (attempt - 1)) : 1_100)
+            + Math.floor(Math.random() * 250);
+        const remaining = recoveryDeadline - performance.now();
+        // Never retry earlier than an advertised delay, or extend the finite
+        // recovery window. A network/parse/timeout failure below escapes unchanged.
+        if (wait >= remaining)
+            break;
+        readSignal?.throwIfAborted();
+        await sleep(wait, undefined, { signal: readSignal });
+        const budget = recoveryDeadline - performance.now();
+        if (budget <= 0)
+            break;
+        const signal = method === 'GET' ? readSignal
+            : AbortSignal.any([...(options.signal ? [options.signal] : []), AbortSignal.timeout(Math.ceil(budget))]);
+        result = await jsonRequest(route, { ...request, signal }, options.maximumResponseBytes);
+    }
+    if (result.status < 200 || result.status >= 300)
+        throw responseError(result.body, result.status);
+    let matches = true;
+    if (['/api/auth/native/register', '/api/auth/native/session'].includes(route.pathname) || route.pathname === '/api/auth/native/workspaces' && method === 'POST') {
+        const choice = options.body && typeof options.body === 'object' && 'workspace_id' in options.body ? options.body.workspace_id : undefined;
+        matches = nativeSessionMatches(result.body, { actor: options.actor, workspace: typeof choice === 'string' ? choice : undefined });
+    }
+    else if (route.pathname === '/api/auth/native/workspaces' && method === 'GET') {
+        matches = nativeWorkspacesMatch(result.body, options.actor, route.searchParams.get('q') ?? '', Number(route.searchParams.get('page') ?? '1'));
+    }
+    else if (route.pathname === '/api/auth/native/organizations' && method === 'GET') {
+        try {
+            const subject = JSON.parse(Buffer.from(accessToken.split('.')[1], 'base64url').toString('utf8')).sub;
+            matches = nativeOrganizationsMatch(result.body, subject, route.searchParams.get('q') ?? '', Number(route.searchParams.get('page') ?? '1'), route.searchParams.get('organization_id') ?? '', options.actor);
+        }
+        catch {
+            matches = false;
+        }
+    }
+    else if (route.pathname === '/api/auth/native/membership-sync')
+        matches = nativeMembershipSyncMatches(result.body);
+    else if (route.pathname === '/api/auth/native/revoke')
+        matches = nativeRevokedMatches(result.body, options.actor);
+    if (!matches)
+        throw new CliError('native_identity_unconfirmed', 'Terminal identity or original selected access could not be confirmed. No additional action was sent.');
+    return result.body;
+}
+async function readyCredentials(signal) {
+    signal?.throwIfAborted();
+    let saved = await loadCredentials();
+    const again = credentialMode() === 'session' ? 'Stop this companion and run firedrill init --session-only again' : 'Run firedrill login again';
+    if (!saved)
+        throw new CliError('authentication_required', credentialMode() === 'session'
+            ? 'This session-only companion is not signed in. Stop it and run firedrill init --session-only.' : 'Run firedrill login to authorize this terminal.', 2);
+    if (saved.state === 'organization_selection_pending')
+        throw new CliError('organization_selection_required', `Organization selection was not completed. ${again}. No workspace access was granted.`, 2);
+    if (saved.state === 'refresh_pending')
+        throw new CliError('refresh_reconciliation_required', `A prior token refresh was not confirmed. ${again}; the old refresh token is not retried.`, 2);
+    if (saved.expires_at <= Date.now() / 1000 + 60) {
+        const config = await configuration(signal);
+        if (config.client_id !== saved.client_id)
+            throw new CliError('auth_configuration_changed', 'Sign in again to use this application.', 2);
+        await saveCredentials({ ...saved, state: 'refresh_pending' }, signal);
+        const organization = organizationClaim(saved.access_token);
+        const result = await tokenRequest(config, { grant_type: 'refresh_token', refresh_token: saved.refresh_token,
+            ...(organization ? { organization_id: organization } : {}) }, signal);
+        if (result.status !== 200)
+            throw new CliError('refresh_not_confirmed', 'The refresh was not confirmed. Sign in again rather than retrying the old token.', 2);
+        saved = credentials(result.body, config, saved);
+        await saveCredentials(saved, signal);
+    }
+    return saved;
+}
+const SESSION_COMPANION_REQUIRED = 'No signed-in session-only companion is running. Run `firedrill run` or `firedrill init --session-only` in another terminal, or sign in with an OS credential store.';
+/** A session-mode client process: credentials live in another (companion) process. */
+function sessionClient() { return credentialMode() === 'session' && !isCredentialCompanion(); }
+async function companionAccessToken(signal) {
+    try {
+        return (await companionRequest('access-token', signal)).access_token;
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === 'companion_unavailable')
+            throw new CliError('session_companion_required', SESSION_COMPANION_REQUIRED, 2);
+        throw error;
+    }
+}
+let readingCredentials = null;
+export async function access(work) {
+    // Session-mode clients never read a store: the companion refreshes in its own
+    // memory (refresh_pending first, no blind retry) and returns a short-lived
+    // access token over authenticated local IPC. Nothing is cached on disk.
+    if (sessionClient())
+        return work(await companionAccessToken());
+    // Serialize keyring/refresh intent, not unrelated business requests. Keeping
+    // the OS credential lock through evidence/model HTTP would prevent the same
+    // runner's presence keeper from maintaining its original finite lease.
+    const reading = readingCredentials ??= credentialLock(active => readyCredentials(active));
+    let credentials;
+    try {
+        credentials = await reading;
+    }
+    finally {
+        if (readingCredentials === reading)
+            readingCredentials = null;
+    }
+    return work(credentials.access_token);
+}
+export async function api(path, options = {}) {
+    return access(async (token) => {
+        try {
+            return await authorized(path, options, token);
+        }
+        catch (error) {
+            if (!(error instanceof CliError) || error.code !== 'native_session_required')
+                throw error;
+            await authorized('/api/auth/native/register', { method: 'POST', body: { label: 'Terminal' } }, token);
+            if (options.method && options.method !== 'GET')
+                throw new CliError('native_session_registered', 'Terminal registration is saved. Run the original command again; it did not pass authentication.');
+            return authorized(path, options, token);
+        }
+    });
+}
+export async function logout(options) {
+    if (sessionClient()) {
+        // Revoke with the companion's current token, then stop the companion so its
+        // volatile credentials end. --local-only only stops the companion.
+        let revoked = false;
+        if (!options.localOnly) {
+            const result = await authorized('/api/auth/native/revoke', { method: 'POST' }, await companionAccessToken());
+            if (result.revoked !== true)
+                throw new CliError('revocation_unconfirmed', 'Terminal revocation was not confirmed. The companion was left running.');
+            revoked = true;
+        }
+        try {
+            await companionRequest('shutdown');
+        }
+        catch (error) {
+            if (!(error instanceof CliError && error.code === 'companion_unavailable'))
+                throw new CliError('companion_shutdown_unconfirmed', `${revoked ? 'Terminal access was revoked, but the' : 'The'} companion did not confirm shutdown. Stop it with Ctrl-C in its terminal.`, 2);
+        }
+        return { revoked, local_removed: true };
+    }
+    return credentialLock(async (active) => {
+        const saved = await loadCredentials();
+        const pending = await loadPendingDevice();
+        if (options.localOnly || !saved) {
+            await removePendingDevice(active);
+            await removeCredentials(active);
+            return { revoked: false, local_removed: true };
+        }
+        // A prior refresh can be uncertain while its old access token is still
+        // valid. Use that only to revoke its own existing session, never to refresh
+        // again or execute resource actions. Expired state needs browser recovery.
+        const current = saved.expires_at > Date.now() / 1000 + 5 ? saved : await readyCredentials(active);
+        const result = await authorized('/api/auth/native/revoke', { method: 'POST', signal: active }, current.access_token);
+        if (result.revoked !== true)
+            throw new CliError('revocation_unconfirmed', 'Terminal revocation was not confirmed.');
+        await removePendingDevice(active);
+        await removeCredentials(active);
+        return { revoked: pending?.state !== 'polling', local_removed: true };
+    });
+}
+/**
+ * Start the companion IPC server in the process selected as companion by
+ * configureCredentialMode(). Session mode serves short-lived access tokens to
+ * same-user CLI processes; persistent mode serves status only (clients read the
+ * OS store themselves). Closing erases volatile credentials. The caller wires
+ * SIGINT/SIGTERM/SIGHUP to handle.close('signal').
+ */
+export async function startCredentialCompanion(options = {}) {
+    if (!isCredentialCompanion())
+        throw new CliError('companion_role_required', 'This process was not started as the Firedrill companion. No local access was opened.', 2);
+    const mode = credentialMode();
+    // Refreshes run under the companion's lifetime, not a client's request: a
+    // client that disconnects or times out must never strand refresh_pending or
+    // discard a token pair the identity provider already rotated.
+    const lifetime = new AbortController();
+    return startCompanionServer({ mode, onShutdown: reason => { lifetime.abort(); options.onShutdown?.(reason); }, handlers: {
+            status: async () => {
+                if (mode === 'session')
+                    return volatileCredentialSummary();
+                const saved = await loadCredentials().catch(() => null);
+                return { signed_in: saved?.state === 'ready', state: saved?.state ?? null, subject: saved?.subject ?? null, expires_at: saved?.expires_at ?? null };
+            },
+            accessToken: async (signal) => {
+                if (mode !== 'session')
+                    throw new CliError('companion_token_not_served', 'This companion uses the OS credential store; other commands read the sign-in from that store. No token was returned.', 2);
+                const work = credentialLock(active => readyCredentials(AbortSignal.any([lifetime.signal, active])));
+                // The request signal only abandons this reply; the refresh itself completes.
+                const ready = await new Promise((resolve, reject) => {
+                    const onAbort = () => reject(new CliError('companion_cancelled', 'The request ended before a token was ready. No token was returned.'));
+                    if (signal.aborted) {
+                        onAbort();
+                        work.catch(() => undefined);
+                        return;
+                    }
+                    signal.addEventListener('abort', onAbort, { once: true });
+                    work.then(value => { signal.removeEventListener('abort', onAbort); resolve(value); }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+                });
+                return { access_token: ready.access_token, expires_at: ready.expires_at };
+            },
+            erase: () => { lifetime.abort(); if (mode === 'session')
+                eraseVolatileCredentials(); },
+        } });
+}
+/** Token-free credential summary for `firedrill status`. */
+export async function credentialOverview(signal) {
+    const mode = credentialMode(), companionProcess = isCredentialCompanion();
+    let running = null;
+    if (!companionProcess) {
+        running = await companionRequest('status', signal).catch(error => {
+            if (error instanceof CliError && error.code === 'companion_unavailable')
+                return null;
+            throw error;
+        });
+    }
+    const companion = running ? { mode: running.mode, pid: running.pid, started_at: running.started_at, signed_in: running.signed_in } : null;
+    if (mode === 'session') {
+        const summary = companionProcess ? volatileCredentialSummary()
+            : { signed_in: running?.mode === 'session' && running.signed_in, state: running?.mode === 'session' ? running.state : null,
+                expires_at: running?.mode === 'session' ? running.expires_at : null };
+        return { mode, companion_process: companionProcess, signed_in: summary.signed_in, state: summary.state, expires_at: summary.expires_at, store: null, companion };
+    }
+    const store = await credentialStoreStatus({ signal });
+    const saved = store.available ? await loadCredentials().catch(() => null) : null;
+    return { mode, companion_process: companionProcess, signed_in: saved?.state === 'ready', state: saved?.state ?? null,
+        expires_at: saved?.expires_at ?? null, store, companion };
+}

package/dist/cli/src/billing-commerce-contracts.js

@@ -0,0 +1 @@
+export * from '../../contracts/billing-commerce-contracts.js';