dashboards/.agents/phases/complete/11_admin_login/05_login_page.md

Task 05 — The login page

Phase: 11_admin_login · Source: operator request 2026-10-17 — "password protect this dashboard" Story: n/a

Objective

A single-purpose page at /login that asks for the admin password, says honestly why it refused, and lands the operator on / (or the page they were heading to). Hand-rolled HTML + one small script, no CDN, dark/light parity with the dashboards.

Work

1. src/dashboards/web/pages/login.html — modelled on the other four pages' <head> (/static/dash.css, the same inline SVG favicon, data-theme="dark" so app.js can flip it from localStorage before paint):
   • title Homelab · sign in; the .masthead brand link, but no .tabs nav — the tabs lead to pages that would bounce straight back here, and a nav of links that all redirect is a lie about what is available.
   • one .card in main: <h1>Sign in</h1>, a .sub line naming what this protects ("the fleet's system, engine and battery dashboards — including the UPS controls"), then a form: <label for="admin-password">Admin password</label> + <input id="admin-password" type="password" autocomplete="current-password" required> + <button class="action" id="sign-in" type="submit">Sign in</button>.
   • a <p id="login-error" class="login-error" role="alert" hidden> for refusals and <p id="login-note" class="faint mono" hidden> for the lockout countdown.
   • scripts: /static/app.js then /static/page-login.js, defer.
   • no username field: one admin, and a field that is always the same word teaches the operator that half the form is theatre (auth.ADMIN_USER is the server's business).
2. src/dashboards/web/static/page-login.js — IIFE in the house style (see page-index.js), no framework:
   • submit handler → POST /api/auth/login with Dash.fetchJSON (it adds the JSON accept header and turns a non-2xx into a thrown Error with status/body); body {password};
   • on success location.assign(body.next || '/');
   • on 401 show Wrong password. and select the field's contents (fixing a typo without retyping is the whole UX of a login form);
   • on 429 show the detail plus the Retry-After seconds ticking down, and disable the button until it reaches 0 — a submit that will be refused should not look pressable;
   • on any other failure print the server's detail verbatim through the escape path the app already uses for text (textContent, never innerHTML);
   • honour ?next= only if it starts with / and not // (the same rule the server enforces; a client-side copy is defence in depth, and the server's check is the one that counts);
   • if the browser already holds a valid session, GET /api/auth/status succeeds → redirect to / immediately (task 03 also does this server-side; this is what stops a flash of the form).
3. src/dashboards/web/static/dash.css:
   • extend the existing input[type="text"] rule (line ~642) to input[type="text"], input[type="password"] — do not duplicate it;
   • add .login-card { max-width: 26rem; margin: 3rem auto; } and .login-error { color: var(--fail); }, .login-card form { display: grid; gap: .6rem; }, plus .login-card label { font-size: 10.5px; text-transform: uppercase; letter-spacing: .06em; color: var(--text-faint); } (the same caption vocabulary as .hero .label);
   • only existing :root tokens (--fail, --text-faint, --accent, …) — tests/test_api.py fails if a rule reaches for a token :root does not declare, and if a .sev-* family appears.
4. Keep the invariant: nothing external. tests/test_api.py already asserts the pages load no foreign asset — extend that assertion to /login (same test, one more path).

Testing & Quality

• tests/test_api.py (the served-HTML section) — /login is served anonymously with HTTP/1.1 200, contains id="admin-password", type="password", autocomplete="current-password", role="alert", and no /system-style .tabs; no http:// or https:// asset reference in the served bytes.
• Orphan-id pin: every new id (admin-password, sign-in, login-error, login-note) must be referenced by page-login.js (or the CSS) — that test fails on a dead id, so name what you use and use what you name.
• node --check src/dashboards/web/static/page-login.js (part of validate.sh).
• Coverage: no new Python; the served-bytes assertions are the tests. Do not add a JS test runner (a locked anchor).

Completion Criteria

• anonymous GET /login → 200 with the form; anonymous GET / → 303 to /login?next=/
• in the dev server: wrong password shows Wrong password. inline with no page reload; testpass lands on / and the header status dots go green
• five wrong passwords then a correct one shows the lockout with a counting-down Retry-After and a disabled button; it clears and the next attempt works
• /login?next=/ups after a successful sign-in lands on /ups
• dark and light both readable (screenshot both, or one plus a note in NOTES-*.md)
• uv run pytest green; ruff + pyright clean; bash .agents/validate.sh green