waku-memory 0.2.0 → 0.3.0

package/dist/hook.js

@@ -1,49 +1,69 @@
 // The `hook` subcommand's decision logic. Wired by cli.ts: run() reads one
-// Claude Code hook event as JSON off stdin (that part deliberately does not
-// live here -- see the note on handleHookEvent below) and calls
-// handleHookEvent with the parsed event and a real deps bag. Everything in
-// this file takes its inputs as plain values, so hook.test.mjs can call it
-// directly against temp files and an injected fetchImpl, the same way
-// cli.test.mjs drives applyToHarness without touching a real ~/.claude.json.
+// hook event as JSON off stdin (that part deliberately does not live here --
+// see the note on handleHookEvent below) and calls handleHookEvent with the
+// parsed event and a real deps bag. Everything in this file takes its
+// inputs as plain values, so hook.test.mjs can call it directly against temp
+// files and an injected fetchImpl, the same way cli.test.mjs drives
+// applyToHarness without touching a real ~/.claude.json.
+//
+// Claude Code and Codex both land here (spec 012 §4): the event shape and
+// the stdin fields this file reads were measured identical across the two,
+// so this module itself never asks which harness sent an event -- deps
+// carries a HarnessId, handleHookEvent resolves it to one HarnessProfile
+// (harnesses.ts's PROFILES) up front, and every harness-specific choice
+// (content format, delta formatter, timing budgets, how the brief is
+// printed) reads off that one value. A third harness is a third profile,
+// never a new branch in this file.
 //
 // This is the one piece of the shim that runs unattended, on every turn, in
 // the middle of somebody else's tool -- see task 14's brief for the full
 // argument. Two consequences shape every decision below:
 //
 //   1. It must never throw and never leave a nonzero exit behind. A capture
-//      bug must not read to the user as their actual Claude Code session
-//      failing. handleHookEvent wraps its entire body in one try/catch for
-//      exactly this reason, and every expected failure (missing config, no
-//      new bytes, a non-2xx response, a rejected fetch) returns through its
-//      own branch before ever reaching that catch -- the catch is the net
-//      under the net, for whatever this file's author did not think of.
+//      bug must not read to the user as their actual session failing.
+//      handleHookEvent wraps its entire body in one try/catch for exactly
+//      this reason, and every expected failure (missing config, no new
+//      bytes, a non-2xx response, a rejected fetch) returns through its own
+//      branch before ever reaching that catch -- the catch is the net under
+//      the net, for whatever this file's author did not think of.
 //   2. Content goes to the ingest endpoint and nowhere else, with one
 //      deliberate exception: SessionStart's postBrief writes POST /brief's
-//      `text` to stdout, which Claude Code folds into the session's
-//      context -- that is the entire point of task 9. stdout carries the
-//      brief and nothing else, ever. Every other channel is stderr
-//      (console.error), and never carries a transcript byte, a delta, or
-//      any other response body -- only counts, status codes, and the
-//      event/session names Claude Code itself already put on stdin.
+//      `text` (run through the harness profile's briefOutput -- identity
+//      for Claude Code, the hook JSON contract for Codex) to stdout, which
+//      the harness folds into the session's context -- that is the entire
+//      point of task 9. stdout carries the brief and nothing else, ever.
+//      Every other channel is stderr (console.error), and never carries a
+//      transcript byte, a delta, or any other response body -- only counts,
+//      status codes, and the event/session names already on stdin. The one
+//      further exception is ruling R4 (spec 012 §4.1): the Codex profile
+//      stays silent on stderr too when there is no usable credential, since
+//      Codex has no interactive onboarding to have warned the user first.
 //
 // Zero dependencies, per the brief: only node:fs and node:path here (plus
-// the sibling dialogue.ts module for the cc-dialogue-v1 rule, spec 011
-// §1 -- a local file, not an npm package), plus the global fetch (Node
-// 18+, no import needed) that deps.fetchImpl defaults to at the real call
-// site in cli.ts.
+// the sibling dialogue.ts and harnesses.ts modules -- local files, not npm
+// packages), plus the global fetch (Node 18+, no import needed) that
+// deps.fetchImpl defaults to at the real call site in cli.ts.
 import { appendFileSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
-import { CONTENT_FORMAT, formatDelta, renderEntries } from "./dialogue.js";
+import { formatDelta, renderEntries } from "./dialogue.js";
+import { profileFor } from "./harnesses.js";
 import { resolveProject } from "./project.js";
+// SESSION_END_HOOK_TIMEOUT_S/SESSION_END_TIMEOUT_MS are the Claude Code
+// profile's numbers (harnesses.ts's PROFILES.claude_code) -- defined there,
+// not here, to avoid an import cycle (this file imports profileFor from
+// harnesses.ts; harnesses.ts must not import back). Re-exported unchanged so
+// capture.ts's existing `import { ... } from './hook.ts'` keeps working. See
+// harnesses.ts's own comment on them for the full derivation.
+export { SESSION_END_HOOK_TIMEOUT_S, SESSION_END_TIMEOUT_MS } from "./harnesses.js";
 // Bumped by hand at release time alongside package.json's "version" -- the
 // brief's call: a build-time constant here is fine, and it keeps this file
 // free of any fs reach into its own package.json (which would also be
 // wrong at runtime, since dist/hook.js does not sit next to package.json
 // the way src/hook.ts does). Exported since postBrief's request body and
 // hook.test.mjs's drift check (against package.json) both need it; task 14
-// bumps this and package.json to 0.2.0 together.
-export const SHIM_VERSION = '0.2.0';
-const HARNESS = 'claude_code';
+// (spec 012 §9) bumps this, package.json and the plugin manifest
+// (.codex-plugin/plugin.json) to 0.3.0 together.
+export const SHIM_VERSION = '0.3.0';
 // Exported for capture.ts, which writes the file this module reads.
 export const CONFIG_FILE_NAME = 'config.json';
 // Same-directory temp file + rename, exactly atomicWriteJson's technique in
@@ -133,7 +153,14 @@ export function droppedMarkerPath(watermarkPath) {
 // zero pieces -- every new line was dropped by the formatting rule -- and
 // the caller still advances the watermark to `end` in that case, per
 // formatDelta's own contract.
-export function readDelta(transcriptPath, watermarkPath) {
+export function readDelta(transcriptPath, watermarkPath, 
+// Which formatting rule to run past the watermark -- dialogue.ts's
+// cc-dialogue-v1 by default (every caller before task 8, and every reader
+// test above, wants exactly that); postDelta below passes the running
+// event's profile.formatDelta instead, so the same watermark/piece
+// machinery serves codex-dialogue-v1 too without a second copy of this
+// function.
+formatDeltaFn = formatDelta) {
     let buf;
     try {
         buf = readFileSync(transcriptPath);
@@ -144,7 +171,7 @@ export function readDelta(transcriptPath, watermarkPath) {
     const offset = readWatermark(watermarkPath);
     if (offset >= buf.length)
         return null; // nothing new since last watermark (also covers a shrunk/rotated file)
-    const { pieces, end } = formatDelta(buf.subarray(offset));
+    const { pieces, end } = formatDeltaFn(buf.subarray(offset));
     if (end === 0)
         return null; // the only new bytes are an incomplete trailing line
     return { pieces: pieces.map((p) => ({ ...p, end: offset + p.end })), end: offset + end, offset };
@@ -190,27 +217,6 @@ function postJson(deps, config, path, body, signal) {
         signal,
     });
 }
-// The SessionEnd flush has to finish inside the hook entry capture.ts
-// installs for it, or Claude Code kills the process mid-request with no
-// chance to log why. That entry's `timeout` (seconds) is
-// SESSION_END_HOOK_TIMEOUT_S, defined here so capture.ts imports it and the
-// two numbers cannot drift apart again: until 2026-09-04 the network budget
-// below was 800 ms, derived from Claude Code's 1.5 s *default* SessionEnd
-// budget, while the installed entry had already raised that budget to 10 s
-// -- and 800 ms is one cold round trip to api.waku.one from Yang's machine
-// (three real POST /ingest/session calls measured 822, 644 and 1174 ms), so
-// two of every three flushes were aborted by our own timer. That is the
-// last turn of every session, and all of a single-turn one.
-//
-// The network budget is the process budget minus what happens before the
-// request: `npx -y waku-memory hook` took 2.8 s to reach this code cold
-// (2026-09-04), and Node startup, stdin and the transcript read are a few
-// hundred milliseconds more. 5 s leaves about 2 s of the 10 s for a slower
-// machine. hook.test.mjs pins both bounds. Stop is not bounded this way
-// (600 s budget, and runs "async": true), so its path through postDelta
-// below does not use this.
-export const SESSION_END_HOOK_TIMEOUT_S = 10;
-export const SESSION_END_TIMEOUT_MS = 5000;
 // undici wraps every network-level failure as TypeError("fetch failed") and
 // puts the reason on `cause` -- a DNS name, a refused connection, our own
 // abort, or (2026-09-04) an Authorization header carrying a control
@@ -238,10 +244,15 @@ export const BRIEF_TIMEOUT_MS = 3000;
 // do-nothing-and-log branches) but now bounded by an AbortController --
 // unlike a heartbeat nobody was waiting on, a hung /brief request sits in
 // the middle of the user's SessionStart, so this cannot wait forever.
-async function postBrief(event, deps) {
+async function postBrief(event, deps, profile) {
     const config = readConfig(deps.configDir);
     if (!config) {
-        console.error(`waku-memory hook: no usable config at ${join(deps.configDir, CONFIG_FILE_NAME)} -- no brief.`);
+        // Ruling R4 (spec 012 §4.1): Codex-only, quiet without a credential --
+        // no stdout, no stderr, no fetch call. Claude Code keeps this line
+        // (spec 011 A9: its output is unchanged).
+        if (!profile.silentWithoutCredential) {
+            console.error(`waku-memory hook: no usable config at ${join(deps.configDir, CONFIG_FILE_NAME)} -- no brief.`);
+        }
         return;
     }
     if (typeof event.cwd !== 'string' || event.cwd === '') {
@@ -254,15 +265,19 @@ async function postBrief(event, deps) {
     const timer = setTimeout(() => controller.abort(), deps.briefTimeoutMs ?? BRIEF_TIMEOUT_MS);
     try {
         // POST, not GET: `project` is caller-supplied free text and a query
-        // string would put it in every access log (spec 011 §5).
-        const res = await postJson(deps, config, '/brief', { harness: HARNESS, version: SHIM_VERSION, project }, controller.signal);
+        // string would put it in every access log (spec 011 §5). session_id
+        // travels here too (spec 012 §4) -- every harness, not just Codex.
+        const res = await postJson(deps, config, '/brief', { harness: profile.id, version: SHIM_VERSION, project, session_id: event.session_id }, controller.signal);
         if (!res.ok) {
             console.error(`waku-memory hook: /brief responded ${res.status} -- no brief.`);
             return;
         }
         const body = (await res.json());
         if (typeof body.text === 'string' && body.text !== '') {
-            (deps.stdout ?? defaultStdout)(body.text);
+            // Identity for Claude Code (plain text); Codex wraps it in the hook
+            // JSON contract (spec 012 §4) -- the only place that knows which is
+            // profile.briefOutput itself, never a check here.
+            (deps.stdout ?? defaultStdout)(profile.briefOutput(body.text));
         }
         else {
             // A 2xx with missing, non-string, or empty text is a failure like any other.
@@ -302,15 +317,22 @@ export function trailingAssistantText(entries) {
         .map((e) => e.text)
         .join(' ');
 }
-async function postDelta(event, deps, source) {
-    if (!event.transcript_path) {
-        console.error(`waku-memory hook: no transcript_path on this ${event.hook_event_name} event -- skipping.`);
-        return;
-    }
+async function postDelta(event, deps, source, profile) {
+    // Config is checked before transcript_path, deliberately: ruling R4 (spec
+    // 012 §4.1) says a Codex event with no usable config.json exits quietly
+    // regardless of what else about the event is missing or malformed --
+    // checking transcript_path first would let that branch's stderr line fire
+    // ahead of the credential check and break the "no stderr at all" promise.
     const configPath = join(deps.configDir, CONFIG_FILE_NAME);
     const config = readConfig(deps.configDir);
     if (!config) {
-        console.error(`waku-memory hook: no usable config at ${configPath} -- skipping.`);
+        if (!profile.silentWithoutCredential) {
+            console.error(`waku-memory hook: no usable config at ${configPath} -- skipping.`);
+        }
+        return;
+    }
+    if (!event.transcript_path) {
+        console.error(`waku-memory hook: no transcript_path on this ${event.hook_event_name} event -- skipping.`);
         return;
     }
     // session_id arrives parsed from stdin and is used as a path segment
@@ -319,7 +341,7 @@ async function postDelta(event, deps, source) {
     // configDir/state. The same-user trust boundary already limits the blast
     // radius, but this removes the footgun rather than relying on that alone.
     const watermarkPath = join(deps.configDir, 'state', basename(event.session_id));
-    let delta = readDelta(event.transcript_path, watermarkPath);
+    let delta = readDelta(event.transcript_path, watermarkPath, profile.formatDelta);
     if (delta === null) {
         // spec 011 §2: the transcript can lag the turn past every complete
         // line it holds. On Stop, a non-empty last_assistant_message is
@@ -364,14 +386,15 @@ async function postDelta(event, deps, source) {
             }
         }
     }
-    // Only session-end is bounded -- see SESSION_END_TIMEOUT_MS's comment.
-    // One deadline for the whole flush, not one budget per piece: several
-    // pieces each getting the full SESSION_END_TIMEOUT_MS would let a
-    // many-piece session run far longer than the budget the installed hook
-    // entry actually gives the process. Stop's deadline stays undefined, so
-    // every piece's controller below is undefined too -- identical to not
-    // passing a signal at all.
-    const budgetMs = deps.sessionEndTimeoutMs ?? SESSION_END_TIMEOUT_MS;
+    // Only session-end is bounded -- see harnesses.ts's SESSION_END_TIMEOUT_MS
+    // comment. One deadline for the whole flush, not one budget per piece:
+    // several pieces each getting the full budget would let a many-piece
+    // session run far longer than the budget the installed hook entry
+    // actually gives the process. Stop's deadline stays undefined, so every
+    // piece's controller below is undefined too -- identical to not passing a
+    // signal at all. profile.sessionEndTimeoutMs is Codex's 2000 ms or Claude
+    // Code's 5000 ms; deps.sessionEndTimeoutMs (test-only) overrides either.
+    const budgetMs = deps.sessionEndTimeoutMs ?? profile.sessionEndTimeoutMs;
     const deadline = source === 'session-end' ? Date.now() + budgetMs : undefined;
     let previousEnd = delta.offset;
     for (const piece of delta.pieces) {
@@ -380,11 +403,11 @@ async function postDelta(event, deps, source) {
         let res;
         try {
             res = await postJson(deps, config, '/ingest/session', {
-                harness: HARNESS,
+                harness: profile.id,
                 session_id: event.session_id,
                 source,
                 content: piece.text,
-                content_format: CONTENT_FORMAT,
+                content_format: profile.contentFormat,
                 ...(event.cwd ? { project: resolveProject(event.cwd) } : {}),
             }, controller?.signal);
         }
@@ -459,15 +482,21 @@ export async function handleHookEvent(event, deps) {
             console.error('waku-memory hook: received a malformed hook event on stdin -- skipping.');
             return;
         }
+        // The only place that asks "which harness?" -- everything downstream
+        // (postBrief, postDelta, readDelta) takes the answer as a profile, never
+        // as a string to compare against. deps.harness is typed HarnessId, so
+        // profileFor always finds an entry in PROFILES; cli.ts's dispatch() is
+        // what rejects an unknown --harness value before this is ever reached.
+        const profile = profileFor(deps.harness ?? 'claude_code');
         switch (event.hook_event_name) {
             case 'SessionStart':
-                await postBrief(event, deps);
+                await postBrief(event, deps, profile);
                 return;
             case 'Stop':
-                await postDelta(event, deps, 'stop');
+                await postDelta(event, deps, 'stop', profile);
                 return;
             case 'SessionEnd':
-                await postDelta(event, deps, 'session-end');
+                await postDelta(event, deps, 'session-end', profile);
                 return;
             default:
                 console.error(`waku-memory hook: ignoring unhandled event "${String(event.hook_event_name)}".`);

package/dist/login.js

@@ -0,0 +1,312 @@
+// `login` -- the browser OAuth flow that mints an API key without the
+// person ever seeing one (spec 012 §7). Wired by cli.ts's `login` command
+// and, since task 13, `capture enable`'s third path (a person who has no
+// key yet is offered this instead of the paste prompt); this file only
+// orchestrates the flow itself against an injected deps bag, the same
+// split hook.ts/capture.ts already established, so login.test.mjs can
+// drive it against a fake authorization server and a fake API on
+// 127.0.0.1 and never touch a real browser or a real waku.one.
+//
+// The shape, in order: discover the authorization server from the API's
+// protected-resource metadata, dynamically register a public client,
+// listen on a loopback port, send the person to the authorization
+// endpoint (PKCE S256, a random state, printed and opened), wait for the
+// redirect back, exchange the code for a token, mint a key with it, and
+// write that key exactly where a pasted one goes (writeConfigJson,
+// sanitizeKey -- both capture.ts's, not reimplemented here).
+//
+// Zero new runtime dependency, per the shim's package.json: node:http,
+// node:crypto, node:os and capture.ts (itself dependency-free) only.
+import { createServer } from 'node:http';
+import { randomBytes, createHash } from 'node:crypto';
+import { hostname } from 'node:os';
+import { sanitizeKey, writeConfigJson } from "./capture.js";
+// §7: five minutes to complete a browser round trip is generous without
+// being indefinite -- a person who wanders off leaves nothing running past
+// that, and the loopback server closes either way (see login()'s finish).
+export const LOGIN_TIMEOUT_MS = 300_000;
+export const LOGIN_SCOPES = 'openid profile email offline_access';
+// The `resource` parameter (RFC 8707) login sends in the authorize URL and
+// the token request is always derived at runtime from deps.apiBase --
+// `${apiBase}/mcp` with a trailing slash stripped first -- never this
+// constant. LOGIN_RESOURCE exists only as the documented value for the
+// default apiBase, so a reader (or a test asserting against the default)
+// has something to compare the runtime value to without recomputing it.
+export const LOGIN_RESOURCE = 'https://api.waku.one/mcp';
+const REGISTERED_REDIRECT_URI = 'http://127.0.0.1/callback';
+// Carries which of the four network steps failed and the HTTP status that
+// said so -- login()'s refusal branches read both off this and print
+// neither a response body nor anything from the request (never the token,
+// never the key): "Sign-in failed at <step> (HTTP <status>)." is the whole
+// line.
+class StepError extends Error {
+    step;
+    status;
+    constructor(step, status) {
+        super(`${step} step failed with HTTP ${status}`);
+        this.step = step;
+        this.status = status;
+    }
+}
+function stripSlash(url) {
+    return url.replace(/\/+$/, '');
+}
+// GET <apiBase>/.well-known/oauth-protected-resource for the resource's
+// authorization server, then that server's own
+// /.well-known/oauth-authorization-server for the three endpoints login
+// needs. Throws StepError('discovery', status) on anything short of a
+// clean pair of 2xx JSON responses carrying the fields this reads --
+// login() is the only caller and turns that into the one printed line.
+export async function discover(apiBase, fetchImpl) {
+    const base = stripSlash(apiBase);
+    const resourceRes = await fetchImpl(`${base}/.well-known/oauth-protected-resource`);
+    if (!resourceRes.ok)
+        throw new StepError('discovery', resourceRes.status);
+    const resourceBody = (await resourceRes.json());
+    const issuer = Array.isArray(resourceBody.authorization_servers) ? resourceBody.authorization_servers[0] : undefined;
+    if (typeof issuer !== 'string' || issuer === '')
+        throw new StepError('discovery', resourceRes.status);
+    const asRes = await fetchImpl(`${stripSlash(issuer)}/.well-known/oauth-authorization-server`);
+    if (!asRes.ok)
+        throw new StepError('discovery', asRes.status);
+    const asBody = (await asRes.json());
+    const { authorization_endpoint, token_endpoint, registration_endpoint } = asBody;
+    if (typeof authorization_endpoint !== 'string' ||
+        typeof token_endpoint !== 'string' ||
+        typeof registration_endpoint !== 'string') {
+        throw new StepError('discovery', asRes.status);
+    }
+    return {
+        issuer,
+        authorizationEndpoint: authorization_endpoint,
+        tokenEndpoint: token_endpoint,
+        registrationEndpoint: registration_endpoint,
+    };
+}
+// Dynamic client registration (RFC 7591): a public client, redirect fixed
+// at the bare loopback address (RFC 8252 §7.3 -- the *port* login actually
+// redirects to is chosen per run and never registered, which is the whole
+// point of the loopback exception). Returns client_id; throws
+// StepError('registration', status) otherwise.
+export async function registerClient(registrationEndpoint, fetchImpl, version) {
+    const res = await fetchImpl(registrationEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            client_name: `waku-memory ${version}`,
+            redirect_uris: [REGISTERED_REDIRECT_URI],
+            grant_types: ['authorization_code'],
+            response_types: ['code'],
+            token_endpoint_auth_method: 'none',
+        }),
+    });
+    if (!res.ok)
+        throw new StepError('registration', res.status);
+    const body = (await res.json());
+    if (typeof body.client_id !== 'string' || body.client_id === '')
+        throw new StepError('registration', res.status);
+    return body.client_id;
+}
+// PKCE (RFC 7636), S256 only: a 32-byte random verifier, base64url; the
+// challenge is its SHA-256 digest, also base64url. Buffer's own
+// 'base64url' encoding already omits padding, so neither value needs the
+// usual base64 cleanup.
+export function pkce() {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    return { verifier, challenge };
+}
+export function authorizeUrl(p) {
+    const url = new URL(p.authorizationEndpoint);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', p.clientId);
+    url.searchParams.set('redirect_uri', p.redirectUri);
+    url.searchParams.set('state', p.state);
+    url.searchParams.set('code_challenge', p.challenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    url.searchParams.set('scope', LOGIN_SCOPES);
+    url.searchParams.set('resource', p.resource);
+    return url.toString();
+}
+async function exchangeToken(tokenEndpoint, fetchImpl, p) {
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        code: p.code,
+        redirect_uri: p.redirectUri,
+        client_id: p.clientId,
+        code_verifier: p.verifier,
+        resource: p.resource,
+    });
+    const res = await fetchImpl(tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: body.toString(),
+    });
+    if (!res.ok)
+        throw new StepError('token', res.status);
+    const json = (await res.json());
+    if (typeof json.access_token !== 'string' || json.access_token === '')
+        throw new StepError('token', res.status);
+    return { accessToken: json.access_token, idToken: typeof json.id_token === 'string' ? json.id_token : undefined };
+}
+// The email printed in the final "Signed in as <email>" line -- read from
+// the token response's id_token, an unsigned decode of its middle segment
+// (base64url JSON), never signature-checked: it arrived over TLS from the
+// issuer discover() itself found, and the only use is one word in a
+// stdout line, not an authorization decision. Anything short of a clean
+// {email: string} there (no id_token, unparseable, wrong shape) falls back
+// to the literal word "you" -- login() never blocks on this.
+function emailFromIdToken(idToken) {
+    if (!idToken)
+        return null;
+    const parts = idToken.split('.');
+    if (parts.length < 2)
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        return typeof payload.email === 'string' && payload.email !== '' ? payload.email : null;
+    }
+    catch {
+        return null;
+    }
+}
+// keys.py's CreateKeyRequest.label: free text, default "unnamed", capped
+// at 200 chars server-side -- truncated here too so a very long hostname
+// never trips the server's own validation into a refusal this file would
+// then have to explain.
+function keyLabel() {
+    const label = `waku-memory on ${hostname()}`;
+    return label.length > 200 ? label.slice(0, 200) : label;
+}
+function reportRefusal(deps, fallbackStep, err) {
+    const step = err instanceof StepError ? err.step : fallbackStep;
+    const status = err instanceof StepError ? err.status : 0;
+    deps.stdout(`Sign-in failed at ${step} (HTTP ${status}).`);
+}
+// The whole flow. Never prints the token or the key on any path -- the
+// only things written to deps.stdout are the authorize URL, the final
+// "Signed in as <email>" line, and (on refusal) the one-line step/status
+// report above. The loopback server, once opened, is closed on every path
+// out of the returned promise: 'signed-in', 'timeout', and 'refused' from
+// a bad token or keys response all go through the same finish().
+// 'refused' from discovery or registration returns before any server
+// exists, so there is nothing to close on those two paths.
+export async function login(deps) {
+    const apiBase = stripSlash(deps.apiBase);
+    const resource = `${apiBase}/mcp`;
+    const timeoutMs = deps.timeoutMs ?? LOGIN_TIMEOUT_MS;
+    let discovered;
+    try {
+        discovered = await discover(apiBase, deps.fetchImpl);
+    }
+    catch (err) {
+        reportRefusal(deps, 'discovery', err);
+        return 'refused';
+    }
+    let clientId;
+    try {
+        clientId = await registerClient(discovered.registrationEndpoint, deps.fetchImpl, deps.version);
+    }
+    catch (err) {
+        reportRefusal(deps, 'registration', err);
+        return 'refused';
+    }
+    const { verifier, challenge } = pkce();
+    const state = randomBytes(16).toString('hex');
+    return new Promise((resolveLogin) => {
+        let settled = false;
+        let port = 0;
+        let accepted = false;
+        const server = createServer((req, res) => {
+            const requestUrl = new URL(req.url ?? '/', 'http://127.0.0.1');
+            if (requestUrl.pathname !== '/callback') {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const code = requestUrl.searchParams.get('code');
+            const receivedState = requestUrl.searchParams.get('state');
+            if (receivedState !== state || !code) {
+                // Wrong or missing state: keep waiting -- a stray or forged hit on
+                // this port must not end the flow the real browser is still
+                // carrying.
+                res.writeHead(400);
+                res.end();
+                return;
+            }
+            // OAuth codes are single-use and minting a credential should be
+            // idempotent only by accident; the client must not rely on the
+            // authorization server to defend against replay. Guard here: flag
+            // the code accepted before any async work, so a concurrent request
+            // sees the flag and returns 200 without re-running the exchange.
+            if (accepted) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end('Signed in. You can close this tab.');
+                return;
+            }
+            accepted = true;
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end('Signed in. You can close this tab.');
+            void finishSignIn(code);
+        });
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            server.close();
+            resolveLogin(result);
+        };
+        async function finishSignIn(code) {
+            try {
+                const redirectUri = `http://127.0.0.1:${port}/callback`;
+                const tokenResult = await exchangeToken(discovered.tokenEndpoint, deps.fetchImpl, {
+                    code,
+                    redirectUri,
+                    clientId,
+                    verifier,
+                    resource,
+                });
+                const keysRes = await deps.fetchImpl(`${apiBase}/keys`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: `Bearer ${tokenResult.accessToken}`,
+                    },
+                    body: JSON.stringify({ label: keyLabel() }),
+                });
+                if (!keysRes.ok)
+                    throw new StepError('keys', keysRes.status);
+                const keysBody = (await keysRes.json());
+                if (typeof keysBody.plaintext !== 'string' || keysBody.plaintext === '') {
+                    throw new StepError('keys', keysRes.status);
+                }
+                const { key } = sanitizeKey(keysBody.plaintext);
+                writeConfigJson(deps.configDir, { url: apiBase, key });
+                const email = emailFromIdToken(tokenResult.idToken) ?? 'you';
+                deps.stdout(`Signed in as ${email}. Key stored in ${deps.configDir}/config.json.`);
+                finish('signed-in');
+            }
+            catch (err) {
+                reportRefusal(deps, 'token', err);
+                finish('refused');
+            }
+        }
+        const timer = setTimeout(() => finish('timeout'), timeoutMs);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            port = typeof address === 'object' && address !== null ? address.port : 0;
+            const redirectUri = `http://127.0.0.1:${port}/callback`;
+            const url = authorizeUrl({
+                authorizationEndpoint: discovered.authorizationEndpoint,
+                clientId,
+                redirectUri,
+                state,
+                challenge,
+                resource,
+            });
+            deps.stdout(`Open this URL if your browser did not: ${url}`);
+            deps.openBrowser(url);
+        });
+    });
+}