@enrichlayer/el-linear 1.4.0 → 1.5.0

package/README.md

@@ -122,6 +122,60 @@ The active profile is selected by, in priority:
 The legacy fallback means **existing single-profile users see no
 behavior change** — profiles are purely opt-in.
 
+## Migrating from v1.0–1.3
+
+Versions 1.0–1.3 stored everything in the single-file layout
+(`~/.config/el-linear/{token,config.json}`). 1.4 introduced **named
+profiles** (`~/.config/el-linear/profiles/<name>/{token,config.json}`) and
+the legacy single-file layout still works as a fallback.
+
+Some upgrade paths leave the legacy `config.json` on disk (with all your
+member aliases and brand rules) but no usable token, in which case every
+command fails with a generic `No API token found` error. 1.5 detects this
+state and prints a one-line stderr hint *before* the auth error fires:
+
+```
+el-linear: legacy config detected at ~/.config/el-linear/config.json
+but no token. Migrate with:
+
+  el-linear profile migrate-legacy [--name <profile>]
+
+Or suppress this hint with EL_LINEAR_SKIP_MIGRATION_HINT=1.
+```
+
+Run the suggested command to copy your legacy config into a named profile
+in one step:
+
+```bash
+# Default target name is "default"; pass --name to choose another.
+el-linear profile migrate-legacy
+
+# CI / scripted: read the token from a file, skip all prompts.
+el-linear profile migrate-legacy \
+  --name work \
+  --token-from /path/to/token.txt \
+  --yes
+
+# Pick the token up from an env var instead.
+EL_LINEAR_TOKEN=lin_api_xxx el-linear profile migrate-legacy --yes
+```
+
+The migration is **idempotent** — re-running with the same inputs is a no-op.
+If the destination profile already has a different `config.json` or token,
+the command refuses unless you pass `--force` (and confirms before
+overwriting unless you also pass `--yes`).
+
+The legacy `~/.config/el-linear/config.json` is **never deleted** — you keep
+a rollback path. Once you've verified the new profile works, you can remove
+the legacy file by hand at your leisure.
+
+If you've decided to stay on the legacy single-file layout intentionally,
+suppress the hint with:
+
+```bash
+export EL_LINEAR_SKIP_MIGRATION_HINT=1
+```
+
 ## Configuration
 
 el-linear reads `~/.config/el-linear/config.json` on startup. All keys are

package/dist/auth/oauth-callback.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Localhost HTTP listener that captures the OAuth redirect.
+ *
+ * Linear redirects the user's browser to
+ *   http://localhost:<port>/oauth/callback?code=…&state=…
+ * after they approve the app. We spin a one-shot HTTP server, parse the
+ * callback, validate `state`, return `{code, state}`, then close.
+ *
+ * Hardening:
+ *   - Only listens on `127.0.0.1` (NOT `0.0.0.0`) so other hosts on the
+ *     network can't race to grab the code.
+ *   - Rejects requests with a missing/wrong `state` parameter.
+ *   - Has a timeout (default 5 minutes) so a user who closes the browser
+ *     tab doesn't leave the CLI hanging forever.
+ *   - Sends a friendly success/error HTML page back so the user knows what
+ *     to do next ("you can close this tab").
+ */
+import { type Server } from "node:http";
+import { type CallbackParams } from "./oauth-client.js";
+export declare const DEFAULT_CALLBACK_PATH = "/oauth/callback";
+export declare const DEFAULT_LISTEN_HOST = "127.0.0.1";
+export declare const DEFAULT_TIMEOUT_MS: number;
+export interface CallbackOptions {
+    port: number;
+    expectedState: string;
+    host?: string;
+    callbackPath?: string;
+    timeoutMs?: number;
+}
+/**
+ * Spin up a one-shot HTTP server on `127.0.0.1:<port>`, accept the OAuth
+ * callback, validate state, and resolve with `{code, state}`.
+ *
+ * Always closes the server before resolving / rejecting.
+ *
+ * Test seam: `serverFactory` lets tests inject a mock server so we don't
+ * have to bind to a real port (and avoid flakiness from port collisions in
+ * CI).
+ */
+export declare function runLocalhostCallback(options: CallbackOptions, serverFactory?: () => Server): Promise<CallbackParams>;

package/dist/auth/oauth-callback.js

@@ -0,0 +1,142 @@
+/**
+ * Localhost HTTP listener that captures the OAuth redirect.
+ *
+ * Linear redirects the user's browser to
+ *   http://localhost:<port>/oauth/callback?code=…&state=…
+ * after they approve the app. We spin a one-shot HTTP server, parse the
+ * callback, validate `state`, return `{code, state}`, then close.
+ *
+ * Hardening:
+ *   - Only listens on `127.0.0.1` (NOT `0.0.0.0`) so other hosts on the
+ *     network can't race to grab the code.
+ *   - Rejects requests with a missing/wrong `state` parameter.
+ *   - Has a timeout (default 5 minutes) so a user who closes the browser
+ *     tab doesn't leave the CLI hanging forever.
+ *   - Sends a friendly success/error HTML page back so the user knows what
+ *     to do next ("you can close this tab").
+ */
+import { createServer } from "node:http";
+import { parseCallbackUrl } from "./oauth-client.js";
+export const DEFAULT_CALLBACK_PATH = "/oauth/callback";
+export const DEFAULT_LISTEN_HOST = "127.0.0.1";
+export const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const SUCCESS_HTML = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>el-linear · authorized</title>
+<style>body{font-family:system-ui,sans-serif;max-width:560px;margin:64px auto;padding:0 16px;color:#1a1a1a}h1{font-size:18px;margin:0 0 12px}p{margin:8px 0}.ok{color:#0a7e35}</style>
+</head>
+<body>
+<h1 class="ok">el-linear · authorization complete</h1>
+<p>You can close this tab and return to your terminal.</p>
+</body>
+</html>`;
+function errorHtml(message) {
+    const safe = message.replace(/[<>&]/g, "");
+    return `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>el-linear · authorization error</title>
+<style>body{font-family:system-ui,sans-serif;max-width:560px;margin:64px auto;padding:0 16px;color:#1a1a1a}h1{font-size:18px;margin:0 0 12px}p{margin:8px 0}.bad{color:#a30000}code{background:#f4f4f4;padding:2px 4px;border-radius:3px}</style>
+</head>
+<body>
+<h1 class="bad">el-linear · authorization error</h1>
+<p>${safe}</p>
+<p>You can close this tab. Re-run <code>el-linear init oauth</code> to retry.</p>
+</body>
+</html>`;
+}
+/**
+ * Spin up a one-shot HTTP server on `127.0.0.1:<port>`, accept the OAuth
+ * callback, validate state, and resolve with `{code, state}`.
+ *
+ * Always closes the server before resolving / rejecting.
+ *
+ * Test seam: `serverFactory` lets tests inject a mock server so we don't
+ * have to bind to a real port (and avoid flakiness from port collisions in
+ * CI).
+ */
+export async function runLocalhostCallback(options, serverFactory = () => createServer()) {
+    const host = options.host ?? DEFAULT_LISTEN_HOST;
+    const callbackPath = options.callbackPath ?? DEFAULT_CALLBACK_PATH;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const server = serverFactory();
+    let timeoutHandle = null;
+    return new Promise((resolve, reject) => {
+        const settle = (run, finalize = { closeServer: true }) => {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+                timeoutHandle = null;
+            }
+            if (finalize.closeServer) {
+                server.close(() => run());
+            }
+            else {
+                run();
+            }
+        };
+        server.on("request", (req, res) => {
+            try {
+                const incoming = req;
+                const rawUrl = incoming.url ?? "";
+                // Only respond on the configured callback path; all other
+                // requests get a 404 so a stray `/favicon.ico` poke doesn't
+                // trigger a parse error.
+                const pathname = new URL(rawUrl, "http://localhost").pathname;
+                if (pathname !== callbackPath) {
+                    res.statusCode = 404;
+                    res.setHeader("content-type", "text/plain; charset=utf-8");
+                    res.end("Not found.");
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = parseCallbackUrl(rawUrl);
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    res.statusCode = 400;
+                    res.setHeader("content-type", "text/html; charset=utf-8");
+                    res.end(errorHtml(message));
+                    settle(() => reject(new Error(message)));
+                    return;
+                }
+                if (parsed.state !== options.expectedState) {
+                    const message = "State mismatch — the OAuth callback's `state` parameter doesn't match what we sent. This could indicate a CSRF attempt; aborting.";
+                    res.statusCode = 400;
+                    res.setHeader("content-type", "text/html; charset=utf-8");
+                    res.end(errorHtml(message));
+                    settle(() => reject(new Error(message)));
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader("content-type", "text/html; charset=utf-8");
+                res.end(SUCCESS_HTML);
+                settle(() => resolve(parsed));
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                try {
+                    res.statusCode = 500;
+                    res.setHeader("content-type", "text/plain; charset=utf-8");
+                    res.end(`internal error: ${message}`);
+                }
+                catch {
+                    // Connection already closed — nothing to do.
+                }
+                settle(() => reject(err instanceof Error ? err : new Error(message)));
+            }
+        });
+        server.on("error", (err) => {
+            const code = err.code ?? "UNKNOWN";
+            const friendly = code === "EADDRINUSE"
+                ? `Port ${options.port} is already in use. Pick another with --port <n>.`
+                : `Could not start localhost listener on ${host}:${options.port} (${code}: ${err.message}).`;
+            settle(() => reject(new Error(friendly)), { closeServer: false });
+        });
+        timeoutHandle = setTimeout(() => {
+            settle(() => reject(new Error(`OAuth callback timed out after ${Math.round(timeoutMs / 1000)}s. Re-run \`el-linear init oauth\`.`)));
+        }, timeoutMs);
+        // Don't keep the event loop alive solely on the timeout.
+        timeoutHandle.unref?.();
+        server.listen(options.port, host);
+    });
+}

package/dist/auth/oauth-client.d.ts

@@ -0,0 +1,55 @@
+/** Default scope set picked when the user doesn't customise. */
+export declare const DEFAULT_SCOPES: readonly OAuthScope[];
+/** All scopes Linear advertises. Keep in sync with their docs. */
+export declare const ALL_SCOPES: readonly ["read", "write", "issues:create", "comments:create", "timeSchedule:write", "admin", "app:assignable", "app:mentionable"];
+export type OAuthScope = (typeof ALL_SCOPES)[number];
+export declare const SCOPE_DESCRIPTIONS: Record<OAuthScope, string>;
+export declare const LINEAR_AUTHORIZE_URL = "https://linear.app/oauth/authorize";
+export declare const LINEAR_TOKEN_URL = "https://api.linear.app/oauth/token";
+export declare const LINEAR_REVOKE_URL = "https://api.linear.app/oauth/revoke";
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+    method: "S256";
+}
+/**
+ * Generate a PKCE verifier + S256 challenge.
+ *
+ * Per RFC 7636 §4.1, verifier length is between 43 and 128 chars after
+ * base64url encoding. We pick 32 raw bytes which yields a 43-char verifier —
+ * the floor, but cryptographically plenty (256 bits of entropy).
+ */
+export declare function generatePkce(): PkcePair;
+/** Cryptographically random `state` parameter. 16 bytes → 22-char b64url. */
+export declare function generateState(): string;
+export interface AuthorizeUrlInput {
+    clientId: string;
+    redirectUri: string;
+    scopes: readonly string[];
+    state: string;
+    codeChallenge: string;
+    /** "consent" forces the consent screen even for previously-authorized users. */
+    prompt?: "consent";
+}
+/**
+ * Build the URL to send the user to. Linear's authorize endpoint accepts
+ * scope as a comma-separated list.
+ */
+export declare function buildAuthorizeUrl(input: AuthorizeUrlInput): string;
+export interface CallbackParams {
+    code: string;
+    state: string;
+}
+/**
+ * Parse a callback URL like
+ *   http://localhost:8765/oauth/callback?code=…&state=…
+ *
+ * Throws on missing parameters or on `?error=…` responses (Linear sends
+ * `error=access_denied` if the user cancels).
+ */
+export declare function parseCallbackUrl(rawUrl: string): CallbackParams;
+/**
+ * Validate scope strings against Linear's known set. Returns the validated
+ * tuple; throws on any unknown scope (typo guard).
+ */
+export declare function validateScopes(scopes: readonly string[]): OAuthScope[];

package/dist/auth/oauth-client.js

@@ -0,0 +1,134 @@
+/**
+ * OAuth 2.0 PKCE primitives for Linear.
+ *
+ * Linear's OAuth flow follows the standard authorization-code-with-PKCE shape:
+ *
+ *   1. Generate a random `code_verifier` and its SHA-256 `code_challenge`.
+ *   2. Send the user to /oauth/authorize with `code_challenge` + `state`.
+ *   3. Linear redirects back to our `redirect_uri` with `?code=…&state=…`.
+ *   4. We exchange `code` + `code_verifier` for an access token.
+ *
+ * Notes specific to Linear (per https://linear.app/developers/oauth-2-0-authentication):
+ *   - Scopes are joined with commas (`scope=read,write,issues:create`),
+ *     not spaces. Defensive: we encode the comma so URL parsers don't treat
+ *     it as a multi-value separator.
+ *   - `client_secret` is required by Linear's token endpoint even with PKCE
+ *     for confidential apps. Public/native apps configured without a secret
+ *     can omit it; we let the caller decide.
+ */
+import { createHash, randomBytes } from "node:crypto";
+/** Default scope set picked when the user doesn't customise. */
+export const DEFAULT_SCOPES = [
+    "read",
+    "write",
+    "issues:create",
+    "comments:create",
+];
+/** All scopes Linear advertises. Keep in sync with their docs. */
+export const ALL_SCOPES = [
+    "read",
+    "write",
+    "issues:create",
+    "comments:create",
+    "timeSchedule:write",
+    "admin",
+    "app:assignable",
+    "app:mentionable",
+];
+export const SCOPE_DESCRIPTIONS = {
+    read: "Read access to the user's account.",
+    write: "Write access. Without admin, also requires issues:create / comments:create for those mutations.",
+    "issues:create": "Allow creating new issues and their attachments.",
+    "comments:create": "Allow creating new issue comments.",
+    "timeSchedule:write": "Manage on-call schedules.",
+    admin: "Full administrative permissions.",
+    "app:assignable": "Mark this app as assignable to issues (Agents API).",
+    "app:mentionable": "Mark this app as mentionable from comments (Agents API).",
+};
+export const LINEAR_AUTHORIZE_URL = "https://linear.app/oauth/authorize";
+export const LINEAR_TOKEN_URL = "https://api.linear.app/oauth/token";
+export const LINEAR_REVOKE_URL = "https://api.linear.app/oauth/revoke";
+/**
+ * Encode bytes as base64url per RFC 4648 §5: replace `+` and `/`, strip `=`.
+ * `Buffer.toString("base64url")` is available in Node 22+ (we require 22+).
+ */
+function toBase64Url(buf) {
+    return buf.toString("base64url");
+}
+/**
+ * Generate a PKCE verifier + S256 challenge.
+ *
+ * Per RFC 7636 §4.1, verifier length is between 43 and 128 chars after
+ * base64url encoding. We pick 32 raw bytes which yields a 43-char verifier —
+ * the floor, but cryptographically plenty (256 bits of entropy).
+ */
+export function generatePkce() {
+    const verifier = toBase64Url(randomBytes(32));
+    const challenge = toBase64Url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge, method: "S256" };
+}
+/** Cryptographically random `state` parameter. 16 bytes → 22-char b64url. */
+export function generateState() {
+    return toBase64Url(randomBytes(16));
+}
+/**
+ * Build the URL to send the user to. Linear's authorize endpoint accepts
+ * scope as a comma-separated list.
+ */
+export function buildAuthorizeUrl(input) {
+    const url = new URL(LINEAR_AUTHORIZE_URL);
+    url.searchParams.set("client_id", input.clientId);
+    url.searchParams.set("redirect_uri", input.redirectUri);
+    url.searchParams.set("response_type", "code");
+    // Linear's docs are explicit: scopes are joined with `,`. URLSearchParams
+    // will URL-encode the comma to %2C, which Linear accepts.
+    url.searchParams.set("scope", input.scopes.join(","));
+    url.searchParams.set("state", input.state);
+    url.searchParams.set("code_challenge", input.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    if (input.prompt) {
+        url.searchParams.set("prompt", input.prompt);
+    }
+    return url.toString();
+}
+/**
+ * Parse a callback URL like
+ *   http://localhost:8765/oauth/callback?code=…&state=…
+ *
+ * Throws on missing parameters or on `?error=…` responses (Linear sends
+ * `error=access_denied` if the user cancels).
+ */
+export function parseCallbackUrl(rawUrl) {
+    const url = new URL(rawUrl, "http://localhost");
+    const error = url.searchParams.get("error");
+    if (error) {
+        const description = url.searchParams.get("error_description") ?? "no description provided";
+        throw new Error(`OAuth error: ${error} (${description})`);
+    }
+    const code = url.searchParams.get("code");
+    const state = url.searchParams.get("state");
+    if (!code)
+        throw new Error("OAuth callback missing `code` parameter");
+    if (!state)
+        throw new Error("OAuth callback missing `state` parameter");
+    return { code, state };
+}
+/**
+ * Validate scope strings against Linear's known set. Returns the validated
+ * tuple; throws on any unknown scope (typo guard).
+ */
+export function validateScopes(scopes) {
+    const known = new Set(ALL_SCOPES);
+    const out = [];
+    for (const s of scopes) {
+        const trimmed = s.trim();
+        if (!known.has(trimmed)) {
+            throw new Error(`Unknown OAuth scope: "${trimmed}". Allowed: ${ALL_SCOPES.join(", ")}.`);
+        }
+        out.push(trimmed);
+    }
+    if (out.length === 0) {
+        throw new Error("At least one OAuth scope is required.");
+    }
+    return out;
+}

package/dist/auth/oauth-fs.d.ts

@@ -0,0 +1 @@
+export declare function atomicWrite(targetPath: string, data: string | Uint8Array, mode?: number): Promise<void>;

package/dist/auth/oauth-fs.js

@@ -0,0 +1,29 @@
+/**
+ * Internal: atomic write helper used by `oauth-storage.ts`.
+ *
+ * The wizard already has an `atomicWrite` in `commands/init/shared.ts`, but
+ * importing wizard internals from non-wizard code creates a cycle (the
+ * wizard depends on `auth/`, and `auth/` would depend back on the wizard).
+ * Duplicating the 12-line helper here keeps the dependency graph clean.
+ *
+ * Behaviour matches `commands/init/shared.ts#atomicWrite`: write to a sibling
+ * tmp file then `rename`. On POSIX same-filesystem, rename is atomic. The
+ * tmp suffix uses crypto-random bytes so concurrent writers don't collide.
+ */
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+export async function atomicWrite(targetPath, data, mode = 0o644) {
+    const tmpPath = `${targetPath}.tmp-${randomBytes(8).toString("hex")}`;
+    try {
+        await fs.writeFile(tmpPath, data, { encoding: "utf8", mode });
+        // fs.writeFile only honours `mode` when the file is newly created.
+        // Tmp paths are always new, but be explicit to make this airtight if
+        // the random suffix ever collides with a stale tmp.
+        await fs.chmod(tmpPath, mode);
+        await fs.rename(tmpPath, targetPath);
+    }
+    catch (err) {
+        await fs.unlink(tmpPath).catch(() => { });
+        throw err;
+    }
+}

package/dist/auth/oauth-headless.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Headless OAuth fallback: print the authorize URL, ask the user to open
+ * it in any browser, then paste the redirected URL (or just the `code`
+ * fragment) back into the terminal.
+ *
+ * This is the escape hatch for environments where:
+ *   - The CLI can't open a browser (SSH session, remote shell).
+ *   - The user explicitly passes `--no-browser`.
+ *   - The localhost listener fails (port in use, firewall, restricted
+ *     container).
+ *
+ * Linear's OAuth app config requires a redirect URI matching the
+ * `redirect_uri` we sent. If the user is somewhere they can't run a
+ * localhost listener, they can still paste the full callback URL —
+ * Linear's redirect happens client-side in the browser regardless of
+ * whether the URL is reachable.
+ */
+import { type CallbackParams } from "./oauth-client.js";
+export interface PromptForPastedCodeOptions {
+    expectedState: string;
+    /** Test seam — defaults to @inquirer/prompts `input`. */
+    prompt?: (opts: {
+        message: string;
+        validate?: (value: string) => boolean | string;
+    }) => Promise<string>;
+}
+/**
+ * Ask the user to paste either:
+ *   - The full callback URL (we extract code+state ourselves), OR
+ *   - Just the `code` value (we accept the user's word on state).
+ *
+ * For the URL form, state is validated against `expectedState`.
+ *
+ * Returns `{code, state}`. When the user pasted only a code, `state` is
+ * the expected value (the user has implicitly trusted it; we have no
+ * other check available).
+ */
+export declare function promptForPastedCode(options: PromptForPastedCodeOptions): Promise<CallbackParams>;

package/dist/auth/oauth-headless.js

@@ -0,0 +1,50 @@
+/**
+ * Headless OAuth fallback: print the authorize URL, ask the user to open
+ * it in any browser, then paste the redirected URL (or just the `code`
+ * fragment) back into the terminal.
+ *
+ * This is the escape hatch for environments where:
+ *   - The CLI can't open a browser (SSH session, remote shell).
+ *   - The user explicitly passes `--no-browser`.
+ *   - The localhost listener fails (port in use, firewall, restricted
+ *     container).
+ *
+ * Linear's OAuth app config requires a redirect URI matching the
+ * `redirect_uri` we sent. If the user is somewhere they can't run a
+ * localhost listener, they can still paste the full callback URL —
+ * Linear's redirect happens client-side in the browser regardless of
+ * whether the URL is reachable.
+ */
+import { input } from "@inquirer/prompts";
+import { parseCallbackUrl } from "./oauth-client.js";
+/**
+ * Ask the user to paste either:
+ *   - The full callback URL (we extract code+state ourselves), OR
+ *   - Just the `code` value (we accept the user's word on state).
+ *
+ * For the URL form, state is validated against `expectedState`.
+ *
+ * Returns `{code, state}`. When the user pasted only a code, `state` is
+ * the expected value (the user has implicitly trusted it; we have no
+ * other check available).
+ */
+export async function promptForPastedCode(options) {
+    const ask = options.prompt ?? ((o) => input(o));
+    const raw = (await ask({
+        message: "Paste the full callback URL (or just the `code` value):",
+        validate: (value) => value.trim().length > 0 || "Cannot be empty",
+    })).trim();
+    if (raw.startsWith("http://") || raw.startsWith("https://")) {
+        const parsed = parseCallbackUrl(raw);
+        if (parsed.state !== options.expectedState) {
+            throw new Error("State mismatch — the pasted URL's `state` doesn't match the value we sent. Re-run `el-linear init oauth`.");
+        }
+        return parsed;
+    }
+    // Bare code path. Reject anything that looks like it has a query
+    // string but isn't a URL (the user partially copied something).
+    if (raw.includes("=") || raw.includes("?")) {
+        throw new Error("Pasted value looks malformed. Paste either the full callback URL or just the `code` value (alphanumeric + dashes).");
+    }
+    return { code: raw, state: options.expectedState };
+}

package/dist/auth/oauth-storage.d.ts

@@ -0,0 +1,51 @@
+export declare const OAUTH_STATE_VERSION = 1;
+export declare const OAUTH_STATE_FILENAME = "oauth.json";
+/**
+ * Persisted OAuth state. Mirrors what we got back from Linear's token
+ * endpoint plus the bits we need to refresh / re-authorize.
+ */
+export interface OAuthState {
+    v: typeof OAUTH_STATE_VERSION;
+    clientId: string;
+    clientSecret?: string;
+    registeredRedirectUri: string;
+    accessToken: string;
+    refreshToken?: string;
+    tokenType: string;
+    scopes: string[];
+    /** Unix epoch milliseconds; computed at write time from `expires_in`. */
+    expiresAt: number;
+    /** When we last fetched a token (for diagnostics). */
+    obtainedAt: number;
+}
+/**
+ * Resolve the path to the active profile's `oauth.json`. Mirrors
+ * `activePaths()` in `commands/init/shared.ts` so OAuth state lands in the
+ * same directory as the profile's `config.json` and `token`.
+ */
+export declare function oauthStatePath(): string;
+/**
+ * Read the active profile's OAuth state, or `null` if none has been written.
+ * Returns `null` (not throw) on JSON parse errors so callers can fall back
+ * to personal-token auth without spamming users with repair instructions —
+ * the `init oauth` command is responsible for repair.
+ */
+export declare function readOAuthState(): Promise<OAuthState | null>;
+/**
+ * Write the active profile's OAuth state atomically with mode 0600.
+ *
+ * IMPORTANT: uses the same write-tmp + rename pattern as `writeToken` so a
+ * pre-existing 0644 file gets its mode reset. Tokens leaking via group/other
+ * read is the failure mode we want to make impossible.
+ */
+export declare function writeOAuthState(state: OAuthState): Promise<void>;
+/**
+ * Delete the active profile's OAuth state. No-op if the file is already gone.
+ */
+export declare function clearOAuthState(): Promise<void>;
+/**
+ * Return `true` when the access token is still valid for at least
+ * `skewMs` milliseconds. Default 60s skew protects against clock drift +
+ * network latency.
+ */
+export declare function isAccessTokenFresh(state: OAuthState, skewMs?: number): boolean;