zarinpal-analytics-backend/docs/decisions/0014-server-side-merchant-sessions.md

ADR 0014: Use revocable server-side merchant sessions

• Status: Accepted
• Date: 2026-08-20

Context

The merchant dashboard needs simple username/password authentication, strict tenant isolation, logout, account disablement, and authenticated SSE reconnect/replay. Browser-stored JWTs would make immediate revocation and logout enforcement more complex and would expose bearer material to frontend-readable storage if implemented carelessly. A server-side session adds a lookup but keeps authorization state under backend control.

Decision

Use cryptographically random opaque session tokens transported only in host-only Secure, HttpOnly, SameSite=Lax cookies. Store only a non-reversible token digest with server-side session state. Never place authentication tokens in local storage, session storage, URLs, or frontend-readable application state.

Sessions expire after 12 hours of inactivity and no later than seven days after creation. Logout revokes the current session before clearing the cookie; disabling a merchant user revokes every active session for that user. Every protected HTTP request, SSE connection, and replay request resolves the merchant boundary from the current server-side session.

Passwords use Argon2id with unique salts and reviewed parameters. Expected login failures are externally generic. Demo credentials are generated through a one-time administrative workflow, displayed once, and never stored in Git or logs.

Consequences

• Logout, disablement, expiry, and incident response can invalidate access immediately.
• The backend session store is on the protected-request path and must fail closed, be indexed, and have observable latency/availability.
• SSE reconnect and replay must reauthorize instead of trusting a previous connection or event id.
• Scaling API instances does not require sticky sessions when they share the approved authoritative session store.
• Cookie scope, CSRF controls, login throttling, and the physical session-store contract remain explicit Identity-spec decisions rather than implicit framework defaults.