docs(auth): add password security hardening plan and code markers

SECURITY_PASSWORD_PLAN.md

@@ -0,0 +1,77 @@
+# Password Security Hardening Plan
+
+## Scope
+- Applies to auth and password flows in:
+  - `index.js`
+  - `auth/authEmail.js`
+  - `mongoDB.js`
+
+## 1. Replace insecure reset flow with token-based reset
+- Problem:
+  - Current flow resets by username and emails a plaintext temporary password.
+- Implementation:
+  - Add `POST /password/request-reset`:
+    - Accept identifier (email).
+    - Always return generic success response.
+    - If account exists, create one-time reset token with short TTL (15-30 min), store hashed token, email reset link.
+  - Add `POST /password/confirm-reset`:
+    - Accept token + new password.
+    - Validate token (exists, not expired, unused), then rotate password hash and invalidate all active sessions.
+  - Data model:
+    - New collection `password_reset_tokens` with fields:
+      - `userId`, `tokenHash`, `expiresAt`, `usedAt`, `createdAt`, `requestMeta`.
+    - Add TTL index on `expiresAt`.
+
+## 2. Remove credential handling from GET/query
+- Problem:
+  - `/signup` and `/login` accept GET and query params for credentials.
+- Implementation:
+  - Change auth routes to `POST` only.
+  - Read credentials from JSON body only.
+  - Reject query-based credential inputs with `400`.
+  - Update Swagger docs and clients accordingly.
+
+## 3. Add account-aware brute-force protection
+- Problem:
+  - Only global IP limiter exists; auth endpoints are not sufficiently protected.
+- Implementation:
+  - Add dedicated limiter middleware for auth endpoints (`/login`, `/password/request-reset`, `/password/confirm-reset`):
+    - Combined key: normalized username/email + source IP.
+    - Lower thresholds and progressive backoff/lockout window.
+  - Add telemetry for blocked attempts.
+  - Optionally store counters in Redis if horizontally scaled.
+
+## 4. Prevent account enumeration
+- Problem:
+  - API exposes different responses for unknown user vs wrong password.
+- Implementation:
+  - Login: same response for invalid credentials regardless of user existence.
+  - Reset request: always same response regardless of account existence.
+  - Keep detailed reason only in internal logs/analytics.
+
+## 5. Keep strong password hashing policy (clarify bcrypt behavior)
+- Problem:
+  - Existing TODO comments incorrectly state bcrypt needs manual salt handling.
+- Implementation:
+  - Keep bcrypt (or migrate to Argon2id in a separate change set).
+  - Centralize hash policy:
+    - cost factor (benchmark-backed; start at 12 if acceptable latency).
+    - minimum password length and strength checks.
+  - On login, detect outdated hash params and rehash after successful auth.
+
+## Suggested rollout order
+1. Tokenized reset flow (new endpoints + DB token store).
+2. POST-only auth route enforcement.
+3. Generic auth/reset responses.
+4. Dedicated auth rate limiting.
+5. Hash policy tuning + opportunistic rehash.
+
+## Validation checklist
+- Unit/integration tests:
+  - reset token creation, expiry, one-time use, invalid token paths.
+  - login generic error response behavior.
+  - auth rate limiter trigger and cooldown.
+  - query credential rejection.
+- Manual:
+  - verify no plaintext password emails are sent.
+  - verify existing sessions are revoked after password reset.