From 317508c60fe48a8527cb676cbfc4b3f11da01b01 Mon Sep 17 00:00:00 2001
From: geb <samananiascases@gmail.com>
Date: Fri, 4 Sep 2026 23:19:22 +0800
Subject: [PATCH] auth: PIN login gate - one-time login issues in-memory
 session tokens
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- app/services/sessions.py: module-level token set (secrets.token_urlsafe),
  no persistence - a restart invalidates every token, and since config
  loads once at startup a PIN change is a restart, so one rule covers both
  re-prompt triggers
- require_pin additively accepts a valid token in X-Session-Token; the
  raw X-API-PIN header path is unchanged
- new GET /auth/status (always 200; pin_required + session_valid
  true/false/null) and POST /auth/login (401 wrong PIN, 400 when no PIN
  is configured); router mounted in app/main.py
- web: shared gate overlay (GATE_HTML) on both pages styled as a third
  notebook page, Remember checkbox picks localStorage vs sessionStorage,
  the old per-action id="pin" field and its JS read sites are gone in
  favor of one authHeaders() helper, 401 mid-action re-raises the gate,
  and checkGate() rides the 30 s health poll for restart re-prompt
- docs: LOGIN_PLAN.md decision record (review + as-built), WEBDESIGN_PLAN
  §12 addendum, SOURCE_OF_TRUTH §8/§11, README/.env.example API_PIN text
- tests: new unit (sessions, token path of require_pin), API
  (/auth/status, /auth/login, token-unlocks-route integration) and web
  gate tests plus an autouse fresh_sessions fixture; suite 316 -> 378,
  coverage 95.75 %, ruff clean
---
 .env.example                 |   5 +-
 README.md                    |   2 +-
 app/api/auth.py              |  53 +++++
 app/api/web.py               | 233 ++++++++++++++++----
 app/main.py                  |   7 +
 app/models/auth.py           |  28 +++
 app/services/auth.py         |  17 +-
 app/services/sessions.py     |  48 +++++
 docs/LOGIN_PLAN.md           | 401 +++++++++++++++++++++++++++++++++++
 docs/SOURCE_OF_TRUTH.md      |   3 +
 docs/WEBDESIGN_PLAN.md       |  51 ++++-
 tests/api/test_auth_api.py   | 100 +++++++++
 tests/api/test_health_web.py |  59 ++++++
 tests/conftest.py            |  14 +-
 tests/unit/test_auth.py      |  46 +++-
 tests/unit/test_sessions.py  |  36 ++++
 16 files changed, 1047 insertions(+), 56 deletions(-)
 create mode 100644 app/api/auth.py
 create mode 100644 app/models/auth.py
 create mode 100644 app/services/sessions.py
 create mode 100644 docs/LOGIN_PLAN.md
 create mode 100644 tests/api/test_auth_api.py
 create mode 100644 tests/unit/test_sessions.py

diff --git a/.env.example b/.env.example
index 5514657..78116f8 100644
--- a/.env.example
+++ b/.env.example
@@ -7,8 +7,9 @@ PORT=8000
 # Max upload size in megabytes (README Section 8)
 MAX_UPLOAD_MB=25
 
-# Optional shared PIN the phone must send with each request (README Section 8).
-# Leave empty to disable authentication entirely.
+# Optional shared PIN (README Section 8). When set, the web UI shows a
+# one-time login gate that exchanges it for a session token; raw API
+# requests may still send the X-API-PIN header. Empty = auth disabled.
 API_PIN=
 
 # Printer to submit jobs to (Phase 5). Empty = the Windows default printer.
diff --git a/README.md b/README.md
index 1322383..0230de8 100644
--- a/README.md
+++ b/README.md
@@ -269,7 +269,7 @@ Copy `.env.example` to `.env` to configure optional server settings. All keys ar
 | Key | Default | Description |
 |---|---|---|
 | `MAX_UPLOAD_MB` | `25` | Maximum allowed upload size in megabytes (larger files rejected with HTTP 413). |
-| `API_PIN` | *(empty)* | Optional security PIN. When set, requests require the `X-API-PIN` header (the web interface will display a PIN input field). |
+| `API_PIN` | *(empty)* | Optional security PIN. When set, the web interface shows a one-time login gate (the PIN is exchanged for a session token, then never sent again); API clients may still send the raw `X-API-PIN` header. Leave empty to disable authentication entirely. |
 | `PRINTER_NAME` | *(empty)* | Specific Windows printer name to target. If empty, the system default printer is used. |
 | `SUMATRA_PATH` | *(empty)* | Custom path to `SumatraPDF.exe`. Leave empty to use automatic standard path detection. |
 | `PAPER_SIZE` | *(empty)* | Default paper size token passed to driver (e.g. `A4`). Leave empty to let the Windows driver choose. |
diff --git a/app/api/auth.py b/app/api/auth.py
new file mode 100644
index 0000000..90c05c1
--- /dev/null
+++ b/app/api/auth.py
@@ -0,0 +1,53 @@
+"""Auth endpoints for the PIN login gate (docs/LOGIN_PLAN.md §4).
+
+Two endpoints, same conventions as /scanners and /print:
+
+- GET /auth/status — the endpoint the page calls before rendering
+  anything. Never requires the PIN itself and never errors (always 200),
+  mirroring /scanners' "must be checkable before you know whether to show
+  UI for it" role.
+- POST /auth/login — the only place the raw PIN is ever submitted.
+  Deliberately open (you can't require the PIN to submit the PIN); abuse
+  throttling is a Phase 4 add-on per LOGIN_PLAN §7/§11.
+"""
+
+import hmac
+
+from fastapi import APIRouter, Header, HTTPException
+
+from app.config import API_PIN
+from app.models.auth import AuthStatus, LoginRequest, LoginResponse
+from app.services import sessions
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+@router.get("/status", response_model=AuthStatus)
+def auth_status(
+    x_session_token: str | None = Header(default=None),
+) -> AuthStatus:
+    """Report whether the gate exists and whether a presented token is
+    still good. session_valid is None when no token was sent or when no
+    PIN is configured (sessions can only exist while a PIN does, so the
+    field is simply not meaningful then)."""
+    pin_required = bool(API_PIN)
+    session_valid = None
+    if pin_required and x_session_token:
+        session_valid = sessions.is_valid(x_session_token)
+    return AuthStatus(pin_required=pin_required, session_valid=session_valid)
+
+
+@router.post("/login", response_model=LoginResponse)
+def login(request: LoginRequest) -> LoginResponse:
+    """Exchange the raw PIN for an opaque session token (one per device).
+
+    401 on a wrong PIN with a clear message; 400 when no PIN is
+    configured at all, since there is nothing to log in to."""
+    if not API_PIN:
+        raise HTTPException(
+            status_code=400,
+            detail="No PIN is configured — the login gate is disabled.",
+        )
+    if not request.pin or not hmac.compare_digest(request.pin, API_PIN):
+        raise HTTPException(status_code=401, detail="Incorrect PIN.")
+    return LoginResponse(token=sessions.create_session())
diff --git a/app/api/web.py b/app/api/web.py
index 5936b95..c1ab9e2 100644
--- a/app/api/web.py
+++ b/app/api/web.py
@@ -32,12 +32,16 @@
      multipart boundary itself; setting it manually breaks the request.
   4. The response is the JSON from POST /print, which we display.
 
-The JS logic (upload, PIN header, polling, scan detection, innerHTML
-safety) carries over from the previous page — this revision restyled
-presentation and status rendering (emoji status markers are gone: status
-is icon + exact API word + pen color), and added a Jobs list (GET /jobs,
-already served by app/api/jobs.py) written on the ruled lines with
-per-state ink colors and a cancel button for active jobs.
+The JS logic (upload, session-token auth, polling, scan detection,
+innerHTML safety) carries over from the previous page — this revision
+restyled presentation and status rendering (emoji status markers are
+gone: status is icon + exact API word + pen color), and added a Jobs list
+(GET /jobs, already served by app/api/jobs.py) written on the ruled lines
+with per-state ink colors and a cancel button for active jobs. The PIN
+login gate (docs/LOGIN_PLAN.md) then replaced the old type-it-every-time
+PIN field: the raw PIN is submitted once to POST /auth/login, the opaque
+token it returns is stored client-side, and every request sends it in
+X-Session-Token via the shared authHeaders() helper.
 """
 
 import base64
@@ -347,6 +351,17 @@ def _icon_sprite() -> str:
                text-decoration: none; color: inherit; }
   .topright { display: flex; align-items: center; gap: 12px; }
   .btn.nav { min-height: 44px; padding: 6px 16px; font-size: 17px; }
+
+  /* ---- the login gate (LOGIN_PLAN §6): a third page, not a dialog ----
+     Full-viewport takeover on the same paper — never a floating card
+     (WEBDESIGN_PLAN: no cards, shadows, or boxed containers). */
+  .gate { position: fixed; inset: 0; z-index: 40; background: var(--paper);
+          overflow: auto; }
+  .gate-remember { display: flex; align-items: center; gap: 9px;
+                   margin: 2px 0 16px 8px; font-size: 14px;
+                   color: var(--graphite); cursor: pointer; }
+  .gate-remember input { width: 18px; height: 18px; flex: none;
+                         accent-color: var(--ink-blue); }
 </style>
 </head>
 <body>
@@ -378,12 +393,6 @@ def _icon_sprite() -> str:
       <input type="file" id="file"
              accept=".pdf,.jpg,.jpeg,.png,.webp,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.odt,.ods,.odp,.txt,.csv">
     </div>
-    <div class="row">
-      <span class="ic xs" style="color:var(--graphite)"
-            aria-hidden="true"><svg><use href="#i-lock-key"/></svg></span>
-      <input type="password" id="pin" autocomplete="off"
-             placeholder="PIN (only if the server set one)">
-    </div>
     <button id="printBtn" class="btn" onclick="sendPrint()">Print<svg
       class="btail" aria-hidden="true"><use href="#i-printer"/></svg></button>
     <button id="retryBtn" class="btn hidden" style="margin-left:10px"
@@ -466,12 +475,7 @@ def _icon_sprite() -> str:
     <div id="scanControls" style="display:none;">
       <p class="sub">Scanner: <span id="scanName"></span></p>
       <div class="row">
-        <span class="ic xs" style="color:var(--graphite)"
-              aria-hidden="true"><svg><use href="#i-lock-key"/></svg></span>
-        <input type="password" id="pin" autocomplete="off"
-               placeholder="PIN (only if the server set one)">
-      </div>
-      <button id="scanBtn" class="btn scanbtn" onclick="startScan()">Scan<svg
+        <button id="scanBtn" class="btn scanbtn" onclick="startScan()">Scan<svg
         class="btail" aria-hidden="true"><use href="#i-scan"/></svg></button>
       <div class="working" id="scanWorking" hidden aria-hidden="true">
         <svg viewBox="0 0 150 28" width="132" height="25">
@@ -512,6 +516,39 @@ def _icon_sprite() -> str:
 </main>
 """
 
+# The login gate (docs/LOGIN_PLAN.md §6) — shared by BOTH pages, a third
+# page of the same notebook rather than a modal card. Hidden by default:
+# JS reveals it only when /auth/status reports a PIN is required AND the
+# stored session token is not currently valid. The ids are test-pinned
+# hooks (same convention as startScan()/scanBtn).
+GATE_HTML = """<div id="pinOverlay" class="gate hidden" role="dialog"
+     aria-modal="true" aria-labelledby="gateTitle">
+  <header class="top">
+    <div class="brand">
+      <img src="/favicon.svg" alt="">
+      <h1>printerService</h1>
+    </div>
+    <span class="ic health" aria-hidden="true"><svg><use
+      href="#i-lock-key"/></svg></span>
+  </header>
+  <main class="sheet">
+    <section class="act">
+      <h2 class="rulehead" id="gateTitle"><span class="ic"
+        aria-hidden="true"><svg><use href="#i-lock-key"/></svg></span>
+        Enter PIN</h2>
+      <div class="row">
+        <input type="password" id="pinInput" autocomplete="current-password"
+               placeholder="PIN" aria-label="PIN">
+      </div>
+      <label class="gate-remember"><input type="checkbox" id="pinRemember"
+        checked> Remember this device</label>
+      <button class="btn" onclick="submitLogin()">Unlock</button>
+      <div id="pinError" class="status err hidden" role="alert"></div>
+    </section>
+  </main>
+</div>
+"""
+
 PAGE_JS1 = """
 <script>
 // ---- handles over the redesigned DOM (ids are pinned by tests) ----
@@ -558,8 +595,7 @@ def _icon_sprite() -> str:
 // needed. Resumes polling as if the job had just been queued.
 async function retryJob() {
   if (!failedJobId) { return; }
-  const pin = document.getElementById("pin").value.trim();
-  const headers = pin ? { "X-API-PIN": pin } : {};
+  const headers = authHeaders();
   retryControls(false);
   show("Retrying job " + failedJobId + "…", "ok");
   try {
@@ -568,6 +604,8 @@ def _icon_sprite() -> str:
     const data = await response.json();
     if (response.ok) {
       poll(failedJobId, 0);
+    } else if (response.status === 401) {
+      sessionExpired();
     } else {
       show("Retry refused: " + (data.detail || response.status), "err");
     }
@@ -603,10 +641,9 @@ def _icon_sprite() -> str:
     body.append("paper", document.getElementById("paper").value);
     body.append("color_mode", document.getElementById("colorMode").value);
 
-    // Send the PIN header only if the user typed one; the server ignores
-    // it entirely when no PIN is configured (auth disabled).
-    const pin = document.getElementById("pin").value.trim();
-    const headers = pin ? { "X-API-PIN": pin } : {};
+    // Credentials come from the login gate's stored session token
+    // (authHeaders below); the server never trusts the browser anyway.
+    const headers = authHeaders();
 
     const response = await fetch("/print", { method: "POST", body, headers });
     const data = await response.json();
@@ -616,7 +653,7 @@ def _icon_sprite() -> str:
       poll(data.job_id, 0);
       loadJobs();
     } else if (response.status === 401) {
-      show("Wrong PIN.", "err");
+      sessionExpired();
     } else {
       // The server answered with a problem (415 not-a-PDF, 413 too big, …)
       show("Server said: " + (data.detail || response.status), "err");
@@ -641,9 +678,7 @@ def _icon_sprite() -> str:
     return;
   }
   try {
-    const pin = document.getElementById("pin").value.trim();
-    const headers = pin ? { "X-API-PIN": pin } : {};
-    const response = await fetch("/jobs/" + jobId, { headers });
+    const response = await fetch("/jobs/" + jobId, { headers: authHeaders() });
     if (!response.ok) {
       show("Lost track of job " + jobId + " (HTTP " + response.status + ")",
            "err");
@@ -777,12 +812,13 @@ def _icon_sprite() -> str:
 }
 
 async function cancelJob(jobId) {
-  const pin = document.getElementById("pin").value.trim();
-  const headers = pin ? { "X-API-PIN": pin } : {};
+  const headers = authHeaders();
   try {
     const response = await fetch("/jobs/" + jobId,
                                  { method: "DELETE", headers });
-    if (!response.ok) {
+    if (response.status === 401) {
+      sessionExpired();
+    } else if (!response.ok) {
       const data = await response.json().catch(() => ({}));
       show("Cancel refused: " + (data.detail || response.status), "err");
     }
@@ -791,6 +827,120 @@ def _icon_sprite() -> str:
   }
   loadJobs();
 }
+
+// ---- the login gate (docs/LOGIN_PLAN.md §3/§5) ----
+// One shared block for both pages. The raw PIN is submitted exactly once,
+// to POST /auth/login; from then on every request carries the opaque
+// session token it returned — never the PIN, never persisted anywhere the
+// server can see. "Remember this device" is purely a client-side storage
+// choice: localStorage survives the browser, sessionStorage dies with it.
+const TOKEN_KEY = "printerService.pinToken";
+
+function storedToken() {
+  return sessionStorage.getItem(TOKEN_KEY) || localStorage.getItem(TOKEN_KEY);
+}
+
+function saveToken(token, remember) {
+  (remember ? localStorage : sessionStorage).setItem(TOKEN_KEY, token);
+}
+
+function clearToken() {
+  localStorage.removeItem(TOKEN_KEY);
+  sessionStorage.removeItem(TOKEN_KEY);
+}
+
+// The single place every authed request builds its headers — replaces the
+// old per-action "type the PIN again" field.
+function authHeaders() {
+  const token = storedToken();
+  return token ? { "X-Session-Token": token } : {};
+}
+
+function showGate() {
+  const overlay = document.getElementById("pinOverlay");
+  if (!overlay) { return; }
+  overlay.classList.remove("hidden");
+  document.getElementById("pinError").classList.add("hidden");
+  const input = document.getElementById("pinInput");
+  input.value = "";
+  input.focus();
+}
+
+function hideGate() {
+  document.getElementById("pinOverlay").classList.add("hidden");
+}
+
+// A 401 from any protected route means the session died mid-action
+// (server restarted since login) — raise the gate, not a dead-end error.
+function sessionExpired() {
+  clearToken();
+  showGate();
+}
+
+// Focus is trapped while the gate is up: unlike every convenience
+// overlay in this app, this one genuinely blocks use of the page.
+document.addEventListener("keydown", function (event) {
+  const overlay = document.getElementById("pinOverlay");
+  if (!overlay || overlay.classList.contains("hidden")
+      || event.key !== "Tab") { return; }
+  const focusable = overlay.querySelectorAll("input, button");
+  const first = focusable[0];
+  const last = focusable[focusable.length - 1];
+  if (event.shiftKey && document.activeElement === first) {
+    event.preventDefault();
+    last.focus();
+  } else if (!event.shiftKey && document.activeElement === last) {
+    event.preventDefault();
+    first.focus();
+  }
+});
+
+async function submitLogin() {
+  const input = document.getElementById("pinInput");
+  const error = document.getElementById("pinError");
+  const pin = input.value.trim();
+  if (!pin) { input.focus(); return; }
+  try {
+    const response = await fetch("/auth/login", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ pin: pin }),
+    });
+    if (response.ok) {
+      const data = await response.json();
+      saveToken(data.token,
+                document.getElementById("pinRemember").checked);
+      hideGate();
+    } else {
+      // Error detail is real information: system font, --red-pen, never
+      // the handwriting face (WEBDESIGN_PLAN §3). Stale tokens, if any,
+      // are discarded; focus stays in the field.
+      error.textContent = "Incorrect PIN.";
+      error.classList.remove("hidden");
+      clearToken();
+      input.focus();
+      input.select();
+    }
+  } catch (networkError) {
+    error.textContent = "Could not reach the server. Are you on the same Wi-Fi?";
+    error.classList.remove("hidden");
+  }
+}
+
+// Phase 3 (LOGIN_PLAN §5 step 5): the initial check happens at load, and
+// the same check runs on the health poll's 30 s cadence — so a server
+// restart mid-session raises the gate on the next beat without a reload.
+async function checkGate() {
+  try {
+    const response = await fetch("/auth/status", { headers: authHeaders() });
+    const info = await response.json();
+    if (info.pin_required && info.session_valid !== true) {
+      sessionExpired();
+    }
+  } catch (networkError) {
+    /* server unreachable — the header wifi icon already says so */
+  }
+}
 """
 PAGE_JS3 = """
 // ---- Scan page (owner request: scan lives on its own page at GET /scan,
@@ -854,8 +1004,7 @@ def _icon_sprite() -> str:
     scanBtn.disabled = true;
     scanWorking.hidden = false;
     scanShow("Starting scan…", "ok");
-    const pin = document.getElementById("pin").value.trim();
-    const headers = pin ? { "X-API-PIN": pin } : {};
+    const headers = authHeaders();
     // Scan options (Phase 4): DPI, color mode, output format — strictly
     // allowlisted server-side; the selects only ever offer valid values.
     const body = new FormData();
@@ -870,7 +1019,7 @@ def _icon_sprite() -> str:
         pollScan(data.job_id, 0);
       } else if (response.status === 401) {
         scanSettle();
-        scanShow("Wrong PIN.", "err");
+        sessionExpired();
       } else {
         scanSettle();
         scanShow("Server said: " + (data.detail || response.status), "err");
@@ -891,9 +1040,8 @@ def _icon_sprite() -> str:
       return;
     }
     try {
-      const pin = document.getElementById("pin").value.trim();
-      const headers = pin ? { "X-API-PIN": pin } : {};
-      const response = await fetch("/scan/jobs/" + jobId, { headers });
+      const response = await fetch("/scan/jobs/" + jobId,
+                                   { headers: authHeaders() });
       if (!response.ok) {
         scanSettle();
         scanShow("Lost track of scan job " + jobId + " (HTTP " +
@@ -965,6 +1113,8 @@ def _icon_sprite() -> str:
 }
 
 checkHealth();   // the header wifi icon exists on both pages
+checkGate();     // the login gate: on load, and again on the health
+setInterval(checkGate, 30000);   // poll's cadence (LOGIN_PLAN §5 step 5)
 if (document.getElementById("jobList")) {   // the print page only
   loadJobs();
   setInterval(loadJobs, 5000);  // cheap on a LAN; keeps the sheet fresh
@@ -975,13 +1125,14 @@ def _icon_sprite() -> str:
 </html>"""
 # The two pages are assembled once at import: asset placeholders become the
 # inlined font and the icon sprite (both degrading to nothing if the
-# committed files are missing).
+# committed files are missing), and the shared login-gate markup is added
+# to both — hidden by default, revealed by /auth/status-driven JS only.
 PAGE = (
-    PAGE_CSS1 + PAGE_CSS2 + PAGE_CSS3 + PAGE_BODY_HOME + PAGE_HTML2
-    + PAGE_JS1 + PAGE_JS2 + PAGE_JS3
+    PAGE_CSS1 + PAGE_CSS2 + PAGE_CSS3 + GATE_HTML + PAGE_BODY_HOME
+    + PAGE_HTML2 + PAGE_JS1 + PAGE_JS2 + PAGE_JS3
 )
 SCAN_PAGE = (
-    PAGE_CSS1 + PAGE_CSS2 + PAGE_CSS3 + PAGE_BODY_SCAN
+    PAGE_CSS1 + PAGE_CSS2 + PAGE_CSS3 + GATE_HTML + PAGE_BODY_SCAN
     + PAGE_JS1 + PAGE_JS2 + PAGE_JS3
 )
 for _page_name, _page in (("PAGE", PAGE), ("SCAN_PAGE", SCAN_PAGE)):
diff --git a/app/main.py b/app/main.py
index c8b2f1d..060620c 100644
--- a/app/main.py
+++ b/app/main.py
@@ -30,6 +30,7 @@
 
 from fastapi import FastAPI
 
+from app.api.auth import router as auth_router
 from app.api.jobs import router as jobs_router
 from app.api.print import router as print_router
 from app.api.printers import router as printers_router
@@ -112,3 +113,9 @@ def health():
 # download / cancel. Own store, own namespace — never touches print code.
 app.include_router(scan_router)
 
+# PIN login gate (docs/LOGIN_PLAN.md Phase 1): GET /auth/status + POST
+# /auth/login. Deliberately open endpoints — /status must be checkable
+# before the client knows whether to show the gate, and /login is how the
+# raw PIN is exchanged once for a session token.
+app.include_router(auth_router)
+
diff --git a/app/models/auth.py b/app/models/auth.py
new file mode 100644
index 0000000..41a2819
--- /dev/null
+++ b/app/models/auth.py
@@ -0,0 +1,28 @@
+"""Pydantic shapes for the PIN login gate (docs/LOGIN_PLAN.md §4)."""
+
+from pydantic import BaseModel
+
+
+class LoginRequest(BaseModel):
+    """Body of POST /auth/login — the only place the raw PIN is submitted."""
+
+    pin: str
+
+
+class LoginResponse(BaseModel):
+    """200 body of POST /auth/login — the opaque token the client stores
+    (never the PIN) and sends in X-Session-Token from then on."""
+
+    token: str
+
+
+class AuthStatus(BaseModel):
+    """GET /auth/status — checked before the page renders anything.
+
+    session_valid is None when no token was sent (or no PIN is
+    configured, making the whole gate moot), False when a token was sent
+    but isn't currently active (wrong, or the server restarted since it
+    was issued), True when good."""
+
+    pin_required: bool
+    session_valid: bool | None = None
diff --git a/app/services/auth.py b/app/services/auth.py
index 970d69c..8397d67 100644
--- a/app/services/auth.py
+++ b/app/services/auth.py
@@ -21,13 +21,26 @@
 from fastapi import Header, HTTPException
 
 from app.config import API_PIN
+from app.services import sessions
 
 
-def require_pin(x_api_pin: str | None = Header(default=None)) -> None:
-    """FastAPI dependency: attach to any route that changes state."""
+def require_pin(
+    x_api_pin: str | None = Header(default=None),
+    x_session_token: str | None = Header(default=None),
+) -> None:
+    """FastAPI dependency: attach to any route that changes state.
+
+    LOGIN_PLAN §3.2: valid if the classic X-API-PIN header matches, OR a
+    currently-active session token is presented in X-Session-Token (the
+    web page's post-login credential). Purely additive — every caller
+    that only sends the PIN header behaves exactly as before.
+    """
     if not API_PIN:
         return  # auth disabled
 
+    if x_session_token and sessions.is_valid(x_session_token):
+        return
+
     if not x_api_pin or not hmac.compare_digest(x_api_pin, API_PIN):
         raise HTTPException(
             status_code=401,
diff --git a/app/services/sessions.py b/app/services/sessions.py
new file mode 100644
index 0000000..e9d9b07
--- /dev/null
+++ b/app/services/sessions.py
@@ -0,0 +1,48 @@
+"""
+In-memory session tokens for the PIN login gate (docs/LOGIN_PLAN.md §3).
+
+Design: after a successful POST /auth/login the client holds an opaque
+token (secrets.token_urlsafe(32) — 256 bits, server-generated, never
+client-chosen) and sends it in the "X-Session-Token" header. The token set
+lives ONLY in process memory, structured like this codebase's other
+in-memory stores (module-level state + a lock):
+
+- No persistence, no TTL bookkeeping — deliberately. The process's memory
+  lifetime IS the session lifetime, which is the property LOGIN_PLAN §1's
+  answer #4 needs: a server restart silently invalidates every issued
+  token, so a session can never outlive the PIN that authorized it (and
+  since config loads once at startup, a PIN change is a restart — one rule
+  covers both re-prompt triggers).
+- Tokens accumulate only on successful logins, so on a home-lab scale the
+  set stays trivially small; no expiry sweep is worth the bookkeeping.
+"""
+
+import secrets
+import threading
+
+_lock = threading.RLock()
+_active_tokens: set[str] = set()
+
+
+def create_session() -> str:
+    """Mint a fresh opaque token and remember it until the process ends."""
+    token = secrets.token_urlsafe(32)
+    with _lock:
+        _active_tokens.add(token)
+    return token
+
+
+def is_valid(token: str | None) -> bool:
+    """True only for a token this process issued and has not been
+    restarted since. Empty/None is simply invalid, never an error."""
+    if not token:
+        return False
+    with _lock:
+        return token in _active_tokens
+
+
+def reset() -> None:
+    """Drop every token — the tests' 'server restart' simulation (the real
+    thing happens for free when the process exits)."""
+    with _lock:
+        _active_tokens.clear()
diff --git a/docs/LOGIN_PLAN.md b/docs/LOGIN_PLAN.md
new file mode 100644
index 0000000..2221f17
--- /dev/null
+++ b/docs/LOGIN_PLAN.md
@@ -0,0 +1,401 @@
+# PIN Login Gate — Feasibility, Decision Record & Roadmap
+
+Status: **implemented on branch `auth-security` (2026-09-04).** All §11 open
+items are decided; §0's compatibility review ran against the real source.
+Decisions are recorded inline — the 🔵/🟡/🔴 tags below are kept for
+history, but everything needed to read this as-built is marked ✅.
+Goal: since the router's admin panel doesn't give you enough control to
+firewall the LAN or spin up an isolated guest network, move the "who's
+allowed to use this" boundary up into the app itself — a proper login gate
+in front of the existing PIN, instead of relying on network isolation you
+can't fully configure.
+
+Claims are tagged like SOURCE_OF_TRUTH / MULTI_FORMAT_PLAN / SCAN_PLAN:
+🟢 CONFIRMED FACT · 🔵 RECOMMENDED (decided here) · 🟡 ALTERNATIVE ·
+🔴 NEEDS VERIFICATION (read the real code first) · ⚪ FUTURE
+
+---
+
+## 0. Compatibility review — DONE (2026-09-04) 🟢
+
+Ran against the real source, as SCAN_PLAN §0 did. All three assumptions
+held; one additional finding (the inline PIN field) is folded into §6/§11.
+
+1. ✅ **Header mechanism confirmed.** `app/services/auth.py` defines
+   `require_pin(x_api_pin: Header)` — a FastAPI dependency reading the
+   **`X-API-PIN`** header, compared to `API_PIN` with
+   `hmac.compare_digest`, raising 401 otherwise. Attached via
+   `Depends(require_pin)` to exactly the state-changing routes:
+   `POST /print`, `DELETE /jobs/{id}`, `POST /jobs/{id}/retry`,
+   `POST /scan`, `DELETE /scan/jobs/{id}`. Read-only GETs stay open.
+2. ✅ **Client-side confirmed — and worse than assumed.** Both pages in
+   `app/api/web.py` render a `type="password"` field (`id="pin"`) and the
+   JS reads it fresh at *every* action (~6 sites), sending `X-API-PIN`
+   only when non-empty. Nothing is persisted. With the gate in place this
+   inline field is redundant, so the decision (§11) is to **remove it**
+   and route every client request through the stored session token.
+3. ✅ **Config is load-once, no hot reload.** `app/config.py` parses
+   `.env` once at module import; `API_PIN` is bound at import time and
+   `auth.py` imports it by value. A PIN change *is* a restart — the
+   §3.2/"key insight" design is correct as written.
+
+Also checked: no test pins the old `id="pin"` HTML field (only the
+`X-API-PIN` header in API tests, which this feature does not touch), and
+the suite stood at **316 tests** when this plan was written (not the 342
+cited from SCAN_PLAN §8).
+
+---
+
+## 1. Executive summary — the 5 answers
+
+| # | Question | Decision |
+|---|----------|----------|
+| 1 | Show the gate when no PIN is configured? | **No.** Fully invisible — no overlay, no extra requests — when `PIN` is unset/empty. |
+| 2 | How do we avoid re-entering the PIN every time ("save password")? | Store an **opaque session token** client-side (not the raw PIN), issued once at login. |
+| 3 | Why does it reappear if the PIN changes? | It doesn't need special-casing — see #4. Since config only loads at startup, a PIN change already requires a restart. |
+| 4 | Why does it reappear if "the server is down"? | Sessions live **only in server memory**. A process restart empties that memory, so every previously issued token silently stops working — the client discovers this on its next check-in and re-prompts. |
+| 5 | Does this touch the existing print/scan request flow? | **No.** Existing API requests keep sending the raw PIN header exactly as they do today; the token is a separate, additive "is my remembered credential still good" check — same non-regression guarantee SCAN_PLAN gave the print pipeline. *(As built, the browser itself switched from the per-action PIN field to the stored token — §11's "inline PIN field removed" decision — but `X-API-PIN` is accepted unchanged for direct API use.)* |
+
+**Key insight:** #3 and #4 are the same mechanism. You asked for two
+separate re-prompt triggers ("PIN changed" and "server down"), but because
+this codebase already loads config once at startup (no hot reload), a PIN
+change *is* a restart. One rule — "sessions don't survive a process
+restart" — satisfies both requirements without extra bookkeeping, extra
+config, or a database. This is the same kind of trade-off SOURCE_OF_TRUTH
+§12 already made peace with for jobs ("in-memory... accepted trade-off")
+and it's arguably a *feature* here, not a limitation: it means a session
+can never quietly outlive the PIN that authorized it.
+
+---
+
+## 2. Why an app-level gate instead of network isolation 🔵
+
+SOURCE_OF_TRUTH §8 always treated the shared PIN as "cheap insurance," on
+the assumption that the real boundary was the LAN itself (private-profile
+firewall, no port forwarding, §7/§8). With no ability to firewall
+device-to-device or run a genuinely isolated guest network on this router,
+that assumption weakens — anything else on the Wi-Fi can currently reach
+the service and try the PIN on every request. This plan doesn't change the
+threat model (still LAN-only, still "sensible defaults, not enterprise
+hardening," §8) — it just gives the PIN a real front door instead of
+letting each POST silently 401 with no clear "you need to sign in" moment,
+and adds a small amount of session hygiene (§3, §7) that's easy to get for
+free while doing that.
+
+---
+
+## 3. Session design — the core mechanism 🔵
+
+### 3.1 What gets added
+
+New file `app/services/sessions.py`, structured like the other in-memory
+stores in this codebase (job dict + lock, scan store's own connection +
+`RLock`):
+
+```python
+# app/services/sessions.py  (sketch — confirm naming against auth.py in Phase 0)
+import secrets
+import threading
+
+_lock = threading.RLock()
+_active_tokens: set[str] = set()          # cleared for free on process restart
+
+def create_session() -> str:
+    token = secrets.token_urlsafe(32)
+    with _lock:
+        _active_tokens.add(token)
+    return token
+
+def is_valid(token: str | None) -> bool:
+    if not token:
+        return False
+    with _lock:
+        return token in _active_tokens
+```
+
+No persistence, no SQLite table, no TTL bookkeeping — deliberately. The
+process's memory lifetime *is* the session lifetime, which is exactly the
+property §1's answer #4 needs.
+
+### 3.2 How it plugs into the existing PIN check ✅ (decided: separate header)
+
+`app/services/auth.py`'s `require_pin` currently checks "does the request's
+`X-API-PIN` header match `API_PIN`." Extend it — additively — to also
+accept a currently-valid session token sent in a **separate
+`X-Session-Token` header**:
+
+```
+require_pin passes IF
+    API_PIN is unset                            (unchanged, auth disabled)
+    OR X-API-PIN equals API_PIN                 (unchanged, today's check)
+    OR X-Session-Token is an active session     (new)
+```
+
+Every existing test that exercises "PIN header equals PIN" keeps passing
+unmodified — this is a pure addition to what counts as valid, not a
+replacement.
+
+### 3.4 Where the token lives — DECIDED: separate `X-Session-Token` header ✅
+
+The plan originally leaned toward dual-accepting "PIN or token" in the
+same header, but reading the real code settled it the other way:
+
+- 🔵 **Chosen: separate `X-Session-Token` header.** The real
+  `require_pin` is tiny and its 401 message ("Send it in the 'X-API-PIN'
+  header") stays literally true. Dual-accept would make every
+  state-changing route's auth decision depend on session state and make
+  that error message ambiguous, to save one header — bad trade.
+- 🟡 ~~Same header, dual-accept~~ — rejected for the reasons above.
+
+### 3.3 What the client actually stores
+
+- **The raw PIN is only ever sent once**, in the login request. It is
+  never written to `localStorage`/`sessionStorage`.
+- After a successful login, the client stores the **token** (not the PIN)
+  under a namespaced key, e.g. `printerService.pinToken`.
+- "Remember this device" (checked by default) decides *where*:
+  checked → `localStorage` (survives closing the browser); unchecked →
+  `sessionStorage` (cleared when the tab/browser session ends). Same
+  token, same server-side validity rule either way — this checkbox is
+  purely a client-side storage choice, no server involvement.
+
+---
+
+## 4. API design 🔵
+
+Two new endpoints, same conventions as `/scanners` and `/print`
+(SCAN_PLAN §4, SOURCE_OF_TRUTH §11) — status codes and shape match what's
+already established in this codebase rather than inventing new ones.
+
+| Endpoint | Method | Request | Response | Why |
+|---|---|---|---|---|
+| `/auth/status` | GET | optional: stored token, sent the same way any authed request sends it | `{"pin_required": true/false, "session_valid": true/false/null}` | **The endpoint the page calls before rendering anything.** Never requires the PIN itself — mirrors `/scanners`' "must be checkable before you know whether to show UI for it" role. `session_valid` is `null` when no token was sent, `false` when a token was sent but isn't currently active (wrong, or server restarted since it was issued), `true` when good. Always open, always 200 — same "never errors" spirit as `/scanners`. |
+| `/auth/login` | POST | `{"pin": "..."}` | **200** `{"token": "..."}` on match; **401** with a clear message on mismatch | The only place the raw PIN is ever submitted after this feature ships. Deliberately open (can't require the PIN to submit the PIN) but see §7 for lightweight abuse protection. |
+
+No `/auth/logout` in v1 — see §9 Phase 4 for the optional "forget this
+device" button.
+
+---
+
+## 5. Client-side flow 🔵
+
+1. Either page (`/` or `/scan`) loads. Before rendering the rest of the
+   page's interactive bits, it reads any stored token and calls
+   `GET /auth/status` (attaching the token the same way other requests
+   attach credentials).
+2. `pin_required: false` → nothing else happens. No overlay is ever built
+   or shown, no further auth-related requests are made for the rest of
+   the session. This satisfies your "only shows when a PIN is configured"
+   requirement literally — the gate doesn't exist on a no-PIN install.
+3. `pin_required: true, session_valid: true` → the stored token still
+   works. Overlay stays hidden; the rest of the page behaves exactly as
+   it does today.
+4. `pin_required: true, session_valid: false or null` → show the overlay
+   (§6). The user enters the PIN once, `POST /auth/login`, on success the
+   returned token is stored per the Remember checkbox (§3.3), overlay
+   hides, page proceeds normally.
+5. **Reappearing automatically without a manual refresh:** the existing
+   health/connectivity poll (WEBDESIGN_PLAN §4's `wifi-high`/`wifi-slash`
+   indicator, and the jobs list's 5s refresh per WEBDESIGN_PLAN §11)
+   already round-trips to the server periodically. Piggyback the same
+   `session_valid` check onto that existing poll (or a lightweight
+   parallel one) so that if the server process restarts while the page is
+   left open, the very next poll notices `session_valid: false` and
+   raises the overlay again — the user doesn't have to manually reload
+   the tab to discover they've been logged out.
+6. Wrong PIN → `/auth/login` 401 → inline error in the overlay
+   (`--red-pen`, system font, per WEBDESIGN_PLAN §3's rule that error
+   detail is never handwriting), stored token (if any stale one existed)
+   is discarded, focus stays in the field.
+
+---
+
+## 6. UI / visual design — a Revision-3 addendum to WEBDESIGN_PLAN.md 🔵
+
+This needs its own small addendum to WEBDESIGN_PLAN.md rather than a
+free-standing style, because the notebook world (§0–§2 of that doc) has
+firm opinions this has to honor: no cards/boxes, ruled-paper-is-the-
+container, handwriting only for short labels, `--red-pen` reserved for
+real errors, self-hosted assets only, mobile-first.
+
+**Proposed treatment:** rather than inventing a floating modal/card (which
+WEBDESIGN_PLAN's "no cards, shadows, or boxed containers" rule explicitly
+forbids), treat the gate as **a third page of the same notebook** — a
+full-viewport takeover using the identical ruled/margin `.page` background
+(§2's recipe), so it never reads as a foreign dialog bolted onto the app:
+
+```
+┌──┬──────────────────────────┐
+│  │ printerService     [wifi] │  ← same header zone, nav box hidden
+├──┼──────────────────────────┤     while locked (nothing to nav to yet)
+│▍ │ [lock-key] Enter PIN      │  ← handwriting heading, sits on the
+│▍ │                           │     first rule like any other heading
+│▍ │ [__________________]     │  ← type="password", --paper-raised field
+│▍ │ ☐ Remember this device   │  ← handwriting label (short → allowed)
+│▍ │                           │
+│▍ │      [ Unlock ]           │  ← the existing drawn-box button style,
+│▍ │                           │     --ink-blue border, handwriting label
+│▍ │ Incorrect PIN.            │  ← only on error: system font, --red-pen
+└──┴──────────────────────────┘
+```
+
+- Icon: reuse `lock-key`, already in the WEBDESIGN_PLAN §4 mapping for
+  PIN — no new icon needed for v1.
+- No show/hide-password eye toggle in v1 🔵 — it's one more icon and one
+  more piece of state for a form that's used rarely once "remember" is
+  on; skip it and keep the field a plain `type="password"`. Note as a
+  🟡 later addition if it turns out to be annoying in practice.
+- `autocomplete="current-password"` on the field so the *browser's own*
+  password manager can also offer to remember it — free, complementary
+  to the app-level token, and no extra code.
+- `aria-modal="true"`, labelled, autofocus on the field, focus trapped
+  while shown, since this genuinely blocks use of the page (unlike every
+  other overlay/drawer in WEBDESIGN_PLAN, which are conveniences, not
+  gates).
+- New pinned hooks to add (and keep, per WEBDESIGN_PLAN §0's "test-pinned
+  hooks survive" rule): `id="pinOverlay"`, `id="pinInput"`,
+  `id="pinRemember"`, `id="pinError"`, `onclick="submitLogin()"` — naming
+  in the same style as the existing `startScan()`/`scanBtn` pattern.
+- Shared between both pages: since `/` and `/scan` each build their HTML
+  independently (WEBDESIGN_PLAN §11's "assemble from the same CSS/JS
+  parts"), factor the overlay markup + JS into one function both page
+  builders call, the same way the nav-box hand-off is shared.
+
+---
+
+## 7. Security 🔵
+
+Same posture as SOURCE_OF_TRUTH §8 / SCAN_PLAN §7 — sensible home-lab
+defaults, not enterprise hardening:
+
+- Still LAN-only, still no internet exposure, still plain HTTP — the
+  token travels over the same unencrypted local connection the PIN
+  already does today, so this is not a new exposure, just a narrower one
+  (the raw PIN itself now crosses the wire once per device instead of on
+  every single request).
+- Token generated with `secrets.token_urlsafe(32)` (256 bits) — not
+  guessable; comparison against `settings.PIN` uses a constant-time
+  comparison (`hmac.compare_digest`), same as any credential check.
+- 🔵 **Recommended, not blocking:** a small in-memory failed-attempt
+  counter per source IP on `/auth/login` (e.g., a short delay or lockout
+  after 5 wrong PINs in a minute). This is easy to add now that there's a
+  single dedicated login surface, and meaningfully raises the cost of
+  someone on the LAN brute-forcing the PIN — something that was true of
+  the *old* per-request check too, just less visible as a single target.
+  Not required for a working v1; fine to land in Phase 4.
+- Server-generated tokens only, never client-chosen — same
+  path-traversal-style discipline SOURCE_OF_TRUTH §9 already applies to
+  filenames.
+- No new attack surface beyond what §16/§8 already accept: still nothing
+  beyond SQLite (and this doesn't even need SQLite — sessions are memory-
+  only), still no OAuth/accounts, still PIN/LAN as the whole model.
+
+---
+
+## 8. Edge cases 🔵
+
+- **No PIN configured at all:** `/auth/status` always returns
+  `pin_required: false`; no overlay code path is ever reached. Setting a
+  PIN later (and restarting) turns the gate on for every device on the
+  next load — nothing to migrate.
+- **Token present but server restarted since issuance:** `session_valid:
+  false`; overlay reappears; one PIN entry issues a fresh token; nothing
+  else on the device needs re-entering (no re-upload, no lost job state —
+  jobs live in SQLite already, per SOURCE_OF_TRUTH §12, untouched by this
+  feature).
+- **Two devices, same PIN:** independent tokens, independent sessions;
+  restarting the server logs both out simultaneously (both discover it on
+  their next poll) — consistent, no partial-logout state to reason about.
+- **"Remember" unchecked, tab closed and reopened:** `sessionStorage` is
+  gone → overlay shows again, exactly like a fresh device. Working as
+  intended — that's what unchecking the box means.
+- **PIN typed wrong repeatedly:** 401 each time, inline error, no lockout
+  in v1 unless you take the §7 recommendation into Phase 1 early.
+- **Existing print/scan requests during the transition:** unaffected in
+  every case — §3.2's change is additive, so a device that never visits
+  the login gate at all (e.g., an old bookmark hitting `/print` directly)
+  still authenticates exactly as it does today, with the raw PIN header.
+
+---
+
+## 9. Phased roadmap 🔵 → all phases built ✅ (2026-09-04)
+
+- **Phase 0 — compatibility review (§0):** ✅ done — results recorded at
+  §0; all three assumptions confirmed, the inline-PIN-field finding
+  folded into §11.
+- **Phase 1 — backend session support:** ✅ done —
+  `app/services/sessions.py` (module-level set + `RLock`, `create_session`/
+  `is_valid`/`reset`), the additive `X-Session-Token` branch in
+  `require_pin`, `app/models/auth.py` (`LoginRequest`, `LoginResponse`,
+  `AuthStatus`), `app/api/auth.py` (`GET /auth/status`, `POST /auth/login`),
+  router mounted in `main.py`, and an autouse `fresh_sessions` conftest
+  fixture (the session set is module-level state, so tests reset it the
+  same way the job store gets a fresh one). One deviation from the §4
+  table: `/auth/login` returns **400** (not silently 200) when no PIN is
+  configured — there is nothing to log in to.
+- **Phase 2 — login gate UI:** ✅ done — `GATE_HTML` shared by both pages
+  in `app/api/web.py`, wired to `/auth/status` + `/auth/login`, Remember
+  checkbox driving `localStorage` vs `sessionStorage`, inline error via
+  `.status.err`, old inline `id="pin"` field and its ~6 JS read sites
+  removed in favor of one `authHeaders()` helper.
+- **Phase 3 — auto re-prompt on restart:** ✅ done — `checkGate()` runs
+  at load and on the health poll's 30 s cadence; a `session_valid`
+  flip to false raises the overlay without a manual reload. A 401 from
+  any protected route also re-raises the gate mid-action.
+- **Phase 4 (⚪ optional / v2):** login-attempt throttling (§7); a
+  "forget this device" button; a soft max-age on tokens; a show/hide
+  password toggle. Not built.
+
+---
+
+## 10. Testing plan 🔵
+
+Mirrors the existing suite's core trick (SOURCE_OF_TRUTH §13): fake the
+boundary, never rely on real timing or a real browser.
+
+| What | How |
+|---|---|
+| Session store: create/validate, "restart" clears everything | Unit tests against a fresh module import / re-instantiated set |
+| PIN-check dependency: old PIN-header path unaffected; new token path accepted when valid, rejected when stale/unknown | Unit tests, same fake-module style already used for `win32print`/`win32com` |
+| `/auth/status`: never errors; correct `pin_required`/`session_valid` combinations, including "no token sent" (`null`) | API tests via `TestClient` |
+| `/auth/login`: correct PIN → 200 + usable token; wrong PIN → 401; missing field → 422 | API tests |
+| Web page: overlay hooks present; overlay absent entirely when `pin_required:false`; Remember checkbox picks `localStorage` vs `sessionStorage`; error text never uses the handwriting face | Web-page tests, same style as `TestNotebookRedesign` |
+| **Regression guard:** the full existing suite (316 tests when this plan was written) still passes unmodified | Just run it |
+
+Same CI gates apply: `ruff check .` + `pytest --cov-fail-under=90`.
+
+---
+
+## 11. Open items for you to decide before Phase 1
+
+- [x] §3.4 — **separate `X-Session-Token` header** (decided against the
+      plan's original lean, after reading the real `auth.py` — see §3.4).
+- [x] §7 — **throttling deferred to Phase 4** (not required for the
+      feature to work correctly, and Phase 1 is already the riskiest
+      phase).
+- [x] §6 — **full-page takeover confirmed** — the "third page of the
+      notebook" treatment, leaning into "no cards, ever."
+- [x] Remember-this-device default: **checked by default** (least
+      friction; matches a personal home-lab device).
+- [x] *(New item, raised by the §0 review)* The old inline
+      `id="pin"` field on both pages is **removed** — with the gate and
+      the stored token, retyping the PIN per page load is exactly the
+      friction this feature exists to remove. All ~6 JS header-building
+      sites switch to a shared `authHeaders()` that sends
+      `X-Session-Token`; a 401 mid-action re-raises the gate.
+- [x] *(New item, recorded explicitly)* Read-only GETs (`/jobs`,
+      `/printers`, `/scanners`, scan downloads) **stay open without any
+      credential**, per the existing auth convention. The gate stops
+      people from *acting*, not from *reading* — an accepted property of
+      the LAN threat model (§2), not an oversight.
+
+---
+
+*Companion to MULTI_FORMAT_PLAN.md, SCAN_PLAN.md, and WEBDESIGN_PLAN.md —
+same tagging convention, same "decision record before code" discipline.
+No hardware spike required; this is a pure software/UX feature.*
+
+**As-built (2026-09-04):** suite 378 tests, 95.75 % coverage (gate 90 %),
+ruff clean — the pre-existing suite passed unmodified throughout; every
+test added here is new coverage. WEBDESIGN_PLAN §12 records the visual
+addendum; SOURCE_OF_TRUTH §8/§11 record the security and API decisions.
\ No newline at end of file
diff --git a/docs/SOURCE_OF_TRUTH.md b/docs/SOURCE_OF_TRUTH.md
index 5fb351d..31c6390 100644
--- a/docs/SOURCE_OF_TRUTH.md
+++ b/docs/SOURCE_OF_TRUTH.md
@@ -276,6 +276,7 @@ This is a home-lab project, so the goal is **sensible defaults**, not enterprise
 
 - **Should the service be local-network-only?** 🔵 **Yes, by default.** Don't forward the port through your router to the internet. As long as it's local-network-only, the "attack surface" is limited to devices already trusted enough to be on your Wi-Fi.
 - **Should authentication be implemented?** 🟡 Optional for a true home-lab MVP where you trust everyone on your network, but a **simple shared PIN/token** (a fixed string the phone must send along with each request) is a cheap, educational first step into authentication concepts, and cheap insurance if a neighbor's device or an IoT gadget ever gets on your Wi-Fi.
+- 🟢 **PIN login gate (2026-09-04, full decision record: [LOGIN_PLAN.md](LOGIN_PLAN.md)):** with no router-level device isolation available, the PIN got a real front door. When `API_PIN` is set, the web UI shows a one-time login gate (`POST /auth/login`) that exchanges the raw PIN for an opaque 256-bit session token — held only in server memory, so any restart invalidates every token, which (since config loads once at startup) also covers PIN changes with the same rule. State-changing routes accept either the raw `X-API-PIN` header (unchanged, additive) or the token in `X-Session-Token`. Read-only GETs stay open per the existing convention: the gate stops people from *acting*, not *reading* — an accepted property of the LAN threat model, recorded deliberately, not an oversight.
 - **Should you expose the service to the internet?** 🔴 **No, not for this project.** Beyond the immediate risk, unauthenticated file upload + "please execute a print" is exactly the kind of endpoint attackers scan the internet for. If you ever want *remote* printing later, that's a deliberate ⚪ future project with its own security design (e.g., a VPN into your home network, not a directly exposed port).
 - **What if you accidentally expose the API (e.g., misconfigured router)?** Worst case with no auth: anyone who finds the port could send arbitrary files to be printed (a nuisance/paper-waste/DoS risk) or attempt to exploit a bug in your file-handling code. This is why file validation (below) and *not* forwarding the port matter.
 - **What firewall rules should you use?** Allow inbound TCP on your chosen port (e.g., 8000), scoped to your **private network profile** in Windows Firewall (not "public"), so it isn't inadvertently exposed if the PC ever joins another network.
@@ -404,6 +405,8 @@ Keep it this flat at first — you can split `api/`, `printer/`, etc. further on
 | `/jobs/{id}` | GET | job id in URL | Status of one specific job | Lets the UI poll "is my print done yet?" |
 | `/jobs/{id}` | DELETE | job id in URL | Confirmation / error | Lets you cancel a queued job — useful once you've accidentally queued the wrong file (you will). |
 | `/jobs/{id}/retry` | POST | job id in URL | The job re-queued | Re-print a failed job from its stored upload (p14) — no re-upload needed. |
+| `/auth/status` | GET | optional: stored session token in `X-Session-Token` | `{"pin_required": true/false, "session_valid": true/false/null}` | The login gate's pre-render check: does a gate exist, and is this device's remembered token still good? Always open, always 200 — same never-errors spirit as `/scanners`. |
+| `/auth/login` | POST | `{"pin": "..."}` | `200 {"token": "..."}`; `401` wrong PIN; `400` no PIN configured | The only place the raw PIN is ever submitted; exchanges it once per device for an opaque session token (in-memory, restart-invalidated). |
 
 Nothing here is over-engineered: every endpoint maps directly to something you'll actually need while testing the system by hand.
 
diff --git a/docs/WEBDESIGN_PLAN.md b/docs/WEBDESIGN_PLAN.md
index 56ca96b..ea0aa92 100644
--- a/docs/WEBDESIGN_PLAN.md
+++ b/docs/WEBDESIGN_PLAN.md
@@ -492,22 +492,59 @@ MOBILE — SCAN PAGE (/scan, same sheet)
   `getElementById("scanDpi"|"scanColorMode"|"scanFormat")`,
   `href="/favicon.svg"` — zero test changes were needed for the restyle;
   the new tests only *add* pins.
-- **Fetch/FormData logic untouched** — upload, PIN header, polling
-  cadence, and the innerHTML-safety rule (nothing from the server enters
-  `innerHTML` except the server-issued job id in the scan download link)
-  all carry over unchanged.
+- **Fetch/FormData logic untouched** — upload, polling cadence, and the
+  innerHTML-safety rule (nothing from the server enters `innerHTML`
+  except the server-issued job id in the scan download link) all carry
+  over unchanged. (The PIN-header half of this line was later superseded
+  by the login gate — §12.)
 - The favicon SVG stays as-is (PRODUCT.md brand commitment) — its cyan/
   magenta/yellow accents are the print-service mark, not the page theme.
 - The durable visual system is recorded in `DESIGN.md` +
   `.impeccable/design.json`; product truth in `PRODUCT.md`.
 
+---
+
+## 12. Addendum — the login gate (2026-09-04)
+
+The PIN login gate (full decision record: [LOGIN_PLAN.md](LOGIN_PLAN.md))
+is a **third page of the same notebook**, not a dialog: a full-viewport
+takeover reusing the identical `.top` header zone and ruled `.sheet`
+background, hidden by default (`class="gate hidden"`) and revealed only
+when `GET /auth/status` reports `pin_required: true` and no valid stored
+session token.
+
+- **No new visual vocabulary.** No card, no shadow, no dimmed backdrop —
+  the "no boxed containers" rule holds. The heading sits on the first
+  rule like any other `.rulehead`; the field is the standard
+  `--paper-raised` input; the Unlock button is the existing drawn-box
+  `.btn`. Icon: `lock-key` (already in the §4 mapping — no new icon).
+- **New pinned hooks** (same convention as `startScan()`/`scanBtn`):
+  `id="pinOverlay"`, `id="pinInput"`, `id="pinRemember"`,
+  `id="pinError"`, `onclick="submitLogin()"` — pinned by
+  `TestLoginGate` in `tests/api/test_health_web.py`.
+- **The old per-action PIN field is gone.** Revision 2's inline
+  `id="pin"` field on both pages was removed: the raw PIN is submitted
+  exactly once to `POST /auth/login`, the returned opaque token is
+  stored client-side (`localStorage` vs `sessionStorage` per the
+  Remember checkbox, namespaced key `printerService.pinToken`), and
+  every request sends it in `X-Session-Token` via one shared
+  `authHeaders()` helper.
+- **Error text never uses the handwriting face** (§3 rule): "Incorrect
+  PIN." renders through `.status.err` — system font, `--red-pen`.
+- **It genuinely blocks the page** (unlike every convenience overlay
+  here): `role="dialog"`, `aria-modal="true"`, autofocus, Tab focus
+  trap.
+- Gate markup + JS are shared by both pages — assembled into `PAGE` and
+  `SCAN_PAGE` from one `GATE_HTML` block, the same way the nav hand-off
+  is shared.
 
 ---
 
 *Revision 2 — the exercise-book world, decided by the owner 2026-09-03
-("elementary: paper with blue-red-blue lines"). Product truth lives in
-`PRODUCT.md`; this file owns the visual world. v1 (print shop) is retired
-but its state-color discipline and constraint set survive here.*
+("elementary: paper with blue-red-blue lines"); §12 addendum (the login
+gate) 2026-09-04. Product truth lives in `PRODUCT.md`; this file owns
+the visual world. v1 (print shop) is retired but its state-color
+discipline and constraint set survive here.*
 
 
 
diff --git a/tests/api/test_auth_api.py b/tests/api/test_auth_api.py
new file mode 100644
index 0000000..9ed2703
--- /dev/null
+++ b/tests/api/test_auth_api.py
@@ -0,0 +1,100 @@
+"""API tests for the PIN login gate endpoints (docs/LOGIN_PLAN.md §4/§10).
+
+/auth/status must never error and must report the full
+pin_required/session_valid (true/false/null) matrix; /auth/login must
+issue a usable token on the right PIN and refuse everything else. A final
+integration test proves the issued token actually unlocks a state-changing
+route via X-Session-Token, and that the old X-API-PIN path is untouched.
+"""
+
+import pytest
+
+from app.services import sessions
+
+
+@pytest.fixture
+def pin_on(monkeypatch):
+    """A configured PIN, patched where it is actually READ (imported by
+    value into both consumers — conftest.py rule #2)."""
+    monkeypatch.setattr("app.services.auth.API_PIN", "1234")
+    monkeypatch.setattr("app.api.auth.API_PIN", "1234")
+
+
+class TestAuthStatus:
+    def test_no_pin_configured_gate_does_not_exist(self, client):
+        response = client.get("/auth/status")
+        assert response.status_code == 200
+        assert response.json() == {"pin_required": False, "session_valid": None}
+
+    def test_pin_configured_no_token_sent(self, client, pin_on):
+        response = client.get("/auth/status")
+        assert response.status_code == 200
+        assert response.json() == {"pin_required": True, "session_valid": None}
+
+    def test_stale_token_reported_false_not_error(self, client, pin_on):
+        response = client.get(
+            "/auth/status", headers={"X-Session-Token": "expired-or-forged"}
+        )
+        assert response.status_code == 200
+        assert response.json() == {"pin_required": True, "session_valid": False}
+
+    def test_valid_token_reported_true(self, client, pin_on):
+        token = sessions.create_session()
+        response = client.get(
+            "/auth/status", headers={"X-Session-Token": token}
+        )
+        assert response.status_code == 200
+        assert response.json() == {"pin_required": True, "session_valid": True}
+
+
+class TestAuthLogin:
+    def test_correct_pin_returns_usable_token(self, client, pin_on):
+        response = client.post("/auth/login", json={"pin": "1234"})
+        assert response.status_code == 200
+        token = response.json()["token"]
+        assert token and sessions.is_valid(token)
+
+    def test_wrong_pin_rejected_with_401(self, client, pin_on):
+        response = client.post("/auth/login", json={"pin": "9999"})
+        assert response.status_code == 401
+        assert "PIN" in response.json()["detail"]
+
+    def test_missing_field_is_422(self, client, pin_on):
+        response = client.post("/auth/login", json={})
+        assert response.status_code == 422
+
+    def test_no_pin_configured_is_400(self, client):
+        response = client.post("/auth/login", json={"pin": "1234"})
+        assert response.status_code == 400
+        assert "No PIN" in response.json()["detail"]
+
+    def test_empty_pin_rejected(self, client, pin_on):
+        response = client.post("/auth/login", json={"pin": ""})
+        assert response.status_code == 401
+
+
+class TestTokenUnlocksStateChangingRoutes:
+    """The end-to-end point of the feature: one login, then the token
+    stands in for the PIN everywhere require_pin is attached — while the
+    raw-PIN path keeps working exactly as before (regression guard)."""
+
+    def test_login_then_token_works_on_protected_route(self, client, pin_on):
+        token = client.post("/auth/login", json={"pin": "1234"}).json()["token"]
+
+        cancelled = client.delete(
+            "/jobs/does-not-matter", headers={"X-Session-Token": token}
+        )
+        # 404 (unknown job) NOT 401 — the token got through the gate.
+        assert cancelled.status_code == 404
+
+    def test_stale_token_still_401_on_protected_route(self, client, pin_on):
+        response = client.delete(
+            "/jobs/does-not-matter", headers={"X-Session-Token": "forged"}
+        )
+        assert response.status_code == 401
+
+    def test_raw_pin_header_path_untouched(self, client, pin_on):
+        wrong = client.delete("/jobs/abc", headers={"X-API-PIN": "0000"})
+        right = client.delete("/jobs/abc", headers={"X-API-PIN": "1234"})
+        assert wrong.status_code == 401
+        assert right.status_code == 404  # past auth, unknown job
diff --git a/tests/api/test_health_web.py b/tests/api/test_health_web.py
index 8ba9b6a..31fb526 100644
--- a/tests/api/test_health_web.py
+++ b/tests/api/test_health_web.py
@@ -129,3 +129,62 @@ def test_assets_are_inlined_and_self_hosted(self, client):
         assert '<symbol id="i-pencil"' in page    # the signature element
 
 
+
+
+class TestLoginGate:
+    """The PIN login gate (docs/LOGIN_PLAN.md §6/§10): one shared overlay
+    on both pages, the old type-it-every-time PIN field gone, and the
+    gate provably inert when the server runs without a PIN."""
+
+    def test_gate_hooks_present_on_both_pages(self, client):
+        # Test-pinned hooks (LOGIN_PLAN §6), same convention as scanBtn.
+        for path in ("/", "/scan"):
+            page = client.get(path).text
+            assert 'id="pinOverlay"' in page
+            assert 'id="pinInput"' in page
+            assert 'id="pinRemember"' in page
+            assert 'id="pinError"' in page
+            assert 'onclick="submitLogin()"' in page
+
+    def test_gate_starts_hidden_and_is_status_driven(self, client):
+        # The gate must never show on its own initiative: hidden class by
+        # default, revealed only after /auth/status says pin_required.
+        for path in ("/", "/scan"):
+            page = client.get(path).text
+            assert 'class="gate hidden"' in page
+            assert 'fetch("/auth/status"' in page
+            assert "pin_required" in page
+            assert "session_valid" in page
+
+    def test_remember_checkbox_picks_storage(self, client):
+        # localStorage (remembered) vs sessionStorage (this tab only) —
+        # the plan's §3.3 client-side-only choice.
+        page = client.get("/").text
+        assert 'id="pinRemember"' in page
+        assert "localStorage" in page and "sessionStorage" in page
+        assert 'printerService.pinToken' in page   # namespaced key
+
+    def test_requests_use_the_session_token_not_the_pin(self, client):
+        # The old per-action PIN entry is gone; authHeaders() sends the
+        # opaque token instead. The raw PIN appears only in the login POST.
+        page = client.get("/").text
+        assert 'getElementById("pin")' not in page  # old field + reads gone
+        assert '"X-API-PIN"' not in page
+        assert "X-Session-Token" in page
+        assert 'fetch("/auth/login"' in page
+        scan_page = client.get("/scan").text
+        assert 'getElementById("pin")' not in scan_page
+
+    def test_error_text_stays_out_of_the_handwriting_face(self, client):
+        # WEBDESIGN_PLAN §3: error detail is real information — the
+        # pinError element carries the .status class (system font), and
+        # the handwriting .btn face stays on the Unlock button only.
+        page = client.get("/").text
+        assert 'id="pinError" class="status err hidden"' in page
+
+    def test_gate_wired_into_the_poll_cadence(self, client):
+        # Phase 3: a mid-session server restart raises the gate on the
+        # next 30 s beat, no manual reload needed.
+        page = client.get("/").text
+        assert "setInterval(checkGate, 30000)" in page
+        assert "checkGate();" in page
diff --git a/tests/conftest.py b/tests/conftest.py
index d7c1160..e4916b9 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -30,7 +30,7 @@
 from fastapi.testclient import TestClient
 
 from app.printer import windows
-from app.services import jobs, scan_jobs
+from app.services import jobs, scan_jobs, sessions
 
 # The printer name the fakes pretend Windows reports (matching the real
 # L3210's queue name keeps the tests readable).
@@ -58,6 +58,18 @@ def fresh_job_store(tmp_path, monkeypatch):
     monkeypatch.setattr(scan_jobs, "_conn", None)
 
 
+@pytest.fixture(autouse=True)
+def fresh_sessions(monkeypatch):
+    """An empty session-token set for every test (LOGIN_PLAN §3).
+
+    sessions.py keeps a module-level set, exactly like the job store
+    above — without this, a token minted in one test would still validate
+    in the next. reset() is the same thing a real server restart does for
+    free.
+    """
+    sessions.reset()
+
+
 @pytest.fixture(autouse=True)
 def tmp_upload_dir(tmp_path, monkeypatch) -> Path:
     """Redirect uploads/ to a temp dir for every test.
diff --git a/tests/unit/test_auth.py b/tests/unit/test_auth.py
index 1055060..895b1bc 100644
--- a/tests/unit/test_auth.py
+++ b/tests/unit/test_auth.py
@@ -1,13 +1,15 @@
 """Unit tests for the shared-PIN dependency (app/services/auth.py).
 
-require_pin() is a plain function taking the header value, so the auth
+require_pin() is a plain function taking the header values, so the auth
 RULES can be tested directly without HTTP: disabled when no PIN is
-configured, 401 otherwise.
+configured, 401 otherwise — and, since LOGIN_PLAN §3.2, also passes on a
+currently-active session token in the separate X-Session-Token header.
 """
 
 import pytest
 from fastapi import HTTPException
 
+from app.services import sessions
 from app.services.auth import require_pin
 
 
@@ -32,3 +34,43 @@ def test_missing_header_rejected_with_401(self, monkeypatch):
         with pytest.raises(HTTPException) as exc_info:
             require_pin(None)
         assert exc_info.value.status_code == 401
+
+
+class TestRequirePinSessionToken:
+    """The additive half of the check (LOGIN_PLAN §3.2): an active session
+    token counts as a credential, without touching the PIN path above."""
+
+    def test_active_token_passes_without_pin_header(self, monkeypatch):
+        monkeypatch.setattr("app.services.auth.API_PIN", "1234")
+        token = sessions.create_session()
+        assert require_pin(None, token) is None
+
+    def test_stale_or_unknown_token_rejected(self, monkeypatch):
+        monkeypatch.setattr("app.services.auth.API_PIN", "1234")
+        with pytest.raises(HTTPException) as exc_info:
+            require_pin(None, "forged-token")
+        assert exc_info.value.status_code == 401
+
+    def test_empty_token_header_ignored(self, monkeypatch):
+        monkeypatch.setattr("app.services.auth.API_PIN", "1234")
+        with pytest.raises(HTTPException):
+            require_pin(None, "")
+
+    def test_token_survives_after_reset_rejection(self, monkeypatch):
+        """A token issued, then invalidated by a 'restart' (reset), must
+        not keep working — the whole §1 answer-#4 property."""
+        monkeypatch.setattr("app.services.auth.API_PIN", "1234")
+        token = sessions.create_session()
+        sessions.reset()
+        with pytest.raises(HTTPException) as exc_info:
+            require_pin(None, token)
+        assert exc_info.value.status_code == 401
+
+    def test_pin_path_still_works_alongside_token_path(self, monkeypatch):
+        monkeypatch.setattr("app.services.auth.API_PIN", "1234")
+        assert require_pin("1234", None) is None
+        assert require_pin("1234", "even-with-a-token-present") is None
+
+    def test_no_pin_configured_token_irrelevant(self, monkeypatch):
+        monkeypatch.setattr("app.services.auth.API_PIN", "")
+        assert require_pin(None, "anything") is None
diff --git a/tests/unit/test_sessions.py b/tests/unit/test_sessions.py
new file mode 100644
index 0000000..d810a55
--- /dev/null
+++ b/tests/unit/test_sessions.py
@@ -0,0 +1,36 @@
+"""Unit tests for the in-memory session store (app/services/sessions.py).
+
+LOGIN_PLAN §10: create/validate, plus the "restart clears everything"
+rule — simulated here with reset(), which is what a real process exit
+does for free since the store is module-level memory.
+"""
+
+from app.services import sessions
+
+
+class TestSessionStore:
+    def test_created_token_validates(self):
+        token = sessions.create_session()
+        assert isinstance(token, str) and token
+        assert sessions.is_valid(token) is True
+
+    def test_unknown_token_rejected(self):
+        sessions.create_session()
+        assert sessions.is_valid("not-a-token") is False
+
+    def test_none_and_empty_rejected_without_error(self):
+        assert sessions.is_valid(None) is False
+        assert sessions.is_valid("") is False
+
+    def test_tokens_are_distinct_and_opaque(self):
+        first = sessions.create_session()
+        second = sessions.create_session()
+        assert first != second
+        # 256-bit urlsafe tokens: no structural prefix to guess.
+        assert not first.startswith("sess")
+
+    def test_reset_clears_every_issued_token(self):
+        token = sessions.create_session()
+        assert sessions.is_valid(token) is True
+        sessions.reset()
+        assert sessions.is_valid(token) is False