tools-legacy/openspec/changes/archive/2026-09-30-fpagent-tools-ui/design.md

# Design

## Context

`app.py` (Flask + python-socketio) serves the UI from `public/{mode}` and talks
to libfprint via PyGObject; fpagent replaces the capture side entirely with a
guarded Socket.IO server on `127.0.0.1:9000` (enroll-only: `fprint-enroll`,
`fprint-enroll-status`, `fprint-enroll-done`, `fprint-enroll-stop`,
`agent-hello`). The YOUreka Auth pattern is proven in `one-school-chat`
(`src/lib/server/yrka-auth.ts` + `routes/login/+page.server.ts`): portal
`POST /api/web/auth` → redirect → `GET /api/web/auth/{sessionId}/cookie` →
store the PB cookie value under an httpOnly `session` cookie → PocketBase SDK
`authRefresh()` when near expiry. fpagent's permit logic
(`internal/permit/permit.go`) defines the OpenFGA check this app replicates for
domain filtering. See proposal.md for motivation and scope.

## Goals / Non-Goals

**Goals:**
- Zero-configuration operation: every URL and the port hardcoded in source.
- Smallest reliable stack: Express + static CDN pages, no build step, no
  session store, no template engine.
- Credentials stay server-side where possible: a2loft calls proxied same-origin
  with phone injected from the session; only the PocketBase token is handed to
  the page (fpagent's contract requires the page to emit it).

**Non-Goals:**
- clockio/identify/verify (fpagent is enroll-only by design).
- TypeScript, bundlers, component frameworks, server-side templating.
- Permission caching or a domain-management UI (catalog is hardcoded).
- Changes to a2loft's API contract or fpagent itself.

## Decisions

1. **Static CDN front-end, no build step.** The existing `public/capture` page
   is Vue 2 + Bootstrap 4 + socket.io + axios via CDN; the wizard reuses that
   stack unchanged in shape. Alternative (SvelteKit like one-school-chat)
   rejected: new toolchain in this repo for one page.
2. **Session = PB cookie value in an httpOnly cookie; no server store.** Same
   as one-school-chat; any instance can serve any request, and refresh happens
   server-side per request via the PocketBase SDK against `pb.itcass.net`.
   Alternative (express-session + store) rejected: nothing server-side needs
   more than the cookie already carries.
3. **Token delivery via `GET /auth/session` JSON** rather than templating: the
   wizard is a static page; one fetch returns token, profile, agent URL, and
   permitted domains. The token must live in the page because fpagent's
   `fprint-enroll` requires it — that is the agent's designed flow, and fpagent
   re-validates it per request.
4. **Domain filtering server-side, parallel, fail-closed, cached 5 min.**
   Five domains × ≤2 sequential verify calls each, run with `Promise.all`
   per (re)check; results cached in an in-memory `Map<phone, {allowed,
   checkedAt}>` with a 5-minute TTL (one constant, matching the session
   refresh buffer). `/auth/session` serves the cached set within the TTL;
   a force-refresh endpoint re-checks all catalog domains, bypassing and
   then replacing the cache, and is refused while the cache is fresh. The
   filter is UX only; fpagent re-enforces at enroll time, so a revoked
   permission degrades gracefully (enroll rejected) even mid-session, and
   the wizard's refresh control covers the residual staleness window.
5. **a2loft behind same-origin proxies.** The page calls
   `POST /api/:domain/staff/:reference` (lookup) and
   `POST /api/:domain/staff/:reference/fingerprints` (save); the server
   attaches `phone` from the session and forwards the page-supplied `otp` as
   query params — a2loft's contract (`?phone=&otp=`, same response shapes) is
   untouched. This keeps the operator's a2loft credential flow out of
   page-to-third-party calls and lets the phone come from the trusted session.
6. **Hardcoded config incl. port 4173.** Moving an endpoint or the port is a
   one-constant source change; env-var plumbing is unused flexibility.
7. **Python retirement in the same change, gated on a parity walkthrough.**
   `app.py` + `requirement.txt` + `public/` are deleted only after the new
   wizard completes a real capture-and-save round trip; git history preserves
   them. Rollback = revert.

## Risks / Trade-offs

- [a2loft auth contract drifts (no longer `?phone=&otp=`)] → only the two
  proxy handlers change; page and specs unaffected.
- [Revoked permission lingers in the UI up to 5 minutes] → bounded by the
  cache TTL; fpagent re-enforces at enroll, and the wizard's refresh control
  (enabled once the cache elapses) re-checks on demand.
- [Port 4173 already in use on a laptop] → deliberate hardcode; change the one
  constant (and fpagent's `-allowed-origins`) if a machine conflicts.
- [Browser → `http://127.0.0.1:9000` blocked as mixed content] → loopback is a
  potentially trustworthy origin in all current browsers; works from both http
  and https pages. Watch for corporate-policy exceptions in the field.
- [CORS misconfig blocks the wizard silently] → README documents the fpagent
  `-allowed-origins` requirement (`http://localhost:4173` in dev); wizard shows
  connection state from `agent-hello` so an unreachable/blocked agent is
  visible.
- [Vue 2 is EOL] → acceptable for an internal tool page already on it; the
  page is isolated and small.

## Migration Plan

1. Build `tools/` alongside the untouched python app (different port; no
   interference).
2. Parity walkthrough on field hardware: login → domain filter → lookup →
   capture ×2 → save; fingerprints verify against a2loft as before.
3. Delete `app.py`, `requirement.txt`, `public/`; update README.
4. Deploy note: fpagent must include the tools origin in `-allowed-origins`.

## Open Questions

None — a2loft's contract (unchanged, `?phone=&otp=`), hardcoded endpoints, and
the domain catalog were all confirmed with the operator.