ADR-005 — Admin listener and console authentication¶
Status¶
Accepted in part. The human decided on 2026-10-04: users are the console's own, stored in the database with an adaptive
password hash, and there are two roles, ADMIN (everything) and OPERATOR (read-only search and trail). Every line marked
(origin: agent) below is a design choice of the agent that the human has not confirmed yet: confirm it or change it. All agent items below were confirmed by the human on 2026-10-05; Argon2id stays deferred (keep BCrypt).
Context¶
- S5 adds an administration console (merchant hierarchy, users, payment search and trail, dashboard, audit) to a gateway whose other two surfaces are the POS API (VPN side, ADR-004) and the Prisma callbacks (public HTTPS, apikey, ADR-004).
- The money path must never depend on the console: no session, no login, no admin table is read to answer the POS or Prisma (INV-03: a callback is always accepted).
- The console can read card-adjacent data (the payment trail) and change which merchants may sell, so who can reach it and who can log in are security decisions, not features.
- No identity provider exists at Almacor; the gateway runs as a Windows service next to SQL Server.
Alternatives¶
| Option | Pros | Cons |
|---|---|---|
| Own users in the database, adaptive hash (chosen, human) | No new infrastructure; works offline; one audit trail | The gateway owns password handling: policy, lockout, reset |
| Basic auth with one shared secret in configuration | Trivial | No individual accountability; no roles; the audit cannot say who |
| OIDC / the company directory | Central control, no passwords stored | Needs an identity provider that does not exist; the console would stop working when it is down |
| Reverse proxy with its own login | Nothing to build | Another component to install and secure; roles and audit are lost |
Decision¶
Decided by the human (2026-10-04):
- The console has its own users, stored in the database (
admin_user), with an adaptive password hash (the algorithm and its cost can change without a migration). - Two roles:
ADMIN(the configuration, the users, the audit, and everythingOPERATORcan do) andOPERATOR(read-only: payment search and trail, and the dashboard).
Design items of the agent, each one to be confirmed or changed by the human:
- A third connector for
/admin/**(the console's files and/admin/api/v1/**), separate from the POS and callbacks connectors; the listener separation filter serves each port only its own paths. (origin: agent, confirmed: 2026-10-05) - The admin connector binds to loopback by default; a non-loopback address is refused at startup unless
gateway.admin.allow-remote=trueand an SSL bundle gives it HTTPS. (origin: agent, confirmed: 2026-10-05) - Authentication is a JSON login that opens an HTTP session (
HttpOnly,SameSite=Strictcookie,Secureon HTTPS, idle timeout of 30 minutes, session id changed at login); every request re-reads the user, so a disabled user or a changed role applies at once. (origin: agent, confirmed: 2026-10-05) - CSRF protection by cookie plus header on every state-changing request, the login included. (origin: agent, confirmed: 2026-10-05)
- Lockout after 5 wrong passwords in a row for 15 minutes, per user, judged by database time; one error for an unknown user, a wrong password, a disabled user and a locked one. (origin: agent, confirmed: 2026-10-05)
- The first ADMIN comes from a one-shot command (password from an environment variable or a prompt, never a flag) that refuses to run when any ADMIN exists; there is no default user or password. (origin: agent, confirmed: 2026-10-05)
- Every write of the console is audited in the same transaction as the write (
admin_audit: who, what, when, before and after as JSON, never a password, hash or apikey); the audit is read in the console byADMINonly. (origin: agent, confirmed: 2026-10-05) - The password hash is BCrypt (cost 12) for now, behind a delegating format so that Argon2id can replace it later with a rehash at login; Argon2id waits for a dependency decision (D-S5-4). (origin: agent, confirmed: 2026-10-05)
Consequences¶
- The gateway is responsible for password handling; the policy (12 to 72 bytes), the lockout and the reset are code it must keep correct.
- Sessions live in the memory of one node (D-S5-7): with two nodes the operator logs in on one of them.
- Lockout per user lets someone who can reach the port lock a known user out (D-S5-3); the loopback default and the firewall are the defence.
- A reverse proxy on the same host would pass the loopback check (D-S5-8): not part of this design.
- Roles are two and fixed; a third role is a code change.
Implementation Plan¶
application.admin.AdminAuthenticationis the one seam for login, lockout, password change and session revalidation; the web adapter only turns its answer into a session.config/AdminListener(third connector and its startup refusals),ListenerSeparationFilter,adapter.in.admin.AdminSecurityConfiguration(Spring Security for/admin/**only, roles by method and path).- Plain JDBC behind ports (
AdminUsers,AdminAudit,ConfigurationStore,PaymentQueries); no JPA entity. - Documentation: docs/CONVENTIONS.md section 12 and docs/RUNBOOK.md (bootstrap, listener, console build).
Verification¶
- [ ]
AdminControllersTestwalks every admin endpoint and checks anonymous,OPERATORandADMIN. - [ ]
AdminApiIT.s5_*: login, lockout, CSRF, role enforcement and audit against the real database. - [ ]
AdminListenerSeparationITandStartupRefusalIT.s5_*: each port serves only its paths; a non-loopback address without HTTPS does not start. - [ ]
AdminTlsIT: HTTPS on the admin connector. - [ ]
AdminBootstrapIT: the one-shot command creates oneADMINand refuses a second.