Files

T

adebisi-fa 109a69961a 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

3.1 KiB

Raw Permalink Blame History

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.

3.1 KiB Raw Permalink Blame History