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.
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
# fingerprint-wizard Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
The Fingerprint Agent enrollment wizard at `/fingerprint`: offers the operator
|
||||
only the domains they may capture for, runs two-finger enrollment through the
|
||||
local fpagent capture agent, and saves the resulting templates to a2loft with
|
||||
per-call OTP validation.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Permitted domain selection
|
||||
The wizard SHALL offer, from the hardcoded catalog — UNICAL (`uc`),
|
||||
Metropolitan Hotel (`mtr`), UCTH (`ucth`), UNICAL Radio International (`uri`),
|
||||
YOUreka (`yrka`) — only the domains the operator is permitted to capture for.
|
||||
Permission SHALL be determined after login against the same public portal
|
||||
OpenFGA verify endpoint fpagent uses (`https://portal.yrka.app/api/openfga/verify`),
|
||||
requesting the `capture_biometric` relation for `domain:<code>` on subsystem
|
||||
`idid` for the operator's phone (leading `+` stripped), with a fallback check
|
||||
against `domain:idid`; the operator is permitted if either check allows. Each
|
||||
domain's checks SHALL fail closed on error or denial. Catalog checks SHALL run
|
||||
in parallel, and their results SHALL be cached per operator phone for 5
|
||||
minutes: session fetches within that window SHALL serve the cached result
|
||||
without contacting the portal, and all catalog domains SHALL be re-checked in
|
||||
parallel once that period expires.
|
||||
|
||||
#### Scenario: Permitted domain is offered
|
||||
- **WHEN** the portal verify endpoint allows the operator for a catalog
|
||||
domain
|
||||
- **THEN** that domain appears in the wizard's domain selection
|
||||
|
||||
#### Scenario: Denied or unavailable domain is hidden
|
||||
- **WHEN** the portal verify endpoint denies a domain, or the check errors
|
||||
- **THEN** that domain is not offered
|
||||
|
||||
#### Scenario: Fallback object allows capture
|
||||
- **WHEN** the `domain:<code>` check denies but the `domain:idid` check
|
||||
allows
|
||||
- **THEN** the domain is offered
|
||||
|
||||
#### Scenario: Cached result within the TTL
|
||||
- **WHEN** a session fetch occurs within 5 minutes of the last permission
|
||||
check for the operator
|
||||
- **THEN** the cached permitted-domain list is served without calling the
|
||||
portal verify endpoint
|
||||
|
||||
#### Scenario: Re-check after the TTL
|
||||
- **WHEN** a session fetch occurs after the 5-minute cache period has
|
||||
elapsed
|
||||
- **THEN** all catalog domains are re-checked and the list reflects current
|
||||
permissions
|
||||
|
||||
#### Scenario: No permitted domains
|
||||
- **WHEN** no catalog domain is permitted for the operator
|
||||
- **THEN** the wizard explains they are not permitted to capture
|
||||
fingerprints for any domain and offers no capture UI
|
||||
|
||||
### Requirement: Manual refresh of permitted domains
|
||||
The wizard SHALL offer a refresh control for the permitted-domain list that
|
||||
stays disabled until the 5-minute cache period since the last check has
|
||||
elapsed. Using it SHALL call the app's force-refresh endpoint, update the
|
||||
offered domains, and update the displayed last-checked time; a refresh
|
||||
refused because the cache is still fresh SHALL leave the current list and
|
||||
state unchanged.
|
||||
|
||||
#### Scenario: Refresh control locked while the cache is fresh
|
||||
- **WHEN** fewer than 5 minutes have passed since the permitted-domain set
|
||||
was last checked
|
||||
- **THEN** the refresh control is disabled
|
||||
|
||||
#### Scenario: Refresh after the cache elapses
|
||||
- **WHEN** the cache period has elapsed and the operator uses the refresh
|
||||
control
|
||||
- **THEN** the wizard calls the force-refresh endpoint and the offered
|
||||
domains update to the re-checked result
|
||||
|
||||
#### Scenario: Refused refresh leaves state unchanged
|
||||
- **WHEN** a refresh request is refused because the cache is still fresh
|
||||
- **THEN** the wizard keeps the current domain list and selection
|
||||
|
||||
### Requirement: Enrollment captures via fpagent
|
||||
The wizard SHALL capture fingerprints through fpagent at the URL provided by
|
||||
the session endpoint, emitting `fprint-enroll` with the session's PocketBase
|
||||
token, the selected domain code, the finger name, and the staff reference. It
|
||||
SHALL display capture progress from `fprint-enroll-status` events, record the
|
||||
returned fingerprint template, image, and enrollment id on
|
||||
`fprint-enroll-done` with `ok: true`, and surface the failure message and
|
||||
return to idle on `ok: false`. The wizard SHALL offer cancellation of an
|
||||
in-flight capture (emitting `fprint-enroll-stop`), SHALL prevent starting a
|
||||
capture while another is in flight (fpagent serves one enrollment at a time),
|
||||
and SHALL display the agent version reported on connect.
|
||||
|
||||
#### Scenario: Successful capture
|
||||
- **WHEN** the operator starts a capture for a finger and fpagent reports
|
||||
`fprint-enroll-done` with `ok: true`
|
||||
- **THEN** the wizard records the fingerprint, image, and enrollment id for
|
||||
that finger and displays the enrollment id
|
||||
|
||||
#### Scenario: Failed capture
|
||||
- **WHEN** fpagent reports `fprint-enroll-done` with `ok: false`
|
||||
(authentication failed, authorization unavailable, not authorized, or
|
||||
capture failed)
|
||||
- **THEN** the wizard shows the failure message and returns to the idle
|
||||
state without recording artifacts
|
||||
|
||||
#### Scenario: Cancel in-flight capture
|
||||
- **WHEN** the operator cancels a capture in progress
|
||||
- **THEN** the wizard emits the stop event and returns to the idle state
|
||||
|
||||
#### Scenario: No concurrent captures
|
||||
- **WHEN** a capture is in flight
|
||||
- **THEN** the capture controls for both fingers are disabled until it
|
||||
completes or is cancelled
|
||||
|
||||
### Requirement: Two-finger enrollment flow
|
||||
The wizard SHALL enroll a profile by: selecting a permitted domain, looking
|
||||
up staff by reference (OTP-validated through the a2loft proxy), displaying
|
||||
the staff details, capturing the right thumb and right index finger, and
|
||||
saving both fingerprints through the a2loft proxy with an OTP. The wizard
|
||||
SHALL offer per-finger recapture until save, SHALL require both fingers
|
||||
before save, and SHALL reset domain-independent state (reference, staff
|
||||
details, captured artifacts) when starting a new enrollment.
|
||||
|
||||
#### Scenario: Complete enrollment
|
||||
- **WHEN** the operator looks up staff, captures both fingers, and saves
|
||||
with an OTP
|
||||
- **THEN** both fingerprints are saved through the a2loft proxy and the
|
||||
wizard reports success
|
||||
|
||||
#### Scenario: Save requires both fingers
|
||||
- **WHEN** the operator attempts to save with only one finger captured
|
||||
- **THEN** the wizard rejects the save and explains both fingers are
|
||||
required
|
||||
|
||||
#### Scenario: New enrollment resets state
|
||||
- **WHEN** the operator starts a new enrollment after a save
|
||||
- **THEN** the reference, staff details, and captured finger artifacts are
|
||||
cleared while the permitted domain list persists
|
||||
|
||||
### Requirement: OTP validated on every a2loft call
|
||||
The wizard SHALL collect an OTP for each a2loft call — staff lookup and
|
||||
fingerprint save — and pass it to the same-origin proxy; a2loft validates it.
|
||||
Submission SHALL be blocked while the OTP is missing.
|
||||
|
||||
#### Scenario: Lookup with OTP
|
||||
- **WHEN** the operator submits a reference with an OTP
|
||||
- **THEN** the wizard calls the staff-lookup proxy with that OTP and
|
||||
displays the returned staff details
|
||||
|
||||
#### Scenario: Save requires a fresh OTP
|
||||
- **WHEN** the operator saves the captured fingerprints
|
||||
- **THEN** the wizard sends the OTP entered for the save call
|
||||
|
||||
#### Scenario: Missing OTP blocks submission
|
||||
- **WHEN** the OTP field is empty for a lookup or save
|
||||
- **THEN** the corresponding submit control is disabled
|
||||
@@ -0,0 +1,129 @@
|
||||
# tools-app Specification
|
||||
|
||||
## Purpose
|
||||
|
||||
Host the YOUreka tools web front-end: a landing page linking the Image Cropper
|
||||
and the Fingerprint Agent wizard, YOUreka Auth cookie-session login, and
|
||||
same-origin proxies to the a2loft identity API so browser calls never carry
|
||||
operator credentials directly to third parties.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Landing page links the YOUreka tools
|
||||
The app SHALL serve a landing page at `/` containing links to the Image
|
||||
Cropper (`https://smart-pxa.yrka.app`) and to the Fingerprint Agent page
|
||||
(`/fingerprint`).
|
||||
|
||||
#### Scenario: Landing page renders both tool links
|
||||
- **WHEN** a user opens the app root URL
|
||||
- **THEN** the page shows a link to the Image Cropper pointing at
|
||||
`https://smart-pxa.yrka.app` and a link to `/fingerprint`
|
||||
|
||||
### Requirement: YOUreka Auth login establishes a cookie session
|
||||
The app SHALL authenticate operators through the YOUreka portal web-auth
|
||||
flow: create a web auth session at the portal with a local callback URL,
|
||||
redirect the operator to the portal's login URL, and on callback redeem the
|
||||
returned session id for a PocketBase session cookie. The app SHALL persist
|
||||
the PocketBase cookie value under its own httpOnly `session` cookie (30-day
|
||||
max age) together with the operator's profile (first name, last name,
|
||||
phone).
|
||||
|
||||
#### Scenario: Successful login round-trip
|
||||
- **WHEN** the operator completes the portal login and returns with a
|
||||
redeemable session id
|
||||
- **THEN** the app sets the `session` and profile cookies and redirects to
|
||||
`/fingerprint`
|
||||
|
||||
#### Scenario: Expired or rejected login link
|
||||
- **WHEN** the callback session id cannot be redeemed (expired, timed out,
|
||||
or incomplete verification)
|
||||
- **THEN** the app shows an authentication error and does not set a session
|
||||
cookie
|
||||
|
||||
### Requirement: Session persistence and refresh
|
||||
The app SHALL recover the operator's PocketBase session from the `session`
|
||||
cookie on every request, refreshing the token when it is invalid or expires
|
||||
within 5 minutes, and SHALL persist the refreshed cookie value. When the
|
||||
session cannot be recovered, the app SHALL treat the operator as anonymous
|
||||
and clear the stale cookie.
|
||||
|
||||
#### Scenario: Refresh near expiry
|
||||
- **WHEN** a request arrives with a session cookie whose token expires
|
||||
within 5 minutes and the portal accepts a refresh
|
||||
- **THEN** the app serves the request with the refreshed token and updates
|
||||
the `session` cookie
|
||||
|
||||
#### Scenario: Unrecoverable session
|
||||
- **WHEN** the stored token is expired and refresh fails
|
||||
- **THEN** the request is treated as anonymous and the stale cookie is
|
||||
cleared
|
||||
|
||||
### Requirement: Protected pages require a session
|
||||
The app SHALL redirect anonymous operators to the login flow when they
|
||||
request the Fingerprint Agent page, and SHALL return an authentication
|
||||
error for session-requiring API calls made without a session.
|
||||
|
||||
#### Scenario: Anonymous access to the wizard page
|
||||
- **WHEN** an operator without a valid session requests `/fingerprint`
|
||||
- **THEN** the app redirects them to the login flow
|
||||
|
||||
### Requirement: Session endpoint exposes capture context
|
||||
The app SHALL expose a session endpoint that, for an authenticated
|
||||
operator, returns the current PocketBase token, the operator's phone and
|
||||
name, the fpagent URL, the list of permitted domains (see the
|
||||
fingerprint-wizard capability for the checking and caching rules), and the
|
||||
time that set was last checked.
|
||||
|
||||
#### Scenario: Authenticated session fetch
|
||||
- **WHEN** an authenticated operator fetches the session endpoint
|
||||
- **THEN** the response includes their token, phone, name, the fpagent URL,
|
||||
the permitted domains, and the time the set was last checked
|
||||
|
||||
### Requirement: Forced domain re-check endpoint
|
||||
The app SHALL provide a force-refresh endpoint that, for the authenticated
|
||||
operator, re-checks every catalog domain against the portal verify endpoint
|
||||
bypassing the cache, replaces the cached result, and returns the updated
|
||||
permitted-domain list with the new last-checked time. It SHALL refuse the
|
||||
request while the 5-minute cache is still fresh, without contacting the
|
||||
portal.
|
||||
|
||||
#### Scenario: Force-refresh after the cache elapses
|
||||
- **WHEN** the cache period has elapsed and the operator's client calls the
|
||||
force-refresh endpoint
|
||||
- **THEN** every catalog domain is re-checked, the cache is replaced, and
|
||||
the response carries the updated list and last-checked time
|
||||
|
||||
#### Scenario: Force-refresh refused while the cache is fresh
|
||||
- **WHEN** the force-refresh endpoint is called within 5 minutes of the
|
||||
last check
|
||||
- **THEN** the request is refused with an error and no portal calls are
|
||||
made
|
||||
|
||||
### Requirement: a2loft proxies inject operator identity
|
||||
The app SHALL proxy staff lookup and fingerprint-save calls to
|
||||
`https://apis.a2loft.net` under same-origin API routes. The proxy SHALL
|
||||
attach the operator's phone from the server-side session and forward the
|
||||
OTP supplied by the page as query parameters (`phone`, `otp`), preserving
|
||||
the a2loft request and response shapes. The proxies SHALL require a
|
||||
session; the OTP SHALL NOT be accepted without one.
|
||||
|
||||
#### Scenario: Staff lookup via proxy
|
||||
- **WHEN** the page requests staff details for a domain and reference with
|
||||
an OTP
|
||||
- **THEN** the app calls a2loft's identity endpoint with the operator's
|
||||
phone from the session and the supplied OTP, and returns a2loft's
|
||||
response unchanged
|
||||
|
||||
#### Scenario: Unauthenticated proxy call rejected
|
||||
- **WHEN** a proxy route is called without a valid session
|
||||
- **THEN** the app rejects the call without contacting a2loft
|
||||
|
||||
### Requirement: Configuration is hardcoded
|
||||
The app SHALL hardcode all configuration in source: port `4173`, portal
|
||||
`https://portal.yrka.app`, PocketBase `https://pb.itcass.net`, a2loft
|
||||
`https://apis.a2loft.net`, and agent `http://127.0.0.1:9000`. There SHALL
|
||||
be no runtime configuration via environment variables or config files.
|
||||
|
||||
#### Scenario: No configuration required to run
|
||||
- **WHEN** the app is started with no environment variables or config files
|
||||
- **THEN** it serves on port 4173 with the hardcoded external endpoints
|
||||
Reference in New Issue
Block a user