Saltar a contenido

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 everything OPERATOR can do) and OPERATOR (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=true and an SSL bundle gives it HTTPS. (origin: agent, confirmed: 2026-10-05)
  • Authentication is a JSON login that opens an HTTP session (HttpOnly, SameSite=Strict cookie, Secure on 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 by ADMIN only. (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.AdminAuthentication is 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

  • [ ] AdminControllersTest walks every admin endpoint and checks anonymous, OPERATOR and ADMIN.
  • [ ] AdminApiIT.s5_*: login, lockout, CSRF, role enforcement and audit against the real database.
  • [ ] AdminListenerSeparationIT and StartupRefusalIT.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 one ADMIN and refuses a second.