@bubblebrain-ai/bubble 0.0.63 → 0.0.64

package/dist/oauth/grok.js

@@ -0,0 +1,251 @@
+/**
+ * xAI Grok subscription OAuth login (PKCE + local callback).
+ *
+ * Mirrors the public OAuth client used by the official Grok CLI so a Grok
+ * subscription can drive Bubble's native agent loop the same way ChatGPT
+ * OAuth does: browser sign-in once, then bearer + refresh tokens stored in
+ * ~/.bubble/auth.json.
+ */
+import { createServer } from "node:http";
+import { exec } from "node:child_process";
+import { randomBytes, createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { withOAuthRefreshTimeout } from "./refresh-control.js";
+import { chatGptFetch } from "../network/chatgpt-transport.js";
+// Public OAuth client registered for the official Grok CLI ("Grok Build").
+const CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+const AUTH_URL = "https://auth.x.ai/oauth2/authorize";
+const TOKEN_URL = "https://auth.x.ai/oauth2/token";
+const SCOPE = "openid profile email offline_access grok-cli:access api:access conversations:read conversations:write";
+function generatePKCE() {
+    const codeVerifier = randomBytes(32).toString("base64url");
+    const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
+    return { codeVerifier, codeChallenge };
+}
+function generateOpaqueId() {
+    return globalThis.crypto?.randomUUID?.() ?? randomBytes(16).toString("hex");
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    exec(`${cmd} ${JSON.stringify(url)}`, () => {
+        // ignore errors; we show manual fallback in UI
+    });
+}
+/**
+ * xAI's OAuth client allows dynamic loopback ports, so listen on an ephemeral
+ * port. Awaiting this returns only once the socket is actually bound, so the
+ * caller can never build an authorization URL around an empty redirect URI.
+ */
+async function startCallbackServer(timeoutMs, onStatus) {
+    let settle = () => { };
+    let fail = () => { };
+    const result = new Promise((resolve, reject) => {
+        settle = resolve;
+        fail = reject;
+    });
+    // Nothing awaits `result` until the caller has a redirect URI, and an early
+    // rejection (bind failure) would otherwise be an unhandled rejection.
+    result.catch(() => { });
+    return new Promise((resolveListening, rejectListening) => {
+        let resolved = false;
+        const finish = (action) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            server.close(action);
+        };
+        const server = createServer((req, res) => {
+            try {
+                const port = server.address().port;
+                const url = new URL(req.url || "/", `http://127.0.0.1:${port}`);
+                if (url.pathname === "/callback") {
+                    const code = url.searchParams.get("code");
+                    const state = url.searchParams.get("state");
+                    const error = url.searchParams.get("error");
+                    const errorDesc = url.searchParams.get("error_description");
+                    if (error) {
+                        res.writeHead(400, { "Content-Type": "text/html" });
+                        res.end(`<html><body><h1>Authorization failed</h1><p>${errorDesc || error}</p></body></html>`);
+                        finish(() => fail(new Error(`OAuth error: ${errorDesc || error}`)));
+                        return;
+                    }
+                    if (code) {
+                        res.writeHead(200, { "Content-Type": "text/html" });
+                        res.end("<html><body><h1>Authorization received</h1><p>Return to Bubble to check whether sign-in completed. Bubble still needs to exchange and save your credentials.</p></body></html>");
+                        finish(() => settle({ code, state: state || "" }));
+                        return;
+                    }
+                }
+                res.writeHead(404);
+                res.end("Not found");
+            }
+            catch {
+                res.writeHead(500);
+                res.end("Error");
+            }
+        });
+        // Unref'd so a pending login never keeps the process alive on its own,
+        // and cleared on completion so a successful login does not leave the
+        // event loop holding a five-minute timer.
+        const timer = setTimeout(() => {
+            finish(() => fail(new Error(`OAuth login timed out after ${timeoutMs / 1000}s`)));
+        }, timeoutMs);
+        timer.unref?.();
+        // Without this, a failed bind (port exhausted, sandbox denies listening)
+        // never rejects anything — the login just hangs until the timeout.
+        server.on("error", (error) => {
+            clearTimeout(timer);
+            if (resolved)
+                return;
+            resolved = true;
+            rejectListening(error instanceof Error ? error : new Error(String(error)));
+            fail(error instanceof Error ? error : new Error(String(error)));
+        });
+        server.listen(0, "127.0.0.1", () => {
+            const port = server.address().port;
+            onStatus?.(`Local server listening on http://127.0.0.1:${port}`);
+            // Resolve only once the socket is genuinely bound. The caller used to
+            // race this with a single setImmediate tick and declare failure if the
+            // listen callback had not fired yet — which it frequently has not, since
+            // binding is real async I/O.
+            resolveListening({ redirectUri: `http://127.0.0.1:${port}/callback`, result });
+        });
+    });
+}
+function parseTokenResponse(data, fallbackRefreshToken) {
+    if (!data.access_token || typeof data.access_token !== "string") {
+        throw new Error("xAI returned no access token.");
+    }
+    const refreshToken = data.refresh_token || fallbackRefreshToken;
+    if (!refreshToken) {
+        throw new Error("xAI returned no refresh token.");
+    }
+    const expiresIn = typeof data.expires_in === "number" && data.expires_in > 0 ? data.expires_in : 3600;
+    return {
+        accessToken: data.access_token,
+        refreshToken,
+        expiresAt: Date.now() + expiresIn * 1000,
+    };
+}
+export async function loginGrok(callbacks, options = {}) {
+    const fetchImpl = options.fetch ?? chatGptFetch;
+    callbacks?.onStatus("Starting xAI Grok OAuth login...");
+    const pkce = generatePKCE();
+    const state = generateOpaqueId();
+    const nonce = generateOpaqueId();
+    let redirectUri;
+    let serverPromise;
+    try {
+        const server = await startCallbackServer(5 * 60 * 1000, callbacks?.onStatus);
+        redirectUri = server.redirectUri;
+        serverPromise = server.result;
+    }
+    catch (error) {
+        throw new Error(`The local OAuth callback server could not start: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: CLIENT_ID,
+        redirect_uri: redirectUri,
+        scope: SCOPE,
+        code_challenge: pkce.codeChallenge,
+        code_challenge_method: "S256",
+        state,
+        nonce,
+        referrer: "grok-build",
+    });
+    const authUrl = `${AUTH_URL}?${params.toString()}`;
+    callbacks?.onStatus("Opening browser for authorization...");
+    openBrowser(authUrl);
+    callbacks?.onStatus(`If your browser didn't open, copy this URL manually:\n${authUrl}`);
+    callbacks?.onStatus("Waiting for authorization (timeout: 5min)...");
+    const { code, state: returnedState } = await serverPromise;
+    if (returnedState !== state) {
+        throw new Error("OAuth state mismatch. Possible CSRF attack.");
+    }
+    callbacks?.onStatus("Exchanging authorization code for tokens...");
+    const response = await fetchImpl(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            client_id: CLIENT_ID,
+            code_verifier: pkce.codeVerifier,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "Unknown error");
+        throw new Error(`Token exchange failed: ${response.status} ${response.statusText} - ${text}`);
+    }
+    const tokens = parseTokenResponse((await response.json()));
+    callbacks?.onStatus("Login successful!");
+    return tokens;
+}
+export async function refreshGrok(refreshToken, options = {}) {
+    return withOAuthRefreshTimeout(async (signal) => {
+        const fetchImpl = options.fetch ?? chatGptFetch;
+        const response = await fetchImpl(TOKEN_URL, {
+            method: "POST",
+            signal,
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: refreshToken,
+                client_id: CLIENT_ID,
+            }),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => "Unknown error");
+            throw new Error(`Token refresh failed: ${response.status} ${response.statusText} - ${text}`);
+        }
+        return parseTokenResponse((await response.json()), refreshToken);
+    }, options.timeoutMs);
+}
+/**
+ * One-time credential import from the official Grok CLI's auth store (either
+ * Bubble's isolated runtime profile or the user's real ~/.grok). Users who
+ * already completed `grok login` skip the browser round-trip entirely.
+ */
+export function importGrokCliCredentials(bubbleHome = join(homedir(), ".bubble"), 
+// Injectable so tests can isolate the ~/.grok fallback from the real home
+// directory; production callers rely on the default.
+homeDir = homedir()) {
+    const candidates = [
+        join(bubbleHome, "runtimes", "grok", "grok-home", "auth.json"),
+        join(homeDir, ".grok", "auth.json"),
+    ];
+    for (const path of candidates) {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(path, "utf-8"));
+        }
+        catch {
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object")
+            continue;
+        for (const [key, value] of Object.entries(parsed)) {
+            if (!key.startsWith("https://auth.x.ai::"))
+                continue;
+            if (!value || typeof value !== "object")
+                continue;
+            const entry = value;
+            if (typeof entry.key !== "string" || !entry.key || typeof entry.refresh_token !== "string" || !entry.refresh_token) {
+                continue;
+            }
+            const expiresAt = typeof entry.expires_at === "string" ? Date.parse(entry.expires_at) : NaN;
+            return {
+                accessToken: entry.key,
+                refreshToken: entry.refresh_token,
+                // An unparseable expiry just means the first request refreshes.
+                expiresAt: Number.isFinite(expiresAt) ? expiresAt : 0,
+            };
+        }
+    }
+    return undefined;
+}

package/dist/oauth/index.d.ts

@@ -0,0 +1,4 @@
+export { AuthStorage } from "./storage.js";
+export { loginOpenAICodex, refreshOpenAICodex, type OpenAICodexLoginCallbacks } from "./openai-codex.js";
+export { loginGrok, refreshGrok, importGrokCliCredentials, type GrokLoginCallbacks } from "./grok.js";
+export type { OAuthTokens, OAuthCredentials } from "./types.js";

package/dist/oauth/index.js

@@ -0,0 +1,3 @@
+export { AuthStorage } from "./storage.js";
+export { loginOpenAICodex, refreshOpenAICodex } from "./openai-codex.js";
+export { loginGrok, refreshGrok, importGrokCliCredentials } from "./grok.js";

package/dist/oauth/openai-codex.d.ts

@@ -0,0 +1,15 @@
+/**
+ * OpenAI Codex OAuth login (PKCE + local callback).
+ */
+import type { OAuthTokens } from "./types.js";
+import { type ChatGptFetch } from "../network/chatgpt-transport.js";
+export interface OpenAICodexLoginCallbacks {
+    onStatus: (message: string) => void;
+}
+export declare function loginOpenAICodex(callbacks?: OpenAICodexLoginCallbacks, options?: {
+    fetch?: ChatGptFetch;
+}): Promise<OAuthTokens>;
+export declare function refreshOpenAICodex(refreshToken: string, options?: {
+    fetch?: ChatGptFetch;
+    timeoutMs?: number;
+}): Promise<OAuthTokens>;

package/dist/oauth/openai-codex.js

@@ -0,0 +1,193 @@
+/**
+ * OpenAI Codex OAuth login (PKCE + local callback).
+ */
+import { createServer } from "node:http";
+import { exec } from "node:child_process";
+import { randomBytes, createHash } from "node:crypto";
+import { withOAuthRefreshTimeout } from "./refresh-control.js";
+import { chatGptFetch } from "../network/chatgpt-transport.js";
+const CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+const AUTH_URL = "https://auth.openai.com/oauth/authorize";
+const TOKEN_URL = "https://auth.openai.com/oauth/token";
+const REDIRECT_URI = "http://localhost:1455/auth/callback";
+const SCOPE = "openid profile email offline_access";
+function generatePKCE() {
+    const codeVerifier = randomBytes(32).toString("base64url");
+    const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");
+    return { codeVerifier, codeChallenge };
+}
+function generateState() {
+    return randomBytes(16).toString("hex");
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    exec(`${cmd} ${JSON.stringify(url)}`, () => {
+        // ignore errors; we show manual fallback in UI
+    });
+}
+async function startCallbackServer(port, timeoutMs, onStatus) {
+    return new Promise((resolve, reject) => {
+        let resolved = false;
+        const server = createServer((req, res) => {
+            try {
+                const url = new URL(req.url || "/", `http://127.0.0.1:${port}`);
+                onStatus?.(`Received callback request: ${req.url}`);
+                if (url.pathname === "/auth/callback") {
+                    const code = url.searchParams.get("code");
+                    const state = url.searchParams.get("state");
+                    const error = url.searchParams.get("error");
+                    const errorDesc = url.searchParams.get("error_description");
+                    if (error) {
+                        res.writeHead(400, { "Content-Type": "text/html" });
+                        res.end(`<html><body><h1>Authorization failed</h1><p>${errorDesc || error}</p></body></html>`);
+                        if (!resolved) {
+                            resolved = true;
+                            server.close(() => reject(new Error(`OAuth error: ${errorDesc || error}`)));
+                        }
+                        return;
+                    }
+                    if (code) {
+                        res.writeHead(200, { "Content-Type": "text/html" });
+                        res.end(`<html><body><h1>Authorization received</h1><p>Return to Bubble to check whether sign-in completed. Bubble still needs to exchange and save your credentials.</p></body></html>`);
+                        if (!resolved) {
+                            resolved = true;
+                            server.close(() => resolve({ code, state: state || "" }));
+                        }
+                        return;
+                    }
+                }
+                res.writeHead(404);
+                res.end("Not found");
+            }
+            catch {
+                res.writeHead(500);
+                res.end("Error");
+            }
+        });
+        // This flow binds a FIXED port (the provider only whitelists one redirect
+        // URI), so EADDRINUSE is a realistic outcome — a stale login, or any other
+        // process on the port. Without this handler nothing rejects and the user
+        // stares at "waiting for authorization" for the full timeout.
+        server.on("error", (error) => {
+            if (resolved)
+                return;
+            resolved = true;
+            const detail = error?.code === "EADDRINUSE"
+                ? `port ${port} is already in use — close any other sign-in still running and retry`
+                : error instanceof Error ? error.message : String(error);
+            reject(new Error(`The local OAuth callback server could not start: ${detail}`));
+        });
+        server.listen(port, "127.0.0.1", () => {
+            onStatus?.(`Local server listening on http://127.0.0.1:${port}`);
+        });
+        setTimeout(() => {
+            if (!resolved) {
+                resolved = true;
+                server.close(() => reject(new Error(`OAuth login timed out after ${timeoutMs / 1000}s`)));
+            }
+        }, timeoutMs);
+    });
+}
+function parseJWT(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 3)
+            return null;
+        const payload = Buffer.from(parts[1], "base64url").toString("utf-8");
+        return JSON.parse(payload);
+    }
+    catch {
+        return null;
+    }
+}
+function extractAccountId(idToken) {
+    if (!idToken)
+        return undefined;
+    const claims = parseJWT(idToken);
+    const auth = claims?.["https://api.openai.com/auth"];
+    return auth?.chatgpt_account_id || auth?.account_id || claims?.sub;
+}
+export async function loginOpenAICodex(callbacks, options = {}) {
+    const fetchImpl = options.fetch ?? chatGptFetch;
+    callbacks?.onStatus("Starting OpenAI Codex OAuth login...");
+    const pkce = generatePKCE();
+    const state = generateState();
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: CLIENT_ID,
+        redirect_uri: REDIRECT_URI,
+        scope: SCOPE,
+        code_challenge: pkce.codeChallenge,
+        code_challenge_method: "S256",
+        state,
+        id_token_add_organizations: "true",
+        codex_cli_simplified_flow: "true",
+    });
+    const authUrl = `${AUTH_URL}?${params.toString()}`;
+    callbacks?.onStatus("Starting local callback server on port 1455...");
+    const serverPromise = startCallbackServer(1455, 5 * 60 * 1000, callbacks?.onStatus);
+    callbacks?.onStatus("Opening browser for authorization...");
+    openBrowser(authUrl);
+    callbacks?.onStatus(`If your browser didn't open, copy this URL manually:\n${authUrl}`);
+    callbacks?.onStatus("Waiting for authorization (timeout: 5min)...");
+    const { code, state: returnedState } = await serverPromise;
+    if (returnedState !== state) {
+        throw new Error("OAuth state mismatch. Possible CSRF attack.");
+    }
+    callbacks?.onStatus("Exchanging authorization code for tokens...");
+    const response = await fetchImpl(TOKEN_URL, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: REDIRECT_URI,
+            client_id: CLIENT_ID,
+            code_verifier: pkce.codeVerifier,
+        }),
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => "Unknown error");
+        throw new Error(`Token exchange failed: ${response.status} ${response.statusText} - ${text}`);
+    }
+    const data = (await response.json());
+    const expiresAt = Date.now() + data.expires_in * 1000;
+    const accountId = extractAccountId(data.id_token);
+    callbacks?.onStatus("Login successful!");
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt,
+        idToken: data.id_token,
+        accountId,
+    };
+}
+export async function refreshOpenAICodex(refreshToken, options = {}) {
+    return withOAuthRefreshTimeout(async (signal) => {
+        const fetchImpl = options.fetch ?? chatGptFetch;
+        const response = await fetchImpl(TOKEN_URL, {
+            method: "POST",
+            signal,
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: refreshToken,
+                client_id: CLIENT_ID,
+            }),
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => "Unknown error");
+            throw new Error(`Token refresh failed: ${response.status} ${response.statusText} - ${text}`);
+        }
+        const data = (await response.json());
+        const expiresAt = Date.now() + data.expires_in * 1000;
+        const accountId = extractAccountId(data.id_token);
+        return {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token || refreshToken,
+            expiresAt,
+            idToken: data.id_token,
+            accountId,
+        };
+    }, options.timeoutMs);
+}

package/dist/oauth/refresh-control.d.ts

@@ -0,0 +1,12 @@
+export declare const OAUTH_REFRESH_TIMEOUT_MS = 30000;
+/** Cancel only this caller's wait, never the shared credential rotation.
+ * Keep both handlers attached after cancellation so a late refresh rejection
+ * is observed even when every caller has stopped waiting.
+ */
+export declare function waitForOAuth<T>(promise: Promise<T>, signal?: AbortSignal | null): Promise<T>;
+/** The refresh owner has its own deadline, independent of any chat's signal.
+ * Cover response-body reads as well as connection/headers, and release callers
+ * even if a custom transport fails to honor abort. Only the returned result may
+ * be persisted by the registry; a late response after timeout is discarded.
+ */
+export declare function withOAuthRefreshTimeout<T>(request: (signal: AbortSignal) => Promise<T>, timeoutMs?: number): Promise<T>;

package/dist/oauth/refresh-control.js

@@ -0,0 +1,42 @@
+export const OAUTH_REFRESH_TIMEOUT_MS = 30_000;
+/** Cancel only this caller's wait, never the shared credential rotation.
+ * Keep both handlers attached after cancellation so a late refresh rejection
+ * is observed even when every caller has stopped waiting.
+ */
+export function waitForOAuth(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((resolve, reject) => {
+        const abort = () => {
+            signal.removeEventListener("abort", abort);
+            reject(signal.reason ?? new DOMException("Operation aborted", "AbortError"));
+        };
+        promise.then(value => { signal.removeEventListener("abort", abort); resolve(value); }, error => { signal.removeEventListener("abort", abort); reject(error); });
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener("abort", abort, { once: true });
+    });
+}
+/** The refresh owner has its own deadline, independent of any chat's signal.
+ * Cover response-body reads as well as connection/headers, and release callers
+ * even if a custom transport fails to honor abort. Only the returned result may
+ * be persisted by the registry; a late response after timeout is discarded.
+ */
+export async function withOAuthRefreshTimeout(request, timeoutMs = OAUTH_REFRESH_TIMEOUT_MS) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new Error("Invalid OAuth refresh timeout");
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        const error = new Error("OAuth token refresh timed out. Please try again.");
+        error.name = "TimeoutError";
+        controller.abort(error);
+    }, timeoutMs);
+    timer.unref?.();
+    try {
+        return await waitForOAuth(request(controller.signal), controller.signal);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/oauth/storage.d.ts

@@ -0,0 +1,88 @@
+/**
+ * OAuth credential storage in <bubble home>/auth.json.
+ *
+ * The path is resolved at CONSTRUCTION time through getBubbleHome(), never at
+ * module load: a module-level constant froze the real ~/.bubble at import,
+ * which no test could isolate (known-defects #7) and which ignored
+ * BUBBLE_HOME / dev mode while every other config file honored them
+ * (config.json, sessions, memory all derive from getBubbleHome).
+ *
+ * The file is shared by every Bubble process on the machine (several TUIs, the
+ * desktop app, the Feishu host), and OAuth refresh tokens are single-use, so a
+ * stale copy is not harmless — presenting an already-rotated refresh token is
+ * rejected (`refresh_token_reused`) and forces a new login. Hence:
+ *   - writes are read-merge-write of ONE key plus an atomic rename, never a
+ *     dump of this process's whole in-memory map over the file;
+ *   - reads follow the file (mtime/size check) so a token rotated by another
+ *     process is picked up instead of the stale in-memory one;
+ *   - withRefreshLock() serializes refreshes across processes.
+ *
+ * Node has no flock, so both locks are O_EXCL lock files carrying an owner
+ * token: a holder only ever deletes a lock whose content is its own token,
+ * and stale locks are broken one breaker at a time (see breakLockIfStale), so
+ * a breaker cannot remove a successor's live lock. What remains is a holder
+ * suspended past the stale threshold that resumes and releases in the same
+ * microseconds a breaker acts. The refresh path tolerates even that: results
+ * are stored by compare-and-set, and a rejected token triggers a second look
+ * at the file (ProviderRegistry).
+ */
+import type { OAuthCredentials } from "./types.js";
+export declare class AuthStorage {
+    private data;
+    /** Identity of the file as last read/written, to detect foreign writes. */
+    private diskStamp;
+    private mutationListeners;
+    private readonly authPath;
+    constructor(authPath?: string);
+    /**
+     * Observe credential writes/removals. Callers across the codebase mutate
+     * this storage directly (login/logout flows), so consumers that must react
+     * to credential-identity changes (ProviderRegistry's routing revision)
+     * subscribe here instead of wrapping every call site.
+     */
+    onMutation(listener: (providerId: string) => void): () => void;
+    private notifyMutation;
+    private stampOf;
+    private readDisk;
+    private load;
+    /**
+     * Adopt writes made by other processes; notifies for the keys that changed.
+     * `force` skips the stamp shortcut: a token rotation keeps the file size, so
+     * on a coarse-mtime filesystem the stamp alone can miss it. The refresh and
+     * write paths cannot afford that.
+     */
+    sync(force?: boolean): void;
+    /**
+     * Read-merge-write of a single key: entries owned by other processes survive.
+     * The whole sequence runs under the cross-process write lock — without it a
+     * process could read, lose the CPU while another persists a rotated token,
+     * then rename its older snapshot over it.
+     */
+    private commit;
+    /** Force a re-read of the file (see sync). */
+    reload(): void;
+    /**
+     * Serialize token refreshes across processes. Callers must re-read the
+     * credentials inside `fn`: whoever held the lock before may already have
+     * rotated them. `fn` never runs without the lock — presenting a single-use
+     * refresh token concurrently can void the login, while a timeout only costs
+     * one retryable request.
+     */
+    withRefreshLock<T>(fn: () => Promise<T>): Promise<T>;
+    getPath(): string;
+    get(providerId: string): OAuthCredentials | undefined;
+    set(providerId: string, creds: OAuthCredentials): void;
+    /**
+     * Store the result of a refresh only if the entry is still the one that was
+     * refreshed (`fromRefreshToken`; null = the key must still be absent). A
+     * /login or /logout in another process only takes the write lock, so it can
+     * land while a refresh request is in flight; its outcome must win over a
+     * result derived from the credentials it replaced.
+     */
+    replaceIfUnchanged(providerId: string, creds: OAuthCredentials, fromRefreshToken: string | null): boolean;
+    remove(providerId: string): void;
+    has(providerId: string): boolean;
+    isExpired(providerId: string, graceMs?: number): boolean;
+    getAccessToken(providerId: string): string | undefined;
+    list(): string[];
+}