@basein/runner 0.1.1 → 0.2.1

package/docs/loginWeb.md

@@ -0,0 +1,607 @@
+# loginWeb — make `bir login` sign in through the browser
+
+> **Status: implemented (2026-09-08), in runner 0.2.0.** Steps 1–3 of §8 have
+> landed on both sides; step 4 — deleting `--password` and the fallback — is the
+> release after. §15 records what shipped and the two things that changed shape
+> on the way. The rest of this document is the plan as written, kept as the
+> record of why.
+
+It covers both halves — the runner in this repo and the BaseIn service
+(`BaseIntSever/BaseIn`, referred to below as *the service*) — because a web
+sign-in is a contract between them.
+
+---
+
+## 0. Context
+
+Today `bir login` asks for an email and a password in the terminal and posts
+them to `POST /auth/login` ([client.ts:392-408](../src/auth/client.ts#L392-L408)).
+The answer — `{accessToken, refreshToken, expiresIn, user}` — is cached at
+`~/.baseinstrunner/credentials.json`, mode 0600 ([client.ts:105](../src/auth/client.ts#L105)),
+and from then on every process (`bir-hooks`, each `bir-proxy`, the CLI) reuses and
+silently refreshes it. That second half works well and is not what this plan
+changes.
+
+The first half has four problems, one of which is a hard wall:
+
+1. **Google-only accounts cannot use the CLI at all.** The console offers
+   *Continue with Google*, and the Google callback creates users with no
+   password (`users.password_hash` is nullable; `createUser` at `routes.ts:273` in the
+   service). For them `POST /auth/login` can only ever answer
+   `invalid_credentials`. There is no workaround short of setting a password
+   they never wanted.
+2. **A password typed into a terminal is the weakest link we have.** It appears
+   in installer transcripts, it is the thing `describeAuthService`
+   ([client.ts:235](../src/auth/client.ts#L235)) exists to protect — a whole
+   probe was built because passwords were being posted to the wrong host.
+3. **Every future factor has to be built twice.** MFA, SSO, passkeys: anything
+   added to the console's sign-in would need a terminal re-implementation.
+   A browser flow inherits all of it for free.
+4. **Headless machines have no good story.** [installRun.md §7](installRun.md)
+   still says *pre-seed `credentials.json`* — a shared long-lived secret copied
+   by hand.
+
+**The change:** `bir login` starts a sign-in the *browser* completes. The
+terminal shows a short code and a link; the user signs in on the console with
+whatever they already use; the CLI receives the same session payload it receives
+today. Nothing downstream of `credentials.json` changes.
+
+### Not in scope
+
+- The token model (24 h access JWT, rotating 30-day opaque refresh —
+  `config.ts:254-255`, `refresh.ts:72-81`). Unchanged.
+- How `bir-hooks`, `bir-proxy` and `RemoteRecorder` use the cached session
+  ([remote-recorder.ts:285-345](../src/record/remote-recorder.ts#L285-L345)).
+  Unchanged, by design — see §2 decision 2.
+- Machine-to-machine credentials (runner/service tokens for fleets). A real
+  follow-on; §11.
+
+---
+
+## 1. The flow
+
+OAuth 2.0 **Device Authorization Grant**, [RFC 8628](https://www.rfc-editor.org/rfc/rfc8628),
+the same shape as `gh auth login` and every cloud CLI.
+
+```
+ terminal (bir login)                       service (api.)                 browser (console)
+ ─────────────────────                      ──────────────                 ─────────────────
+ POST /auth/device/code ───────────────────▶ mint device_code (secret)
+   {clientName, clientVersion}               + user_code  "BKQM-TXZR"
+ ◀── {deviceCode, userCode, verificationUri,
+      verificationUriComplete, expiresIn:600, interval:5}
+
+ prints:
+   Sign in to BaseIn (https://api.bi2202.com)
+   Open   https://bi2202.com/activate
+   Code   BKQM-TXZR
+   Waiting for approval…  (Ctrl-C to cancel)
+ tries to open verificationUriComplete ─────────────────────────────────▶ /activate?code=BKQM-TXZR
+                                                                          ├─ not signed in → /login
+                                                                          │   (password, Google, …)
+                                                                          │   → back to /activate?code=…
+                                                                          ├─ GET /auth/device/lookup?code=…
+                                                                          │   "bir 0.2.0 on DESKTOP-PQVT0H2
+                                                                          │    (1.2.3.4, 40 s ago) wants to
+                                                                          │    sign in as you@example.com"
+ every 5 s:                                                               └─ [Approve]  [Deny]
+ POST /auth/device/token {deviceCode} ────▶ pending? → 400 authorization_pending
+                                            too fast? → 400 slow_down
+                                            denied?  → 400 access_denied
+                                            expired? → 400 expired_token
+                                            approved → 200 {accessToken, refreshToken,
+                                                            expiresIn, user}   (single use)
+ saveCredentials(…)  →  "Signed in to https://api.bi2202.com as you@example.com."
+```
+
+Two properties make this the right grant, and both come from the RFC's design:
+
+- **The low-entropy code is only ever typed on the already-authenticated side.**
+  The browser session proves *who*; the code only says *which pending request*.
+  The secret that actually redeems a session (`device_code`) never leaves the
+  machine that asked for it.
+- **The machine running `bir` needs no browser, no open port, no display.** The
+  link can be opened on a phone. That is the headless story §0 was missing.
+
+---
+
+## 2. Decisions
+
+1. **Device grant, not a loopback redirect.** The alternative (RFC 8252: the CLI
+   opens a local `http://127.0.0.1:port` listener and the console redirects back
+   to it) is smoother on a desktop and useless over SSH, in a container, or on a
+   runner with no browser — which is exactly where `bir` runs. It also needs a
+   listening port (Windows firewall prompt) and a redirect-URI allowlist on the
+   service. §12 has the comparison.
+2. **Same payload, same file.** `POST /auth/device/token` answers with the
+   existing `AuthSuccess` (`types.ts:15-20`) via the existing `issueSession()`.
+   The CLI maps it with the existing `toSession()` and writes the existing
+   `credentials.json`. `bir-hooks`, the proxies and the recorder's shared-file
+   refresh logic are not touched, and the smoke test's pre-seeded credentials
+   ([smoke-replay.mjs:157-167](../test/smoke-replay.mjs#L157-L167)) keep working.
+3. **Only `bir login` starts a sign-in.** Today `authenticate()` prompts from
+   *inside* any process that happens to have a TTY and no session
+   ([client.ts:377-398](../src/auth/client.ts#L377-L398)) — including
+   `bir-hooks` ([bir-hooks.ts:89](../src/bin/bir-hooks.ts#L89)). With a browser
+   flow that would mean a control server printing a code and blocking for ten
+   minutes, possibly under a supervisor where nobody sees it. `authenticate()`
+   becomes strictly silent: cached → refreshed → `undefined` with the existing
+   `auth.no_session … run bir login` line. The prompt lives in one place.
+4. **The password prompt survives one release, explicitly.** `bir login
+   --password` keeps the current flow, printing a deprecation line. It is also
+   the automatic fallback when the service answers `404` on
+   `/auth/device/code` — a new runner against an old service must still work.
+   Both go in the release after.
+5. **Opening the browser is best-effort and dependency-free.** `package.json`
+   has zero runtime dependencies and stays that way: spawn `cmd /c start "" <url>`
+   on Windows, `open` on macOS, `xdg-open` elsewhere, detached, errors ignored.
+   Skipped under `--no-browser`, when `SSH_CONNECTION`/`SSH_TTY` is set, or when
+   stderr is not a TTY. The link and code are printed regardless, so the flow
+   never depends on the browser having opened.
+6. **The approval page is a console route behind the existing guard.**
+   `/activate` sits inside `RequireAuth` like every other page (`App.tsx:92-135`),
+   so the console's sign-in — password, Google, verification links, the
+   "session expired" notice — is reused rather than reproduced. This is the
+   single reason the whole plan is small.
+7. **Every device sign-in is a login event.** `logLogin({method: 'device'})` at
+   redeem time, so *Sign-in history* shows it with the runner's IP and agent.
+8. **`bir logout` revokes on the server.** Today it only deletes the file
+   ([bir.ts:1061-1064](../src/bin/bir.ts#L1061-L1064)). It should
+   `POST /auth/logout {refreshToken}` first — the endpoint exists and is
+   idempotent (`routes.ts:186-200`).
+
+---
+
+## 3. Service — the API
+
+All under `/auth`, so they inherit `authRouter`'s zod-and-`asyncHandler` style
+and the `/auth` mount (`index.ts:63`).
+
+### 3.1 `POST /auth/device/code` — public
+
+Request: `{ clientName?: string ≤ 100, clientVersion?: string ≤ 40 }` — the
+runner sends `os.hostname()` and `packageVersion()`.
+
+Response `200`:
+
+```json
+{
+  "deviceCode": "…43 chars base64url…",
+  "userCode": "BKQM-TXZR",
+  "verificationUri": "https://bi2202.com/activate",
+  "verificationUriComplete": "https://bi2202.com/activate?code=BKQM-TXZR",
+  "expiresIn": 600,
+  "interval": 5
+}
+```
+
+`verificationUri` is `${config.webOrigin}/activate` — `webOrigin`
+(`config.ts:51`) is already the one origin CORS trusts and the one the
+verification-email links use, so it is the right source of truth.
+
+### 3.2 `POST /auth/device/token` — public, polled
+
+Request: `{ deviceCode }`. Responses follow RFC 8628 §3.5 exactly, so any
+future client can reuse a standard library:
+
+| State | Status | Body |
+|---|---|---|
+| not yet decided | 400 | `{"error":"authorization_pending"}` |
+| polled faster than `interval` | 400 | `{"error":"slow_down"}` (and the row's interval grows by 5 s) |
+| user pressed Deny | 400 | `{"error":"access_denied"}` |
+| past `expires_at`, or already redeemed | 400 | `{"error":"expired_token"}` |
+| unknown code | 400 | `{"error":"invalid_grant"}` |
+| approved | 200 | `issueSession(user)` — the `AuthSuccess` shape |
+
+Success **consumes** the row (`status='consumed'`) and writes the
+`login_events` row with the *poll request's* `req` — the IP and user-agent
+recorded are the runner's, which is the machine that just received a session.
+
+### 3.3 `GET /auth/device/lookup?code=…` — `requireAuth`
+
+Answers `{ clientName, clientVersion, ip, requestedAt }` for a **pending**
+code, else `404 {"error":"unknown_code"}`. The page uses it to say what is
+asking before offering *Approve*. Never reveals user data — there is none yet.
+
+### 3.4 `POST /auth/device/approve` and `/deny` — `requireAuth`
+
+Request: `{ userCode }`. Approve sets `user_id = req.auth.sub`,
+`status='approved'`, `decided_at`. Deny sets `status='denied'`. Anything not
+pending → `404 unknown_code`, deliberately the same answer for *expired*,
+*already decided* and *never existed*: the approving side learns nothing it
+could use to enumerate codes. `204` on success.
+
+### 3.5 Rate limits — the one thing that will break if forgotten
+
+`authLimiter` is **100 requests per 15 minutes per IP** on everything under
+`/auth` (`index.ts:51-63`). A ten-minute device flow polling every five
+seconds is **120 requests**: the CLI would be cut off by a `429 rate_limited`
+two thirds of the way through, with no `slow_down` to tell it why.
+
+So `/auth/device/token` needs its own limiter mounted before `authLimiter`
+(generous per IP — say 600 / 15 min — because pacing is enforced per *code*
+by `slow_down`), while `/auth/device/code` and `/approve` get a **stricter**
+one (say 20 / 15 min per IP). With an 8-character code over a 20-letter
+alphabet (2.6 × 10¹⁰ codes) and a 10-minute lifetime, 20 guesses per quarter
+hour is not a threat; see §9.
+
+### 3.6 Storage — `src/db.ts`
+
+```sql
+CREATE TABLE IF NOT EXISTS device_authorizations (
+  id               TEXT PRIMARY KEY,           -- 'da_' + uuid
+  device_code_hash TEXT NOT NULL UNIQUE,       -- sha256, like refresh_tokens.token_hash
+  user_code        TEXT NOT NULL,              -- 'BKQMTXZR' (stored without the dash)
+  client_name      TEXT,
+  client_version   TEXT,
+  ip               TEXT,
+  user_agent       TEXT,
+  status           TEXT NOT NULL,              -- pending | approved | denied | consumed
+  user_id          TEXT,                       -- set on approve
+  poll_interval    INTEGER NOT NULL,           -- seconds; grows on slow_down
+  last_poll_at     TEXT,
+  created_at       TEXT NOT NULL,
+  expires_at       TEXT NOT NULL,
+  decided_at       TEXT,
+  consumed_at      TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_device_auth_user_code ON device_authorizations(user_code, status);
+```
+
+`user_code` uniqueness is enforced among *pending* rows at mint time (retry on
+collision). Rows older than 24 h are deleted lazily when a new code is minted —
+the same "housekeeping at the moment someone is looking" pattern
+`recordings/routes.ts` already uses for pruning.
+
+### 3.7 Code generation — `src/auth/device.ts` (new)
+
+- `device_code`: `randomBytes(32).toString('base64url')`, stored hashed with
+  the `hashToken` from `refresh.ts:9`. Returned once.
+- `user_code`: 8 characters from `BCDFGHJKLMNPQRSTVWXZ` — no vowels (no
+  accidental words), no digits, no `I/O/U/Y/A/E` (no `0/O`, `1/I` confusion) —
+  displayed as `XXXX-XXXX`. Comparison uppercases and strips `-` and spaces.
+- Hand `logLogin` a new union member: `method: … | 'device'`
+  (`middleware/loginLogger.ts:10`).
+- **Neither code may ever reach a log line.** `req.log` calls in these handlers
+  log the row `id`, never the codes.
+
+### 3.8 Config
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `DEVICE_CODE_TTL` | `600` | seconds a pending code lives |
+| `DEVICE_POLL_INTERVAL` | `5` | seconds between polls the CLI is told to wait |
+
+Both read in `config.ts` next to the token TTLs.
+
+### 3.9 Tests — `test/auth-device.test.ts`
+
+Same harness as `test/smoke.test.ts` (`DATABASE_PATH=':memory:'`,
+`createApp()`, `listen(0)`):
+
+- mint → poll → `authorization_pending`; approve without a token → 401;
+  approve wrong code → 404; approve → poll → 200 with a session whose refresh
+  token then works on `/auth/refresh`; poll again → `expired_token`
+  (single use).
+- deny → `access_denied`.
+- `DEVICE_CODE_TTL=1` → `expired_token`; lookup of an expired code → 404.
+- two polls inside `interval` → second is `slow_down` and the stored interval
+  grew.
+- a `login_events` row exists with `method='device'` and the poller's IP.
+- 121 polls in a row are **not** rate-limited by `authLimiter` (guards §3.5).
+
+---
+
+## 4. Console — `web/`
+
+### 4.1 `pages/Activate.tsx` (new) — route `/activate`
+
+Registered in `App.tsx` **inside `RequireAuth`**, like `/profile`. Behaviour:
+
+1. Read `?code=`. If absent, show one input (8 letters, auto-formats
+   `XXXX-XXXX`, accepts lowercase, ignores dashes).
+2. `GET /auth/device/lookup?code=…` → render *who is asking*:
+
+   > **bir 0.2.0 on DESKTOP-PQVT0H2** asked to sign in as **you@example.com**
+   > from 1.2.3.4, 40 seconds ago.
+   > Only approve this if *you* just ran `bir login` on that machine.
+   > [Approve] [Deny]
+
+3. Approve → `POST /auth/device/approve` → "Done. You can go back to your
+   terminal." Deny → the mirror sentence.
+4. `404 unknown_code` → "That code isn't valid or has expired. Run `bir login`
+   again to get a new one." Nothing else is distinguishable, on purpose (§3.4).
+
+Wire `deviceLookup`, `deviceApprove`, `deviceDeny` into `api.ts` using the
+`api()`/`apiOk()` helpers from `auth.tsx`, so refresh-on-401 comes for free.
+
+### 4.2 The Google return-path bug this exposes
+
+The guard sends an unsigned-in visitor to `/login` with `from` set to
+`/activate?code=…`, and `SignInCard` navigates back to it after a password
+sign-in (`Login.tsx:401`, `dest = from.pathname + from.search`). **The Google
+path does not:** `GoogleSuccessPage` ends with `navigate('/')` unconditionally
+(`GoogleSuccess.tsx:54`), because Google's redirect round-trips through the
+service and loses React Router's state.
+
+This matters here more than anywhere: a Google-only user is the primary
+beneficiary of the whole change, and today they would land on the dashboard
+with the code gone. Fix: before `href={googleLoginUrl()}` (`Login.tsx:450`)
+stash `dest` in `sessionStorage['rrepeat.returnTo']`; `GoogleSuccessPage`
+reads and clears it and navigates there — after checking it is a same-origin
+path (starts with a single `/`), so the stash can never become an open
+redirect.
+
+### 4.3 Sign-in history
+
+`LoginHistory.tsx:10` types `method` as a four-member union and
+`METHOD_LABEL` (`:31`) maps each to a label. Add `'device'` →
+*"Runner sign-in (device code)"*. Without it the row renders the raw word.
+
+### 4.4 What does not change
+
+- **Caddy / CSP.** `try_files {path} /index.html` already serves any console
+  route, and `connect-src` already allows `https://api.bi2202.com`.
+- **CORS.** `origin: config.webOrigin` (`index.ts:43`) is exactly the origin
+  `/activate` calls from.
+- **Navigation.** No sidebar item; the page is reached by the link or by
+  typing the code. A one-line mention on `/guide/first-recording` where it
+  says `bir login` is enough.
+
+---
+
+## 5. Runner — this repo
+
+### 5.1 `src/auth/client.ts`
+
+| Change | Detail |
+|---|---|
+| **Add** `startDeviceCode(authUrl, client, fetchImpl)` | `POST /auth/device/code`; returns the §3.1 shape. A `404` throws a typed `DeviceFlowUnsupported` so the caller can fall back (decision 4). |
+| **Add** `pollDeviceToken(authUrl, deviceCode, {interval, expiresIn, fetchImpl, sleep, signal})` | The RFC loop. Honours `slow_down` by adding 5 s; stops on `access_denied`, `expired_token`, the deadline, or the signal. Returns an `AuthResponse`. `fetchImpl` and `sleep` are parameters so tests run in milliseconds. |
+| **Add** `deviceLogin(authUrl, {openBrowser, log})` | Orchestrates: probe with `describeAuthService` (keep — the wrong-host mistake is still possible), mint, print the block from §1, open the browser (§2 decision 5), poll, `saveCredentials(toSession(res))`. |
+| **Add** `openBrowser(url)` | `child_process.spawn`, detached, `stdio: 'ignore'`, never throws. No `shell: true`: the URL is one argument. On Windows the form is `cmd /c start "" <url>` — the empty string is `start`'s title argument and is required. |
+| **Change** `authenticate()` | Delete the prompt branch at `:384-408`. After the refresh attempt it always returns `undefined` with `auth.no_session`. The TTY check at `:377` goes with it. |
+| **Move** `prompt`, `promptPassword`, the `/auth/login` post | Into `legacyPasswordLogin(authUrl)`, called only by `bir login --password` and the 404 fallback. Delete with them in 0.3. |
+| **Add** `logout(authUrl)` | Best-effort `POST /auth/logout {refreshToken}` from the cached session, then `clearCredentials()`. |
+
+`loadCredentials`, `saveCredentials`, `clearCredentials`, `toSession`,
+`normalizeAuthUrl`, `describeAuthService`, `AUTH_URL_HINT` are unchanged and
+remain the whole contract with the rest of the runner.
+
+### 5.2 `src/bin/bir.ts`
+
+- `login` (`:1041-1059`): after the existing URL settling and service probe,
+  call `deviceLogin`. On `DeviceFlowUnsupported`, print one line —
+  *"this service does not offer browser sign-in yet; falling back to
+  email/password"* — and call `legacyPasswordLogin`.
+- Flags in `parseArgs` (`:127-197`): `--password` (force legacy, prints a
+  deprecation line), `--no-browser`.
+- `logout` (`:1061-1064`): call the new `logout()`; keep the same output line.
+- Usage text (`:71-100`): `login  sign in to the BaseIn service (opens your
+  browser; --no-browser to only print the link)`.
+
+Output discipline stays as it is: the interactive lines go to **stderr**
+(`process.stderr.write`, as the prompt does today), the final
+`Signed in to … as ….` to stdout via `out()`.
+
+### 5.3 `src/bin/bir-hooks.ts`
+
+No code change at `:89` — but the *behaviour* changes: a `bir-hooks` started
+with a TTY and no session no longer prompts; it logs
+`recorder.disabled why="no BaseIn session — run bir login"` (already there at
+`:91`) and runs as `NullRecorder`. `bir doctor` already turns that into
+*"set BIR_AUTH_URL and run `bir login` in the terminal where you start
+`bir-hooks`"* ([bir.ts:616-617](../src/bin/bir.ts#L616-L617)).
+
+### 5.4 Installer scripts
+
+`scripts/install-runner.sh:144-145` and `install-runner.ps1:153-154` call
+`bir login` in the foreground and need **no code change** — the device flow
+prints its link and code on whatever terminal the script has, and works over
+SSH because the link can be opened anywhere. What changes is the prose around
+them (the *"the password does not appear as you type"* notes) — §7.
+
+### 5.5 Version
+
+`0.2.0`: `authenticate()` stops prompting, which is a behaviour change other
+processes can observe.
+
+---
+
+## 6. Tests — runner
+
+`test/config.test.ts` already unit-tests `describeAuthService` and
+`normalizeAuthUrl` with a fake `fetch` (`:27`, `:125-163`). Add
+`test/auth.test.ts` in the same style:
+
+- `pollDeviceToken`: `pending → pending → ok` resolves to the session and
+  called `sleep(5000)` twice; `slow_down` bumps the next sleep to 10 s;
+  `access_denied` and `expired_token` reject with typed errors; the deadline
+  rejects even while the server keeps saying `pending`.
+- `startDeviceCode`: a `404` throws `DeviceFlowUnsupported`; an HTML answer
+  produces the existing *"this URL is a website"* wording from `postJson`.
+- `authenticate()` with no cache and a TTY **never** writes to stdin/stdout and
+  returns `undefined` (the regression test for decision 3).
+- `saveCredentials` output: shape, and mode `0600` on POSIX.
+
+`test/cli.test.ts` runs the built CLI as a process (`runBir`, `:36`). Add:
+
+- `bir login --no-browser` against a local `createServer` stand-in (the pattern
+  in [recorder.test.ts:55-100](../test/recorder.test.ts#L55-L100)) that answers
+  `/health` with JSON, mints a code, says `pending` once, then `200`. Assert the
+  code appears on stderr, `Signed in to … as …` on stdout, and
+  `credentials.json` under the test's `BIR_HOME`.
+- `bir login` against a stand-in whose `/auth/device/code` is `404` and whose
+  `/auth/login` succeeds — with stdin fed `email\npassword\n` — exercises the
+  fallback. Delete this test in 0.3 with the fallback.
+- `bir logout` hits `/auth/logout` with the cached refresh token and removes
+  the file.
+
+`test/smoke-replay.mjs` is unchanged: it pre-seeds credentials and never logs in.
+
+---
+
+## 7. Documentation to change
+
+Every place that shows or describes the prompt:
+
+| File | What |
+|---|---|
+| [README.md](../README.md) `:54` | the `bir login  # once` line gets the one-sentence description |
+| [quickstart.md](quickstart.md) `:63-70` | the `Email:` / `Password:` transcript becomes the link-and-code block; delete *"The password does not appear as you type"* |
+| [installInst.md](../installInst.md) Step 5 | same transcript change; the table row about `HTTP 405` stays |
+| [installInstMAC.md](../installInstMAC.md) | same |
+| [installRun.md](installRun.md) §5.1, §7 | §7 *Headless authentication* is rewritten: the device flow is the headless answer for **people** (approve from a phone); pre-seeded credentials remain for **service accounts**; runner tokens stay the follow-on |
+| [calculatedReplayGuide.md](calculatedReplayGuide.md) §1 | the prerequisite table row |
+| [my-first-sample.md](my-first-sample.md) §2 row 6, §4 | prerequisite row and Part B's `bir login  # once` |
+| `bir --help` | §5.2 |
+
+---
+
+## 8. Compatibility and rollout
+
+Ship in this order; each step is safe on its own.
+
+1. **Service**: table, endpoints, limiter split, `login_events` method. Purely
+   additive — `/auth/login` is untouched, so every deployed runner keeps
+   working.
+2. **Console**: `/activate`, the Google return-path fix, the history label.
+3. **Runner 0.2.0**: device flow by default, `--password` and the 404 fallback
+   kept. A new runner against an old service degrades to today's behaviour with
+   one explanatory line.
+4. **Runner 0.3.0**: remove `--password`, the fallback, and `legacyPasswordLogin`.
+
+Old runner + new service: unchanged. New runner + old service: fallback (step 3).
+
+---
+
+## 9. Security
+
+The device grant's own threat model is RFC 8628 §5; this is how each item lands
+here.
+
+| Concern | Answer |
+|---|---|
+| Guessing a `user_code` | 20⁸ ≈ 2.6 × 10¹⁰ codes, 10-minute life, approve limited to ~20 attempts / 15 min / IP (§3.5), constant-time compare. Not a threat. |
+| Stealing a `device_code` | It never leaves the runner, travels only in a POST body over TLS, is stored hashed, and is single-use. It is not in any URL. |
+| Phishing — *"enter this code on your account"* | The one real risk of every device flow. Mitigations: the page states *what* is asking (client, version, IP, age) and *who* it will sign in as, with the sentence *only approve if you just ran `bir login` yourself*; codes expire in 10 minutes; a wrong approval is one session, visible and revocable in Sign-in history. |
+| Codes in logs | Handlers log the row `id` only; `req.log` never sees either code. |
+| Tokens in URLs | None — an improvement on the Google handoff, which puts them in a fragment (`routes.ts:288-293`). |
+| CSRF | Not applicable: bearer JSON API, no cookies on these routes. |
+| Open redirect via the Google stash | The stored return path must start with a single `/` (§4.2). |
+| Shell injection via `openBrowser` | `spawn` without a shell; the URL is one argument built by the service from `webOrigin` plus a code from a fixed alphabet. |
+| A runner under a supervisor | Cannot start a sign-in any more (decision 3), so no unattended process ever holds an open device code. |
+
+---
+
+## 10. Edge cases
+
+- **Ctrl-C while waiting** — exit 130; the code stays pending until it expires;
+  nothing was written.
+- **User approves after the CLI gave up** — the next `bir login` mints a fresh
+  code; the stale approval is consumed by nobody and pruned.
+- **Two `bir login` on one machine** — independent codes; last writer wins
+  `credentials.json`. Same as today.
+- **Approve twice** — the second is a `404`; the page says so.
+- **Signed into the console as the wrong account** — the page names the account
+  it will sign the runner in as, before the button.
+- **`BIR_HOME`, `BIR_AUTH_DISABLE=1`** — unchanged.
+- **`describeAuthService` still runs first** — the wrong-host mistake now costs
+  nothing (no password is ever posted), but the diagnosis is still the useful
+  one.
+
+---
+
+## 11. Follow-ons this plan deliberately leaves out
+
+- **Runner tokens** for fleets (installRun.md §7 item 3): long-lived, scoped,
+  revocable credentials created in the console and passed as `BIR_TOKEN` /
+  `bir login --token`. This is the right answer for service accounts and it is
+  a separate design: token scopes, a *Tokens* section on the account page, and
+  a revocation story.
+- **Naming CLI sessions.** A `client_name` column on `refresh_tokens` would let
+  a future *Sessions* page show "bir on DESKTOP-PQVT0H2 — last used 2 h ago
+  — [sign out]". Cheap to add now while the device flow already knows the name;
+  worth doing if that page is coming.
+- **A QR code in the terminal** for the phone case. Zero-dependency ASCII QR
+  is ~150 lines; only worth it once the flow is in use.
+
+---
+
+## 12. Alternatives considered
+
+| Option | Why not |
+|---|---|
+| **Loopback redirect** (RFC 8252) | Fails exactly where `bir` runs: SSH, containers, runners with no browser. Needs a local listening port and a service-side redirect-URI allowlist. Could be added later as an *optimisation* of the same flow (auto-complete instead of poll) without changing the API. |
+| **Paste a token from the console** | Works, but the user types a long secret into a terminal (history, transcripts), and "create a token" is a worse first-run than "approve". Kept as the shape of the fleet follow-on (§11), where it belongs. |
+| **Keep the password, add "set a password" for Google users** | Forces a password on people who chose not to have one, and leaves problems 2–4 of §0 in place. |
+| **Reverse device flow** — the console shows a code the user types into the terminal | Puts the low-entropy code on the *unauthenticated* side, which is the property the RFC's direction exists to avoid, and the terminal still has to poll or paste. |
+
+---
+
+## 13. Open questions
+
+1. Should sessions issued to a CLI have a different refresh lifetime than the
+   console's 30 days? (A runner is long-lived by nature; the console default is
+   probably right.)
+2. Is `DEVICE_POLL_INTERVAL=5` right for the hosted service, or should it start
+   at 3 with the first `slow_down` moving it to 8?
+3. Add the `client_name` column to `refresh_tokens` now (§11) or leave the
+   schema alone until a *Sessions* page is planned?
+
+---
+
+## 14. Size
+
+| Piece | Effort |
+|---|---|
+| Service: table, `device.ts`, four routes, limiter split, tests | ~1 day |
+| Console: `/activate`, Google return path, history label | ~1 day |
+| Runner: client functions, CLI flags, logout, tests | ~1 day |
+| Docs, installer prose, manual acceptance run | ~½ day |
+
+**Acceptance, by hand:** `bir logout` → `bir login` → approve in the console
+signed in **with a Google account that has no password** → `bir doctor` says
+`Recording: yes` → record one run → Sign-in history shows *Runner sign-in
+(device code)* with the runner's IP → `bir logout` → the old refresh token now
+gets `401` from `/auth/refresh`.
+
+---
+
+## 15. What shipped
+
+Implemented 2026-09-08. Runner **0.2.0**; service and console changes are
+additive and went first, as §8 requires.
+
+| Where | Files |
+|---|---|
+| Service | `src/auth/device.ts` (new) · `src/auth/routes.ts` (4 routes) · `src/db.ts` (`device_authorizations`) · `src/config.ts` (4 knobs) · `src/index.ts` (limiter split) · `src/middleware/loginLogger.ts` · `test/auth-device.test.ts` (new, 16 tests) |
+| Console | `web/src/pages/Activate.tsx` (new) · `App.tsx` (route) · `api.ts` (return-path stash, device shapes) · `Login.tsx` + `GoogleSuccess.tsx` (the §4.2 fix) · `LoginHistory.tsx` · `FirstRecordingGuide.tsx` |
+| Runner | `src/auth/client.ts` (device flow; `authenticate` made silent) · `src/bin/bir.ts` (login/logout, `--password`, `--no-browser`) · `src/proxy/session.ts` · `test/auth.test.ts` (new, 13 tests) · `test/cli.test.ts` (+5) |
+| Docs | README · quickstart · installInst · installInstMAC · installRun §7 · calculatedReplayGuide · my-first-sample |
+
+Green: service 202 tests, runner 253 (252 + 1 platform skip), console build,
+`test:smoke`, and the §14 acceptance run against a **password-less account**.
+
+### Two things that changed shape
+
+**`nonInteractive` is gone rather than defaulted.** §2 decision 3 made
+`authenticate()` silent, which left `AuthenticateOptions.nonInteractive` a flag
+that could not change anything. A no-op option invites someone to toggle it and
+expect a different outcome, so it was removed and `proxy/session.ts` updated —
+the guarantee is now structural rather than requested.
+
+**The password fallback cannot be driven by a pipe, so its test asserts the
+decision.** `legacyPasswordLogin` refuses a non-TTY stdin, deliberately: a
+password must not be readable from somewhere a script could have put it. The
+CLI test therefore proves the 404 → fallback path is *taken* (and that the
+browser flow was tried first), not that a piped password is accepted. Driving
+the prompt itself would need a pseudo-terminal, for code being deleted next
+release.
+
+### One bug this found in existing code
+
+The Google sign-in return path (§4.2) was already broken for every deep link,
+not only `/activate` — `GoogleSuccessPage` navigated to `/` unconditionally, so
+any guard-interrupted destination was lost for Google users. Fixed here because
+a Google-only account is the primary beneficiary of the whole change.