tools-legacy/README.md

YOUreka Tools — Fingerprint Service

A small Express app that hosts the YOUreka tools landing page and the Fingerprint Agent enrollment wizard. Fingerprint capture is performed by the local fpagent binary (Socket.IO on 127.0.0.1:9000); this app provides the login (YOUreka Auth), the permitted domain selection, and the a2loft integration that stores the enrolled fingerprints.

Layout

tools/
├── server.js               # Express app: routes, session middleware, proxies
├── yrka-auth.js            # YOUreka Auth cookie session → PocketBase (authRefresh)
├── permit.js               # OpenFGA domain permission checks + 5-minute cache
├── public/
│   ├── index.html          # landing page (Image Cropper + Fingerprint Agent)
│   └── assets/
│       ├── style.css
│       └── fp/             # /fingerprint enrollment wizard (Vue 2 via CDN)
└── test/                   # node --test suite (fake portal / PocketBase / a2loft)

Running

Prerequisites: Node.js 22+, fpagent installed and running on this laptop (see the fingerprint-agent repository for installation), the U.are.U 4500 scanner attached.

cd tools
npm install
npm start          # → http://localhost:4173

Open http://localhost:4173 and sign in with your YOUreka account.

fpagent must allow the tools origin. On a dev machine run it with: fpagent -allowed-origins http://localhost:4173

How enrollment works

1. Sign in — YOUreka Auth (portal web-auth redirect). The PocketBase session is kept in an httpOnly cookie and refreshed server-side.
2. Pick a domain — the hardcoded catalog (UNICAL, Metropolitan Hotel, UCTH, UNICAL Radio International, YOUreka) is filtered against the same portal OpenFGA endpoint fpagent uses (capture_biometric per domain). Results are cached for 5 minutes; the Refresh domains control unlocks once the cache expires. fpagent re-authorizes every capture regardless.
3. Locate the staff profile — reference + OTP, validated by apis.a2loft.net through a same-origin proxy (the operator's phone comes from the session).
4. Capture — right thumb and right index finger, one capture at a time, with per-scan progress and cancel; the PocketBase token, domain and reference travel with every fprint-enroll to fpagent.
5. Save — both templates are posted to a2loft (with a fresh OTP).

Configuration

Everything is hardcoded in tools/server.js by design — port 4173, portal https://portal.yrka.app, PocketBase https://pb.itcass.net, a2loft https://apis.a2loft.net, agent http://127.0.0.1:9000, and the domain catalog. Change them there; there are no environment variables or config files.

Tests

cd tools
npm test           # node --test — 27 tests, no network or hardware required

Docker

The app is stateless, so the container only serves the web front-end; fpagent keeps running on the operator's laptop (the wizard connects to http://127.0.0.1:9000 from the browser, wherever this container lives).

docker build -t yreka-tools .
docker run -d -p 4173:4173 --name yreka-tools yreka-tools

Behind a TLS-terminating proxy the app honours X-Forwarded-Proto (trust proxy is enabled), so session cookies get the Secure flag automatically.

Field walkthrough (real portal, PocketBase, a2loft, and U.are.U 4500): login → permitted-domain filtering → staff lookup → two scanner captures with cancel path → save → reset, all verified end to end via Playwright.