@mnemom/mnemom 0.14.6 → 0.15.1-next.0

package/dist/lib/oauth.js

@@ -0,0 +1,490 @@
+/**
+ * OAuth 2.1 client for the Mnemom Authorization Server.
+ *
+ * `mnemom login` authenticates against the Mnemom OAuth AS (the same AS that
+ * fronts the MCP control plane) instead of doing a raw Supabase session login.
+ * This yields SCOPED access tokens (`mcp:read` / `mcp:write`) — not the full
+ * Supabase god-token — so a leaked CLI credential can only do what the CLI was
+ * granted, and grants are independently revocable server-side (MNE-805/806).
+ *
+ * Two interactive flows, both standards-based:
+ *   - Authorization Code + PKCE with a loopback redirect (the `wrangler login`
+ *     pattern): open the browser to /authorize, catch the redirect on a
+ *     localhost listener, exchange code+verifier at /token.
+ *   - RFC 8628 Device Authorization Grant (`--no-browser` / headless): POST
+ *     /device_authorization, print the user_code + verification_uri, poll
+ *     /token honoring `authorization_pending` and `slow_down`.
+ *
+ * Everything is driven off RFC 8414 discovery
+ * (/.well-known/oauth-authorization-server) — endpoint paths are NOT hardcoded.
+ * The public client_id is obtained via RFC 7591 Dynamic Client Registration and
+ * cached, so there is no client secret to embed (the AS advertises
+ * token_endpoint_auth_method "none" — public clients only).
+ */
+import * as http from "node:http";
+import * as crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { getApiUrl } from "./config.js";
+// The scopes the CLI requests. The AS currently advertises mcp:read + mcp:write
+// (scopes_supported in discovery); we request both so a single login covers the
+// full command surface. If discovery ever narrows what's available we intersect
+// against scopes_supported before asking, so we never request an unknown scope.
+const REQUESTED_SCOPES = ["mcp:read", "mcp:write"];
+const CLIENT_NAME = "Mnemom CLI";
+const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+// Loopback login waits at most this long for the browser round-trip before
+// giving up and freeing the port.
+const LOOPBACK_TIMEOUT_MS = 5 * 60 * 1000;
+// Cadence for the "…still waiting for you to finish signing in" heartbeat that
+// both interactive login poll loops emit, so a multi-minute browser sign-in
+// doesn't read as a hung CLI (matches the card-write retry tick in try-me).
+const LOGIN_HEARTBEAT_MS = 15 * 1000;
+let cachedMetadata = null;
+/**
+ * Fetch (and process-cache) the AS metadata document. We resolve it relative to
+ * the active API base URL so staging/local point at their own AS.
+ */
+export async function discover() {
+    if (cachedMetadata)
+        return cachedMetadata;
+    const url = `${getApiUrl()}/.well-known/oauth-authorization-server`;
+    const res = await fetch(url, { headers: { Accept: "application/json" } });
+    if (!res.ok) {
+        throw new Error(`Could not load OAuth metadata from ${url} (HTTP ${res.status}). ` + `Is the API reachable?`);
+    }
+    const meta = (await res.json());
+    if (!meta.authorization_endpoint || !meta.token_endpoint) {
+        throw new Error("OAuth metadata is missing authorization_endpoint/token_endpoint.");
+    }
+    cachedMetadata = meta;
+    return meta;
+}
+/** Reset the process-level discovery cache (used by tests). */
+export function _resetDiscoveryCache() {
+    cachedMetadata = null;
+}
+/** Intersect our requested scopes with what the AS advertises. */
+function negotiateScopes(meta) {
+    const supported = meta.scopes_supported;
+    const scopes = supported && supported.length > 0
+        ? REQUESTED_SCOPES.filter((s) => supported.includes(s))
+        : REQUESTED_SCOPES;
+    // If nothing intersects (misconfigured AS), fall back to asking for what the
+    // AS says it supports rather than sending an empty scope.
+    return (scopes.length > 0 ? scopes : (supported ?? REQUESTED_SCOPES)).join(" ");
+}
+// ============================================================================
+// Dynamic Client Registration (RFC 7591)
+// ============================================================================
+/**
+ * Register a public client for the CLI and return its client_id. The AS issues
+ * public clients (token_endpoint_auth_method "none"), so there is no secret to
+ * persist. The caller is responsible for caching the returned id.
+ */
+export async function registerClient(redirectUris) {
+    const meta = await discover();
+    if (!meta.registration_endpoint) {
+        throw new Error("This Authorization Server does not support dynamic client registration; " +
+            "no public CLI client_id is available.");
+    }
+    const res = await fetch(meta.registration_endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({
+            client_name: CLIENT_NAME,
+            redirect_uris: redirectUris,
+            grant_types: ["authorization_code", "refresh_token", DEVICE_CODE_GRANT],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`Client registration failed (HTTP ${res.status}): ${await safeBody(res)}`);
+    }
+    const data = (await res.json());
+    if (!data.client_id) {
+        throw new Error("Client registration response did not include a client_id.");
+    }
+    return data.client_id;
+}
+/**
+ * Generate a PKCE verifier/challenge pair. The verifier is a high-entropy
+ * URL-safe string (RFC 7636 §4.1: 43–128 chars from the unreserved set); the
+ * challenge is BASE64URL(SHA256(verifier)) for the S256 method (the only method
+ * the AS advertises, and the only one allowed under OAuth 2.1).
+ */
+export function generatePkce() {
+    const verifier = base64url(crypto.randomBytes(32));
+    const challenge = base64url(crypto.createHash("sha256").update(verifier).digest());
+    return { verifier, challenge, method: "S256" };
+}
+function base64url(buf) {
+    return buf.toString("base64url");
+}
+function tokensFromResponse(data) {
+    const now = Math.floor(Date.now() / 1000);
+    const expiresIn = typeof data.expires_in === "number" ? data.expires_in : 3600;
+    return {
+        accessToken: data.access_token,
+        tokenType: data.token_type ?? "Bearer",
+        refreshToken: data.refresh_token,
+        scope: data.scope,
+        expiresAt: now + expiresIn,
+    };
+}
+/**
+ * Run the interactive authorization-code + PKCE login. Returns the issued
+ * scoped tokens plus the client_id that was used (so the caller can persist it
+ * for refresh). `openUrl` is injectable so tests can drive the flow without
+ * spawning a real browser.
+ */
+export async function loginWithLoopback(openUrl = openBrowser) {
+    const meta = await discover();
+    const pkce = generatePkce();
+    const state = crypto.randomBytes(16).toString("hex");
+    const { port, codePromise, close } = await startLoopbackServer(state);
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    // Register a client bound to the exact loopback redirect URI. OAuth 2.1
+    // requires exact redirect_uri matching, and the loopback port is ephemeral,
+    // so we register per-login (cheap, public client, no secret).
+    const clientId = await registerClient([redirectUri]);
+    const authUrl = new URL(meta.authorization_endpoint);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", clientId);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("scope", negotiateScopes(meta));
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("code_challenge", pkce.challenge);
+    authUrl.searchParams.set("code_challenge_method", pkce.method);
+    console.log("Opening browser to authenticate...");
+    console.log(`If the browser doesn't open, visit:\n  ${authUrl.toString()}\n`);
+    openUrl(authUrl.toString());
+    console.log("Waiting for authentication...");
+    try {
+        // Heartbeat while we await the loopback redirect — otherwise the sign-in
+        // round-trip is dead silent and reads as a hung CLI.
+        const code = await withHeartbeat(codePromise, LOGIN_HEARTBEAT_MS, (s) => console.log(`…still waiting for you to finish signing in (${s}s)`));
+        const tokens = await exchangeCode(meta, clientId, code, pkce.verifier, redirectUri);
+        return { tokens, clientId };
+    }
+    finally {
+        close();
+    }
+}
+/**
+ * Start a loopback HTTP listener that captures the OAuth redirect
+ * (GET /callback?code=...&state=...). Resolves with the authorization code once
+ * a redirect with a matching state arrives; rejects on error/mismatch/timeout.
+ */
+function startLoopbackServer(expectedState) {
+    let resolveCode;
+    let rejectCode;
+    const codePromise = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+    });
+    const server = http.createServer((req, res) => {
+        const reqUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (req.method !== "GET" || reqUrl.pathname !== "/callback") {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not found");
+            return;
+        }
+        const error = reqUrl.searchParams.get("error");
+        const code = reqUrl.searchParams.get("code");
+        const state = reqUrl.searchParams.get("state");
+        if (error) {
+            const desc = reqUrl.searchParams.get("error_description") ?? error;
+            respondHtml(res, 400, "Authentication failed", desc);
+            rejectCode(new Error(`Authorization denied: ${desc}`));
+            return;
+        }
+        // Constant-time state comparison to avoid leaking timing on the CSRF token.
+        if (!state || !timingSafeEqual(state, expectedState)) {
+            respondHtml(res, 403, "Authentication failed", "State mismatch — possible CSRF.");
+            rejectCode(new Error("State mismatch — possible CSRF attack"));
+            return;
+        }
+        if (!code) {
+            respondHtml(res, 400, "Authentication failed", "No authorization code in callback.");
+            rejectCode(new Error("No authorization code in callback"));
+            return;
+        }
+        respondHtml(res, 200, "Authenticated!", "You can close this tab and return to the terminal.");
+        resolveCode(code);
+    });
+    return new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => {
+            const port = server.address().port;
+            const timeout = setTimeout(() => {
+                rejectCode(new Error("Login timed out. Please try again."));
+                server.close();
+            }, LOOPBACK_TIMEOUT_MS);
+            resolve({
+                port,
+                codePromise,
+                close: () => {
+                    clearTimeout(timeout);
+                    server.close();
+                },
+            });
+        });
+    });
+}
+async function exchangeCode(meta, clientId, code, verifier, redirectUri) {
+    const res = await fetch(meta.token_endpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            client_id: clientId,
+            code_verifier: verifier,
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`Token exchange failed: ${await oauthError(res)}`);
+    }
+    return tokensFromResponse((await res.json()));
+}
+/**
+ * Run the RFC 8628 device authorization grant. Registers a client (the device
+ * flow needs no redirect, but the AS's DCR validation requires a valid
+ * redirect_uri — HTTPS or a loopback — so we register a loopback placeholder it
+ * will never redirect to), requests a device code, prints the user_code +
+ * verification_uri for the user to approve in any browser, then polls the token
+ * endpoint until approval — honoring `authorization_pending` and `slow_down`
+ * per the spec.
+ *
+ * `display` and `sleep` are injectable so tests can drive the poll loop
+ * deterministically without real timers or stdout.
+ */
+export async function loginWithDevice(opts) {
+    const display = opts?.display ?? ((line) => console.log(line));
+    const sleep = opts?.sleep ?? defaultSleep;
+    const meta = await discover();
+    if (!meta.device_authorization_endpoint) {
+        throw new Error("This Authorization Server does not support the device flow.");
+    }
+    // Device flow has no redirect, but the AS's DCR validation rejects the OAuth
+    // OOB sentinel ("redirect_uri must be HTTPS or a loopback for native
+    // clients"). Register a loopback placeholder — it satisfies validation and is
+    // never used, since the device grant never redirects.
+    const clientId = await registerClient(["http://127.0.0.1/callback"]);
+    const authzRes = await fetch(meta.device_authorization_endpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        },
+        body: new URLSearchParams({ client_id: clientId, scope: negotiateScopes(meta) }),
+    });
+    if (!authzRes.ok) {
+        throw new Error(`Device authorization failed: ${await oauthError(authzRes)}`);
+    }
+    const authz = (await authzRes.json());
+    display("");
+    display("To authenticate, visit:");
+    display(`  ${authz.verification_uri}`);
+    display("");
+    display(`And enter the code:  ${authz.user_code}`);
+    if (authz.verification_uri_complete) {
+        display("");
+        display(`Or open this URL directly:`);
+        display(`  ${authz.verification_uri_complete}`);
+    }
+    display("");
+    display("Waiting for authorization...");
+    const tokens = await pollDeviceToken(meta, clientId, authz, sleep, display);
+    return { tokens, clientId };
+}
+async function pollDeviceToken(meta, clientId, authz, sleep, display) {
+    // RFC 8628 §3.5: default interval is 5s if the server omits it; on slow_down
+    // we increase the interval by 5s and keep that as the new minimum.
+    let intervalMs = (authz.interval ?? 5) * 1000;
+    const deadline = Date.now() + authz.expires_in * 1000;
+    // Heartbeat off accumulated poll time (not wall-clock) so it stays correct
+    // even when sleep is stubbed in tests; ticks every LOGIN_HEARTBEAT_MS.
+    let waitedMs = 0;
+    let nextHeartbeatMs = LOGIN_HEARTBEAT_MS;
+    for (;;) {
+        if (Date.now() >= deadline) {
+            throw new Error("Device authorization expired before approval. Please try again.");
+        }
+        await sleep(intervalMs);
+        waitedMs += intervalMs;
+        const res = await fetch(meta.token_endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: new URLSearchParams({
+                grant_type: DEVICE_CODE_GRANT,
+                device_code: authz.device_code,
+                client_id: clientId,
+            }),
+        });
+        if (res.ok) {
+            return tokensFromResponse((await res.json()));
+        }
+        const body = (await res.json().catch(() => ({})));
+        switch (body.error) {
+            case "authorization_pending":
+                break; // keep polling at the current interval
+            case "slow_down":
+                intervalMs += 5000; // RFC 8628 §3.5
+                break;
+            case "expired_token":
+                throw new Error("Device authorization expired before approval. Please try again.");
+            case "access_denied":
+                throw new Error("Authorization was denied.");
+            default:
+                throw new Error(`Device authorization failed: ${body.error ?? `HTTP ${res.status}`}` +
+                    (body.error_description ? ` — ${body.error_description}` : ""));
+        }
+        // Still pending (authorization_pending / slow_down) — emit a heartbeat
+        // every ~15s so a multi-minute approval doesn't look hung.
+        if (waitedMs >= nextHeartbeatMs) {
+            display(`…still waiting for you to finish signing in (${Math.round(waitedMs / 1000)}s)`);
+            nextHeartbeatMs += LOGIN_HEARTBEAT_MS;
+        }
+    }
+}
+// ============================================================================
+// Refresh (RFC 6749 §6)
+// ============================================================================
+/**
+ * Exchange a refresh token for a fresh access token. Returns null if refresh is
+ * not possible (no refresh token, or the AS rejects it — e.g. revoked/expired),
+ * so callers can fall back to prompting for re-login rather than crashing.
+ */
+export async function refreshTokens(refreshToken, clientId) {
+    if (!refreshToken || !clientId)
+        return null;
+    try {
+        const meta = await discover();
+        const res = await fetch(meta.token_endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: refreshToken,
+                client_id: clientId,
+            }),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const tokens = tokensFromResponse(data);
+        // Per RFC 6749 §6, a refresh response MAY omit a new refresh token, in which
+        // case the old one remains valid — preserve it so the next refresh works.
+        if (!tokens.refreshToken)
+            tokens.refreshToken = refreshToken;
+        return tokens;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Open `url` in the user's default browser WITHOUT a shell. The URL is always
+ * passed as a separate argv element (never concatenated into a command string),
+ * so shell metacharacters — `$(...)`, backticks, `\` — in the URL can never be
+ * interpreted as a command. Fire-and-forget: any failure (no opener installed,
+ * headless host) is swallowed because callers already print a manual-URL
+ * fallback, so a missing browser must not crash login.
+ */
+export function openBrowser(url) {
+    // On Windows, `start` is a cmd builtin and its FIRST quoted arg is the window
+    // title; the empty "" makes the URL the target rather than the title.
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = execFile(command, args, () => {
+            /* swallow opener errors — the manual URL fallback is already printed */
+        });
+        // Don't keep the event loop alive on the opener; login flow waits on the
+        // loopback/device promise, not on the browser process.
+        child.unref?.();
+    }
+    catch {
+        /* execFile threw synchronously (e.g. command not found) — ignore */
+    }
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Await `promise` while emitting a heartbeat tick every `intervalMs`, so a long
+ * silent wait (a browser sign-in round-trip) doesn't look hung. `onTick` is
+ * called with the elapsed whole-seconds count. The timer is always cleared when
+ * the promise settles, and is unref'd so it never keeps the event loop alive on
+ * its own. `timers` is injectable so tests drive the ticks without real clocks.
+ */
+export async function withHeartbeat(promise, intervalMs, onTick, timers = {}) {
+    const set = timers.set ?? ((cb, ms) => setInterval(cb, ms));
+    const clear = timers.clear ?? ((h) => clearInterval(h));
+    let elapsedMs = 0;
+    const handle = set(() => {
+        elapsedMs += intervalMs;
+        onTick(Math.round(elapsedMs / 1000));
+    }, intervalMs);
+    handle?.unref?.();
+    try {
+        return await promise;
+    }
+    finally {
+        clear(handle);
+    }
+}
+/** Constant-time string compare that tolerates length differences. */
+function timingSafeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length)
+        return false;
+    return crypto.timingSafeEqual(ab, bb);
+}
+/** Escape a string for safe interpolation into HTML text content. */
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function respondHtml(res, status, title, body) {
+    res.writeHead(status, { "Content-Type": "text/html; charset=utf-8" });
+    // title/body are escaped: on the error path `body` carries the OAuth
+    // error_description straight from the callback query string (attacker-
+    // controllable on the loopback URL), so interpolating it raw is reflected XSS
+    // (CodeQL js/reflected-xss). Escaping closes it; the page is plain text anyway.
+    res.end(`<html><body style="font-family:system-ui;text-align:center;padding:60px">` +
+        `<h2>${escapeHtml(title)}</h2><p>${escapeHtml(body)}</p></body></html>`);
+}
+/** Format a standard OAuth error response ({error, error_description}). */
+async function oauthError(res) {
+    const body = (await res.json().catch(() => ({})));
+    if (body.error) {
+        return body.error + (body.error_description ? ` — ${body.error_description}` : "");
+    }
+    return `HTTP ${res.status}`;
+}
+async function safeBody(res) {
+    return (await res.text().catch(() => "")) || `HTTP ${res.status}`;
+}

package/dist/lib/prompt.js

@@ -162,6 +162,11 @@ export async function askMultiSelect(question, options) {
         });
     });
 }
+/** Map a typed answer ("1".."n") to its option label, or null if out of range. */
+function resolveSelection(answer, options) {
+    const idx = parseInt(answer.trim(), 10) - 1;
+    return idx >= 0 && idx < options.length ? options[idx] : null;
+}
 /**
  * Single-select prompt. Displays numbered options, user enters a number.
  * Returns selected label or null if invalid.
@@ -171,6 +176,19 @@ export async function askSelect(question, options) {
     for (let i = 0; i < options.length; i++) {
         console.log(`  ${i + 1}) ${options[i]}`);
     }
+    // Non-interactive stdin (pipe / CI / agent-driven): serve the next buffered
+    // line from the SAME shared reader askInput uses. A fresh per-prompt readline
+    // interface drops buffered lines on a pipe (MNE-269), and `rl.question` never
+    // resolves on EOF — so a non-TTY run would silently hang here. Read the
+    // shared buffer instead; on EOF there's nothing to pick, so return null and
+    // let the caller fall back.
+    if (!process.stdin.isTTY) {
+        process.stdout.write("Select: ");
+        const lines = await readPipedStdinLines();
+        const next = lines.shift();
+        process.stdout.write("\n");
+        return resolveSelection(next ?? "", options);
+    }
     const rl = readline.createInterface({
         input: process.stdin,
         output: process.stdout,
@@ -178,13 +196,7 @@ export async function askSelect(question, options) {
     return new Promise((resolve) => {
         rl.question("Select: ", (answer) => {
             rl.close();
-            const idx = parseInt(answer.trim(), 10) - 1;
-            if (idx >= 0 && idx < options.length) {
-                resolve(options[idx]);
-            }
-            else {
-                resolve(null);
-            }
+            resolve(resolveSelection(answer, options));
         });
     });
 }