voxflow 1.15.0 → 1.15.2

package/lib/core/auth.js

@@ -0,0 +1,880 @@
+/**
+ * VoxFlow CLI — Authentication module
+ *
+ * Device-flow login (RFC 8628 inspired):
+ *   1. CLI: POST /api/device-auth/code → { deviceCode, userCode, verifyUrl }
+ *   2. CLI: print userCode + verifyUrl, optionally open browser
+ *   3. User: open verifyUrl in browser, log in via Supabase, confirm pairing
+ *   4. CLI: poll POST /api/device-auth/token until 200 or timeout
+ *   5. CLI: cache token
+ *
+ * No localhost callback. Works under PNA, SSH, containers, AI agents.
+ */
+
+const fs = require('fs');
+const crypto = require('crypto');
+const readline = require('readline');
+const { TOKEN_PATH, getConfigDir, LOGIN_PAGE, AUTH_TIMEOUT_MS, API_BASE, SUPABASE_URL, SUPABASE_ANON_KEY } = require('./config');
+const { detectAIAgent, buildUserActionPanel } = require('./agent-env');
+
+// Inside an AI agent, user round-trips are slow (the agent has to relay the
+// URL to a human, the human has to context-switch into a browser, etc.).
+// The default 3-minute timeout is too short for that flow — bump to 10 min.
+const AI_AGENT_AUTH_TIMEOUT_MS = 600_000;
+
+// ─── Token cache ────────────────────────────────────────────────────────────
+
+/**
+ * Token 剩余有效期低于此阈值（秒）时视为即将过期，需要刷新或重新登录。
+ *
+ * 10 分钟 (600s) — 比 5 分钟更激进。voxflow 不少命令是长任务
+ * (`video-translate` / `asr-jobs` 轮询 / `render`)，启动时多留点裕度
+ * 可以避免请求中途 401。AWS botocore 用的就是 600s 的 mandatory_refresh_timeout。
+ */
+const MIN_TOKEN_REMAINING_SEC = 600;
+const SUPABASE_AUTH_TIMEOUT_MS = 15_000;
+
+// ─── Refresh-token plausibility ─────────────────────────────────────────────
+
+/**
+ * Detect obviously-bad refresh tokens **before** writing them to the cache,
+ * so a malformed paste doesn't silently break the next refresh cycle.
+ *
+ * Empty / undefined is allowed — "I deliberately don't have one" (CI with
+ * only VOXFLOW_TOKEN env var, or first call before login).
+ *
+ * **History — 2026-05-07 lesson learned**: an earlier version of this
+ * validator required ≥20 chars based on a wrong assumption that all
+ * Supabase refresh tokens are long. The actual VoxFlow project signs
+ * 12-char `[a-z0-9]{12}` refresh tokens, so the strict floor was
+ * silently rejecting *every* legitimate token returned by `/auth/v1/token`
+ * and stripping it from the cache. That broke the silent-refresh loop
+ * for every user who upgraded to 1.10.19 (~24h window).
+ *
+ * The check now leans on **shape**, not length:
+ *   - non-empty string
+ *   - only opaque-token-safe characters (matches what Supabase, OAuth 2,
+ *     and JWT-style refresh tokens use); rejects whitespace, newlines,
+ *     quotes, and other paste-corruption signs
+ *   - very small floor (≥6) to catch literal placeholders ("test", "todo")
+ */
+function isPlausibleRefreshToken(token) {
+  if (token == null || token === '') return true;
+  if (typeof token !== 'string') return false;
+  if (token.length < 6) return false;
+  if (!/^[A-Za-z0-9._\-+/=]+$/.test(token)) return false;
+  return true;
+}
+
+function classifyRefreshToken(token) {
+  if (token == null || token === '') return 'missing';
+  if (!isPlausibleRefreshToken(token)) return 'malformed';
+  return 'ok';
+}
+
+// ─── Single-flight refresh lock ─────────────────────────────────────────────
+//
+// Multiple parallel CLI invocations (e.g. running 5 `voxflow synthesize` in a
+// shell loop, or a long task spawning sub-tasks) can all hit "token expiring"
+// at the same time. Without a lock, each one independently calls
+// /auth/v1/token?grant_type=refresh_token. Supabase rotates the refresh_token
+// on every call, so whichever response comes back last wins — earlier callers
+// have a stale refresh_token and the next refresh will hard-fail, kicking the
+// user to a browser login. gcloud solves this with a sqlite row lock; we use
+// a simple mkdir-based file lock (atomic on POSIX & NTFS, no native deps).
+
+const LOCK_DIR_NAME = 'token.json.lock';
+const LOCK_STALE_MS = 30_000;
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_WAIT_MS = 5_000;
+
+function lockPath() {
+  return TOKEN_PATH + '.lock';
+}
+
+async function withRefreshLock(fn) {
+  const start = Date.now();
+  const lockDir = lockPath();
+  // Ensure parent dir exists so mkdir(lockDir) doesn't fail with ENOENT
+  // before the user has ever logged in.
+  try { fs.mkdirSync(getConfigDir(), { recursive: true, mode: 0o700 }); } catch { /* race-safe */ }
+
+  while (true) {
+    try {
+      fs.mkdirSync(lockDir);
+      try {
+        return await fn();
+      } finally {
+        try { fs.rmdirSync(lockDir); } catch { /* lock already gone */ }
+      }
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+
+      // Steal a stale lock from a crashed previous process. statSync may race
+      // with the holder's rmdir — that's fine, we'll just retry.
+      try {
+        const stat = fs.statSync(lockDir);
+        if (Date.now() - stat.mtimeMs > LOCK_STALE_MS) {
+          try { fs.rmdirSync(lockDir); } catch { /* someone else freed it */ }
+          continue;
+        }
+      } catch { /* lock disappeared between EEXIST and stat — retry */ }
+
+      if (Date.now() - start > LOCK_MAX_WAIT_MS) {
+        // Degrade gracefully — don't deadlock the user. The worst case is a
+        // duplicate refresh; better than blocking forever on a stuck lock.
+        return await fn();
+      }
+      await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
+    }
+  }
+}
+
+// Suppress unused-export warning — exposed via _test for unit tests.
+void LOCK_DIR_NAME;
+
+/**
+ * Read cached token from disk.
+ * Returns null if missing, corrupt, or expired.
+ */
+function readCachedToken() {
+  try {
+    const raw = fs.readFileSync(TOKEN_PATH, 'utf8');
+    const cached = JSON.parse(raw);
+    if (!cached.access_token) return null;
+
+    // Decode JWT payload to check expiry
+    const payload = decodeJwtPayload(cached.access_token);
+    if (!payload || !payload.exp) return null;
+
+    // Expired if less than 5 minutes remain
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp - now < MIN_TOKEN_REMAINING_SEC) return null;
+
+    return cached;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read cached token without expiry check (for refresh flow).
+ * Returns null only if file is missing or corrupt.
+ */
+function readRawCachedToken() {
+  try {
+    const raw = fs.readFileSync(TOKEN_PATH, 'utf8');
+    const cached = JSON.parse(raw);
+    if (!cached.access_token) return null;
+    return cached;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write token to cache file with restrictive permissions.
+ *
+ * Defensively strips obviously-malformed refresh_tokens — see
+ * isPlausibleRefreshToken() for the rationale (the 12-char paste incident).
+ * If a bad refresh_token was provided, we warn on stderr and drop it, so
+ * the cache never carries a value that we *know* will fail at refresh time.
+ */
+function writeCachedToken(tokenData) {
+  const dir = getConfigDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+
+  let safeData = tokenData;
+  if (tokenData && tokenData.refresh_token != null && tokenData.refresh_token !== '') {
+    if (!isPlausibleRefreshToken(tokenData.refresh_token)) {
+      try {
+        process.stderr.write(
+          '\x1b[33m⚠ Dropped malformed refresh_token (length ' +
+          String(tokenData.refresh_token).length +
+          '). Run `voxflow login` to refresh credentials cleanly.\x1b[0m\n'
+        );
+      } catch { /* stderr might be closed in some sandbox harnesses */ }
+      safeData = { ...tokenData, refresh_token: '' };
+    }
+  }
+
+  const tmpPath = TOKEN_PATH + '.tmp';
+  // Use openSync(O_CREAT|O_WRONLY|O_TRUNC) with mode 0o600 so a leftover
+  // .tmp from a crashed previous run is truncated but its mode is the new
+  // one, not whatever was on disk. writeFileSync's `mode` only applies on
+  // CREATE and is umask-masked, which is why we also chmod afterwards.
+  const fd = fs.openSync(tmpPath, 'w', 0o600);
+  try {
+    fs.writeSync(fd, JSON.stringify(safeData, null, 2));
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.chmodSync(tmpPath, 0o600);
+  fs.renameSync(tmpPath, TOKEN_PATH);
+}
+
+/**
+ * Delete cached token.
+ */
+function clearToken() {
+  try {
+    fs.unlinkSync(TOKEN_PATH);
+  } catch {
+    // Already gone — fine
+  }
+}
+
+/**
+ * Decode JWT payload (base64url → JSON). No signature verification.
+ */
+function decodeJwtPayload(jwt) {
+  try {
+    const parts = jwt.split('.');
+    if (parts.length !== 3) return null;
+    const payload = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+    return JSON.parse(Buffer.from(payload, 'base64').toString('utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function parseManualAuthInput(input) {
+  const value = String(input || '').trim();
+  if (!value) return null;
+
+  let payload = null;
+  if (value.startsWith('{')) {
+    try {
+      payload = JSON.parse(value);
+    } catch {
+      return null;
+    }
+  }
+
+  const accessToken = payload
+    ? (payload.access_token || payload.accessToken || payload.token || '')
+    : value;
+  const rawRefresh = payload
+    ? (payload.refresh_token || payload.refreshToken || '')
+    : '';
+
+  if (!decodeJwtPayload(accessToken)) return null;
+
+  // Drop a refresh_token that's clearly garbage — but DON'T fail the parse,
+  // a valid access_token alone is still usable for ~1h. The browser-paste
+  // copy panel sometimes includes the access_token without the refresh_token
+  // (older clipboard targets), so a missing refresh is not invalid input.
+  const refreshToken = isPlausibleRefreshToken(rawRefresh) ? rawRefresh : '';
+
+  return { accessToken, refreshToken };
+}
+
+/**
+ * Resolve token from environment for non-interactive automation.
+ * Supported vars: VOXFLOW_TOKEN, VOXFLOW_JWT
+ */
+function readEnvToken() {
+  const token = (process.env.VOXFLOW_TOKEN || process.env.VOXFLOW_JWT || '').trim();
+  if (!token) return null;
+
+  const payload = decodeJwtPayload(token);
+  if (!payload) return null;
+
+  if (!payload.exp) return null;
+
+  const now = Math.floor(Date.now() / 1000);
+  if (payload.exp - now < MIN_TOKEN_REMAINING_SEC) return null;
+
+  return token;
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Get a valid JWT token. Uses cache if available, otherwise opens browser login.
+ *
+ * @param {object} opts
+ * @param {string} [opts.api]   - API base URL override
+ * @param {boolean} [opts.force] - Force re-login even if cached token is valid
+ * @param {boolean} [opts.refresh] - Force refresh_token exchange before browser login
+ * @returns {Promise<string>} JWT access token
+ */
+async function getToken({ api, force, refresh } = {}) {
+  // Prefer env token for automation scenarios.
+  // This bypasses browser login and works in CI/agent environments.
+  if (!force && !refresh) {
+    const envToken = readEnvToken();
+    if (envToken) return envToken;
+  }
+
+  // Check cache first (unless force)
+  if (!force && !refresh) {
+    const cached = readCachedToken();
+    if (cached) {
+      const apiMatch = !api || api === cached.api;
+      if (apiMatch) return cached.access_token;
+    }
+  }
+
+  if (!force) {
+    // Token expired or explicitly rejected — try silent refresh before opening browser.
+    const refreshed = await refreshCachedToken(api);
+    if (refreshed) return refreshed;
+  }
+
+  // Need to login via browser (works in both interactive and non-interactive environments)
+  return browserLogin(api || API_BASE);
+}
+
+async function refreshCachedToken(apiBase) {
+  return withRefreshLock(async () => {
+    // Re-read under lock — another process / parallel `voxflow` invocation
+    // may have just refreshed for us, in which case readCachedToken returns
+    // a still-valid token (>10 min remaining). Skipping the network call
+    // avoids burning a Supabase rotation slot we don't need.
+    const stillValid = readCachedToken();
+    if (stillValid) return stillValid.access_token;
+
+    const raw = readRawCachedToken();
+    if (!raw?.refresh_token) return null;
+    if (!isPlausibleRefreshToken(raw.refresh_token)) return null;
+    return tryRefreshToken(raw.refresh_token, apiBase || raw.api || API_BASE);
+  });
+}
+
+/**
+ * Silently refresh an expired access_token using the stored refresh_token.
+ * Calls Supabase /auth/v1/token?grant_type=refresh_token.
+ *
+ * @param {string} refreshToken
+ * @param {string} apiBase - API base URL for caching
+ * @returns {Promise<string|null>} new access_token, or null on failure
+ */
+async function tryRefreshToken(refreshToken, apiBase = API_BASE) {
+  try {
+    const result = await supabasePost(
+      `${SUPABASE_URL}/auth/v1/token?grant_type=refresh_token`,
+      { refresh_token: refreshToken }
+    );
+
+    if (result.status >= 400 || !result.data?.access_token) return null;
+
+    const token = result.data.access_token;
+    const payload = decodeJwtPayload(token);
+
+    writeCachedToken({
+      access_token: token,
+      refresh_token: result.data.refresh_token || refreshToken,
+      expires_at: payload?.exp || 0,
+      email: payload?.email || '',
+      api: apiBase,
+      cached_at: new Date().toISOString(),
+    });
+
+    return token;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Get info about the currently cached token.
+ * Returns null if no valid cached token.
+ */
+function getTokenInfo() {
+  const cached = readCachedToken();
+  if (!cached) return null;
+
+  const payload = decodeJwtPayload(cached.access_token);
+  if (!payload) return null;
+
+  const now = Math.floor(Date.now() / 1000);
+  return {
+    email: payload.email || cached.email || '(unknown)',
+    expiresAt: new Date(payload.exp * 1000).toISOString(),
+    remaining: payload.exp - now,
+    valid: payload.exp - now > MIN_TOKEN_REMAINING_SEC,
+    api: cached.api || API_BASE,
+    refreshHealth: classifyRefreshToken(cached.refresh_token),
+  };
+}
+
+async function getFreshTokenInfo({ api } = {}) {
+  const current = getTokenInfo();
+  if (current) return current;
+
+  const refreshed = await refreshCachedToken(api);
+  if (!refreshed) return null;
+  return getTokenInfo();
+}
+
+// ─── Background refresh for long-running commands ───────────────────────────
+//
+// Long-running commands (`video-translate`, `asr-jobs` polling, large
+// `dub` runs, future `render`) routinely outlive the 1-hour Supabase JWT.
+// runWithRetry catches a 401 *after* it happens — that's a single
+// recoverable miss, but the user sees a noisy "Token expired, refreshing..."
+// line in the middle of progress output. This helper schedules a refresh
+// **before** expiry so the long task feels seamless.
+//
+// Usage:
+//   const stop = startBackgroundRefresh({ api });
+//   try {
+//     // ... long task ...
+//   } finally {
+//     stop();
+//   }
+//
+// Aligned with AWS botocore's RefreshableCredentials pattern but stripped
+// to a single Node.js setTimeout — no thread lock needed since we already
+// hold withRefreshLock() inside refreshCachedToken().
+
+const BG_REFRESH_LEAD_SEC = 300; // refresh 5 min before expiry
+
+function startBackgroundRefresh({ api } = {}) {
+  let stopped = false;
+  let timer = null;
+
+  function schedule() {
+    if (stopped) return;
+    const cached = readRawCachedToken();
+    if (!cached?.access_token) return;
+    const payload = decodeJwtPayload(cached.access_token);
+    if (!payload?.exp) return;
+
+    const now = Math.floor(Date.now() / 1000);
+    const secsUntilRefresh = Math.max(30, payload.exp - now - BG_REFRESH_LEAD_SEC);
+
+    timer = setTimeout(async () => {
+      if (stopped) return;
+      try { await refreshCachedToken(api); } catch { /* swallow — retry on 401 will catch it */ }
+      schedule();
+    }, secsUntilRefresh * 1000);
+
+    // Don't keep the event loop alive solely for the refresh timer — when
+    // the long-running command finishes, Node should exit even if stop()
+    // wasn't explicitly called (defensive against forgotten cleanup).
+    if (typeof timer.unref === 'function') timer.unref();
+  }
+
+  schedule();
+
+  return function stop() {
+    stopped = true;
+    if (timer) { clearTimeout(timer); timer = null; }
+  };
+}
+
+// ─── Device-flow login (RFC 8628 inspired) ──────────────────────────────────
+//
+// The previous browserLogin used a localhost callback server, which broke
+// under Chrome's Private Network Access policy (HTTPS → http://127.0.0.1
+// requires a CORS+PNA preflight that we never answered). It also failed in
+// SSH sessions, dev containers, and Claude-Code-piped environments.
+//
+// New flow:
+//   1. POST /api/device-auth/code → { deviceCode, userCode, verifyUrl, interval, expiresIn }
+//   2. Display userCode + verifyUrl. Optionally open browser.
+//   3. Poll POST /api/device-auth/token { deviceCode } every `interval` seconds:
+//        202 authorization_pending → keep polling
+//        200 success → cache tokens, return
+//        410 expired / 404 invalid / 409 consumed / 429 too_many → fail
+//
+// No localhost listener, no stdin paste. Works in every environment that
+// can reach the API.
+
+/**
+ * POST a JSON body to a URL, parse JSON response. Tiny self-contained helper
+ * to keep this module dep-free of `core/http.js` (which depends on logger
+ * which depends on a bunch of stuff we don't want pulled in here).
+ */
+function postDeviceAuth(apiBase, path, body) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(path, apiBase);
+    const mod = url.protocol === 'https:' ? require('https') : require('http');
+    const postData = JSON.stringify(body || {});
+    const req = mod.request({
+      hostname: url.hostname,
+      port: url.port || (url.protocol === 'https:' ? 443 : 80),
+      path: url.pathname + url.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(postData),
+        'X-Client-Source': 'cli',
+      },
+    }, (resp) => {
+      const chunks = [];
+      resp.on('data', (c) => chunks.push(c));
+      resp.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        try {
+          resolve({ status: resp.statusCode, data: JSON.parse(raw) });
+        } catch {
+          resolve({ status: resp.statusCode, data: { raw } });
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(30_000, () => {
+      req.destroy(new Error('Device auth request timeout (30s)'));
+    });
+    req.write(postData);
+    req.end();
+  });
+}
+
+const POLL_INTERVAL_FALLBACK_SEC = 5;
+
+function browserLogin(apiBase) {
+  return new Promise((resolve, reject) => {
+    (async () => {
+      // ─── Step 1: request a device code ─────────────────────────────────
+      let deviceCode, userCode, verifyUrl, intervalSec, expiresInSec;
+      try {
+        const { status, data } = await postDeviceAuth(apiBase, '/api/device-auth/code', {});
+        if (status !== 200 || data?.code !== 'success' || !data?.data?.deviceCode) {
+          return reject(new Error(
+            `Failed to start device login (HTTP ${status}): ${data?.message || 'unexpected response'}`
+          ));
+        }
+        ({ deviceCode, userCode, verifyUrl } = data.data);
+        intervalSec = data.data.interval || POLL_INTERVAL_FALLBACK_SEC;
+        expiresInSec = data.data.expiresIn || 300;
+      } catch (err) {
+        return reject(new Error(`Cannot reach ${apiBase}: ${err.message}`));
+      }
+
+      // ─── Step 2: show code + URL, open browser if GUI ──────────────────
+      const isInteractive = process.stdin.isTTY;
+      const agentName = detectAIAgent();
+      const inAIAgent = agentName !== null;
+      const hasGui = process.platform === 'darwin'
+        || process.platform === 'win32'
+        || !!(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+      const shouldOpenBrowser = !process.env.CI && (isInteractive || hasGui);
+
+      if (inAIAgent) {
+        const timeoutMs = Math.min(AI_AGENT_AUTH_TIMEOUT_MS, expiresInSec * 1000);
+        process.stderr.write(buildUserActionPanel({
+          loginUrl: verifyUrl,
+          agentName,
+          timeoutSec: Math.round(timeoutMs / 1000),
+          userCode,
+        }));
+      } else {
+        const out = isInteractive ? console.log : (msg) => process.stderr.write(msg + '\n');
+        out('');
+        out('\x1b[33m🔐 Confirm device authorization\x1b[0m');
+        out('');
+        out(`   Pairing code:   \x1b[1;36m${userCode}\x1b[0m`);
+        out(`   Verify at:      \x1b[36m${verifyUrl}\x1b[0m`);
+        out('');
+        out(`   Code expires in ${Math.round(expiresInSec / 60)} min. Polling every ${intervalSec}s...`);
+        out('');
+      }
+
+      if (shouldOpenBrowser) {
+        try {
+          const open = (await import('open')).default;
+          const cp = await open(verifyUrl);
+          if (cp && typeof cp.on === 'function') {
+            cp.on('error', () => {
+              process.stderr.write('\x1b[31m   Browser auto-open failed. Open the URL above manually.\x1b[0m\n');
+            });
+          }
+        } catch {
+          process.stderr.write('\x1b[31m   Browser auto-open failed. Open the URL above manually.\x1b[0m\n');
+        }
+      }
+
+      // ─── Step 3: poll until approved or expired ────────────────────────
+      const overallTimeoutMs = Math.min(
+        inAIAgent ? AI_AGENT_AUTH_TIMEOUT_MS : AUTH_TIMEOUT_MS,
+        expiresInSec * 1000
+      );
+      const deadline = Date.now() + overallTimeoutMs;
+      let pollIntervalMs = intervalSec * 1000;
+
+      while (Date.now() < deadline) {
+        await new Promise(r => setTimeout(r, pollIntervalMs));
+
+        let pollResp;
+        try {
+          pollResp = await postDeviceAuth(apiBase, '/api/device-auth/token', { deviceCode });
+        } catch (err) {
+          // Transient network error — keep polling, don't bail.
+          process.stderr.write(`\x1b[33m   Poll error (${err.message}), retrying...\x1b[0m\n`);
+          continue;
+        }
+
+        const { status, data } = pollResp;
+        const code = data?.code;
+
+        if (status === 200 && code === 'success' && data?.data?.token) {
+          const token = data.data.token;
+          const refreshToken = data.data.refreshToken || '';
+          const payload = decodeJwtPayload(token);
+          writeCachedToken({
+            access_token: token,
+            refresh_token: refreshToken,
+            expires_at: payload?.exp || 0,
+            email: payload?.email || '',
+            api: apiBase,
+            cached_at: new Date().toISOString(),
+          });
+          if (isInteractive) {
+            console.log(`\x1b[32m✓ Authorized (${payload?.email || 'user'})\x1b[0m\n`);
+          }
+          return resolve(token);
+        }
+
+        if (status === 202 || code === 'authorization_pending') {
+          continue;
+        }
+        if (code === 'too_many_attempts') {
+          // Server says back off — double interval (with cap).
+          pollIntervalMs = Math.min(pollIntervalMs * 2, 30_000);
+          continue;
+        }
+        if (code === 'expired' || status === 410) {
+          return reject(new Error(
+            `Pairing code expired before login. Run \`voxflow login\` again.`
+          ));
+        }
+        if (code === 'invalid_device_code' || status === 404) {
+          return reject(new Error(
+            `Pairing code invalidated by server. Run \`voxflow login\` again.`
+          ));
+        }
+        if (code === 'already_consumed' || status === 409) {
+          return reject(new Error(
+            `Token already issued for this code. Run \`voxflow login\` again.`
+          ));
+        }
+        // Unknown response — keep polling but log it.
+        process.stderr.write(`\x1b[33m   Unexpected poll response (HTTP ${status}, code=${code}), retrying...\x1b[0m\n`);
+      }
+
+      return reject(new Error(
+        `Login timed out (${Math.round(overallTimeoutMs / 1000)}s). ` +
+        `Please retry: voxflow login   ` +
+        `(or set VOXFLOW_TOKEN in env to skip browser login)`
+      ));
+    })();
+  });
+}
+
+// ─── Terminal OTP login (no browser) ────────────────────────────────────────
+
+/**
+ * Prompt for email + OTP code in terminal, authenticate via Supabase REST API.
+ * No browser needed — works in SSH, containers, and headless environments.
+ *
+ * @param {string} apiBase - API base URL (for caching)
+ * @returns {Promise<string>} JWT access token
+ */
+function terminalOtpLogin(apiBase = API_BASE) {
+  return new Promise((resolve, reject) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    function ask(question) {
+      return new Promise(r => rl.question(question, r));
+    }
+
+    (async () => {
+      try {
+        console.log('\n\x1b[33m🔐 Terminal login (no browser needed)\x1b[0m\n');
+
+        // Step 1: Get email
+        const email = (await ask('   Email: ')).trim();
+        if (!email || !email.includes('@')) {
+          throw new Error('Invalid email address.');
+        }
+
+        // Step 2: Send OTP via Supabase REST API
+        process.stdout.write('   Sending verification code... ');
+
+        const otpResult = await supabasePost(`${SUPABASE_URL}/auth/v1/otp`, {
+          email,
+          create_user: true,
+        });
+
+        if (otpResult.status >= 400) {
+          const msg = otpResult.data?.error_description || otpResult.data?.msg || otpResult.data?.message || JSON.stringify(otpResult.data);
+          throw new Error(`OTP send failed (${otpResult.status}): ${msg}`);
+        }
+
+        console.log('✓ Code sent!');
+        console.log('   \x1b[36mCheck your email for the 6-digit verification code.\x1b[0m\n');
+
+        // Step 3: Get OTP code
+        const code = (await ask('   Verification code: ')).trim();
+        if (!code) {
+          throw new Error('No verification code entered.');
+        }
+
+        // Step 4: Verify OTP via Supabase REST API
+        process.stdout.write('   Verifying... ');
+
+        const verifyResult = await supabasePost(`${SUPABASE_URL}/auth/v1/verify`, {
+          email,
+          token: code,
+          type: 'email',
+        });
+
+        if (verifyResult.status >= 400 || !verifyResult.data?.access_token) {
+          const msg = verifyResult.data?.error_description || verifyResult.data?.msg || verifyResult.data?.message || 'Invalid or expired code';
+          throw new Error(`Verification failed: ${msg}`);
+        }
+
+        const token = verifyResult.data.access_token;
+        const payload = decodeJwtPayload(token);
+
+        // Cache token
+        writeCachedToken({
+          access_token: token,
+          refresh_token: verifyResult.data.refresh_token || '',
+          expires_at: payload?.exp || 0,
+          email: payload?.email || email,
+          api: apiBase,
+          cached_at: new Date().toISOString(),
+        });
+
+        console.log('✓ Success!');
+        console.log(`\n\x1b[32m✓ Logged in as ${payload?.email || email}\x1b[0m\n`);
+
+        rl.close();
+        resolve(token);
+      } catch (err) {
+        rl.close();
+        reject(err);
+      }
+    })();
+  });
+}
+
+/**
+ * POST to Supabase auth endpoint with apikey header.
+ */
+function supabasePost(url, body) {
+  const https = require('https');
+  const postData = JSON.stringify(body);
+  const parsed = new URL(url);
+
+  return new Promise((resolve, reject) => {
+    const req = https.request({
+      hostname: parsed.hostname,
+      port: 443,
+      // Keep query string (e.g. ?grant_type=refresh_token), otherwise
+      // refresh-token flow will silently fail and always fall back to login.
+      path: parsed.pathname + parsed.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'apikey': SUPABASE_ANON_KEY,
+        'Content-Length': Buffer.byteLength(postData),
+      },
+    }, (resp) => {
+      let data = '';
+      resp.on('data', d => data += d);
+      resp.on('end', () => {
+        try {
+          resolve({ status: resp.statusCode, data: JSON.parse(data) });
+        } catch {
+          resolve({ status: resp.statusCode, data });
+        }
+      });
+    });
+    req.on('error', reject);
+    req.setTimeout(SUPABASE_AUTH_TIMEOUT_MS, () => {
+      req.destroy(new Error(`Supabase auth request timeout (${SUPABASE_AUTH_TIMEOUT_MS / 1000}s)`));
+    });
+    req.write(postData);
+    req.end();
+  });
+}
+
+/**
+ * Build the same login URL that browserLogin generates, but DO NOT listen
+ * for the callback. Used by `voxflow login --print-url` so AI agents that
+ * can't run interactive flows can hand the URL to a human, then receive
+ * the auth payload back through `voxflow login --paste`.
+ *
+ * The URL still carries a `callback_port` for compatibility with the page,
+ * but it points to nothing — the page's JS detects the callback failure
+ * and shows the manual-paste UI with the JSON payload visible.
+ */
+function buildPrintOnlyLoginUrl() {
+  // callback_port=0 is the sentinel — clearly not a real listener, so the
+  // page falls back to the manual-paste UI showing the JSON payload.
+  // No state param: the paste-back flow returns the JWT directly, so a
+  // request/response state-binding token would not bind anything that
+  // matters (an attacker controlling the URL only forces the user to
+  // paste back their own session). Removed to avoid signaling a CSRF
+  // protection that does not exist.
+  return `${LOGIN_PAGE}?callback_port=0`;
+}
+
+/**
+ * Accept a manually-provided auth payload (JSON or raw JWT) and write it
+ * to the local token cache. Validates that the access_token decodes as a
+ * JWT and is not already expired. Returns { ok, info, reason } where info
+ * is the same shape as getTokenInfo() on success.
+ *
+ * Used by `voxflow login --paste '<payload>'`.
+ */
+function acceptManualAuthPayload(input, apiBase = API_BASE) {
+  const parsed = parseManualAuthInput(input);
+  if (!parsed) {
+    return { ok: false, reason: 'invalid-payload', message: 'Could not parse the auth payload — expected JSON {"access_token":"..."} or a raw JWT.' };
+  }
+  const payload = decodeJwtPayload(parsed.accessToken);
+  if (!payload) {
+    return { ok: false, reason: 'invalid-jwt', message: 'access_token is not a valid JWT.' };
+  }
+  const now = Math.floor(Date.now() / 1000);
+  if (payload.exp && payload.exp < now) {
+    return { ok: false, reason: 'expired', message: 'Token has already expired. Re-run the login URL and paste a fresh payload.' };
+  }
+  writeCachedToken({
+    access_token: parsed.accessToken,
+    refresh_token: parsed.refreshToken || '',
+    expires_at: payload.exp || 0,
+    email: payload.email || '',
+    api: apiBase,
+    cached_at: new Date().toISOString(),
+  });
+  return {
+    ok: true,
+    info: {
+      email: payload.email || '(unknown)',
+      expiresAt: new Date((payload.exp || 0) * 1000).toISOString(),
+      api: apiBase,
+    },
+  };
+}
+
+module.exports = {
+  getToken,
+  clearToken,
+  getTokenInfo,
+  getFreshTokenInfo,
+  terminalOtpLogin,
+  readCachedToken,
+  buildPrintOnlyLoginUrl,
+  acceptManualAuthPayload,
+  startBackgroundRefresh,
+  isPlausibleRefreshToken,
+  _test: {
+    parseManualAuthInput,
+    tryRefreshToken,
+    withRefreshLock,
+    refreshCachedToken,
+    classifyRefreshToken,
+    MIN_TOKEN_REMAINING_SEC,
+  },
+};