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
 

03 - API Reference/Dispute API.md

@@ -5,7 +5,10 @@ tags: [api, dispute, reference]
 
 # Dispute API
 
-Endpoints live under `/api/disputes/*`. The router is [`backend/src/routes/disputeRoutes.ts`](../../backend/src/routes/disputeRoutes.ts) and delegates to `DisputeController` ([`backend/src/controllers/disputeController.ts`](../../backend/src/controllers/disputeController.ts)). The router applies `authenticateToken` globally — every endpoint requires `Bearer JWT`.
+> [!warning] Not implemented
+> The Dispute module is **documented but not yet implemented** in the backend. There is no `backend/src/services/dispute/` directory, no `backend/src/routes/disputeRoutes.ts`, and no `/api/disputes` mount in `app.ts`. The API specification below reflects the *intended* design only.
+
+Endpoints are planned to live under `/api/disputes/*`. The router would be `backend/src/routes/disputeRoutes.ts` and delegate to `DisputeController` (`backend/src/controllers/disputeController.ts`). The router would apply `authenticateToken` globally — every endpoint requires `Bearer JWT`.
 
 Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[Payment]] and is the input to the mediation workflow that ends in either a `resolved_buyer` or `resolved_seller` decision and triggers an escrow release or refund via the [[Payment API]].
 

03 - API Reference/Payment API.md

@@ -301,7 +301,7 @@ Payouts are SHKeeper-side outbound transfers (admin pays the seller from a hot w
 ### POST /api/payment/decentralized/save
 
 **Description:** Persists a Web3-initiated payment record.
-**Auth required:** No
+**Auth required:** Bearer JWT (enforces `userId` ownership match)
 **Request body:**
 ```ts
 {
@@ -326,7 +326,7 @@ Payouts are SHKeeper-side outbound transfers (admin pays the seller from a hot w
 ### PUT /api/payment/decentralized/update
 
 **Description:** Update a decentralized payment's status / confirmations.
-**Auth required:** No
+**Auth required:** Bearer JWT (owner or admin)
 **Request body:** `{ paymentId, status, confirmations? }`
 
 ### GET /api/payment/decentralized/receiver
@@ -337,17 +337,17 @@ Payouts are SHKeeper-side outbound transfers (admin pays the seller from a hot w
 ### GET /api/payment/decentralized/history/:userId
 
 **Description:** Decentralized payment history for a user.
-**Auth required:** No
+**Auth required:** Bearer JWT (self or admin)
 
 ### POST /api/payment/decentralized/verify/:paymentId
 
 **Description:** Re-verifies a single decentralized payment against the chain.
-**Auth required:** No
+**Auth required:** Bearer JWT (owner or admin)
 
 ### POST /api/payment/decentralized/verify-all-pending
 
 **Description:** Iterates all `pending` decentralized payments and re-verifies them.
-**Auth required:** No (typically called by a cron)
+**Auth required:** Bearer JWT (admin only)
 
 ### POST /api/payment/decentralized/admin-payout
 
@@ -371,6 +371,7 @@ Payouts are SHKeeper-side outbound transfers (admin pays the seller from a hot w
 
 - `pending` - intent created, awaiting on-chain settlement
 - `processing` - settlement seen, awaiting confirmations
+- `confirmed` - fully credited (intermediate; sometimes skipped)
 - `completed` - confirmed, escrow funded
 - `failed` - intentionally failed (expired, declined, refused)
 - `cancelled` - cancelled by user/admin