fix(admin): renew browser session in place instead of a rotting admin credential (task #6)

[TennyZhuang]

Problem (task #6 — admin 401, ADMIN_RELOGIN_REQUIRED)

The admin console does a live Raft role re-check by storing the user's Raft access token (raft_access_token_ciphertext) on the session and calling /api/oauth/userinfo each request. That credential rots independently of the 14-day Hands session: Raft's token lives ~1h and issues no refresh_token, and a SIGNED_URL_SECRET rotation makes the ciphertext undecryptable. Result: the outer session stays valid (app pages work) while /admin 401s forever — "logged in but can't enter admin" — and the SPA collapsed six distinct 401 codes into one misleading "sign in again".

Design (confirmed against the Raft OAuth contract)

Raft's token response is {access_token, token_type, expires_in:3600} — no refresh_token (D0 out); server_role comes only from user-token-scoped userinfo/serverinfo — no service-credential role endpoint (D2 out). So the fix is in-place browser-session renewal (Yaoheng's refined option 3 / Argus's silent re-auth): when the credential rots, renew the whole session with one full-page Login-with-Raft, which is seamless while the user's Raft session is alive.

Changes

• worker/src/middleware/hands_admin.ts — return SESSION_REAUTH_REQUIRED for the browser-recoverable failures (ciphertext won't decrypt = key rotated; Raft rejects the token = expired/member-removed). The NULL-ciphertext branch stays ADMIN_RELOGIN_REQUIRED so agent/API sessions (for which NULL is legitimate) are never told to re-auth.
• admin/src/lib/api.ts — on SESSION_REAUTH_REQUIRED the shared request layer does one full-page renewal (/api/auth/login?return=<path>) that atomically replaces the browser session. Single-flight + 30s loop guard: a renewal that comes back still-failing (Raft not logged in, or user removed) falls through to the manual page instead of redirect-looping.
• admin/src/pages/HandsAdmin.tsx — distinguish ADMIN_AUTH_UNAVAILABLE (server config → contact ops, no login) from the recoverable re-login fallback.

Gates (Yaoheng's acceptance)

1. Only browser sessions renew; agent/API never redirect (SPA is browser-only; NULL-ciphertext stays a non-reauth code). ✅
2. Single-flight + loop guard. ✅
3. Config/403 never re-login. ✅
4. Renew → /admin 200 and per-request live role revocation still immediate (existing owner/admin→200, member/viewer→403 tests). ✅

Verification

• worker/test/hands_admin_access.test.ts +4 (agent-safe NULL → ADMIN_RELOGIN_REQUIRED; decrypt-fail & Raft-reject → SESSION_REAUTH_REQUIRED; config → ADMIN_AUTH_UNAVAILABLE) — 11/11.
• Worker tsc + admin tsc + admin vite build clean; full worker suite green (the one sqlite3-ENOENT failure is environment-only — absent locally, green in CI).

Honest residual constraint

Raft's 1h token + no refresh means active admin use hits a seamless auto-renewal ~hourly (a brief redirect, no password/consent while Raft is logged in). A truly gap-free admin session would need a Raft-side service-role endpoint or a longer token — a cross-Raft ask, out of scope here.

Not deployed by this PR — deploy runs through the migration/deploy gate after review.

🤖 Generated with Claude Code

---

Review round 1 (Yaoheng) — fixed at 52625446

• human+NULL now renews: hands_admin.ts branches the NULL-ciphertext case by principal_type — human+NULL → SESSION_REAUTH_REQUIRED (the likely shape of artin's current lock-out), agent+NULL → ADMIN_RELOGIN_REQUIRED (never browser-renew an agent).
• frontend reauth tests: admin/src/lib/apiReauth.dom.test.ts (jsdom, +5) locks the 4 gates.
• wording: the renewal is a client-side switch to a new session (localStorage token), not a server-side atomic replace; the old D1 row just expires.

Gate ⑤ — pre-deploy verification (REQUIRED before task #6 is marked done)

This PR fixes the credential rot (Box A: artin's current ADMIN_RELOGIN_REQUIRED). It does not touch the separate, still-unexplained "re-login also fails" (Box B) — a fresh login always writes a ciphertext (auth.ts:577), so it never hits the NULL branch. Box B is verified only empirically, by a test admin (e.g. Artea), not artin, on prod (no staging exists):

Steps: fully log out (clear hands_session / hands:auth-token) → open /admin → Continue with Raft → complete the flow → land on /admin.

• /admin 200 ⇒ the fresh-login path is healthy ⇒ Box B is not a general bug; artin's "re-login fails" was his own stale session/cookie, which this PR's human+NULL renewal handles. This PR closes the incident.
• Fails (400 "Missing or invalid browser login proof", or a 401 loop) ⇒ Box B is a real fresh-login bug (prime suspect: the fix(auth): bind browser login state to local proof #460 browser-login proof cookie — 10-min state TTL / browser cookie policy / prod cookie domain). This PR alone does not resolve artin → a separate fix is required.

Do not mark task #6 done on Box A alone.