melchizedek-agents 1.1.0 → 1.3.0

package/dist/lib/chatgpt/oauth.js

@@ -0,0 +1,448 @@
+/**
+ * lib/chatgpt/oauth.ts — OpenAI's Sign in with ChatGPT, plan-usage flow, for a
+ * local app (ADR 0126).
+ *
+ * Implemented from OpenAI's documentation of the flow for open-source apps
+ * that run on the user's machine:
+ *   https://developers.openai.com/siwc/token-sharing-open-source
+ *   https://developers.openai.com/siwc/token-sharing-open-source/sign-in
+ *   https://developers.openai.com/siwc/token-sharing-open-source/profiles-and-sessions
+ *   https://developers.openai.com/siwc/token-sharing-open-source/token-reference
+ *   https://developers.openai.com/siwc/token-sharing-open-source/errors-and-recovery
+ *
+ * THE FLOW: an authorization-code grant with PKCE (S256), a fresh state and
+ * nonce per attempt, and a loopback redirect on http://127.0.0.1:<port>/auth/callback.
+ * The app registers itself dynamically: the first authorization sends
+ * `client_id=dynamic_agent_client` with an `agent_name_hint`, and the callback
+ * returns the client id OpenAI issued, which is kept for every later sign-in
+ * and refresh. No client secret, no pre-registration, and never another
+ * app's client id or stored token. The token request names the resource
+ * `https://api.openai.com/v1`; the ID token is verified (signature against
+ * the issuer's JWKS, iss, aud = the issued client id, exp, nonce) before
+ * anything is saved, and the plan scope must be granted.
+ *
+ * TOKENS: an access token lasts an hour and the refresh token rotates on every
+ * refresh. Refreshes are serialized through a lock file (lib/chatgpt/store.ts)
+ * and an unusable refresh token clears the tokens and asks for a new sign-in.
+ * No token is ever logged or put in an error message.
+ */
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import { trimTrailingSlashes } from '../models/urls.js';
+import { PLAN_SCOPE, isSignedIn, readStoredSignIn } from './state.js';
+import { clearTokens, withSignInLock, writeStoredSignIn } from './store.js';
+export const OPENAI_AUTH_ISSUER = 'https://auth.openai.com';
+/** The resource the tokens are for: the public API, where the Responses endpoint lives. */
+export const OPENAI_API_RESOURCE = 'https://api.openai.com/v1';
+export const SIGNIN_SCOPES = `openid profile email offline_access resource.invoke ${PLAN_SCOPE}`;
+export const CALLBACK_PATH = '/auth/callback';
+/** The client id an app sends before OpenAI has issued it one. */
+export const DYNAMIC_CLIENT_ID = 'dynamic_agent_client';
+export const APP_NAME = 'Melchizedek';
+/** Refresh error codes after which the refresh token is unusable (errors-and-recovery). */
+const UNUSABLE_REFRESH = new Set([
+    'invalid_grant',
+    'invalid_refresh_token',
+    'token_expired',
+    'refresh_token_expired',
+    'refresh_token_invalidated',
+    'refresh_token_reused',
+]);
+/** A sign-in failure: a code for the program, a message for the person, never a token. */
+export class SignInError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SignInError';
+        this.code = code;
+    }
+}
+function isLoopbackHost(host) {
+    return host === '127.0.0.1' || host === 'localhost' || host === '[::1]';
+}
+function issuerOf(opts) {
+    const issuer = trimTrailingSlashes(opts.issuer ?? OPENAI_AUTH_ISSUER);
+    const u = new URL(issuer);
+    if (u.protocol !== 'https:' && !(u.protocol === 'http:' && isLoopbackHost(u.hostname))) {
+        throw new SignInError('bad_issuer', 'The sign-in issuer must be https.');
+    }
+    return issuer;
+}
+/** The issuer's OpenID configuration; every endpoint must be on the issuer's own origin. */
+export async function discover(opts = {}) {
+    const issuer = issuerOf(opts);
+    let data;
+    try {
+        const res = await fetch(`${issuer}/.well-known/openid-configuration`, { redirect: 'error', signal: AbortSignal.timeout(15_000) });
+        data = res.ok ? await res.json() : undefined;
+    }
+    catch {
+        data = undefined;
+    }
+    if (!data || data.issuer !== issuer)
+        throw new SignInError('discovery_failed', 'The ChatGPT sign-in configuration could not be read or verified.');
+    const origin = new URL(issuer).origin;
+    for (const key of ['authorization_endpoint', 'token_endpoint', 'jwks_uri', 'revocation_endpoint']) {
+        const v = data[key];
+        if (v === undefined && key === 'revocation_endpoint')
+            continue;
+        if (typeof v !== 'string' || new URL(v).origin !== origin) {
+            throw new SignInError('discovery_failed', 'The ChatGPT sign-in configuration names an endpoint off the issuer.');
+        }
+    }
+    return data;
+}
+const randomValue = () => randomBytes(32).toString('base64url');
+export const pkceChallenge = (verifier) => createHash('sha256').update(verifier).digest('base64url');
+/** A token-endpoint call: form-encoded, JSON back, the error code (never a token) on failure. */
+async function tokenRequest(endpoint, form) {
+    let res;
+    try {
+        res = await fetch(endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+            body: new URLSearchParams(form),
+            redirect: 'error',
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch {
+        throw new SignInError('network_error', 'Could not reach the ChatGPT sign-in service.');
+    }
+    let data;
+    try {
+        data = await res.json();
+    }
+    catch {
+        data = undefined;
+    }
+    if (!res.ok) {
+        const raw = typeof data?.error === 'string' ? data.error : typeof data?.error?.code === 'string' ? data.error.code : `http_${res.status}`;
+        const code = /^[a-z0-9_.-]{1,64}$/i.test(raw) ? raw : `http_${res.status}`;
+        throw new SignInError(code, `The ChatGPT sign-in service refused the request (${code}).`);
+    }
+    if (!data || typeof data !== 'object')
+        throw new SignInError('invalid_token_response', 'The ChatGPT sign-in service returned an unreadable token response.');
+    return data;
+}
+/** An `earliest_refresh_at` as epoch milliseconds (seconds, milliseconds or an ISO date), when present. */
+function epochMs(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v < 1e12 ? v * 1000 : v;
+    if (typeof v === 'string') {
+        const t = Date.parse(v);
+        return Number.isFinite(t) ? t : undefined;
+    }
+    return undefined;
+}
+/** The token fields a response carries, validated. */
+function tokenFields(data, previousScopes) {
+    const scope = typeof data.scope === 'string' ? data.scope : previousScopes?.join(' ');
+    if (typeof scope !== 'string')
+        throw new SignInError('invalid_token_response', 'The ChatGPT sign-in service did not confirm the granted permissions.');
+    const scopes = scope.split(' ').filter(Boolean);
+    if (typeof data.access_token !== 'string' || !data.access_token ||
+        typeof data.token_type !== 'string' || data.token_type.toLowerCase() !== 'bearer' ||
+        typeof data.expires_in !== 'number' || !(data.expires_in > 0) ||
+        typeof data.refresh_token !== 'string' || !data.refresh_token) {
+        throw new SignInError('invalid_token_response', 'The ChatGPT sign-in service returned incomplete credentials.');
+    }
+    const earliest = epochMs(data.earliest_refresh_at);
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt: Date.now() + data.expires_in * 1000,
+        ...(earliest !== undefined ? { earliestRefreshAt: earliest } : {}),
+        scopes,
+    };
+}
+/** Verify an ID token against the issuer's keys; the verified subject. */
+async function verifyIdToken(idToken, d, clientId, nonce) {
+    if (typeof idToken !== 'string' || !idToken)
+        throw new SignInError('invalid_id_token', 'The ChatGPT sign-in returned no verifiable identity.');
+    try {
+        const { payload } = await jwtVerify(idToken, createRemoteJWKSet(new URL(d.jwks_uri)), {
+            issuer: d.issuer,
+            audience: clientId,
+            algorithms: ['RS256'],
+            clockTolerance: 5,
+            requiredClaims: ['iss', 'aud', 'exp', 'iat', 'sub'],
+        });
+        if (typeof payload.sub !== 'string' || !payload.sub)
+            throw new Error('no subject');
+        if (nonce !== undefined && payload.nonce !== nonce)
+            throw new Error('nonce');
+        if (payload.azp !== undefined && payload.azp !== clientId)
+            throw new Error('azp');
+        return payload.sub;
+    }
+    catch {
+        throw new SignInError('invalid_id_token', 'The ChatGPT identity could not be verified. Sign in again.');
+    }
+}
+// ── The loopback listener ────────────────────────────────────────────────────
+const CLIENT_ID_SHAPE = /^[A-Za-z0-9_-]{1,200}$/;
+const PAGE_HEADERS = {
+    'content-type': 'text/html; charset=utf-8',
+    'cache-control': 'no-store',
+    'referrer-policy': 'no-referrer',
+    'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'",
+};
+const page = (title, body) => `<!doctype html><html lang="en"><meta charset="utf-8"><title>${title}</title><style>body{font:16px system-ui;max-width:32rem;margin:15vh auto;padding:24px}</style><h1>${title}</h1><p>${body}</p></html>`;
+/**
+ * A one-shot listener on 127.0.0.1. A request with the wrong host, path,
+ * method or state is refused (400 or 404) and does not end the wait: an
+ * unrelated loopback request must not cancel a sign-in in progress.
+ */
+async function listen(port, state, savedClientId, timeoutMs, signal) {
+    let settle;
+    let done = false;
+    const result = new Promise((resolve, reject) => {
+        settle = (v) => {
+            if (done)
+                return;
+            done = true;
+            if (v instanceof SignInError)
+                reject(v);
+            else
+                resolve(v);
+        };
+    });
+    result.catch(() => undefined);
+    let bound = port;
+    const expected = Buffer.from(state);
+    const handler = (req, res) => {
+        let url;
+        try {
+            url = new URL(req.url ?? '/', `http://127.0.0.1:${bound}`);
+        }
+        catch {
+            res.writeHead(400).end();
+            return;
+        }
+        if (done || req.method !== 'GET' || req.headers.host !== `127.0.0.1:${bound}` || url.pathname !== CALLBACK_PATH) {
+            res.writeHead(404).end();
+            return;
+        }
+        const states = url.searchParams.getAll('state');
+        const got = Buffer.from(states[0] ?? '');
+        if (states.length !== 1 || got.length !== expected.length || !timingSafeEqual(got, expected)) {
+            res.writeHead(400, PAGE_HEADERS).end(page('Sign-in not recognized', 'This sign-in response does not match the one Melchizedek started. Return to the terminal and try again.'));
+            return;
+        }
+        if (url.searchParams.has('error')) {
+            res.writeHead(200, PAGE_HEADERS).end(page('Sign-in cancelled', 'You can close this tab and return to the terminal.'));
+            const raw = url.searchParams.get('error') ?? '';
+            const code = /^[a-z0-9_.-]{1,64}$/i.test(raw) ? raw : 'authorization_failed';
+            settle(new SignInError(code, `ChatGPT did not authorize the sign-in (${code}).`));
+            return;
+        }
+        const codes = url.searchParams.getAll('code');
+        const ids = url.searchParams.getAll('client_id');
+        const clientId = ids[0] ?? savedClientId;
+        res.writeHead(200, PAGE_HEADERS).end(page('Return to the terminal', 'Melchizedek is finishing your ChatGPT sign-in. You can close this tab.'));
+        if (codes.length !== 1 || !codes[0] || ids.length > 1 ||
+            !clientId || !CLIENT_ID_SHAPE.test(clientId) || clientId === DYNAMIC_CLIENT_ID ||
+            (savedClientId !== undefined && ids.length === 1 && ids[0] !== savedClientId)) {
+            settle(new SignInError('registration_incomplete', 'ChatGPT did not complete the app registration. Sign in again.'));
+            return;
+        }
+        settle({ code: codes[0], clientId });
+    };
+    const server = createServer(handler);
+    server.requestTimeout = 15_000;
+    server.headersTimeout = 10_000;
+    await new Promise((resolve, reject) => {
+        server.once('error', () => reject(new SignInError('callback_port_unavailable', `Port ${port} on 127.0.0.1 is unavailable for the sign-in callback; pass another with --port.`)));
+        server.listen({ port, host: '127.0.0.1' }, () => {
+            const a = server.address();
+            if (a && typeof a !== 'string')
+                bound = a.port;
+            resolve();
+        });
+    });
+    const timer = setTimeout(() => settle(new SignInError('timeout', 'The ChatGPT sign-in was not completed in time.')), timeoutMs);
+    const abort = () => settle(new SignInError('cancelled', 'The ChatGPT sign-in was cancelled.'));
+    signal?.addEventListener('abort', abort, { once: true });
+    const close = () => {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', abort);
+        server.close();
+        server.closeAllConnections();
+    };
+    return { redirectUri: `http://127.0.0.1:${bound}${CALLBACK_PATH}`, result, close };
+}
+/** Open a URL in the default browser, with no shell. */
+export async function openInBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', url]] : ['xdg-open', [url]];
+    await new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, { stdio: 'ignore', shell: false });
+        child.once('error', () => reject(new SignInError('browser_unavailable', 'The browser could not be opened; open the printed link yourself.')));
+        child.once('exit', (code) => (code === 0 ? resolve() : reject(new SignInError('browser_unavailable', 'The browser could not be opened; open the printed link yourself.'))));
+    });
+}
+/**
+ * The browser sign-in. Stores the registration (host id, issued client id)
+ * before the code exchange, and the tokens after the ID token verifies and
+ * the plan scope is confirmed.
+ */
+export async function signIn(opts) {
+    const issuer = issuerOf(opts);
+    const d = await discover({ issuer });
+    const previous = readStoredSignIn(opts.file);
+    const sameIssuer = previous?.issuer === issuer;
+    const hostId = previous?.hostId ?? `urn:uuid:${randomUUID()}`;
+    const savedClientId = sameIssuer ? previous?.clientId : undefined;
+    const state = randomValue();
+    const nonce = randomValue();
+    const verifier = randomValue();
+    const listener = await listen(opts.port ?? 0, state, savedClientId, opts.timeoutMs ?? 5 * 60_000, opts.signal);
+    try {
+        const auth = new URL(d.authorization_endpoint);
+        auth.search = new URLSearchParams({
+            client_id: savedClientId ?? DYNAMIC_CLIENT_ID,
+            response_type: 'code',
+            redirect_uri: listener.redirectUri,
+            scope: SIGNIN_SCOPES,
+            resource: OPENAI_API_RESOURCE,
+            state,
+            nonce,
+            code_challenge_method: 'S256',
+            code_challenge: pkceChallenge(verifier),
+            ext_agent_host_id: hostId,
+            ...(savedClientId ? {} : { agent_name_hint: APP_NAME }),
+        }).toString();
+        opts.onUrl?.(auth.toString());
+        await (opts.openBrowser ?? openInBrowser)(auth.toString()).catch((err) => {
+            // The printed link still works; only a cancelled sign-in ends here.
+            if (!(err instanceof SignInError) || err.code !== 'browser_unavailable')
+                throw err;
+        });
+        const cb = await listener.result;
+        // Keep the issued registration even if the one-time code fails below.
+        const registration = sameIssuer && previous
+            ? { ...previous, clientId: cb.clientId, hostId }
+            : { version: 1, issuer, hostId, clientId: cb.clientId };
+        writeStoredSignIn(opts.file, registration);
+        const data = await tokenRequest(d.token_endpoint, {
+            grant_type: 'authorization_code',
+            client_id: cb.clientId,
+            code: cb.code,
+            code_verifier: verifier,
+            redirect_uri: listener.redirectUri,
+            resource: OPENAI_API_RESOURCE,
+        });
+        const subject = await verifyIdToken(data.id_token, d, cb.clientId, nonce);
+        const fields = tokenFields(data);
+        const planUsage = fields.scopes.includes(PLAN_SCOPE);
+        if (!planUsage) {
+            throw new SignInError('plan_not_granted', 'The sign-in did not grant use of your ChatGPT plan; sign in again and allow it.');
+        }
+        writeStoredSignIn(opts.file, { ...registration, subject, ...fields, savedAt: new Date().toISOString() });
+        return { subject, scopes: fields.scopes, expiresAt: fields.expiresAt, planUsage };
+    }
+    finally {
+        listener.close();
+    }
+}
+/** One refresh of the stored session; the caller holds the lock. */
+async function refreshOnce(file, s, opts) {
+    const issuer = issuerOf(opts);
+    if (s.issuer !== issuer || !s.clientId || !s.refreshToken) {
+        throw new SignInError('not_signed_in', 'The stored ChatGPT sign-in cannot be refreshed here; sign in again.');
+    }
+    const d = await discover({ issuer });
+    let data;
+    try {
+        data = await tokenRequest(d.token_endpoint, {
+            grant_type: 'refresh_token',
+            client_id: s.clientId,
+            refresh_token: s.refreshToken,
+            resource: OPENAI_API_RESOURCE,
+        });
+    }
+    catch (err) {
+        if (err instanceof SignInError && UNUSABLE_REFRESH.has(err.code)) {
+            clearTokens(file);
+            throw new SignInError('signin_expired', 'Your ChatGPT sign-in has expired or was revoked; run `melchizedek-setup --chatgpt-signin` again.');
+        }
+        throw err;
+    }
+    const fields = tokenFields(data, s.scopes);
+    if (data.id_token !== undefined) {
+        const subject = await verifyIdToken(data.id_token, d, s.clientId);
+        if (s.subject && subject !== s.subject)
+            throw new SignInError('account_mismatch', 'The refreshed ChatGPT identity is a different account; sign in again.');
+    }
+    const next = { ...s, ...fields, savedAt: new Date().toISOString() };
+    writeStoredSignIn(file, next);
+    return next;
+}
+const SKEW_MS = 120_000;
+/**
+ * A usable access token from the credential file, refreshed when it is within
+ * two minutes of expiry (and past `earliest_refresh_at`). Refreshes take the
+ * file's lock and re-read it first, so a refresh another process just made is
+ * used rather than repeated.
+ */
+export async function freshAccessToken(file, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const fresh = (s) => isSignedIn(s) && (s.expiresAt ?? 0) - SKEW_MS > now();
+    const notSignedIn = () => new SignInError('not_signed_in', `No ChatGPT sign-in is stored at ${file}; run \`melchizedek-setup --chatgpt-signin\`.`);
+    const first = readStoredSignIn(file);
+    if (!isSignedIn(first))
+        throw notSignedIn();
+    if (fresh(first))
+        return first.accessToken;
+    return withSignInLock(file, async () => {
+        const s = readStoredSignIn(file);
+        if (!isSignedIn(s))
+            throw notSignedIn();
+        if (fresh(s))
+            return s.accessToken;
+        const valid = (s.expiresAt ?? 0) > now();
+        if (valid && s.earliestRefreshAt !== undefined && now() < s.earliestRefreshAt)
+            return s.accessToken;
+        return (await refreshOnce(file, s, opts)).accessToken;
+    });
+}
+/**
+ * Sign out: the tokens leave the file (the host id and issued client id
+ * stay, for the next sign-in), and the refresh token is revoked at the
+ * issuer. `revoked: false` means the local tokens are gone but the remote
+ * revocation was not confirmed: disconnect the app in ChatGPT's settings.
+ */
+export async function signOut(file, opts = {}) {
+    const s = readStoredSignIn(file);
+    if (!s?.refreshToken) {
+        if (s)
+            clearTokens(file);
+        return { hadTokens: false, revoked: false };
+    }
+    clearTokens(file);
+    try {
+        const d = await discover(opts);
+        if (!d.revocation_endpoint || !s.clientId)
+            return { hadTokens: true, revoked: false };
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const res = await fetch(d.revocation_endpoint, {
+                method: 'POST',
+                headers: { 'content-type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams({ token: s.refreshToken, token_type_hint: 'refresh_token', client_id: s.clientId }),
+                redirect: 'error',
+                signal: AbortSignal.timeout(10_000),
+            }).catch(() => undefined);
+            await res?.body?.cancel().catch(() => undefined);
+            if (res?.status === 200)
+                return { hadTokens: true, revoked: true };
+            if (res && res.status < 500)
+                break;
+        }
+    }
+    catch {
+        // The local tokens are gone either way.
+    }
+    return { hadTokens: true, revoked: false };
+}

package/dist/lib/chatgpt/state.d.ts

@@ -0,0 +1,98 @@
+/**
+ * lib/chatgpt/state.ts — where a Sign in with ChatGPT credential lives, whether
+ * it is the OpenAI path, and the served-surface refusal (ADR 0126).
+ *
+ * WHY a leaf (node:fs, node:os, node:path only):
+ *   The gateway's transport rule (lib/models/gateway.ts), the doctor, the
+ *   resolver and every served bin ask the same two questions — is a sign-in
+ *   stored, and does it carry OpenAI ids here — so the answer lives in one
+ *   module with no adapter or SDK in its import graph.
+ *
+ * LOCAL ONLY:
+ *   OpenAI's plan-usage flow is for open-source apps that run on the user's
+ *   own machine (developers.openai.com/siwc/token-sharing-open-source). The
+ *   A2A server, the worker and any other served surface call
+ *   `refuseChatGptSignInOnServedSurface` at startup and stop while the
+ *   sign-in would carry OpenAI ids; `markServedSurface` also makes the
+ *   adapter refuse at call time, so a surface that skipped the startup check
+ *   still never spends a person's ChatGPT plan on someone else's request.
+ *
+ * WHAT IT NEVER DOES: return or print a token. The status carries presence,
+ * times and the file's path.
+ */
+/** Where the credential file lives, when not the default (a path; never a value). */
+export declare const CHATGPT_SIGNIN_FILE_ENV = "MELCHIZEDEK_CHATGPT_SIGNIN_FILE";
+/** `off` ignores a stored sign-in (a served process on a machine that also signed in). */
+export declare const CHATGPT_SIGNIN_ENV = "MELCHIZEDEK_CHATGPT_SIGNIN";
+/** The scope that lets the token use the person's ChatGPT plan. */
+export declare const PLAN_SCOPE = "chatgpt.tokens.use.direct";
+/** What the credential file holds (version 1). Tokens are present only while signed in. */
+export interface StoredSignIn {
+    version: 1;
+    /** The authorization server the registration belongs to. */
+    issuer: string;
+    /** This installation's opaque host id (`urn:uuid:…`), kept across sign-outs. */
+    hostId: string;
+    /** The client id OpenAI issued at the first sign-in, kept across sign-outs. */
+    clientId?: string;
+    /** The verified account subject of the last sign-in. */
+    subject?: string;
+    scopes?: string[];
+    accessToken?: string;
+    refreshToken?: string;
+    /** Epoch milliseconds. */
+    expiresAt?: number;
+    /** Epoch milliseconds before which a refresh is not attempted while the token is valid. */
+    earliestRefreshAt?: number;
+    savedAt?: string;
+}
+/** The sign-in as the doctor and the bins see it: presence and times, never a token. */
+export interface ChatGptSignInStatus {
+    /** False when MELCHIZEDEK_CHATGPT_SIGNIN=off. */
+    enabled: boolean;
+    file: string;
+    /** A credential file exists at `file`. */
+    present: boolean;
+    /** It holds a refresh token and the plan scope. */
+    signedIn: boolean;
+    /** Epoch milliseconds the access token expires, when signed in. */
+    expiresAt?: number;
+    /** Why a present file cannot be used (permissions, shape). */
+    problem?: string;
+}
+/** The credential file: MELCHIZEDEK_CHATGPT_SIGNIN_FILE, else ~/.melchizedek/chatgpt-signin.json. */
+export declare function signInFile(env?: NodeJS.ProcessEnv): string;
+/** The git work tree a path sits inside, if any (an ancestor holding `.git`). */
+export declare function insideGitWorkTree(file: string): string | undefined;
+/** Whether a parsed value has the stored shape. */
+export declare function isStoredSignIn(v: unknown): v is StoredSignIn;
+/**
+ * Read the credential file: undefined when absent; throws, naming the file
+ * and never its content, when it is readable by others or malformed.
+ */
+export declare function readStoredSignIn(file: string): StoredSignIn | undefined;
+/** Signed in: a refresh token, and the plan scope granted. */
+export declare function isSignedIn(s: StoredSignIn | undefined): boolean;
+/** The stored sign-in's status under this environment. */
+export declare function chatGptSignInStatus(env?: NodeJS.ProcessEnv): ChatGptSignInStatus;
+/**
+ * Whether OpenAI ids would run on the sign-in here: it is enabled and signed
+ * in, no OPENAI_API_KEY is set, and OpenAI is on its own API (no
+ * OPENAI_PLATFORM other than direct, no OPENAI_BASE_URL proxy, which must
+ * never receive the token).
+ */
+export declare function chatGptSignInRoutesOpenAi(env?: NodeJS.ProcessEnv): boolean;
+/** Mark this process a served surface: the sign-in adapter refuses every call from here on. */
+export declare function markServedSurface(surface: string): void;
+/** The served surface this process was marked as, if any. */
+export declare function servedSurface(): string | undefined;
+/** Test seam: forget the mark. */
+export declare function resetServedSurfaceForTests(): void;
+/** The message a served surface stops with. */
+export declare function servedSurfaceMessage(surface: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Called by every served surface at startup: marks the process served, and
+ * throws when the sign-in would carry OpenAI ids here. The A2A app, the A2A
+ * server bin and the worker call it; a new served surface calls it too.
+ */
+export declare function refuseChatGptSignInOnServedSurface(surface: string, env?: NodeJS.ProcessEnv): void;