Design

Architecture

The service is structured around application use cases and explicit ports for storage, security, messaging, and unit-of-work boundaries.

Layering

HTTP handlers
  -> DTO parsing and response mapping
  -> AuthService use cases
  -> Repository / security / messaging ports
  -> Postgres, JWT, bcrypt, SMTP, UUID providers

Core Components

Component Responsibility
AuthService Coordinates sign-up, verification, sign-in, refresh, session revocation, and password changes.
JwtTokenProvider Signs RS256 access and refresh tokens, parses claims, and exposes public JWKS.
SessionRepository Stores refresh-token hashes, token families, expiry, revocation, and replacement links.
EmailOutboxProcessor Claims pending email jobs, sends SMTP messages, and applies retry/dead-letter state.

Token Model

  • Access tokens are RS256 JWTs with short TTL.
  • Refresh tokens are RS256 JWTs delivered through the refresh_token HttpOnly Secure cookie.
  • Only refresh-token hashes are stored in Postgres.
  • Refresh rotates into a new session id while preserving the token family id.
  • Detected refresh-token reuse revokes the whole token family.

Session Semantics

A session is the persisted server-side state that backs both the access token and refresh token lifecycle. Access-token authentication accepts a valid JWT only when the session exists, is not revoked, and is not expired.

Password Change

Password changes verify the current password, validate the new password with the same policy used at sign-up, update the password hash, and revoke all active sessions for the user. The client must sign in again after a successful password change.

Email Verification

Sign-up creates a verification record and writes a pending email job into the outbox in the same transaction. The outbox worker claims jobs with row locking and sends them through SMTP.

Data Ownership

  • users: identity, password hash, verification flags, soft deletion.
  • devices: client device metadata captured during sign-in.
  • sessions: refresh hashes, expiry, revocation, token family, replacement links.
  • email_verifications: verification code hashes and attempt metadata.
  • email_outbox: durable email delivery queue.