driggsby 0.6.3 → 0.7.1

package/dist/login/claim-client.js

@@ -1,8 +1,9 @@
 // The app-token claim flow's HTTP client, against Driggsby's public
-// app-token claim API: create a pending claim, send the user to claim_url,
-// poll with the claim id + poll secret until the user approves. The app
-// token is returned by exactly one poll; callers must never poll again after
-// an approval.
+// app-token claim API: create a pending claim carrying a PKCE challenge,
+// send the user to claim_url, and trade the one-time code the approval
+// produced, with the verifier, for the app token. The poll only tells a
+// waiting sign-in that its claim is gone (denied or expired); Driggsby
+// hands a PKCE claim's token only to the code trade.
 import { CliError } from "../cli-error.js";
 import { knownDevice } from "../device.js";
 import { sanitizeForTerminal } from "../terminal-text.js";
@@ -26,11 +27,18 @@ export const SIGN_IN_START_FAILURE = "We weren't able to start a Driggsby sign-i
 const SIGN_IN_FINISH_FAILURE = "We weren't able to finish your Driggsby sign-in just now. Please try again\nin a minute.";
 // device: this computer's name and system (device.ts), so the sign-in shows
 // up on Driggsby's MCP page as the computer it is; only known values go.
-export async function createClaimRequest(baseUrl, device = { name: null, system: null }) {
+export async function createClaimRequest(baseUrl, pkce, device = { name: null, system: null }) {
     const response = await fetch(`${baseUrl}/app-tokens/claim-requests`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ app_name: CLAIM_APP_NAME, scope: CLAIM_SCOPE, ...deviceField(device) }),
+        body: JSON.stringify({
+            app_name: CLAIM_APP_NAME,
+            scope: CLAIM_SCOPE,
+            code_challenge: pkce.challenge,
+            code_challenge_method: "S256",
+            ...(pkce.redirectUri === null ? {} : { redirect_uri: pkce.redirectUri }),
+            ...deviceField(device),
+        }),
         signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
         // Never follow a redirect: a 307/308 would replay this claim flow —
         // and, on the poll below, the poll secret — to whatever origin a
@@ -119,6 +127,47 @@ export async function pollClaimRequest(baseUrl, credentials) {
             return { kind: "transient" };
     }
 }
+const CODE_REJECTED = "That sign-in code didn't work. It may have been mistyped, used\nalready, or expired.";
+export async function tradeCode(baseUrl, trade) {
+    let response;
+    try {
+        response = await fetch(`${baseUrl}/app-tokens/claim-requests/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                claim_request_id: trade.claimRequestId,
+                code: trade.code,
+                code_verifier: trade.codeVerifier,
+            }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            // The verifier and code must never follow a redirect to another origin.
+            redirect: "error",
+        });
+    }
+    catch {
+        return { kind: "transient" };
+    }
+    const body = await readJsonBody(response);
+    if (response.status === 200) {
+        const appToken = stringField(asRecord(body), "app_token");
+        if (appToken === null) {
+            throw new CliError(SIGN_IN_FINISH_FAILURE, 1);
+        }
+        return { kind: "approved", appToken };
+    }
+    // The CLI says what to do next itself (paste again, or start over), so a
+    // refused code reads in its own words.
+    // 422 too: a paste Driggsby reads as blank (a Unicode space the CLI
+    // doesn't trim) is a wrong code, never the end of the sign-in.
+    if (response.status === 400 || response.status === 422) {
+        return { kind: "rejected", message: CODE_REJECTED };
+    }
+    if (response.status === 429 || response.status >= 500) {
+        return { kind: "transient" };
+    }
+    // Any other answer means our request is wrong, which a retry can't fix.
+    throw new CliError(errorDescription(body) ?? SIGN_IN_FINISH_FAILURE, 1);
+}
 async function readJsonBody(response) {
     let text;
     try {

package/dist/login/login.js

@@ -1,42 +1,151 @@
-// driggsby login: create an app-token claim, send the user to the approval
-// page, poll until they approve, and store the token. The token is shown to
-// no one — it goes straight from the poll response into the credential
-// store.
+// driggsby login: sign in with PKCE. The CLI keeps a verifier, listens on
+// its loopback when it can, and opens Driggsby's approval page itself.
+// Approving there hands the one-time code to this CLI's loopback;
+// approving from any other browser shows the code, to paste here or to
+// finish with `driggsby login --code <CODE>`. Only the code and the
+// verifier together mint the token, which goes straight into the
+// credential store and is shown to no one.
 import { apiBaseUrl, apiHost, baseUrlMayReceiveSavedSignIn } from "../api/base-url.js";
 import { blockedNetworkError } from "../api/network-error.js";
 import { CliError } from "../cli-error.js";
 import { describeDevice } from "../device.js";
 import { defaultCredentialEnvironment, describeStorageLocation, environmentToken, saveToken, } from "../credentials/store.js";
 import { sanitizeForTerminal, wrapProse } from "../terminal-text.js";
-import { createClaimRequest, pollClaimRequest, SIGN_IN_START_FAILURE, } from "./claim-client.js";
+import { awaitToken, ClaimGone, CODE_COMMAND, CODE_WINDOW_MS, LOGIN_RETRY_COMMAND, tradeWithRetries, } from "./await-token.js";
+import { createClaimRequest, SIGN_IN_START_FAILURE } from "./claim-client.js";
+import { startLoopback } from "./loopback.js";
 import { tryOpenUrl } from "./open-url.js";
-const LOGIN_RETRY_COMMAND = "npx driggsby@latest login";
+import { clearPendingLogin, markPendingLoginFinished, readPendingLogin, savePendingLogin, } from "./pending.js";
+import { createPkcePair } from "./pkce.js";
+import { abortableSleep } from "./sleep.js";
+import { terminalCodePrompt } from "./terminal-prompt.js";
 const DEFAULT_POLL_INTERVAL_MS = 4_000;
+// How long a waiting login gives `login --code` to mark a spent claim.
+export const FINISH_MARK_WAIT_MS = 3_000;
+// Where a browser opened "here" may really run on another computer (an SSH
+// session, a cloud dev box forwarding its opener), so its approval could
+// never reach this loopback: the page shows the code to paste instead.
+const REMOTE_SESSION_VARIABLES = ["SSH_CONNECTION", "SSH_TTY", "CODESPACES", "GITPOD_WORKSPACE_ID"];
 function defaultLoginIo() {
     return {
         out: (text) => {
             process.stdout.write(text);
         },
         openUrl: tryOpenUrl,
-        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        sleep: abortableSleep,
         now: () => Date.now(),
         pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+        startLoopback,
+        codePrompt: terminalCodePrompt,
     };
 }
 export async function runLogin(environment = defaultCredentialEnvironment(), io = defaultLoginIo()) {
     const baseUrl = apiBaseUrl(environment.env);
     io.out("Sign in to Driggsby\n\n");
-    const claim = await createClaim(baseUrl);
-    const claimUrl = approvedClaimUrl(claim.claimUrl, baseUrl);
-    const browserOpened = await io.openUrl(claimUrl);
-    io.out(browserOpened
-        ? "Your browser should open a Driggsby approval page. If it doesn't, open\nthis link:\n\n"
-        : "Open this link in your browser to approve access for this machine:\n\n");
-    io.out(`  ${claimUrl}\n\n`);
-    const minutes = approximateMinutes(claim.expiresInSeconds);
-    const minutesWord = minutes === 1 ? "minute" : "minutes";
-    io.out(`Waiting for your approval (the link is good for about ${minutes} ${minutesWord})...\n`);
-    const appToken = await pollUntilApproved(baseUrl, claim, io);
+    const pkce = createPkcePair();
+    const remoteSession = REMOTE_SESSION_VARIABLES.some((name) => (environment.env[name] ?? "") !== "");
+    const loopback = remoteSession ? null : await io.startLoopback();
+    let prompt = null;
+    try {
+        const claim = await createClaim(baseUrl, { challenge: pkce.challenge, redirectUri: loopback?.redirectUri ?? null });
+        const claimUrl = approvedClaimUrl(claim.claimUrl, baseUrl);
+        const expiresAt = io.now() + claim.expiresInSeconds * 1_000;
+        const pending = {
+            baseUrl,
+            claimRequestId: claim.claimRequestId,
+            codeVerifier: pkce.verifier,
+            expiresAt: expiresAt + CODE_WINDOW_MS,
+            finished: false,
+        };
+        const remembered = await rememberPendingLogin(environment, pending);
+        prompt = io.codePrompt();
+        // With no one at a prompt and no loopback, only `login --code` can
+        // finish, and it needs the record: refuse before a page opens that
+        // nothing could finish.
+        if (prompt === null && loopback === null && !remembered) {
+            throw cantFinishHere();
+        }
+        // Only a page this CLI opened itself may hand its code to the
+        // loopback; the printed link, opened anywhere, shows the code instead.
+        const browserOpened = await io.openUrl(loopback === null ? claimUrl : handoffUrl(claimUrl));
+        const minutes = approximateMinutes(claim.expiresInSeconds);
+        const minutesWord = minutes === 1 ? "minute" : "minutes";
+        // No one at a prompt, and no page this CLI opened can hand the code to
+        // the loopback: an agent, or a remote session. Nothing in this process
+        // could ever receive the code, so it doesn't wait: the page shows the
+        // code, and `login --code` finishes with the record.
+        const finishesElsewhere = prompt === null && (loopback === null || !browserOpened);
+        if (finishesElsewhere && !remembered) {
+            throw cantFinishHere();
+        }
+        io.out(browserOpened
+            ? "Your browser should open a Driggsby approval page. If it doesn't, open\nthis link:\n\n"
+            : "Open this link in your browser to approve access for this machine:\n\n");
+        io.out(`  ${claimUrl}\n\n`);
+        if (finishesElsewhere) {
+            io.out(`After you approve, the page shows a code. Finish signing in with:\n  ${CODE_COMMAND}\n\n`);
+            io.out(`The link is good for about ${minutes} ${minutesWord}.\n`);
+            return;
+        }
+        io.out(`Waiting for your approval (the link is good for about ${minutes} ${minutesWord})...\n`);
+        if (prompt === null && remembered) {
+            io.out(`If the page shows a code instead, finish with:\n  ${CODE_COMMAND}\n`);
+        }
+        const finish = await awaitTokenOrElsewhere(pending, awaitToken({
+            baseUrl,
+            claimRequestId: claim.claimRequestId,
+            pollSecret: claim.pollSecret,
+            codeVerifier: pkce.verifier,
+            deadline: expiresAt,
+            landingUrl: claimUrl,
+            loopback,
+            prompt,
+            promptQuestion: "If the page shows a code instead, paste it here: ",
+        }, io), remembered, environment, io);
+        prompt?.close();
+        prompt = null;
+        // The claim is spent either way; only this sign-in's own record goes.
+        await forgetPendingLogin(environment, pending, io);
+        if (finish.kind === "elsewhere") {
+            io.out("\nThis sign-in was finished by npx driggsby@latest login --code in\n" +
+                "another command; its output says where the token was saved.\n");
+            return;
+        }
+        await finishSignIn(finish.appToken, environment, io);
+    }
+    finally {
+        prompt?.close();
+        loopback?.close();
+    }
+}
+// driggsby login --code <CODE>: finish the sign-in waiting on this computer
+// with the code its approval page showed.
+export async function runLoginWithCode(code, environment = defaultCredentialEnvironment(), io = defaultLoginIo()) {
+    const baseUrl = apiBaseUrl(environment.env);
+    const pending = await readPendingLogin(environment.homeDirectory, io.now());
+    if (pending?.baseUrl !== baseUrl) {
+        throw new CliError("No sign-in is waiting for a code on this computer. It may have expired.\n\n" +
+            `Start a fresh sign-in:\n  ${LOGIN_RETRY_COMMAND}`, 1);
+    }
+    if (pending.finished) {
+        throw new CliError(`This sign-in already finished.\n\nTo sign in again:\n  ${LOGIN_RETRY_COMMAND}`, 1);
+    }
+    const result = await tradeWithRetries(pending, code.trim(), io);
+    if (result.kind === "unreachable") {
+        throw new CliError(`${result.message}\n\nYour code may still work: run the same command again in a minute.\n` +
+            `Or start a fresh sign-in:\n  ${LOGIN_RETRY_COMMAND}`, 1);
+    }
+    if (result.kind === "rejected") {
+        // One record per computer: a newer `login` replaced an older one's.
+        throw new CliError(`${result.message}\n\nCheck the code and run the command again. Only the code from the latest\n` +
+            `sign-in started on this computer works here. Or start a fresh sign-in:\n  ${LOGIN_RETRY_COMMAND}`, 1);
+    }
+    // Marked once the claim is spent, before the token is saved: a login
+    // still waiting on this claim sees it finished here, not failed.
+    await markFinished(environment, pending, io);
+    await finishSignIn(result.appToken, environment, io);
+}
+async function finishSignIn(appToken, environment, io) {
     // Warnings are held back and printed after the "Approved." line — and when
     // one fires, it replaces the all-clear closer: the last thing the user
     // reads must never contradict a warning they were just shown.
@@ -53,6 +162,81 @@ export async function runLogin(environment = defaultCredentialEnvironment(), io
     }
     io.out("\nNext:\n  You're all set — driggsby commands will use this saved token\n  automatically. Deploy an app with npx driggsby@latest deploy.\n");
 }
+// The record `login --code` finishes from. Best effort: without it, the
+// loopback and the prompt still work. True once it is saved.
+async function rememberPendingLogin(environment, pending) {
+    try {
+        await savePendingLogin(environment.homeDirectory, pending);
+        return true;
+    }
+    catch {
+        // The credential save reports an unwritable home directory itself.
+        return false;
+    }
+}
+// The wait's token, or "elsewhere" when `login --code` in another command
+// finished this very sign-in meanwhile: the claim reads gone, and this
+// claim's record says finished. Any other failure also ends this sign-in
+// for good, so its record goes with it.
+async function awaitTokenOrElsewhere(pending, wait, remembered, environment, io) {
+    try {
+        return { kind: "token", appToken: await wait };
+    }
+    catch (error) {
+        if (remembered && error instanceof ClaimGone && (await finishedElsewhere(environment, pending, io))) {
+            return { kind: "elsewhere" };
+        }
+        await forgetPendingLogin(environment, pending, io);
+        throw error;
+    }
+}
+// `login --code` marks the record just after its trade spends the claim,
+// so a poll can read gone a moment before the mark lands: a record still
+// this claim's but not yet finished is read once more after a pause.
+async function finishedElsewhere(environment, pending, io) {
+    for (let look = 1;; look += 1) {
+        let current;
+        try {
+            current = await readPendingLogin(environment.homeDirectory, io.now());
+        }
+        catch {
+            return false;
+        }
+        if (current?.claimRequestId !== pending.claimRequestId) {
+            return false;
+        }
+        if (current.finished || look >= 2) {
+            return current.finished;
+        }
+        await io.sleep(FINISH_MARK_WAIT_MS);
+    }
+}
+async function forgetPendingLogin(environment, pending, io) {
+    try {
+        await clearPendingLogin(environment.homeDirectory, pending.claimRequestId, io.now());
+    }
+    catch {
+        // It expires on its own.
+    }
+}
+async function markFinished(environment, pending, io) {
+    try {
+        await markPendingLoginFinished(environment.homeDirectory, pending.claimRequestId, io.now());
+    }
+    catch {
+        // Only a login still waiting on this claim reads it, and it then
+        // reports the claim gone: the token below is saved all the same.
+    }
+}
+function cantFinishHere() {
+    return new CliError("We couldn't save this sign-in on this machine to finish it later, so it\n" +
+        `can't finish here. Run it in a terminal instead:\n  ${LOGIN_RETRY_COMMAND}`, 1);
+}
+function handoffUrl(claimUrl) {
+    const url = new URL(claimUrl);
+    url.searchParams.set("handoff", "loopback");
+    return url.href;
+}
 // The one-time token is already consumed by the time saving starts, so a
 // storage failure must say clearly that a fresh sign-in is needed — never
 // the generic "something went wrong".
@@ -68,12 +252,12 @@ async function storeApprovedToken(appToken, environment, warn) {
             `on this machine. Please sign in again:\n  ${LOGIN_RETRY_COMMAND}`, 1);
     }
 }
-async function createClaim(baseUrl) {
+async function createClaim(baseUrl, pkce) {
     try {
         // This computer's name goes only to Driggsby (or a local run), never
         // to another host a base-URL override names.
         const device = baseUrlMayReceiveSavedSignIn(baseUrl) ? describeDevice() : { name: null, system: null };
-        return await createClaimRequest(baseUrl, device);
+        return await createClaimRequest(baseUrl, pkce, device);
     }
     catch (error) {
         const blocked = blockedNetworkError(error, {
@@ -112,27 +296,6 @@ function approvedClaimUrl(rawClaimUrl, baseUrl) {
     }
     return sanitizeForTerminal(parsed.href);
 }
-async function pollUntilApproved(baseUrl, claim, io) {
-    const deadline = io.now() + claim.expiresInSeconds * 1_000;
-    const credentials = { claimRequestId: claim.claimRequestId, pollSecret: claim.pollSecret };
-    while (io.now() < deadline) {
-        await io.sleep(io.pollIntervalMs);
-        const result = await pollClaimRequest(baseUrl, credentials);
-        switch (result.kind) {
-            case "approved":
-                // The token is delivered exactly once; from here on, never poll again.
-                return result.appToken;
-            case "gone":
-                throw new CliError("This sign-in link is no longer active — it may have been declined or timed out.\n\n" +
-                    `Start a fresh sign-in:\n  ${LOGIN_RETRY_COMMAND}`, 1);
-            case "pending":
-            case "transient":
-                break;
-        }
-    }
-    throw new CliError("The sign-in link expired before it was approved.\n\n" +
-        `Start a fresh sign-in:\n  ${LOGIN_RETRY_COMMAND}`, 1);
-}
 // DRIGGSBY_TOKEN outranks every saved token, so a login that saved one has
 // not actually changed which token commands use. The warning joins the same
 // held-back channel as storage warnings: after the "Approved." line, in

package/dist/login/loopback.js

@@ -0,0 +1,153 @@
+// The loopback listener for driggsby login (RFC 8252). When this CLI opens
+// Driggsby's approval page itself, approving there sends the browser to
+// http://127.0.0.1:<port>/callback with the one-time code (or
+// error=access_denied). A browser on any other computer lands on its own
+// loopback, where nothing listens, so the code reaches only this machine.
+//
+// Any page in any browser on this computer can also reach the loopback, so
+// a callback proves nothing by itself: the caller trades each code (only
+// the approval's real code works with this CLI's verifier) and confirms a
+// denial with Driggsby before believing it. Each callback's browser waits
+// until the caller answers it: a real one goes back to the Driggsby page
+// that says how the sign-in went, and a refused one learns nothing, not
+// even where that page is. Once the sign-in has ended, a callback taken
+// before the listener closes goes back to that page, which by then can only
+// say it is over; one still held when it closes is told it can close the
+// tab.
+import { createServer } from "node:http";
+const HOST = "127.0.0.1";
+const CALLBACK_PATH = "/callback";
+// Driggsby's codes are four groups of five; anything else is not one.
+const CODE_PATTERN = /^[A-Za-z0-9-]{1,64}$/;
+// A browser is never left hanging if a callback goes unanswered.
+const HELD_RESPONSE_MS = 30_000;
+// Callbacks waiting for the caller; more than this is someone knocking.
+const MAX_QUEUED = 32;
+const HEADERS = { "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" };
+// null when this environment can't listen on the loopback (a sandbox that
+// forbids it): the approval page then shows the code to paste instead.
+export function startLoopback() {
+    return new Promise((resolve) => {
+        const queued = [];
+        const waiting = [];
+        // Each waiting browser, with the timer that answers it if no one does.
+        const held = new Map();
+        let port = 0;
+        const server = createServer((request, response) => {
+            const parsed = readCallback(request, port);
+            if (parsed === null || queued.length >= MAX_QUEUED) {
+                response.writeHead(404, { ...HEADERS, "Content-Type": "text/plain; charset=utf-8" });
+                response.end("Not found\n");
+                return;
+            }
+            const settle = (landingUrl, refused) => {
+                clearTimeout(held.get(response));
+                held.delete(response);
+                answer(response, landingUrl, refused);
+            };
+            held.set(response, setTimeout(() => {
+                settle(null, false);
+            }, HELD_RESPONSE_MS));
+            const reply = {
+                answer: (landingUrl) => {
+                    settle(landingUrl, false);
+                },
+                refuse: () => {
+                    settle(null, true);
+                },
+            };
+            const callback = parsed.kind === "code" ? { kind: "code", code: parsed.code, ...reply } : { kind: "denied", ...reply };
+            const taker = waiting.shift();
+            if (taker === undefined) {
+                queued.push(callback);
+            }
+            else {
+                taker(callback);
+            }
+        });
+        let stopped = false;
+        const stop = () => {
+            if (stopped) {
+                return;
+            }
+            stopped = true;
+            for (const [response, timer] of held) {
+                clearTimeout(timer);
+                answer(response, null, false);
+            }
+            held.clear();
+            server.close();
+            server.closeAllConnections();
+        };
+        // Before listening, an error means this CLI can't listen here; after,
+        // any error (an accept failure, say) stops the listener rather than
+        // the command.
+        let listening = false;
+        server.on("error", () => {
+            if (listening) {
+                stop();
+            }
+            else {
+                resolve(null);
+            }
+        });
+        server.listen(0, HOST, () => {
+            const address = server.address();
+            if (address === null || typeof address === "string") {
+                stop();
+                resolve(null);
+                return;
+            }
+            port = address.port;
+            listening = true;
+            resolve({
+                redirectUri: `http://${HOST}:${port}${CALLBACK_PATH}`,
+                next: () => {
+                    const ready = queued.shift();
+                    return ready === undefined ? new Promise((take) => waiting.push(take)) : Promise.resolve(ready);
+                },
+                close: stop,
+            });
+        });
+    });
+}
+// Only a GET for /callback, addressed to this very listener (a Host header
+// naming anything else is a DNS-rebinding page, not Driggsby's redirect),
+// carrying a code or Driggsby's denial. Everything else is ignored.
+function readCallback(request, port) {
+    if (request.method !== "GET" || request.headers.host !== `${HOST}:${port}`) {
+        return null;
+    }
+    let url;
+    try {
+        url = new URL(request.url ?? "", `http://${HOST}:${port}`);
+    }
+    catch {
+        return null;
+    }
+    if (url.pathname !== CALLBACK_PATH) {
+        return null;
+    }
+    const code = url.searchParams.get("code");
+    if (code !== null && CODE_PATTERN.test(code)) {
+        return { kind: "code", code };
+    }
+    return url.searchParams.get("error") === "access_denied" ? { kind: "denied" } : null;
+}
+function answer(response, landingUrl, refused) {
+    if (response.writableEnded) {
+        return;
+    }
+    if (refused) {
+        response.writeHead(400, { ...HEADERS, "Content-Type": "text/plain; charset=utf-8" });
+        response.end("This sign-in callback wasn't accepted.\n");
+        return;
+    }
+    if (landingUrl === null) {
+        response.writeHead(200, { ...HEADERS, "Content-Type": "text/plain; charset=utf-8" });
+        response.end("You can close this tab and go back to your terminal.\n");
+        return;
+    }
+    response.writeHead(303, { ...HEADERS, Location: landingUrl });
+    response.end();
+}

package/dist/login/pending.js

@@ -0,0 +1,68 @@
+// The sign-in waiting for its code, kept at ~/.driggsby/pending-login.json
+// (owner-only, like the saved token) so `driggsby login --code <CODE>` can
+// finish it from another command: an agent without a terminal prompt runs
+// login, the person approves in a browser elsewhere, and the agent finishes
+// with the code the page showed. The verifier alone mints nothing, and a
+// record is ignored once it expires.
+//
+// Only the command that started a sign-in removes its record. `login
+// --code` marks it finished instead, so a login still waiting on the same
+// claim can tell the sign-in finished there rather than failed.
+import { readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { driggsbyDirectory, writeOwnerOnlyFile } from "../owner-only-file.js";
+const PENDING_FILE_NAME = "pending-login.json";
+export async function savePendingLogin(homeDirectory, pending) {
+    const body = {
+        base_url: pending.baseUrl,
+        claim_request_id: pending.claimRequestId,
+        code_verifier: pending.codeVerifier,
+        expires_at: pending.expiresAt,
+        finished: pending.finished,
+    };
+    await writeOwnerOnlyFile(homeDirectory, PENDING_FILE_NAME, `${JSON.stringify(body, null, 2)}\n`);
+}
+// null when nothing is waiting, the record is unreadable, or it expired.
+export async function readPendingLogin(homeDirectory, now) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await readFile(pendingPath(homeDirectory), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return null;
+    }
+    const record = parsed;
+    const { base_url: baseUrl, claim_request_id: claimRequestId, code_verifier: codeVerifier } = record;
+    const expiresAt = record.expires_at;
+    if (typeof baseUrl !== "string" ||
+        typeof claimRequestId !== "string" ||
+        typeof codeVerifier !== "string" ||
+        typeof expiresAt !== "number" ||
+        expiresAt <= now) {
+        return null;
+    }
+    return { baseUrl, claimRequestId, codeVerifier, expiresAt, finished: record.finished === true };
+}
+// Removes the record only while it is still this claim's: a newer sign-in
+// may have replaced it.
+export async function clearPendingLogin(homeDirectory, claimRequestId, now) {
+    const current = await readPendingLogin(homeDirectory, now);
+    if (current === null || current.claimRequestId === claimRequestId) {
+        await rm(pendingPath(homeDirectory), { force: true });
+    }
+}
+// Marks the record finished only while it is still this claim's (a newer
+// sign-in may have replaced it), and drops the spent verifier with it.
+export async function markPendingLoginFinished(homeDirectory, claimRequestId, now) {
+    const current = await readPendingLogin(homeDirectory, now);
+    if (current?.claimRequestId !== claimRequestId) {
+        return;
+    }
+    await savePendingLogin(homeDirectory, { ...current, codeVerifier: "", finished: true });
+}
+function pendingPath(homeDirectory) {
+    return join(driggsbyDirectory(homeDirectory), PENDING_FILE_NAME);
+}

package/dist/login/pkce.js

@@ -0,0 +1,14 @@
+// PKCE for driggsby login (RFC 7636, S256). The verifier never leaves this
+// process except to trade the one-time code the approval page produced;
+// Driggsby mints the token only for the code and the verifier together, so
+// whoever else holds the approval link gets nothing from someone's approval.
+import { createHash, randomBytes } from "node:crypto";
+export function createPkcePair() {
+    // 32 random bytes are 43 base64url characters: the RFC's minimum length
+    // and 256 bits of entropy.
+    const verifier = randomBytes(32).toString("base64url");
+    return { verifier, challenge: challengeFor(verifier) };
+}
+export function challengeFor(verifier) {
+    return createHash("sha256").update(verifier, "ascii").digest("base64url");
+}

package/dist/login/sleep.js

@@ -0,0 +1,21 @@
+// A sleep that ends early, quietly, once its signal aborts, so a finished
+// wait never holds the process open. Its abort listener goes when the
+// timer fires too: a wait that sleeps every few seconds on one signal
+// must not pile listeners onto it (Node warns past ten).
+export function abortableSleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted === true) {
+            resolve();
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}