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

Feature Specification: Authentication Hardening

Feature Branch: 013-auth-hardening

Created: 2026-09-07

Status: Draft

Input: User description: "Phase 11 security hardening pass, first slice: password-reset (self-service, with a stubbed email-delivery step logging the reset link instead of actually emailing it), a password-strength policy applied wherever a password is set, and login rate-limiting to slow down credential-stuffing/brute-force attempts against POST /auth/login. MFA is a separate, larger follow-up feature, not this one's scope."

User Scenarios & Testing (mandatory)

User Story 1 - A user resets a forgotten password (Priority: P1)

A user who has forgotten their password requests a reset; the system issues a single-use, short-lived reset token and "delivers" it (this feature stubs delivery — see Assumptions — a later feature wires up real email). The user submits the token with a new password and can log in with it immediately afterward.

Why this priority: 010-identity-auth explicitly deferred this ("the smallest viable fix today is an admin recreating the account") — this is the first real self-service fix for a locked-out user, and the whole reason this feature exists.

Independent Test: Request a reset for a known account; retrieve the issued token (via the stub's own log output, since there's no real inbox to check); consume it with a new password; confirm login succeeds with the new password and fails with the old one.

Acceptance Scenarios:

1. Given an existing account, When its email requests a password reset, Then a single-use reset token is issued and "delivered" via the stub — the response itself never includes the token (it's not a client-visible value, matching a real email-delivery contract).
2. Given an email that doesn't correspond to any account, When it requests a password reset, Then the response is identical to Scenario 1's own success response — never revealing whether the account exists (mirrors 010's own FR-002 philosophy).
3. Given a valid, unexpired reset token, When it's submitted with a new password meeting the password-strength policy (User Story 2), Then the account's password is updated and the token becomes unusable — a second consume attempt with the same token is rejected.
4. Given an expired or already-used reset token, When it's submitted, Then the request is rejected with a clear, specific reason — never silently accepted.
5. Given a freshly-reset password, When the user logs in with it, Then login succeeds; the old password no longer works.

---

User Story 2 - Password strength is enforced wherever a password is set (Priority: P1)

Whenever a password is set — an admin creating a new staff account, or a user resetting their own — the system enforces a minimum strength policy and rejects a weak password with a specific, actionable reason.

Why this priority: 010-identity-auth's own admin-account-creation (POST /admin/users) and this feature's own password-reset both accept a plaintext password with no strength check today — the most basic hardening gap a "security hardening pass" exists to close first.

Independent Test: Attempt to create an account (or reset a password) with a password that fails the policy (too short); confirm a clear rejection naming what's wrong. Repeat with a policy-meeting password; confirm it succeeds.

Acceptance Scenarios:

1. Given the admin account-creation endpoint, When a password shorter than the configured minimum length is submitted, Then the request is rejected with a message naming the actual requirement, not a generic validation error.
2. Given the password-reset consume endpoint, When a policy-violating password is submitted, Then it's rejected the same way — one policy, enforced identically everywhere a password is ever set.
3. Given a password meeting the policy, When it's submitted to either endpoint, Then it's accepted.

---

User Story 3 - Login attempts are rate-limited (Priority: P1)

Repeated login attempts against the same account within a short window are throttled, slowing down credential-stuffing and brute-force attacks without permanently locking out a legitimate user who mistypes their password a few times.

Why this priority: POST /auth/login has no attempt limit today — an attacker can try passwords against a known email address as fast as the network allows. This is the other baseline hardening gap named explicitly in 010-identity-auth's own Assumptions.

Independent Test: Submit repeated failed login attempts for the same email within the configured window; confirm attempts beyond the configured maximum are rejected with a rate-limit response, distinct from an authentication failure; confirm a successful login for a different account is unaffected.

Acceptance Scenarios:

1. Given the configured maximum login attempts per window has been reached for one email, When another attempt is made for that same email within the window, Then it's rejected with a clear rate-limit response (not the identical-failure-response body User Story 1/010 uses for wrong credentials — a rate limit is a different, honestly-reported condition).
2. Given the same exhausted window, When a login attempt is made for a different email, Then it proceeds normally — the limit is per-account, not global.
3. Given the rate-limit window has elapsed, When a new attempt is made for the previously-limited email, Then it's evaluated normally again.

---

Edge Cases

• What happens if a user requests a password reset for the same account multiple times before consuming the first token? Each request issues its own new token; consuming any valid, unexpired one succeeds, and consuming one invalidates all of that account's other outstanding reset tokens (never allowing two guesses to both later succeed independently).
• What happens if a reset token is consumed for an account that was deactivated after the token was issued but before it was used? The reset is rejected — reactivating a deactivated account is an admin action (010's own domain), not something a password-reset flow performs incidentally.
• What happens to a rate-limited login attempt that would have actually succeeded (correct password, but the account is rate-limited from prior failed attempts)? It's still rejected — the rate limit is evaluated before credentials, exactly like a real brute-force defense must be, not skipped for a lucky correct guess.

Requirements (mandatory)

Functional Requirements

• FR-001: The system MUST let a user request a password reset by email, always returning an identical response regardless of whether the email corresponds to an existing account (mirrors 010's FR-002).
• FR-002: The system MUST issue a single-use, time-limited reset token per request, and MUST invalidate a token immediately upon use or upon a newer token being issued for the same account.
• FR-003: The system MUST "deliver" the reset token via a clearly-labeled stub (server-side log output) rather than a real email — this feature does not add email-sending infrastructure (Assumptions).
• FR-004: The system MUST let a user consume a valid reset token with a new password, updating the account's password hash and rejecting an invalid, expired, or already-used token with a specific, distinguishable reason.
• FR-005: The system MUST enforce one configured password-strength policy (at minimum, a minimum length) identically at every point a password is ever set — admin account creation and password-reset consumption alike — never two different or duplicated policies.
• FR-006: The system MUST rate-limit POST /auth/login attempts per submitted email within a configured window, rejecting attempts beyond the configured maximum with a response distinct from a credentials failure.
• FR-007: The login rate limit MUST be evaluated before password verification, so a rate-limited attempt is rejected regardless of whether the submitted password is actually correct.
• FR-008: The system MUST NOT lock an account indefinitely — the rate limit is a rolling/ fixed window that clears on its own, not a manual-unlock-required lockout.

Key Entities

• Password Reset Token: A single-use, time-limited credential tying one request to one account, consumed exactly once to authorize a password change.
• Password Policy: The configured minimum-strength rule(s) applied identically at every password-setting point in the system.
• Login Attempt Counter: A rolling/fixed-window count of failed login attempts per submitted email, backing the rate limit.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 100% of password-reset requests (existing or nonexistent account) receive an identical response — 0% reveal account existence.
• SC-002: 100% of password-reset tokens are usable exactly once; a second consume attempt with the same token fails 100% of the time.
• SC-003: 100% of passwords accepted by any password-setting endpoint meet the configured policy; 0% of policy-violating passwords are ever stored.
• SC-004: An account subjected to more login attempts than the configured maximum within the configured window is rejected on 100% of the excess attempts, regardless of whether the submitted password was correct.

Assumptions

• Email delivery is stubbed, not real — the reset token is logged server-side rather than emailed, per explicit user decision; wiring up a real email provider is a separate, later concern once that infrastructure choice is made.
• MFA is out of scope — a separate, larger follow-up feature; this pass only closes the two gaps 010-identity-auth's own Assumptions named as "not this feature's job."
• No account self-registration — unchanged from 010; password reset only ever applies to an existing account, never creates one.
• The password-strength policy is a minimum-length rule, configurable, not a fixed hardcoded value (docs/10-implementation-roadmap.md's own "never hardcode a placeholder value and ship it as final" instruction) — the exact minimum is a CONFIGURABLE value with a reasonable default, not a business-confirmed final number; additional complexity rules (character classes, breached-password checks) are a possible future enhancement, not required here.
• Rate limiting is per submitted email, not per IP — the most direct defense against credential-stuffing a specific known account; IP-based limiting is a possible future enhancement layered on top, not required here.
• Existing sessions are not force-revoked on password reset — a reset invalidates the password (and all other outstanding reset tokens for that account), but any already-issued, unexpired login session remains valid until its own natural expiry (010's own 4-hour token lifetime bounds this) rather than requiring a database check on every authenticated request (010's own performance goal of a single Redis round trip per request, no DB read).