feat: add project review notes and security improvement plans

Add comprehensive PLANS.md documenting security issues, code risks, and enhancement opportunities discovered during code review.

Signed-off-by: Grant Ramsay <seapagan@gmail.com>

Author: seapagan

PLANS.md

@@ -0,0 +1,60 @@
+# Project Review Notes
+
+## ⚠️ High Priority Security Issues
+
+**CRITICAL - Refresh Token Authentication Bypass**
+
+- **Issue**: Refresh tokens can be used as access tokens because access tokens
+  don't carry a `typ` claim and `get_jwt_user` doesn't enforce token type. This
+  completely undermines the token separation model and allows 30-day tokens to be
+  used where 120-minute tokens should be required.
+- **Impact**: Attackers with a stolen refresh token get extended unauthorized
+  access to protected endpoints. The entire point of short-lived access tokens is
+  defeated.
+- **Fix**: Add `typ="access"` in `AuthManager.encode_token` and validate
+  `typ="access"` in `get_jwt_user`. Reject any token without the correct type.
+- **Priority**: Fix immediately before addressing other issues.
+
+## Code Issues / Risks
+
+- `payload["typ"]` / `payload["sub"]` are accessed directly in
+  refresh/verify/reset flows; a token missing those keys will throw `KeyError`
+  and return a 500 instead of a clean 401. Use `payload.get(...)` and treat
+  missing keys as invalid token.
+- CORS default allows `cors_origins="*"` with `allow_credentials=True`, which
+  browsers reject. Either disallow `*` when credentials are on or auto-flip
+  `allow_credentials=False` for the wildcard case.
+- `get_jwt_user` doesn’t apply the JWT format/length guard you already built;
+  very large or malformed tokens go straight to `jwt.decode`. Add the
+  `MAX_JWT_TOKEN_LENGTH` and `is_valid_jwt_format` checks here.
+- Verification success uses `HTTPException` for control flow and returns 200
+  with a message; docs already note this should be 204. Consider returning a
+  normal response (or 204) to reduce exception noise.
+
+## Existing TODOs Worth Prioritizing
+
+- Logout + token invalidation (security win)
+- Fix docs status codes/examples (quick win)
+- Test TODOs for better assertions
+- Refactor `ApiKeyAuth.__call__()` complexity
+
+## Enhancements From Code Review
+
+- API key scopes are stored but not enforced anywhere. Add scope checks in a
+  dependency that resources can opt into.
+- Trim/normalize `cors_origins` entries (split+strip) to avoid accidental
+  leading spaces causing mismatches.
+- Consider adding `created_at`/`updated_at` on `User` for auditability and to
+  support features like “recently active users.”
+
+## Feature Ideas (new)
+
+- Session management: list/revoke active refresh tokens per user (ties into
+  logout/invalidations).
+- Account security notifications: email user when password/email changes or
+  when banned/unbanned.
+- API key scope enforcement + per-route required scopes (pairs well with
+  existing API key model).
+- Optional 2FA (TOTP) for admin and/or all users.
+- Webhook events for user lifecycle changes (register/verify/ban/unban/delete)
+  to integrate with external systems.