docs(openspec): fpagent-tools-ui change — proposal, specs, design, tasks

Synced main specs (tools-app, fingerprint-wizard); change archived at 2026-09-30-fpagent-tools-ui. Includes openspec project config and the agent skills installed with it.
2026-09-30 23:12:51 +01:00
parent cdb402cd18
commit 109a69961a
35 changed files with 6255 additions and 0 deletions
@@ -0,0 +1,62 @@
+# Proposal: fpagent-tools-ui
+
+## Why
+
+The python server (`app.py`) that served this project's enrollment UI is being
+replaced by the `fpagent` binary (see `fingerprint-agent`), which owns scanner
+capture on `127.0.0.1:9000` and enforces PocketBase + OpenFGA authorization per
+enroll. The UI must be re-modeled onto fpagent's enroll-only event vocabulary
+and YOUreka Auth, or this repo has no reason to exist alongside fpagent.
+
+## What Changes
+
+- **BREAKING**: Add a new Express app in `tools/` that replaces `app.py` as the
+  UI host: a landing page linking two YOUreka tools — Image Cropper
+  (`https://smart-pxa.yrka.app`) and Fingerprint Agent (`/fingerprint`).
+- New `/fingerprint` enrollment wizard (re-modeled from `public/capture/`) that
+  captures via fpagent Socket.IO: `fprint-enroll {token, domain, finger,
+  reference}` → `fprint-enroll-status` → `fprint-enroll-done`, with
+  `fprint-enroll-stop` cancel and `agent-hello` version display.
+- Operator authentication via YOUreka Auth cookie session (portal
+  `/api/web/auth` redirect flow; PocketBase session refresh server-side), same
+  pattern as `one-school-chat`.
+- Domain selection: a hardcoded catalog (UNICAL `uc`, Metropolitan Hotel `mtr`,
+  UCTH `ucth`, UNICAL Radio International `uri`, YOUreka `yrka`) filtered after
+  login against the same public OpenFGA verify URL fpagent uses; only permitted
+  domains are offered. Results are cached per operator for 5 minutes, with an
+  explicit refresh control available once the cache elapses.
+- a2loft integration (staff lookup, fingerprint save) kept, but moved behind
+  same-origin Express proxies; OTP input retained per a2loft call, validated by
+  a2loft exactly as before (`?phone=&otp=`, phone injected server-side).
+- **BREAKING**: Remove the python server and its UI: `app.py`,
+  `requirement.txt`, `public/` (after the new UI reaches parity).
+- clockio mode is not ported: fpagent is enroll-only by design.
+- All configuration is hardcoded in source: port `4173`, portal
+  `https://portal.yrka.app`, PocketBase `https://pb.itcass.net`, a2loft
+  `https://apis.a2loft.net`, agent `http://127.0.0.1:9000`.
+
+## Capabilities
+
+### New Capabilities
+
+- `tools-app`: the Express tools host — landing page, YOUreka Auth cookie
+  session, hardcoded configuration, same-origin a2loft proxies.
+- `fingerprint-wizard`: the `/fingerprint` enrollment wizard — domain
+  permission filtering, fpagent capture wiring, OTP-validated lookup/save flow.
+
+### Modified Capabilities
+
+(none — this repo has no existing specs)
+
+## Impact
+
+- New code: `tools/` (Express app, static pages, auth session module, domain
+  permit module). New dependencies: `express`, `pocketbase`.
+- Removed code: `app.py`, `requirement.txt`, `public/capture/`,
+  `public/clockio/`, `.config.json` handling.
+- Deployment: fpagent must run with `-allowed-origins` including the tools app
+  origin (`http://localhost:4173` in dev); the wizard page calls fpagent
+  cross-origin from the browser.
+- External systems: `portal.yrka.app` (web-auth + OpenFGA verify), `pb.itcass.net`
+  (PocketBase session), `apis.a2loft.net` (staff lookup + fingerprint save, unchanged
+  contract), fpagent on loopback.