support_backend/specs/013-auth-hardening/research.md

# Research: Authentication Hardening

## Decision: reset tokens live only in Redis, as a paired key shape, never in Postgres

- **Decision**: A random 32-byte token (`crypto.randomBytes(32).toString('hex')`) is generated
  per request; only its SHA-256 hash is ever stored (the raw token is returned to the caller of
  `requestPasswordReset` for the stub-delivery step to log, then discarded). Two Redis keys per
  active token, both with the same TTL (the reset lifetime):
  - `password-reset:token:<hash>` → `userId` (resolves a presented token at consume time)
  - `password-reset:user:<userId>` → `hash` (lets issuing a new token find and delete the prior
    one's `token:` key, invalidating it — FR-002)
- **Rationale**: Storing only the hash (never the raw token) mirrors this codebase's own
  password-hashing discipline (010's `hashPassword`) and 002's encrypted-credential-at-rest
  precedent — a Redis compromise alone shouldn't hand over usable reset tokens. The paired-key
  shape gets "only one active token per account" (FR-002) without a database table or a list
  scan; it's the same Redis-key-with-TTL pattern 010's own revocation denylist and 002's jti
  replay-guard already established, not a new pattern for this codebase.
- **Alternatives considered**: A signed JWT with a `purpose: 'password-reset'` claim — rejected;
  a JWT can't be "invalidated by issuing a new one" without also tracking issued tokens
  somewhere (defeating the point of using a stateless token), so it would need the same Redis
  bookkeeping anyway while adding JWT-parsing overhead for no benefit. A Postgres table — works,
  but adds a migration and a cleanup/expiry job for data Redis's own TTL already expires for
  free; rejected as unnecessary durability for a short-lived, non-audit-relevant credential.

## Decision: the "delivery" stub is a structured log line, not a fake email object

- **Decision**: `requestPasswordReset` logs `{ event: 'password_reset_requested', userId,
  resetUrl }` at `info` level via the existing Pino logger — no new "mock email" abstraction,
  no `EmailService` interface to later swap out.
- **Rationale**: Per the user's own explicit choice (stub delivery, not real email), the
  simplest honest stub is exactly what a developer needs during this phase: the token, visible
  in the same place every other structured log already goes. Building a fake `EmailService`
  interface now, before any real provider is chosen, would be speculative abstraction for a
  contract nobody has decided yet (which provider, which template).
- **Alternatives considered**: A dedicated `EmailService`/`NotificationService` interface with a
  console/log implementation, swapped for a real one later — rejected as premature
  infrastructure for a single call site; revisit when a real provider is actually chosen (a
  separate, later decision per spec.md Assumptions).

## Decision: one shared `validatePasswordStrength`, minimum length only, `PASSWORD_MIN_LENGTH`-configured

- **Decision**: `identity/auth/mapper/password-policy.ts` exports
  `validatePasswordStrength(password: string): void`, throwing `ValidationError` naming the
  actual requirement (e.g. "Password must be at least N characters.") if `password.length <
  env.PASSWORD_MIN_LENGTH`. Called from both `AuthService`'s new `resetPassword` and
  `identity/agents`'s existing `UsersService.create`.
- **Rationale**: FR-005 requires one policy enforced identically everywhere a password is set —
  a shared function is the only way to guarantee that rather than trusting two call sites to
  stay in sync by convention. Minimum length only (no character-class rules) matches current
  NIST guidance (length matters far more than forced complexity) and spec.md's own explicit
  scope boundary.
- **Alternatives considered**: A zod `.refine()` embedded separately in each schema — rejected;
  duplicates the rule text and the minimum-length constant at two call sites, exactly the drift
  FR-005 exists to prevent.

## Decision: login rate-limit reuses the existing `checkRateLimit` helper, keyed by email

- **Decision**: `AuthService.login` calls
  `checkRateLimit(`login:${email}`, env.LOGIN_RATE_LIMIT_MAX_ATTEMPTS,
  env.LOGIN_RATE_LIMIT_WINDOW_SECONDS)` as its very first step, before `repo.findByEmail` or
  `verifyPassword` — throwing `RateLimitError` (already a distinct error/status from
  `AuthenticationError`, per the existing `common/errors`) if exceeded.
- **Rationale**: `checkRateLimit` (`src/infrastructure/cache/rate-limiter.ts`) already exists,
  already used by 002's own inbound-request rate limiting, and is exactly the fixed-window
  Redis-`INCR` shape this feature needs — reusing it is the literal instruction 010's own
  Assumptions gave ("beyond what 002's existing generic rate-limit infrastructure might already
  cover"). Keying by the *submitted* email (not a resolved user id) means the limiter runs
  identically whether or not the account exists, so it can't itself become a second
  account-existence oracle.
- **Alternatives considered**: `@fastify/rate-limit`'s own global plugin (already registered,
  1000 req/min) — insufficient on its own; that's a blunt per-IP-or-global HTTP-level limit, not
  a per-account brute-force defense, and 010's own Assumptions already anticipated needing
  something more targeted for login specifically.

## Decision: `POST /admin/users` gets the shared validator via a one-line call-site change

- **Decision**: `UsersService.create` calls `validatePasswordStrength(body.password)` before
  hashing, right alongside its existing duplicate-email check — no schema change, no new route.
- **Rationale**: FR-005's "identically everywhere" requirement includes this pre-existing
  010 endpoint, which today accepts any non-empty string as a password. Minimal, surgical fix
  at the one call site that needed it.
- **Alternatives considered**: None — this is the only other password-setting call site in the
  codebase (confirmed by searching for every `hashPassword(` call).