docs(audit): align documentation with post-remediation backend reality

- Update data model enums to match backend models
- Update API reference auth requirements
- Add dispute module references and warning blocks
- Add 2026-05-24 audit remediation callout to Overview
- Generate task breakdowns and audit artifacts
- Add doc alignment report (.taskmaster/reports/)

03 - API Reference/API Overview.md

@@ -15,10 +15,10 @@ This page is the entry point for the API. See the individual service pages for e
 - [[Payment API]] - SHKeeper, Web3, DePay, payouts
 - [[Chat API]] - conversations and messages
 - [[Notification API]] - in-app notifications
-- [[Dispute API]] - dispute resolution
-- [[Blog API]] - blog posts (admin-managed)
-- [[Admin API]] - user management, data cleanup, manual ops
-- [[Points API]] - loyalty points, levels, referrals
+- [[Dispute API]] - dispute resolution *(planned, not yet implemented)*
+- [[Blog API]] - blog posts *(planned, not yet implemented)*
+- [[Admin API]] - user management, data cleanup *(planned, not yet implemented)*
+- [[Points API]] - loyalty points, levels, referrals *(planned, not yet implemented)*
 - [[AI API]] - OpenAI-backed text endpoints
 - [[File API]] - upload, delete, serve
 - [[Socket Events]] - real-time events
@@ -133,9 +133,16 @@ Sort parameters: list endpoints commonly accept `sortBy` (default `createdAt`) a
 
 ## Rate limiting
 
-Rate limiting is currently **disabled** in the deployed code (`app.ts` logs `🔓 Rate limiting COMPLETELY DISABLED for personal use`). The intended policy when re-enabled is **100 requests per 15-minute window per IP**, applied per `/api/*` route. The Express `trust proxy` setting is enabled in production so the real client IP is read from `X-Forwarded-For` (Nginx terminator).
+Rate limiting is **enabled** as of the 2026-05-24 remediation. Four tiers are active in `backend/src/app.ts`:
 
-Redis-backed rate limiting helpers exist in `src/services/redis/rateLimitService.ts` and are used by sensitive auth flows (password reset, email verification) even with the global limiter off.
+| Tier | Scope | Limit | Window |
+| --- | --- | --- | --- |
+| Global | All `/api/*` routes (except `/health` and Request-Network webhooks) | 100 req | 15 min per IP |
+| Auth | `/api/auth/*` | 10 req | 15 min per IP |
+| Payment | `/api/payment/*` | 30 req | 15 min per IP |
+| AI | `/api/ai/*` | 20 req | 15 min per IP |
+
+The Express `trust proxy` setting is enabled in production so the real client IP is read from `X-Forwarded-For` (Nginx terminator).
 
 ## CORS
 
@@ -156,7 +163,14 @@ Uploaded files served from `/uploads/*` use `helmet({ crossOriginResourcePolicy:
 
 ## Real-time channel
 
-Socket.IO runs on the same HTTP server. The frontend should connect to the API origin with credentials. Clients join rooms via `join-user-room`, `join-request-room`, `join-seller-room`, `join-buyer-room`, `join-chat-room`. Full catalog: [[Socket Events]].
+Socket.IO runs on the same HTTP server. **All connections require a valid JWT** passed in `socket.auth.token` (or `socket.handshake.query.token`). The server verifies the token with `jwt.verify(config.jwtSecret)` before allowing the connection. Room-join events enforce strict membership checks:
+
+- `join-user-room` — only the authenticated user may join their own room.
+- `join-request-room` — buyer, preferred seller, or offer submitter only.
+- `join-seller-room` / `join-buyer-room` — only the matching user id.
+- `join-chat-room` — active participant only.
+
+Clients join rooms via `join-user-room`, `join-request-room`, `join-seller-room`, `join-buyer-room`, `join-chat-room`. Full catalog: [[Socket Events]].
 
 ## Standard HTTP status codes