nixamp 0.4.0 → 0.5.0

package/dist/oauth.js

@@ -0,0 +1,302 @@
+/**
+ * Signing in with somebody else's account.
+ *
+ * Two providers, GitHub and Google, both plain OAuth 2.0 authorization code
+ * with a client secret held on the server. Neither is configured unless its
+ * two environment variables are set, and what is configured is advertised at
+ * /api/v1/auth/providers so the CLI can offer exactly the choices that will
+ * work rather than a menu of things that 404.
+ *
+ * The callback lives at /api/v1/<provider>/oauth/callback, which is the shape
+ * the rest of the fleet registers with providers: the site's API namespace,
+ * the version, then provider, function, endpoint.
+ *
+ * The one rule worth stating out loud: an address links to an account only if
+ * the provider says it verified it. GitHub and Google both report that per
+ * address, and both are asked. Without that check, anyone who can add an
+ * unverified address at a provider could claim somebody else's nixamp account.
+ */
+import { randomBytes } from "node:crypto";
+const AGENT = { "user-agent": "nixamp" };
+async function readJson(answer) {
+    if (!answer.ok)
+        return {};
+    return (await answer.json().catch(() => ({})));
+}
+export function githubProvider(clientId, clientSecret) {
+    return {
+        id: "github",
+        name: "GitHub",
+        clientId,
+        clientSecret,
+        authorizeUrl: "https://github.com/login/oauth/authorize",
+        tokenUrl: "https://github.com/login/oauth/access_token",
+        // The address is the part nixamp needs, and GitHub keeps it behind its own
+        // scope even when it is public on a profile.
+        scope: "read:user user:email",
+        async identify(accessToken, send) {
+            const headers = { authorization: `Bearer ${accessToken}`, accept: "application/vnd.github+json", ...AGENT };
+            const who = await readJson(await send("https://api.github.com/user", { headers }));
+            const subject = who["id"] === undefined ? "" : String(who["id"]);
+            if (!subject)
+                return null;
+            // /user carries an address only if the account made it public, and even
+            // then it may be an unverified one, so the addresses endpoint is asked.
+            const answer = await send("https://api.github.com/user/emails", { headers });
+            const list = answer.ok ? (await answer.json().catch(() => [])) : [];
+            const usable = Array.isArray(list) ? list.filter((row) => row["verified"] === true) : [];
+            const chosen = usable.find((row) => row["primary"] === true) ?? usable[0];
+            const email = typeof chosen?.["email"] === "string" ? chosen["email"] : "";
+            if (!email)
+                return null;
+            return { provider: "github", subject, email: email.toLowerCase() };
+        },
+    };
+}
+export function googleProvider(clientId, clientSecret) {
+    return {
+        id: "google",
+        name: "Google",
+        clientId,
+        clientSecret,
+        authorizeUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+        tokenUrl: "https://oauth2.googleapis.com/token",
+        scope: "openid email",
+        async identify(accessToken, send) {
+            const who = await readJson(await send("https://openidconnect.googleapis.com/v1/userinfo", {
+                headers: { authorization: `Bearer ${accessToken}`, ...AGENT },
+            }));
+            const subject = typeof who["sub"] === "string" ? who["sub"] : "";
+            const email = typeof who["email"] === "string" ? who["email"] : "";
+            // Google reports this as a boolean or as the string "true" depending on
+            // which endpoint answered, and an unverified address is not a claim.
+            const verified = who["email_verified"] === true || who["email_verified"] === "true";
+            if (!subject || !email || !verified)
+                return null;
+            return { provider: "google", subject, email: email.toLowerCase() };
+        },
+    };
+}
+/** Whichever providers this deployment has been given both halves of. */
+export function providersFrom(env) {
+    const found = [];
+    if (env["GITHUB_CLIENT_ID"] && env["GITHUB_CLIENT_SECRET"]) {
+        found.push(githubProvider(env["GITHUB_CLIENT_ID"], env["GITHUB_CLIENT_SECRET"]));
+    }
+    if (env["GOOGLE_CLIENT_ID"] && env["GOOGLE_CLIENT_SECRET"]) {
+        found.push(googleProvider(env["GOOGLE_CLIENT_ID"], env["GOOGLE_CLIENT_SECRET"]));
+    }
+    return found;
+}
+export function redirectUri(site, provider) {
+    return `${site.replace(/\/+$/, "")}/api/v1/${provider.id}/oauth/callback`;
+}
+/** Where to send the browser. `state` is the only thing standing between this and CSRF. */
+export function authorizeUrl(provider, site, state) {
+    const url = new URL(provider.authorizeUrl);
+    url.searchParams.set("client_id", provider.clientId);
+    url.searchParams.set("redirect_uri", redirectUri(site, provider));
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", provider.scope);
+    url.searchParams.set("state", state);
+    return url.toString();
+}
+/** Swap the code for an access token. Empty string means the provider refused. */
+export async function exchangeCode(provider, code, site, send = fetch) {
+    const answer = await send(provider.tokenUrl, {
+        method: "POST",
+        headers: {
+            // GitHub answers form-encoded unless asked for JSON, which is the trap
+            // that makes a working exchange look like an empty token.
+            accept: "application/json",
+            "content-type": "application/x-www-form-urlencoded",
+            ...AGENT,
+        },
+        body: new URLSearchParams({
+            client_id: provider.clientId,
+            client_secret: provider.clientSecret,
+            code,
+            redirect_uri: redirectUri(site, provider),
+            grant_type: "authorization_code",
+        }).toString(),
+    });
+    const body = await readJson(answer);
+    return typeof body["access_token"] === "string" ? body["access_token"] : "";
+}
+// --- linking an identity to an account --------------------------------------
+const TABLE = "nixamp_identities";
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS ${TABLE} (
+    provider   TEXT NOT NULL,
+    subject    TEXT NOT NULL,
+    user_id    TEXT NOT NULL,
+    email      TEXT NOT NULL DEFAULT '',
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    PRIMARY KEY (provider, subject)
+  );
+`;
+/**
+ * The account behind a provider identity, creating one the first time.
+ *
+ * The account row is made with no password at all rather than a random one
+ * nobody knows. A null password is a fact -- this account signs in with GitHub
+ * -- where a random password is a credential sitting in a database waiting to
+ * be found.
+ */
+export class Identities {
+    db;
+    users;
+    ready = null;
+    constructor(db, users) {
+        this.db = db;
+        this.users = users;
+    }
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    async resolve(identity) {
+        if (!identity.subject || !identity.email)
+            return null;
+        await this.ensure();
+        // Already linked. The subject is what is matched, not the address: people
+        // change the address on a GitHub account and stay the same person.
+        const { rows } = await this.db.query(`SELECT user_id, email FROM ${TABLE} WHERE provider = $1 AND subject = $2`, [
+            identity.provider,
+            identity.subject,
+        ]);
+        const linked = rows[0];
+        if (linked) {
+            const id = String(linked["user_id"] ?? "");
+            if (String(linked["email"] ?? "") !== identity.email) {
+                await this.db.query(`UPDATE ${TABLE} SET email = $3 WHERE provider = $1 AND subject = $2`, [
+                    identity.provider,
+                    identity.subject,
+                    identity.email,
+                ]);
+            }
+            return { id, email: identity.email };
+        }
+        // Not linked, but the address may already have an account -- somebody who
+        // signed up with a password and is now signing in with GitHub. Linking on
+        // a verified address is what makes those the same account instead of two.
+        const existing = await this.users.getUserByEmail(identity.email);
+        const account = existing?.id
+            ? { id: existing.id, email: existing.email ?? identity.email }
+            : await (async () => {
+                const made = await this.users.createUser({
+                    email: identity.email,
+                    password: null,
+                    // The provider verified it, which is the whole reason this is
+                    // allowed to become an account without an email being sent.
+                    emailVerified: true,
+                    profile: { signedUpWith: identity.provider },
+                });
+                return { id: String(made.id ?? ""), email: made.email ?? identity.email };
+            })();
+        if (!account.id)
+            return null;
+        await this.db.query(`INSERT INTO ${TABLE} (provider, subject, user_id, email) VALUES ($1, $2, $3, $4)
+       ON CONFLICT (provider, subject) DO UPDATE SET email = EXCLUDED.email`, [identity.provider, identity.subject, account.id, identity.email]);
+        return account;
+    }
+}
+/** A state is only ever open for the length of one sign-in. */
+export const STATE_TTL_MS = 600_000;
+export class SignIn {
+    providers;
+    device;
+    site;
+    now;
+    states = new Map();
+    constructor(providers, device, site, now = Date.now) {
+        this.providers = providers;
+        this.device = device;
+        this.site = site;
+        this.now = now;
+    }
+    /** What /api/v1/auth/providers says, and what the CLI menu is built from. */
+    get offered() {
+        return this.providers.map((provider) => ({ id: provider.id, name: provider.name }));
+    }
+    provider(id) {
+        return this.providers.find((candidate) => candidate.id === id) ?? null;
+    }
+    /** Start a round trip, and answer the URL the browser should go to. */
+    begin(provider, userCode = "") {
+        this.sweep();
+        const state = randomBytes(24).toString("base64url");
+        this.states.set(state, { provider: provider.id, userCode, createdAt: this.now() });
+        return authorizeUrl(provider, this.site, state);
+    }
+    /** Redeem a state exactly once, so a replayed callback finds nothing. */
+    claim(state) {
+        if (typeof state !== "string" || state === "")
+            return null;
+        const pending = this.states.get(state);
+        if (!pending)
+            return null;
+        this.states.delete(state);
+        return this.now() - pending.createdAt > STATE_TTL_MS ? null : pending;
+    }
+    sweep() {
+        const at = this.now();
+        for (const [state, pending] of this.states) {
+            if (at - pending.createdAt > STATE_TTL_MS)
+                this.states.delete(state);
+        }
+    }
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+}
+const PAGE_STYLE = `
+  :root { color-scheme: dark }
+  body { background:#000; color:#00e676; font:16px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;
+         margin:0; min-height:100vh; display:grid; place-items:center; padding:2rem }
+  main { width:min(30rem,100%) }
+  h1 { font-size:1.1rem; letter-spacing:.2em; text-transform:uppercase; color:#9ad }
+  input { font:inherit; background:#111; color:#00e676; border:1px solid #2a2a2a; padding:.6rem .8rem;
+          width:100%; box-sizing:border-box; letter-spacing:.25em; text-transform:uppercase }
+  button { font:inherit; background:#111; color:#00e676; border:1px solid #2a2a2a; padding:.6rem 1rem;
+           cursor:pointer; width:100%; margin-top:.5rem; text-align:left }
+  button:hover { border-color:#00e676 }
+  p { color:#9a9a9a } code { color:#00e676 }
+`;
+function page(title, body) {
+    return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${escapeHtml(title)} - nixamp</title><style>${PAGE_STYLE}</style></head>
+<body><main>${body}</main></body></html>`;
+}
+/**
+ * The page the terminal sends somebody to.
+ *
+ * It is served by the API rather than the app because it has to work before
+ * there is a session and without the web build being present -- a nixamp
+ * deployed with no web assets can still sign a terminal in.
+ */
+export function devicePage(signIn, code, signedInAs) {
+    const value = escapeHtml(code);
+    const choices = signIn.providers
+        .map((provider) => `<button type="submit" name="with" value="${escapeHtml(provider.id)}">Continue with ${escapeHtml(provider.name)}</button>`)
+        .join("");
+    const approve = signedInAs
+        ? `<button type="submit" name="with" value="">Approve as ${escapeHtml(signedInAs)}</button>`
+        : "";
+    return page("Connect a terminal", `<h1>Connect a terminal</h1>
+     <p>Your terminal is showing a code. Type it here, then choose how to sign in.</p>
+     <form method="POST" action="/api/v1/auth/device">
+       <input name="code" value="${value}" placeholder="XXXX-XXXX" autocomplete="off"
+              autocapitalize="characters" spellcheck="false" required>
+       ${approve}${choices}
+     </form>
+     ${signIn.providers.length === 0 && !signedInAs ? "<p>Sign in on this site first, then come back to this page.</p>" : ""}`);
+}
+export function deviceDonePage(email) {
+    return page("Terminal connected", `<h1>Terminal connected</h1>
+     <p>Signed in as <code>${escapeHtml(email)}</code>. Go back to your terminal; you can close this.</p>`);
+}
+export function signInFailedPage(why) {
+    return page("Sign-in failed", `<h1>Sign-in failed</h1><p>${escapeHtml(why)}</p>`);
+}

package/dist/server.d.ts

@@ -4,6 +4,7 @@ import { Broadcaster, type Destination, type EncoderSettings } from "./broadcast
 import { Ingest } from "./ingest.ts";
 import { Channels } from "./channels.ts";
 import { Accounts } from "./accounts.ts";
+import { SignIn } from "./oauth.ts";
 import { Owner } from "./owner.ts";
 import { Directory } from "./directory.ts";
 import { PartyLine } from "./partyline.ts";
@@ -157,6 +158,11 @@ export declare class EmptyEngine implements Engine {
     replace(): void;
     stop(): void;
 }
+/**
+ * Paths that are how somebody without a key gets one, so they answer before
+ * the share-key check rather than behind it.
+ */
+export declare function isSignInPath(path: string): boolean;
 export interface HandlerOptions {
     web: string | null;
     media: boolean;
@@ -198,6 +204,8 @@ export interface HandlerOptions {
     };
     /** Accounts, on the instance that keeps them. Only nixamp.com passes this. */
     accounts?: Accounts;
+    /** Providers to sign in with, and the terminals waiting to be connected. */
+    signIn?: SignIn;
     /** True when this instance is reached over https, for the cookie's Secure. */
     secureCookies?: boolean;
     /** Who may administer this server. */

package/dist/server.js

@@ -20,6 +20,8 @@ import { Ingest, normaliseFormat } from "./ingest.js";
 import { Channels, cleanId } from "./channels.js";
 import { RtmpListeners } from "./rtmp-in.js";
 import { Accounts, clearedCookie, sessionCookie, tokenFrom } from "./accounts.js";
+import { DeviceGrants } from "./device.js";
+import { deviceDonePage, devicePage, exchangeCode, providersFrom, signInFailedPage, SignIn, } from "./oauth.js";
 import { needsAdmin, Owner } from "./owner.js";
 import { readSession } from "./session.js";
 import { Directory, ENDED_TTL_MS, parseAnnouncement } from "./directory.js";
@@ -472,6 +474,23 @@ const CORS = {
     "access-control-allow-headers": "content-type",
     "access-control-max-age": "86400",
 };
+/** /api/v1/<provider>/oauth/start and .../callback, the house callback shape. */
+const OAUTH_ROUTE = /^\/api\/v1\/([a-z0-9-]+)\/oauth\/(start|callback)$/;
+/**
+ * Paths that are how somebody without a key gets one, so they answer before
+ * the share-key check rather than behind it.
+ */
+export function isSignInPath(path) {
+    return path.startsWith("/api/v1/auth/") || OAUTH_ROUTE.test(path);
+}
+function html(response, code, body) {
+    response.writeHead(code, {
+        "content-type": "text/html; charset=utf-8",
+        "content-length": Buffer.byteLength(body),
+        "cache-control": "no-store",
+    });
+    response.end(body);
+}
 function json(response, code, body) {
     const text = JSON.stringify(body);
     response.writeHead(code, {
@@ -741,7 +760,7 @@ export function createHandler(engine, options) {
         if (key !== null &&
             path !== "/api/health" &&
             path !== "/api/directory" &&
-            !path.startsWith("/api/v1/auth/")) {
+            !isSignInPath(path)) {
             const scope = scopeOf(keyFrom(request, url), key, listenKey);
             if (scope === null) {
                 json(response, 401, { error: "this nixamp needs the key from its share link" });
@@ -774,6 +793,9 @@ export function createHandler(engine, options) {
                 return;
             }
             if (path === "/api/v1/auth/logout") {
+                // The cookie going is what the browser notices; the token going is
+                // what makes it stop working on a machine you no longer have.
+                await accounts.endSession(tokenFrom(request.headers));
                 response.writeHead(200, {
                     ...CORS,
                     "content-type": "application/json; charset=utf-8",
@@ -782,6 +804,150 @@ export function createHandler(engine, options) {
                 response.end(JSON.stringify({ ok: true }));
                 return;
             }
+            // What this deployment will accept, so the CLI offers the ways in that
+            // exist here rather than a menu built from what it hopes is configured.
+            if (path === "/api/v1/auth/providers") {
+                json(response, 200, {
+                    password: true,
+                    device: options.signIn !== undefined,
+                    providers: options.signIn?.offered ?? [],
+                });
+                return;
+            }
+            // --- the device grant, for a terminal with no browser ---------------
+            if (path.startsWith("/api/v1/auth/device") && options.signIn) {
+                const signIn = options.signIn;
+                // A terminal asks for a code to show, and starts polling.
+                if (path === "/api/v1/auth/device/code" && request.method === "POST") {
+                    const grant = signIn.device.start();
+                    const where = `${signIn.site}/api/v1/auth/device`;
+                    json(response, 200, {
+                        device_code: grant.deviceCode,
+                        user_code: grant.userCode,
+                        verification_uri: where,
+                        // The pre-filled link is what makes this one click on a phone.
+                        verification_uri_complete: `${where}?code=${encodeURIComponent(grant.userCode)}`,
+                        expires_in: Math.round((grant.expiresAt - Date.now()) / 1000),
+                        interval: signIn.device.interval,
+                    });
+                    return;
+                }
+                // ... and asks, at that interval, whether anybody has approved it yet.
+                if (path === "/api/v1/auth/device/token" && request.method === "POST") {
+                    let body;
+                    try {
+                        body = JSON.parse(await readBody(request));
+                    }
+                    catch {
+                        json(response, 400, { error: "bad JSON" });
+                        return;
+                    }
+                    const status = signIn.device.poll(String(body.device_code ?? ""));
+                    if (status.status === "ok") {
+                        json(response, 200, { token: status.token, email: status.email });
+                        return;
+                    }
+                    // The names are RFC 8628's, because that is what a client waiting on
+                    // a device grant already knows how to read.
+                    const named = {
+                        pending: "authorization_pending",
+                        slow_down: "slow_down",
+                        expired: "expired_token",
+                        denied: "access_denied",
+                    };
+                    json(response, 400, { error: named[status.status] });
+                    return;
+                }
+                // The page somebody opens on a device that has a keyboard.
+                if (path === "/api/v1/auth/device" && (request.method === "GET" || request.method === "HEAD")) {
+                    const who = await accounts.whoIs(tokenFrom(request.headers));
+                    html(response, 200, devicePage(signIn, url.searchParams.get("code") ?? "", who?.email ?? ""));
+                    return;
+                }
+                if (path === "/api/v1/auth/device" && request.method === "POST") {
+                    const form = new URLSearchParams(await readBody(request));
+                    const code = form.get("code") ?? "";
+                    const grant = signIn.device.find(code);
+                    if (grant === null) {
+                        html(response, 404, signInFailedPage("That code has expired or was already used. Ask your terminal for another."));
+                        return;
+                    }
+                    // Empty means "approve as the account this browser is already signed
+                    // in as"; anything else names a provider to go and ask.
+                    //
+                    // A form on somebody else's site posting here is what would make
+                    // this dangerous, and is what SameSite=Lax on the session cookie
+                    // prevents: a cross-site POST arrives with no cookie, so it is
+                    // nobody, so it approves nothing.
+                    const chosen = form.get("with") ?? "";
+                    if (chosen === "") {
+                        const who = await accounts.whoIs(tokenFrom(request.headers));
+                        if (who === null) {
+                            html(response, 401, signInFailedPage("Sign in first, then approve the terminal."));
+                            return;
+                        }
+                        const token = await accounts.sessionFor(who);
+                        if (!token || !signIn.device.approve(grant.userCode, { token, email: who.email })) {
+                            html(response, 500, signInFailedPage("Could not start a session for that terminal."));
+                            return;
+                        }
+                        html(response, 200, deviceDonePage(who.email));
+                        return;
+                    }
+                    const provider = signIn.provider(chosen);
+                    if (provider === null) {
+                        html(response, 404, signInFailedPage("This nixamp cannot sign you in with that."));
+                        return;
+                    }
+                    // The user code rides along in the state, so the callback knows it
+                    // is approving a terminal rather than signing this browser in.
+                    response.writeHead(302, { location: signIn.begin(provider, grant.userCode) });
+                    response.end();
+                    return;
+                }
+                json(response, 404, { error: "no such endpoint" });
+                return;
+            }
+            // --- tokens a person made on purpose --------------------------------
+            if (path === "/api/v1/auth/tokens" || path.startsWith("/api/v1/auth/tokens/")) {
+                const who = await accounts.whoIs(tokenFrom(request.headers));
+                if (who === null) {
+                    json(response, 401, { error: "not signed in" });
+                    return;
+                }
+                if (path === "/api/v1/auth/tokens" && request.method === "GET") {
+                    json(response, 200, { tokens: await accounts.listTokens(who.id, "cli") });
+                    return;
+                }
+                if (path === "/api/v1/auth/tokens" && request.method === "POST") {
+                    let body;
+                    try {
+                        body = JSON.parse(await readBody(request));
+                    }
+                    catch {
+                        json(response, 400, { error: "bad JSON" });
+                        return;
+                    }
+                    const name = typeof body.name === "string" ? body.name.slice(0, 80) : "";
+                    const made = await accounts.mintCliToken(who, name);
+                    if (made === null) {
+                        json(response, 501, { error: "this nixamp does not keep tokens" });
+                        return;
+                    }
+                    // The whole token is in this answer and in no other: it is not
+                    // stored, so there is nowhere to show it again from.
+                    json(response, 201, { token: made.token, id: made.id, name: made.name });
+                    return;
+                }
+                const id = path.slice("/api/v1/auth/tokens/".length);
+                if (id && request.method === "DELETE") {
+                    const gone = await accounts.revokeToken(who.id, id);
+                    json(response, gone ? 200 : 404, gone ? { ok: true } : { error: "no such token" });
+                    return;
+                }
+                json(response, 405, { error: "GET, POST or DELETE" });
+                return;
+            }
             const signingUp = path === "/api/v1/auth/signup";
             if (!signingUp && path !== "/api/v1/auth/login") {
                 json(response, 404, { error: "no such endpoint" });
@@ -807,14 +973,84 @@ export function createHandler(engine, options) {
                 json(response, signingUp ? 409 : 401, { error: result.error });
                 return;
             }
+            // A password sign-in ends in the same revocable token an OAuth one does,
+            // falling back to the module's JWT where there is no storage to keep one
+            // in. Every way in should be a session that can be listed and ended.
+            const token = result.account
+                ? await accounts.sessionFor(result.account, result.token)
+                : result.token;
             // The token goes back in the body for the CLI and the desktop app, and
             // as a cookie for the browser, which then needs to know nothing about it.
             response.writeHead(200, {
                 ...CORS,
                 "content-type": "application/json; charset=utf-8",
+                "set-cookie": sessionCookie(token, secure),
+            });
+            response.end(JSON.stringify({ account: result.account, token }));
+            return;
+        }
+        // --- coming back from a provider ---------------------------------------
+        //
+        // /api/v1/<provider>/oauth/start sends a browser away, and .../callback is
+        // what the provider was told to send it back to. Both are outside the
+        // /api/v1/auth/ block because that is the URL shape registered with GitHub
+        // and Google, and a redirect URI is not something to change lightly.
+        const oauthRoute = OAUTH_ROUTE.exec(path);
+        if (oauthRoute && options.accounts && options.signIn) {
+            const accounts = options.accounts;
+            const signIn = options.signIn;
+            const secure = options.secureCookies ?? false;
+            const provider = signIn.provider(oauthRoute[1]);
+            if (provider === null) {
+                json(response, 404, { error: "this nixamp cannot sign you in with that" });
+                return;
+            }
+            if (oauthRoute[2] === "start") {
+                // A terminal can link straight here with the code it is showing, which
+                // is one hop shorter than the page for somebody who followed the link.
+                const grant = signIn.device.find(url.searchParams.get("device") ?? "");
+                response.writeHead(302, { location: signIn.begin(provider, grant?.userCode ?? "") });
+                response.end();
+                return;
+            }
+            // A callback carrying no state, or one whose state was already spent, is
+            // not a sign-in: it is somebody replaying a URL they found.
+            const pending = signIn.claim(url.searchParams.get("state"));
+            if (pending === null || pending.provider !== provider.id) {
+                html(response, 400, signInFailedPage("That sign-in link has expired. Start again."));
+                return;
+            }
+            const code = url.searchParams.get("code") ?? "";
+            if (!code) {
+                html(response, 400, signInFailedPage(url.searchParams.get("error") ?? "The provider sent no code."));
+                return;
+            }
+            const access = await exchangeCode(provider, code, signIn.site).catch(() => "");
+            const identity = access ? await provider.identify(access, fetch).catch(() => null) : null;
+            if (identity === null) {
+                html(response, 401, signInFailedPage(`${provider.name} did not confirm a verified email address.`));
+                return;
+            }
+            const result = await accounts.signInWith(identity);
+            if (!result.ok || result.account === null) {
+                html(response, 401, signInFailedPage(result.error || "Could not sign in."));
+                return;
+            }
+            if (pending.userCode) {
+                // This round trip was approving a terminal. The browser is finished;
+                // the session belongs to whatever is polling.
+                if (!signIn.device.approve(pending.userCode, { token: result.token, email: result.account.email })) {
+                    html(response, 410, signInFailedPage("That terminal stopped waiting. Run `nixamp login` again."));
+                    return;
+                }
+                html(response, 200, deviceDonePage(result.account.email));
+                return;
+            }
+            response.writeHead(302, {
                 "set-cookie": sessionCookie(result.token, secure),
+                location: "/",
             });
-            response.end(JSON.stringify({ account: result.account, token: result.token }));
+            response.end();
             return;
         }
         // The directory is public to read and answered before the key check,
@@ -1785,6 +2021,10 @@ export async function serve(argv, version = "0.1.0") {
                     secret: process.env["NIXAMP_JWT_SECRET"] ?? "",
                 }),
                 secureCookies: (process.env["NIXAMP_SITE"] ?? "").startsWith("https://"),
+                // Whichever providers this deployment was given both halves of, plus
+                // the device grant, which is worth having even with no provider at
+                // all: a browser already signed in can approve a terminal.
+                signIn: new SignIn(providersFrom(process.env), new DeviceGrants(), process.env["NIXAMP_SITE"] ?? DEFAULT_DIRECTORY),
             }
             : {}),
     });