A credentials-and-sessions service for the demo environment: Argon2id credential storage, short-lived access tokens, opaque rotating refresh credentials and reuse detection.
Planned · Backend runtime: No deployed runtime — specification stage · Demo data source: Mock
Scope
A backend engineering case study of credential storage, session lifecycle, RBAC and rate limiting for the zolotoy.dev demo environment.
Not in scope
Not enterprise IAM.
Not social login or federated identity.
Not a general OAuth authorization server.
Engineering focus
Session lifecycle, rotation and replay detection, RBAC, rate limiting.
Session lifecycle, rotation and replay detection, RBAC, rate limiting.
Current Implementation
Backend implementation is not present yet. The demo module renders the planned flows with deterministic mock data; the content below is the proposed boundary, not a shipped system.
Current
No backend implementation exists yet: the service is at the specification stage and is represented in the demo by deterministic MSW scenarios only.
Short-lived access tokens in memory on the client; opaque rotating refresh credentials delivered as HttpOnly, Secure, SameSite cookies — never persisted browser storage.
Target auth flow: cookie rotation with reuse detection.
Engineering Decisions
Opaque refresh credentials over JWT refresh tokens
Target design: refresh credentials are opaque server-side records, so revocation is a database write rather than a waiting game with token expiry. Access tokens stay short-lived to bound the revocation gap.
Reuse detection revokes the session family
Target design: a replayed refresh credential is treated as theft evidence. The whole session family is revoked, forcing re-authentication on every device in that family.
Credential enumeration resistance is a response-shape contract
Target design: identical error text, comparable timing and identical status codes for unknown user and wrong password on login and password reset flows.
Reliability / Failure Modes
Concurrent refresh requests
Multiple in-flight refreshes with one credential: exactly one rotation wins; the rest must reuse the coordinator result instead of rotating again and tripping reuse detection.
Reused refresh token
Rotate-on-use means a replayed credential signals theft: revoke the session family, refuse the refresh, and return a distinguishable error so the client can force re-login.
Credential enumeration
Login/register/reset responses must not reveal whether an account exists — same message, same status, similar time profile including hash cost for unknown users.
Redis outage policy
Planned: session lookup must degrade safely (deny or read-through from primary storage) rather than fail open; rate limiting must not silently disappear when Redis is down.
Limits of already-issued JWT revocation
Access tokens cannot be recalled before expiry; revocation only affects refresh. Short access TTL plus server-side session checks for sensitive operations bound the exposure.