89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
# F-083 — Architect: Customers password reset via email link
|
|
|
|
## Goal
|
|
|
|
Secure password reset flow:
|
|
1. Customer enters email → backend always returns 200 (no user enumeration), generates single-use signed token with 1h TTL, stores hash, sends email.
|
|
2. Customer opens email link → storefront form at `/cuenta/restablecer?token=...` submits new password.
|
|
3. Confirm endpoint validates token hash + expiry + unused → updates password hash, marks token used.
|
|
4. Rate limit per IP and per email.
|
|
5. Admin `/customers` row has a "Send reset link" button that triggers the same flow.
|
|
6. Audit log entry for each request and confirm.
|
|
|
|
## Design
|
|
|
|
### Backend
|
|
|
|
**Migration `032_password_reset_tokens.js`**: new table
|
|
```sql
|
|
CREATE TABLE identity_password_reset_tokens (
|
|
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
user_id uuid NOT NULL REFERENCES identity_users(id) ON DELETE CASCADE,
|
|
token_hash text NOT NULL UNIQUE,
|
|
expires_at timestamptz NOT NULL,
|
|
used_at timestamptz,
|
|
request_ip text,
|
|
request_user_agent text,
|
|
created_at timestamptz NOT NULL DEFAULT now()
|
|
);
|
|
CREATE INDEX identity_password_reset_tokens_user_idx ON identity_password_reset_tokens(user_id);
|
|
CREATE INDEX identity_password_reset_tokens_expires_at_idx ON identity_password_reset_tokens(expires_at);
|
|
```
|
|
|
|
**Domain**:
|
|
- `PasswordResetToken` entity with `isExpired()`, `isUsed()`.
|
|
- Errors: `InvalidResetTokenError`, `ExpiredResetTokenError`, `UsedResetTokenError`.
|
|
|
|
**Repository** (`PgPasswordResetTokenRepository`): `create`, `findValidByHash(hash)`, `markUsed(id)`. On create, invalidates all previous unused tokens for that user.
|
|
|
|
**Use cases** (mirror Login/RegisterUser):
|
|
- `RequestPasswordReset({ email, ip, userAgent })`:
|
|
- Normalise email; if user does not exist, return success silently (no enumeration).
|
|
- Invalidate previous unused tokens for that user.
|
|
- Generate cryptographically random token (32 bytes hex → 64 chars), store `hash(token)`.
|
|
- Rate limit: per-IP bucket of 5/hour and per-email bucket of 3/hour. Returns success even when rate-limited (no enumeration).
|
|
- Persist token row with `expires_at = now() + 1h`.
|
|
- Emit `password_reset.requested` audit log entry.
|
|
- Trigger email via `notifications.sendPasswordReset({ email, resetUrl, locale })`.
|
|
- `ConfirmPasswordReset({ token, newPassword })`:
|
|
- Hash incoming token, look up by hash.
|
|
- Reject (HTTP 400) if not found / expired / used → same error code in all cases.
|
|
- Update `users.passwordHash` via `PasswordHasher.hash(newPassword)`.
|
|
- Mark token used.
|
|
- Emit `password_reset.confirmed` audit log.
|
|
|
|
**Routes**:
|
|
```
|
|
POST /auth/password-reset/request { email } -> 200 { ok: true } always
|
|
POST /auth/password-reset/confirm { token, password } -> 200 { ok: true } | 400
|
|
```
|
|
Both are public (no session). Request endpoint should be slow when user not found to equalise timing.
|
|
|
|
### Notifications
|
|
Use existing `notifications.sendEmail` with a new template `password-reset`. Template renders the link with `{{ resetUrl }}`.
|
|
|
|
### Admin
|
|
In `/customers` row, add a button "Enviar enlace de recuperación" that POSTs to `/auth/password-reset/request` with the row's email. Show toast on result.
|
|
|
|
### Storefront
|
|
New page `/cuenta/restablecer` with form for token (from query) + new password + confirm. POSTs to `/auth/password-reset/confirm`.
|
|
|
|
## Risk
|
|
|
|
Medium. Touches auth & email. Mitigations:
|
|
- Tokens are stored as hashes (not raw).
|
|
- Single-use enforcement at DB level (mark used atomically in the same UPDATE that validates expiry).
|
|
- Rate limit prevents brute force / abuse.
|
|
- Always-200 on request prevents user enumeration.
|
|
- Audit log for traceability.
|
|
|
|
## Acceptance mapping
|
|
- "Backend POST /auth/password-reset/request always returns 200" → request handler always 200.
|
|
- "Signed single-use token with TTL ≥30 min ≤24h" → 1h TTL, hash stored.
|
|
- "Email sent with /cuenta/restablecer?token=..." → notifications.sendPasswordReset.
|
|
- "POST /auth/password-reset/confirm rejects invalid/expired/used" → 400 from use case.
|
|
- "New password works for login" → users.passwordHash updated.
|
|
- "Admin row action triggers same flow" → POST /auth/password-reset/request.
|
|
- "Rate limit per IP and per email" → dual-bucket limiter.
|
|
- "Audit log entries" → security_audit_log rows on request and confirm.
|
|
- "verify.sh is green" → typecheck + lint + tests. |