@enrichlayer/el-linear 1.4.0 → 1.5.0

package/dist/auth/oauth-storage.js

@@ -0,0 +1,87 @@
+/**
+ * On-disk storage for OAuth tokens.
+ *
+ * Stored at `<active-profile-dir>/oauth.json` with mode 0600 — same security
+ * posture as the personal-token file. Schema is versioned (`v: 1`) so future
+ * changes can be migrated without silently corrupting older state.
+ *
+ * The personal-token file (`<profile-dir>/token`) and `oauth.json` are
+ * mutually-exclusive *by convention*, not by enforcement: if both exist the
+ * resolver prefers OAuth. We don't delete the personal token automatically
+ * during `init oauth` — operators sometimes keep both for fallback.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { CONFIG_DIR, resolveActiveProfile } from "../config/paths.js";
+import { atomicWrite } from "./oauth-fs.js";
+export const OAUTH_STATE_VERSION = 1;
+export const OAUTH_STATE_FILENAME = "oauth.json";
+/**
+ * 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 function oauthStatePath() {
+    const active = resolveActiveProfile();
+    return path.join(path.dirname(active.configPath), OAUTH_STATE_FILENAME);
+}
+/**
+ * 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 async function readOAuthState() {
+    try {
+        const raw = await fs.readFile(oauthStatePath(), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed?.v !== OAUTH_STATE_VERSION)
+            return null;
+        if (typeof parsed.accessToken !== "string" || parsed.accessToken === "") {
+            return null;
+        }
+        return parsed;
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        // Corrupt JSON or unreadable file — treat as "no state" so the
+        // resolver can fall through to personal-token auth.
+        return 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 async function writeOAuthState(state) {
+    const target = oauthStatePath();
+    // Ensure both the legacy CONFIG_DIR (where active-profile + profiles/
+    // live) and the active profile's directory exist before writing.
+    await fs.mkdir(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    await fs.mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    await atomicWrite(target, `${JSON.stringify(state, null, 2)}\n`, 0o600);
+}
+/**
+ * Delete the active profile's OAuth state. No-op if the file is already gone.
+ */
+export async function clearOAuthState() {
+    try {
+        await fs.unlink(oauthStatePath());
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+}
+/**
+ * Return `true` when the access token is still valid for at least
+ * `skewMs` milliseconds. Default 60s skew protects against clock drift +
+ * network latency.
+ */
+export function isAccessTokenFresh(state, skewMs = 60_000) {
+    return Date.now() + skewMs < state.expiresAt;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Linear OAuth token endpoint calls: code exchange, refresh, and revoke.
+ *
+ * Linear's token endpoint accepts both `application/x-www-form-urlencoded`
+ * and JSON; we use form-encoded because that's what the docs show and what
+ * spec-compliant servers all support.
+ *
+ * We keep the dependency surface tiny — just `globalThis.fetch` (Node 22+
+ * has it native) plus our own tiny error envelope. The only thing the
+ * caller injects is the URL fetcher, so tests can mock without touching the
+ * network.
+ */
+import { type OAuthScope } from "./oauth-client.js";
+/**
+ * Minimal subset of `globalThis.fetch` we use. Typing as the structural
+ * shape (instead of `typeof fetch`) avoids dragging in DOM lib types.
+ */
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    text(): Promise<string>;
+}>;
+export interface ExchangeCodeInput {
+    clientId: string;
+    clientSecret?: string;
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+}
+export interface RefreshTokensInput {
+    clientId: string;
+    clientSecret?: string;
+    refreshToken: string;
+}
+export interface RevokeTokenInput {
+    accessToken: string;
+}
+export interface ExchangeResult {
+    accessToken: string;
+    refreshToken?: string;
+    tokenType: string;
+    scopes: OAuthScope[];
+    /** Unix epoch milliseconds; computed from `expires_in`. */
+    expiresAt: number;
+}
+/**
+ * Exchange an authorization code for tokens. PKCE-aware: send the verifier;
+ * `client_secret` is optional (some Linear apps configured as native/public
+ * don't have one).
+ */
+export declare function exchangeCodeForTokens(input: ExchangeCodeInput, fetchImpl?: FetchLike, now?: () => number): Promise<ExchangeResult>;
+/**
+ * Use a refresh token to get a new access token. Linear may rotate the
+ * refresh token, so we plumb both fields through.
+ */
+export declare function refreshTokens(input: RefreshTokensInput, fetchImpl?: FetchLike, now?: () => number): Promise<ExchangeResult>;
+/**
+ * Revoke an access token. Best-effort — we don't throw on transport
+ * errors so callers can still clear local state.
+ */
+export declare function revokeToken(input: RevokeTokenInput, fetchImpl?: FetchLike): Promise<{
+    ok: boolean;
+    status: number;
+    message?: string;
+}>;

package/dist/auth/oauth-token.js

@@ -0,0 +1,141 @@
+/**
+ * Linear OAuth token endpoint calls: code exchange, refresh, and revoke.
+ *
+ * Linear's token endpoint accepts both `application/x-www-form-urlencoded`
+ * and JSON; we use form-encoded because that's what the docs show and what
+ * spec-compliant servers all support.
+ *
+ * We keep the dependency surface tiny — just `globalThis.fetch` (Node 22+
+ * has it native) plus our own tiny error envelope. The only thing the
+ * caller injects is the URL fetcher, so tests can mock without touching the
+ * network.
+ */
+import { LINEAR_REVOKE_URL, LINEAR_TOKEN_URL, } from "./oauth-client.js";
+const defaultFetch = async (url, init) => {
+    const res = await globalThis.fetch(url, init);
+    return {
+        ok: res.ok,
+        status: res.status,
+        statusText: res.statusText,
+        text: () => res.text(),
+    };
+};
+/** Common form-encoded POST helper. Throws an error with sanitized body on non-2xx. */
+async function postForm(url, params, fetchImpl) {
+    const body = new URLSearchParams(params).toString();
+    let res;
+    try {
+        res = await fetchImpl(url, {
+            method: "POST",
+            headers: {
+                "content-type": "application/x-www-form-urlencoded",
+                accept: "application/json",
+            },
+            body,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Network error talking to ${url}: ${message}`);
+    }
+    const text = await res.text();
+    if (!res.ok) {
+        // Don't dump the request body — it contains client_secret /
+        // refresh_token / authorization code, all of which are secrets.
+        throw new Error(`OAuth endpoint ${url} responded ${res.status} ${res.statusText}: ${text || "(empty body)"}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`OAuth endpoint ${url} returned non-JSON response: ${text.slice(0, 200)}`);
+    }
+}
+function parseScopes(raw) {
+    if (!raw)
+        return [];
+    // Linear docs show scopes are returned comma-separated; some OAuth
+    // servers return space-separated. Accept either.
+    return raw
+        .split(/[,\s]+/)
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function tokenResponseToResult(response, now) {
+    const expiresInMs = typeof response.expires_in === "number" && response.expires_in > 0
+        ? response.expires_in * 1000
+        : // Linear docs say tokens last 24h. If the field is missing, fall
+            // back to 23h to leave a safety margin before forcing a refresh.
+            23 * 60 * 60 * 1000;
+    return {
+        accessToken: response.access_token,
+        refreshToken: response.refresh_token,
+        tokenType: response.token_type ?? "Bearer",
+        scopes: parseScopes(response.scope),
+        expiresAt: now + expiresInMs,
+    };
+}
+/**
+ * Exchange an authorization code for tokens. PKCE-aware: send the verifier;
+ * `client_secret` is optional (some Linear apps configured as native/public
+ * don't have one).
+ */
+export async function exchangeCodeForTokens(input, fetchImpl = defaultFetch, now = Date.now) {
+    const params = {
+        grant_type: "authorization_code",
+        code: input.code,
+        redirect_uri: input.redirectUri,
+        client_id: input.clientId,
+        code_verifier: input.codeVerifier,
+    };
+    if (input.clientSecret)
+        params.client_secret = input.clientSecret;
+    const res = await postForm(LINEAR_TOKEN_URL, params, fetchImpl);
+    if (typeof res.access_token !== "string" || res.access_token === "") {
+        throw new Error("OAuth response missing `access_token`.");
+    }
+    return tokenResponseToResult(res, now());
+}
+/**
+ * Use a refresh token to get a new access token. Linear may rotate the
+ * refresh token, so we plumb both fields through.
+ */
+export async function refreshTokens(input, fetchImpl = defaultFetch, now = Date.now) {
+    const params = {
+        grant_type: "refresh_token",
+        refresh_token: input.refreshToken,
+        client_id: input.clientId,
+    };
+    if (input.clientSecret)
+        params.client_secret = input.clientSecret;
+    const res = await postForm(LINEAR_TOKEN_URL, params, fetchImpl);
+    if (typeof res.access_token !== "string" || res.access_token === "") {
+        throw new Error("OAuth refresh response missing `access_token`.");
+    }
+    return tokenResponseToResult(res, now());
+}
+/**
+ * Revoke an access token. Best-effort — we don't throw on transport
+ * errors so callers can still clear local state.
+ */
+export async function revokeToken(input, fetchImpl = defaultFetch) {
+    try {
+        const res = await fetchImpl(LINEAR_REVOKE_URL, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${input.accessToken}`,
+                "content-type": "application/x-www-form-urlencoded",
+            },
+            body: "",
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            message: res.ok ? undefined : await res.text(),
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, status: 0, message };
+    }
+}

package/dist/auth/token-resolver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Unified resolver: returns the right credential for a CLI invocation,
+ * preferring OAuth state when present and auto-refreshing expired tokens.
+ *
+ * Resolution order (highest priority first):
+ *   1. `--api-token <token>` flag (always personal-style — sent without
+ *      `Bearer `).
+ *   2. `LINEAR_API_TOKEN` env var (personal-style).
+ *   3. Profile OAuth state (`<profile-dir>/oauth.json`) — auto-refreshes
+ *      when the access token has < 60s of validity left.
+ *   4. Profile personal token (`<profile-dir>/token`) and legacy fallbacks.
+ *
+ * The kind discriminant (`personal` vs `oauth`) tells `GraphQLService` which
+ * `Authorization` header shape to use:
+ *   - personal:  `Authorization: <token>`        (no Bearer prefix)
+ *   - oauth:     `Authorization: Bearer <token>`
+ */
+import { type OAuthState } from "./oauth-storage.js";
+import { type FetchLike } from "./oauth-token.js";
+export interface ActiveAuth {
+    kind: "personal" | "oauth";
+    token: string;
+    /** Original OAuth state, when `kind === "oauth"`. */
+    oauth?: OAuthState;
+}
+export interface GetActiveAuthOptions {
+    apiToken?: string;
+    /** Test seam: override the network fetcher used by refresh. */
+    fetchImpl?: FetchLike;
+    /** Test seam: override the wall-clock for refresh expiry checks. */
+    now?: () => number;
+}
+/**
+ * Resolve the credential for this invocation.
+ *
+ * Synchronous personal-token paths still work via `getApiToken` for
+ * backwards compatibility — code that hasn't been migrated to OAuth-aware
+ * call sites keeps using `getApiToken` directly.
+ */
+export declare function getActiveAuth(options?: GetActiveAuthOptions): Promise<ActiveAuth>;
+/**
+ * If the token is fresh, return state unchanged. Otherwise call
+ * `refreshTokens`, write the new state to disk, and return it.
+ *
+ * On refresh failure, throws an actionable error pointing at
+ * `el-linear init oauth`.
+ */
+export declare function ensureFreshAccessToken(state: OAuthState, options?: GetActiveAuthOptions): Promise<OAuthState>;

package/dist/auth/token-resolver.js

@@ -0,0 +1,95 @@
+/**
+ * Unified resolver: returns the right credential for a CLI invocation,
+ * preferring OAuth state when present and auto-refreshing expired tokens.
+ *
+ * Resolution order (highest priority first):
+ *   1. `--api-token <token>` flag (always personal-style — sent without
+ *      `Bearer `).
+ *   2. `LINEAR_API_TOKEN` env var (personal-style).
+ *   3. Profile OAuth state (`<profile-dir>/oauth.json`) — auto-refreshes
+ *      when the access token has < 60s of validity left.
+ *   4. Profile personal token (`<profile-dir>/token`) and legacy fallbacks.
+ *
+ * The kind discriminant (`personal` vs `oauth`) tells `GraphQLService` which
+ * `Authorization` header shape to use:
+ *   - personal:  `Authorization: <token>`        (no Bearer prefix)
+ *   - oauth:     `Authorization: Bearer <token>`
+ */
+import { getApiToken } from "../utils/auth.js";
+import { isAccessTokenFresh, readOAuthState, writeOAuthState, } from "./oauth-storage.js";
+import { refreshTokens, } from "./oauth-token.js";
+/**
+ * Resolve the credential for this invocation.
+ *
+ * Synchronous personal-token paths still work via `getApiToken` for
+ * backwards compatibility — code that hasn't been migrated to OAuth-aware
+ * call sites keeps using `getApiToken` directly.
+ */
+export async function getActiveAuth(options = {}) {
+    // 1) Explicit override: `--api-token` always wins. Personal-style.
+    if (options.apiToken) {
+        return { kind: "personal", token: options.apiToken };
+    }
+    // 2) Env var: same precedence as the legacy resolver. Personal-style.
+    if (process.env.LINEAR_API_TOKEN) {
+        return { kind: "personal", token: process.env.LINEAR_API_TOKEN };
+    }
+    // 3) OAuth state for the active profile, auto-refreshed if needed.
+    const oauth = await readOAuthState();
+    if (oauth) {
+        const fresh = await ensureFreshAccessToken(oauth, options);
+        return { kind: "oauth", token: fresh.accessToken, oauth: fresh };
+    }
+    // 4) Fall back to the existing personal-token resolver (handles
+    //    profile-aware token files, legacy paths, etc.). If no token can
+    //    be found, this throws — and the message already mentions the
+    //    profile, so we don't have to re-wrap.
+    return { kind: "personal", token: getApiToken({}) };
+}
+/**
+ * If the token is fresh, return state unchanged. Otherwise call
+ * `refreshTokens`, write the new state to disk, and return it.
+ *
+ * On refresh failure, throws an actionable error pointing at
+ * `el-linear init oauth`.
+ */
+export async function ensureFreshAccessToken(state, options = {}) {
+    const now = options.now ?? Date.now;
+    if (isAccessTokenFresh(state, /* skewMs */ 60_000)) {
+        // `isAccessTokenFresh` reads `Date.now()` internally; for the
+        // purpose of the test seam we re-check against the injected clock.
+        if (now() + 60_000 < state.expiresAt) {
+            return state;
+        }
+    }
+    if (!state.refreshToken) {
+        throw new Error("OAuth access token expired and no refresh token is stored. Re-run `el-linear init oauth`.");
+    }
+    let refreshed;
+    try {
+        refreshed = await refreshTokens({
+            clientId: state.clientId,
+            clientSecret: state.clientSecret,
+            refreshToken: state.refreshToken,
+        }, options.fetchImpl, now);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`OAuth refresh failed: ${message}. Re-run \`el-linear init oauth\` to re-authorize.`);
+    }
+    const next = {
+        ...state,
+        accessToken: refreshed.accessToken,
+        // Preserve the previous refresh token if the server didn't rotate
+        // (some OAuth servers only return a new refresh_token periodically).
+        refreshToken: refreshed.refreshToken ?? state.refreshToken,
+        tokenType: refreshed.tokenType,
+        // Use the freshly-returned scopes only if non-empty; otherwise keep
+        // what we had, since some token endpoints omit `scope` on refresh.
+        scopes: refreshed.scopes.length > 0 ? refreshed.scopes : state.scopes,
+        expiresAt: refreshed.expiresAt,
+        obtainedAt: now(),
+    };
+    await writeOAuthState(next);
+    return next;
+}

package/dist/commands/init/index.js

@@ -16,6 +16,7 @@
  */
 import { mergeAliasesIntoConfig, runAliasesImport, runAliasesStep, } from "./aliases.js";
 import { runDefaultsStep } from "./defaults.js";
+import { runOAuthRevoke, runOAuthStep } from "./oauth.js";
 import { assignDefined, printStep, readConfig, writeConfig, } from "./shared.js";
 import { runTokenStep } from "./token.js";
 import { runWorkspaceStep } from "./workspace.js";
@@ -56,6 +57,27 @@ export function setupInitCommands(program) {
         printStep("token", "Linear API token");
         await runTokenStep({ force: options.force ?? false });
     }));
+    init
+        .command("oauth")
+        .description("Authorize via OAuth 2.0 (PKCE) — alternative to a personal API token")
+        .option("--force", "ignore existing tokens; re-authorize unconditionally")
+        .option("--revoke", "revoke and remove the stored OAuth tokens")
+        .option("--no-browser", "skip the browser-open + localhost listener; paste the code manually")
+        .option("--port <port>", "localhost callback port (default 8765)", (value) => Number.parseInt(value, 10))
+        .action(withCleanExit(async (options) => {
+        printStep("oauth", "Linear OAuth (PKCE)");
+        if (options.revoke) {
+            const result = await runOAuthRevoke();
+            console.log(`  ${result.message}`);
+            return;
+        }
+        await runOAuthStep({
+            force: options.force ?? false,
+            // commander's `--no-browser` produces `browser: false`.
+            noBrowser: options.browser === false,
+            port: options.port,
+        });
+    }));
     init
         .command("workspace")
         .description("Set the default team and refresh team UUID cache")

package/dist/commands/init/oauth.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Wizard step for OAuth 2.0 (PKCE flow) authorization.
+ *
+ * Flow:
+ *   1. Present a "what is this?" intro pointing the user at Linear's OAuth
+ *      app registration page. (Until we ship a shared OAuth client_id,
+ *      every user registers their own app.)
+ *   2. Prompt for `client_id`, optional `client_secret`, port, scopes.
+ *   3. Generate PKCE verifier + state, build the authorize URL.
+ *   4. Try to open the system browser; fall back to printing the URL.
+ *   5. Spin a localhost listener (or fall back to pasted-code prompt) to
+ *      receive the redirect.
+ *   6. Exchange code for tokens.
+ *   7. Validate by calling `viewer { ... }` with the new bearer token.
+ *   8. Persist `oauth.json` to the active profile.
+ *
+ * Idempotent: if a fresh `oauth.json` already exists, offer keep / re-auth /
+ * revoke before doing anything else.
+ */
+import { runLocalhostCallback } from "../../auth/oauth-callback.js";
+import { type OAuthState } from "../../auth/oauth-storage.js";
+import { type FetchLike } from "../../auth/oauth-token.js";
+interface ViewerResponse {
+    viewer: {
+        id: string;
+        name: string;
+        email: string;
+        displayName: string;
+        organization: {
+            urlKey: string;
+            name: string;
+        };
+    };
+}
+export interface OAuthStepOptions {
+    /** Force re-authorization even if existing state is valid. */
+    force?: boolean;
+    /** Skip the localhost listener; use the headless code-paste prompt. */
+    noBrowser?: boolean;
+    /** Override the localhost port. Default 8765. */
+    port?: number;
+    /** Test seam for the OAuth token endpoint. */
+    fetchImpl?: FetchLike;
+    /**
+     * Test seam for the localhost listener. Default uses the real one.
+     */
+    runLocalhostCallbackImpl?: typeof runLocalhostCallback;
+    /** Test seam for the system-browser opener. Default uses spawn. */
+    openBrowser?: (url: string) => Promise<void>;
+    /** Test seam for `viewer` validation against the new bearer token. */
+    validateViewer?: (oauthToken: string) => Promise<ViewerResponse["viewer"]>;
+}
+export interface OAuthStepResult {
+    state: OAuthState;
+    viewer: ViewerResponse["viewer"];
+}
+/**
+ * Open `url` in the system browser. Forks per-platform:
+ *   - darwin → `open <url>`
+ *   - win32  → `start "" "<url>"` (cmd builtin)
+ *   - other  → `xdg-open <url>` (Linux / BSD with desktop env)
+ *
+ * Returns once the spawn call succeeds — does NOT wait for the browser to
+ * actually load. Throws on spawn failure (e.g. xdg-open not installed in
+ * a barebones container).
+ */
+export declare function openSystemBrowser(url: string): Promise<void>;
+/**
+ * Run the OAuth step. Returns the final stored state + viewer info.
+ *
+ * If the user opts to keep their existing tokens, returns the existing
+ * state unchanged (no network calls).
+ */
+export declare function runOAuthStep(options?: OAuthStepOptions): Promise<OAuthStepResult>;
+/**
+ * `init oauth --revoke`: revoke the active profile's tokens and remove
+ * `oauth.json`. Best-effort on the network call.
+ */
+export declare function runOAuthRevoke(options?: {
+    fetchImpl?: FetchLike;
+}): Promise<{
+    revoked: boolean;
+    message: string;
+}>;
+export {};