feat(F-083): completed feature

work/artifacts/F-083/architect.md

@@ -0,0 +1,89 @@
+# 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.