scava-ai 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# Scava
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hosting, sign-in and a database for the apps your AI builds. One command puts the app online, on its own address.
+People open a link and sign in with Google or a code by email: no password, nothing to install. Data stays in the EU.
+
+## Start
+
+In the folder of your app, or tell your AI to run it:
+
+```
+npx -y scava-ai setup
+```
+
+The first time a browser opens: sign in to Scava and choose Allow. After that it runs without a browser. Any AI with a
+terminal can use it: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity and others. You need Node.js 22
+or newer.
+
+Claude and ChatGPT in the browser have no terminal: add a connector with the address https://scava.ai/mcp.
+
+## Commands
+
+```
+npx -y scava-ai setup [folder]    put the app online; afterwards a test run in a browser here
+npx -y scava-ai share WHO...       let people open it: someone@company.com, "@company.com", group:leads
+npx -y scava-ai apps               your apps
+npx -y scava-ai requests           change requests you accepted, ready to build
+npx -y scava-ai test               test run of the live app, plus problems from visits
+npx -y scava-ai server             the server part of the app
+npx -y scava-ai pull APP [folder]  the files of an app into a folder
+npx -y scava-ai docs               what an app can use on Scava: data, rules, files, server code
+npx -y scava-ai whoami             which account this computer is signed in as
+npx -y scava-ai login              sign in now
+npx -y scava-ai logout             end the access on this computer
+```
+
+The access stays on your computer, in ~/.scava/credentials.json, and whoever works under your user there acts as you.
+Keys for the server code of an app are set in the browser, never in a terminal.
+
+With a one-time link from the Scava tools in your AI (no sign-in here):
+
+```
+npx -y scava-ai upload <folder> <link>
+npx -y scava-ai test <link>
+npx -y scava-ai pull <link> [folder]
+```
+
+More at https://scava.ai/docs
+
+Version 0.2.0.

package/cli/account.js

@@ -0,0 +1,507 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { CMD, LOOPBACK, ScavaError, openBrowser } from './lib.js';
+
+// Signing in on this computer, the way wrangler does it. The first command that needs an account opens the browser; the
+// person signs in to Scava and chooses Allow; the access then stays in a file in the home folder and renews itself. It is
+// the same sign-in every AI uses at /mcp: OAuth with PKCE and a return address on this computer, so a link someone sends
+// to a Scava user hands nothing to the sender.
+//
+// An AI runs this command in a terminal that may stop it after a few seconds, while the person is still signing in. So
+// the waiting does not happen in the command: a small program of its own listens on this computer, on its own, until the
+// person has decided or 15 minutes are over. The command only watches for the result and can simply be run again.
+
+const CLI = fileURLToPath(new URL('./scava.js', import.meta.url));
+const VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  } catch {
+    return '0';
+  }
+})();
+const USER_AGENT = `scava-cli/${VERSION}`;
+const MCP_VERSION = '2025-11-25';
+// Any port on this computer counts as the same return address (RFC 8252).
+const RETURN_ADDRESS = 'http://127.0.0.1/callback';
+// As long as Scava keeps the request of the page.
+const SIGN_IN_MS = 15 * 60_000;
+// Below the two minutes many AI terminals give a command, so an AI hears from this command by itself.
+const AI_WAIT_MS = 100_000;
+const RENEW_EARLY_MS = 60_000;
+const LOCK_STALE_MS = 30_000;
+const NOTE = `Your access to Scava on this computer. Do not show, copy or send this file. End it with: ${CMD} logout`;
+
+// SCAVA_HOME: for tests, which must not touch the access of the computer they run on.
+const folder = () => process.env.SCAVA_HOME || path.join(os.homedir(), '.scava');
+export const credentialsPath = () => path.join(folder(), 'credentials.json');
+const originOf = (server) => new URL(server).origin;
+const signInPath = (server) => path.join(folder(), `sign-in-${crypto.createHash('sha256').update(originOf(server)).digest('hex').slice(0, 12)}.json`);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const pause = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+const busyFile = (e) => e.code === 'EBUSY' || e.code === 'EPERM' || e.code === 'EACCES';
+
+// --- The files --------------------------------------------------------------------------------------------------------
+
+function readPrivate(file) {
+  for (let i = 0; ; i++) {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (e) {
+      if (e.code === 'ENOENT' || e.code === 'ENOTDIR' || e instanceof SyntaxError) return null;
+      // Windows, for a moment, while another command replaces the file.
+      if (i < 20 && busyFile(e)) pause(50);
+      else throw e;
+    }
+  }
+}
+
+// Many AIs run commands in a sandbox that keeps them out of the home folder. Then this is what they have to know.
+function ensureFolder() {
+  try {
+    fs.mkdirSync(folder(), { recursive: true, mode: 0o700 });
+  } catch (e) {
+    throw new ScavaError(`Cannot write to ${folder()} (${e.code}), where the access to Scava is kept. If an AI runs this in a sandbox, allow this command to use the home folder and the network, or run it yourself.`);
+  }
+}
+
+// Only for this user, and replaced in one step: nobody reads half a file.
+function writePrivate(file, data) {
+  ensureFolder();
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  for (let i = 0; ; i++) {
+    try {
+      fs.renameSync(tmp, file);
+      return;
+    } catch (e) {
+      if (i < 20 && busyFile(e)) pause(50);
+      else {
+        fs.rmSync(tmp, { force: true });
+        throw e;
+      }
+    }
+  }
+}
+
+// One access per server: what belongs to one Scava is never sent to another.
+const entryOf = (server) => readPrivate(credentialsPath())?.servers?.[originOf(server)] ?? null;
+
+function setEntry(server, entry) {
+  const servers = { ...(readPrivate(credentialsPath())?.servers ?? {}) };
+  if (entry) servers[originOf(server)] = entry;
+  else delete servers[originOf(server)];
+  if (Object.keys(servers).length) writePrivate(credentialsPath(), { note: NOTE, servers });
+  else fs.rmSync(credentialsPath(), { force: true });
+}
+
+// Refresh tokens are used once. Two commands at the same moment must not both spend the same one.
+async function withLock(fn) {
+  const file = path.join(folder(), 'lock');
+  ensureFolder();
+  const end = Date.now() + LOCK_STALE_MS + 5000;
+  for (;;) {
+    try {
+      fs.closeSync(fs.openSync(file, 'wx', 0o600));
+      break;
+    } catch (e) {
+      if (e.code !== 'EEXIST' && !busyFile(e)) throw e;
+      try {
+        if (Date.now() - fs.statSync(file).mtimeMs > LOCK_STALE_MS) fs.rmSync(file, { force: true });
+      } catch { /* gone in the meantime */ }
+      if (Date.now() > end) throw new ScavaError(`Another ${CMD} command is busy. Please try again.`);
+      await sleep(50);
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    fs.rmSync(file, { force: true });
+  }
+}
+
+// --- Talking to Scava -------------------------------------------------------------------------------------------------
+
+// Never along a redirect: the access goes to this server and nowhere else.
+async function send(url, init) {
+  try {
+    return await fetch(url, { ...init, redirect: 'error', signal: AbortSignal.timeout(60_000), headers: { 'user-agent': USER_AGENT, ...init.headers } });
+  } catch (e) {
+    const moved = /redirect/i.test(String(e?.cause?.message ?? e?.message));
+    throw new ScavaError(`Cannot reach Scava at ${new URL(url).origin}.${moved ? ' It answered with a redirect, and the access never follows one.' : ' If an AI runs this in a sandbox, allow this command to use the network.'}`);
+  }
+}
+
+const form = (fields) => ({ method: 'POST', headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' }, body: new URLSearchParams(fields).toString() });
+const notOpen = (server) => new ScavaError(`Scava at ${originOf(server)} does not take this command yet.`);
+
+// The access only travels encrypted, except to a Scava on this computer.
+function checkServer(server) {
+  let u;
+  try {
+    u = new URL(server);
+  } catch {
+    throw new ScavaError(`${server} is not an address.`);
+  }
+  if (u.protocol === 'https:' || (u.protocol === 'http:' && LOOPBACK.has(u.hostname))) return;
+  throw new ScavaError(`The access to Scava only travels encrypted: ${server} has to start with https, unless it runs on this computer.`);
+}
+
+const fresh = (e) => e.expires_at - RENEW_EARLY_MS > Date.now();
+const toEntry = (d, known) => ({
+  client_id: known.client_id,
+  account: d.account ?? known.account ?? null,
+  access_token: d.access_token,
+  refresh_token: d.refresh_token ?? known.refresh_token,
+  expires_at: Date.now() + (Number(d.expires_in) || 3600) * 1000,
+});
+
+// A new access with the refresh token, or null when that ended: disconnected on the Connect page, 90 days without use,
+// or the token was used elsewhere. Then the next command signs in again. Scava being away ends nothing.
+async function renew(server, failedToken) {
+  return withLock(async () => {
+    const e = entryOf(server);
+    if (!e) return null;
+    if (e.access_token !== failedToken && fresh(e)) return e; // another command just did it
+    const r = await send(`${server}/oauth/token`, form({ grant_type: 'refresh_token', refresh_token: e.refresh_token, client_id: e.client_id, resource: `${server}/mcp` }));
+    const d = await r.json().catch(() => null);
+    if (r.ok && d?.access_token) {
+      const next = toEntry(d, e);
+      setEntry(server, next);
+      return next;
+    }
+    if (r.status === 400 || r.status === 401) {
+      setEntry(server, null);
+      return null;
+    }
+    if (r.status === 404) throw notOpen(server);
+    throw new ScavaError(`Scava answered ${r.status} while renewing the access. Please try again.`);
+  });
+}
+
+async function validEntry(server) {
+  const e = entryOf(server);
+  if (!e) return null;
+  return fresh(e) ? e : renew(server, e.access_token);
+}
+
+const rpc = (server, entry, method, params) => send(`${server}/mcp`, {
+  method: 'POST',
+  headers: { authorization: `Bearer ${entry.access_token}`, 'content-type': 'application/json', accept: 'application/json, text/event-stream', 'mcp-protocol-version': MCP_VERSION },
+  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+});
+
+// Every command that needs an account is one call of the tools every AI gets at /mcp: the rules stay in one place. Returns the text Scava wrote, what it attached for this tool (a one-time link) and whose account it was.
+export async function callTool(server, name, args, signInOptions) {
+  checkServer(server);
+  let entry = (await validEntry(server)) ?? (await signIn(server, signInOptions));
+  for (let attempt = 0; ; attempt++) {
+    const res = await rpc(server, entry, 'tools/call', { name, arguments: args });
+    if (res.status === 401 && attempt < 2) {
+      entry = (await renew(server, entry.access_token)) ?? (await signIn(server, signInOptions));
+      continue;
+    }
+    if (res.status === 404) throw notOpen(server);
+    const d = await res.json().catch(() => null);
+    if (!res.ok || !d?.result) throw new ScavaError(d?.error?.message || `Scava answered ${res.status}.`);
+    const text = (d.result.content ?? []).map((c) => c.text).join('\n');
+    if (d.result.isError) throw new ScavaError(text);
+    return { text, data: d.result.structuredContent ?? {}, account: entry.account };
+  }
+}
+
+// Who this computer is signed in as, checked with Scava. Null when it is not, or no longer.
+export async function whoAmI(server) {
+  checkServer(server);
+  let entry = await validEntry(server);
+  if (!entry) return null;
+  let res = await rpc(server, entry, 'tools/list', {});
+  if (res.status === 401) {
+    entry = await renew(server, entry.access_token);
+    if (!entry) return null;
+    res = await rpc(server, entry, 'tools/list', {});
+  }
+  if (res.status === 404) throw notOpen(server);
+  if (!res.ok) throw new ScavaError(`Scava answered ${res.status}.`);
+  return entry;
+}
+
+// Ends the access at Scava and here. A waiting sign-in ends with it. Other servers stay.
+export async function logout(server) {
+  checkServer(server);
+  fs.rmSync(signInPath(server), { force: true });
+  const e = entryOf(server);
+  if (!e) return { was: false };
+  let reached = false;
+  try {
+    reached = (await send(`${server}/oauth/revoke`, form({ token: e.refresh_token }))).ok;
+  } catch { /* said below */ }
+  await withLock(() => setEntry(server, null));
+  return { was: true, account: e.account, reached };
+}
+
+// --- Signing in -------------------------------------------------------------------------------------------------------
+
+// The name on the page, in the mail and on the Connect page: this computer, so a person can tell their connections apart.
+function clientName() {
+  const host = os.hostname().split('.')[0].replace(/[^\p{L}\p{N}-]/gu, '').slice(0, 40);
+  return host ? `Scava command (${host})` : 'Scava command';
+}
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+// A sign-in that is still waiting on this computer, so a second command does not start another one.
+function pending(server) {
+  const rec = readPrivate(signInPath(server));
+  if (!rec || rec.status || rec.expires_at <= Date.now()) return null;
+  return rec.pid ? (alive(rec.pid) ? rec : null) : (Date.now() - rec.created_at < 10_000 ? rec : null);
+}
+
+function detach(...args) {
+  spawn(process.execPath, [CLI, '__sign-in', ...args], { detached: true, stdio: 'ignore', windowsHide: true, cwd: os.homedir() }).on('error', () => {}).unref();
+}
+
+async function startSignIn(server) {
+  const r = await send(`${server}/oauth/register`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', accept: 'application/json' },
+    body: JSON.stringify({ client_name: clientName(), redirect_uris: [RETURN_ADDRESS], grant_types: ['authorization_code', 'refresh_token'], response_types: ['code'], token_endpoint_auth_method: 'none' }),
+  });
+  if (r.status === 404) throw notOpen(server);
+  const c = await r.json().catch(() => null);
+  if (!r.ok || !c?.client_id) throw new ScavaError(c?.error_description || `Scava answered ${r.status}.`);
+  const t = Date.now();
+  const rec = {
+    server,
+    client_id: c.client_id,
+    verifier: crypto.randomBytes(48).toString('base64url'),
+    state: crypto.randomBytes(24).toString('base64url'),
+    created_at: t,
+    expires_at: t + SIGN_IN_MS,
+  };
+  writePrivate(signInPath(server), rec);
+  detach(signInPath(server), 'start');
+  return rec;
+}
+
+// What came back from the browser, whichever way: is it the answer to this sign-in, from this server?
+function foreignAnswer(u, rec) {
+  const a = Buffer.from(u.searchParams.get('state') ?? '');
+  const b = Buffer.from(rec.state);
+  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return 'This does not belong to the sign-in that is waiting on this computer.';
+  if (u.searchParams.get('iss') !== originOf(rec.server)) return 'This came from another server than the one this computer asked.';
+  return null;
+}
+
+const refusal = (u) => (u.searchParams.get('error') === 'access_denied'
+  ? 'You chose Cancel, so nothing was connected.'
+  : `Scava did not connect this computer: ${(u.searchParams.get('error_description') || u.searchParams.get('error')).replace(/[\x00-\x1f\x7f]/g, ' ').slice(0, 200)}`);
+
+async function complete(rec, code) {
+  const r = await send(`${rec.server}/oauth/token`, form({
+    grant_type: 'authorization_code', code, client_id: rec.client_id, redirect_uri: rec.redirect_uri, code_verifier: rec.verifier, resource: `${rec.server}/mcp`,
+  }));
+  const d = await r.json().catch(() => null);
+  if (!r.ok || !d?.access_token) throw new ScavaError(d?.error_description || `Scava answered ${r.status}.`);
+  await withLock(() => {
+    setEntry(rec.server, toEntry(d, { client_id: rec.client_id }));
+    fs.rmSync(signInPath(rec.server), { force: true });
+  });
+}
+
+// A browser on another device cannot come back to this computer. The person copies the address it tried to open.
+export async function finishWithAddress(server, raw) {
+  const rec = readPrivate(signInPath(server));
+  if (!rec?.redirect_uri || rec.status || rec.expires_at <= Date.now()) throw new ScavaError(`No sign-in is waiting on this computer. Start one with: ${CMD} login`);
+  const wrong = 'That is not the address from the browser. It starts with http://127.0.0.1 and holds code= and state=.';
+  let u;
+  try {
+    u = new URL(String(raw).trim().replace(/^["']|["']$/g, ''));
+  } catch {
+    throw new ScavaError(wrong);
+  }
+  if (u.protocol !== 'http:' || !LOOPBACK.has(u.hostname) || u.pathname !== '/callback') throw new ScavaError(wrong);
+  const foreign = foreignAnswer(u, rec);
+  if (foreign) throw new ScavaError(foreign);
+  if (u.searchParams.get('error')) throw new ScavaError(refusal(u));
+  const code = u.searchParams.get('code');
+  if (!code) throw new ScavaError(wrong);
+  await complete(rec, code);
+}
+
+// The command watches for the result; pasted lines count too. Null when it did not come in time.
+async function waitForAllow(server, waitMs, { log, input }) {
+  const end = Date.now() + waitMs;
+  const rl = input ? readline.createInterface({ input }) : null;
+  rl?.on('line', (line) => {
+    if (line.trim()) finishWithAddress(server, line).catch((e) => log(e.message));
+  });
+  try {
+    for (;;) {
+      const e = entryOf(server);
+      if (e) return e;
+      const rec = readPrivate(signInPath(server));
+      if (rec?.status) {
+        fs.rmSync(signInPath(server), { force: true });
+        throw new ScavaError(rec.message);
+      }
+      if (!rec) {
+        const done = entryOf(server); // finished between the two looks
+        if (done) return done;
+        throw new ScavaError(`The sign-in ended. Please run the command again.`);
+      }
+      if (Date.now() >= end) return null;
+      await sleep(150);
+    }
+  } finally {
+    rl?.close();
+  }
+}
+
+export async function signIn(server, { browser = true, waitMs, reopen = false, log = console.log, input = process.stdin } = {}) {
+  checkServer(server);
+  const atTerminal = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const wait = waitMs ?? (atTerminal ? SIGN_IN_MS : AI_WAIT_MS);
+  let created = false;
+  let rec = await withLock(async () => {
+    const known = pending(server);
+    if (known) return known;
+    created = true;
+    return startSignIn(server);
+  });
+  for (const end = Date.now() + 15_000; !rec?.url; rec = readPrivate(signInPath(server))) {
+    const done = entryOf(server); // another command finished it in the meantime
+    if (done) return done;
+    if (rec?.status) throw new ScavaError(rec.message);
+    if (Date.now() > end) throw new ScavaError('Could not start the sign-in on this computer. Please run the command again.');
+    await sleep(100);
+  }
+
+  const canOpen = browser && !process.env.SSH_CONNECTION && !process.env.SSH_TTY && (process.platform === 'win32' || process.platform === 'darwin' || process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+  if (canOpen && (created || reopen)) openBrowser(rec.url);
+  log(`Scava needs a sign-in on this computer, once. ${canOpen ? 'A browser window opens for it. If not, open this address:' : 'Open this address in a browser, on any device:'}`);
+  log('');
+  log(`  ${rec.url}`);
+  log('');
+  log('Sign in and choose Allow. This continues by itself.');
+  const copy = 'On another device the browser then cannot reach 127.0.0.1. That is normal:';
+  if (atTerminal) log(`${copy} copy the whole address from its address bar and paste it here.`);
+  else {
+    log('');
+    log(`If you are an AI running this: ask the person to sign in in the browser and choose Allow. This command waits ${Math.round(wait / 1000)} seconds. If it ends or your terminal stops it, run it again once they have allowed it: the sign-in keeps waiting for ${Math.ceil((rec.expires_at - Date.now()) / 60_000)} minutes.`);
+    log(`${copy} ask for the whole address from its address bar, then run: ${CMD} login --paste "<address>"`);
+  }
+  log('');
+
+  const entry = await waitForAllow(server, wait, { log, input });
+  if (!entry) throw new ScavaError(`Not signed in yet: the sign-in is waiting in the browser. Once the person has chosen Allow, run this command again.`);
+  log(`Signed in to Scava as ${entry.account ?? 'your account'}. The access stays on this computer, in ${credentialsPath()}. End it with: ${CMD} logout`);
+  log('');
+  return entry;
+}
+
+// --- The small program that waits -------------------------------------------------------------------------------------
+
+const esc = (s) => String(s).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+const pageOf = (title, text) => `<!doctype html><html lang="en"><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(title)} · Scava</title>
+<style>body{margin:0;min-height:100vh;display:grid;place-items:center;padding:1rem;box-sizing:border-box;background:#131518;color:#f2f3f5;font:16px/1.5 system-ui,sans-serif}main{max-width:26rem}h1{font-size:1.4rem;margin:0 0 .5rem}p{margin:0;color:#a9afb8}</style>
+<main><h1>${esc(title)}</h1><p>${esc(text)}</p></main></html>`;
+
+// Started by the command, and started once more by itself, so it is nobody's child: a terminal that ends the command
+// and everything below it does not end the waiting. It holds no connection to the terminal. It ends with the sign-in.
+export async function signInHelper(file, step) {
+  if (step === 'start') {
+    detach(file);
+    return;
+  }
+  const rec = readPrivate(file);
+  if (!rec) return;
+  const fail = (status, message) => {
+    const now = readPrivate(file);
+    if (now) writePrivate(file, { ...now, status, message });
+  };
+  const answer = (s, status, title, text, then) => {
+    s.writeHead(status, {
+      'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', connection: 'close',
+      'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'",
+    });
+    s.end(pageOf(title, text), then);
+  };
+  const finished = () => setTimeout(() => process.exit(0), 100);
+  let current = null;
+  let busy = false;
+
+  const server = http.createServer(async (q, s) => {
+    let u = null;
+    try {
+      u = new URL(q.url, 'http://127.0.0.1');
+    } catch { /* nothing this program sent anyone to */ }
+    if (q.method !== 'GET' || u?.pathname !== '/callback' || !current) {
+      answer(s, 404, 'Nothing here', 'This page belongs to the sign-in of the Scava command.');
+      return;
+    }
+    // Something else knocking does not end the waiting.
+    const foreign = foreignAnswer(u, current);
+    if (foreign) {
+      answer(s, 400, 'Not connected', foreign);
+      return;
+    }
+    if (busy) {
+      answer(s, 409, 'One moment', 'This sign-in is being finished already.');
+      return;
+    }
+    busy = true;
+    if (u.searchParams.get('error')) {
+      fail('refused', refusal(u));
+      answer(s, 200, 'Not connected', 'Nothing was connected. You can close this window.', finished);
+      return;
+    }
+    try {
+      await complete(current, u.searchParams.get('code') ?? '');
+      answer(s, 200, 'Connected', 'You can close this window and go back to your terminal or your AI.', finished);
+    } catch (e) {
+      fail('failed', e.message);
+      answer(s, 200, 'Not connected', e.message, finished);
+    }
+  });
+
+  try {
+    await new Promise((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', resolve);
+    });
+    const redirect = `http://127.0.0.1:${server.address().port}/callback`;
+    const challenge = crypto.createHash('sha256').update(rec.verifier).digest('base64url');
+    const q = new URLSearchParams({
+      response_type: 'code', client_id: rec.client_id, redirect_uri: redirect, state: rec.state,
+      code_challenge: challenge, code_challenge_method: 'S256', scope: 'scava', resource: `${rec.server}/mcp`,
+    });
+    current = { ...rec, redirect_uri: redirect, url: `${rec.server}/oauth/authorize?${q}`, pid: process.pid };
+    writePrivate(file, current);
+  } catch (e) {
+    fail('failed', `Could not wait for the browser on this computer: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Over when the time is up, or when it was finished another way (a pasted address, logout, a newer sign-in).
+  setInterval(() => {
+    const now = readPrivate(file);
+    if (!now || now.pid !== process.pid || now.status) process.exit(0);
+    if (now.expires_at <= Date.now()) {
+      fs.rmSync(file, { force: true });
+      process.exit(0);
+    }
+  }, 1000);
+}