docs: align flow docs with code reality + create 35 implementation issue files

Flow docs updated (11 files):
- Delivery Confirmation: reversed actor roles (buyer generates, seller verifies),
  fixed endpoint paths (/delivery-code/generate, /delivery-code/verify)
- Passkey (WebAuthn): removed stub/simulated-key claims; real @simplewebauthn/server
  attestation is implemented; refresh tokens are persisted
- Dispute: corrected resolve schema (action enum), removed non-existent statuses,
  documented security gaps (no role guards on status/resolve/assign), route shadowing,
  all socket events are TODO stubs
- Seller Offer: corrected all endpoint paths, removed 'active' status, documented
  withdraw dead code, missing seller history page, select-offer notification gap
- Notification: corrected mark-all-read method+path, fixed GET /:id broken lookup,
  added unread-count-update socket event
- Authentication: corrected rate limiter (counts all attempts), axios 403 not handled,
  deleteAccount wrong endpoint bug, changePassword no UI
- Password Reset: corrected 6-digit code (not 8), documented no-complexity gap on
  reset-with-code vs token reset
- Payment Flow DePay: /create→/save, removed phantom sub-routes, SIM_ bypass risk,
  PaymentProvider type gap, getProviderIntentEndpoint routing bug
- Payment Flow SHKeeper: removed phantom polling endpoint, fixed release/refund paths
- Purchase Request: added pending_payment/active statuses, fixed sellers/attachments
  endpoints, corrected socket events, PUT→PATCH bug
- Escrow: documented dispute resolve does not touch escrow, route shadowing, confirm-delivery auth gap

Issues created (35 files in Issues/):
- 9 security issues (critical) including: dispute privilege escalation ×4,
  unauthenticated payment/scanner endpoints ×2, SIM_ production bypass,
  confirm-delivery ownership gap
- 26 additional major/critical bugs covering broken endpoints, missing features,
  data integrity gaps, and frontend-backend mismatches

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

04 - Flows/Payment Flow - SHKeeper.md

@@ -2,9 +2,12 @@
 title: Payment Flow - SHKeeper
 tags: [flow, payment, shkeeper, crypto, escrow, webhook]
 related_models: ["[[Payment]]", "[[PurchaseRequest]]", "[[SellerOffer]]"]
-related_apis: ["POST /api/payment/shkeeper/create", "POST /api/payment/shkeeper/webhook", "GET /api/payment/shkeeper/status/:id"]
+related_apis: ["POST /api/payment/shkeeper/create", "POST /api/payment/shkeeper/webhook", "POST /api/payment/:id/release", "POST /api/payment/:id/refund"]
 ---
 
+> [!caution] Audit — 2026-05-29
+> This document was reviewed against the live codebase. **2 corrections applied**: the non-existent HTTP polling endpoint has been removed (status updates arrive via socket only), and the release/refund/confirm paths have been corrected to remove the erroneous `/shkeeper/` segment.
+
 # Payment Flow — SHKeeper (Crypto Pay-In)
 
 > [!warning] Historical migration document
@@ -32,7 +35,7 @@ Pulled from env: `SHKEEPER_NETWORKS` and `SHKEEPER_ALLOWED_TOKENS` (`shkeeperSer
 - **PaymentCoordinator** (`backend/src/services/payment/paymentCoordinator.ts`) — serialises concurrent payment-status updates from multiple sources (webhook, wallet monitor, manual confirm).
 - **MongoDB** — `payments`, `purchaserequests`, `selleroffers`, `chats`, `notifications`.
 - **Redis** — `paymentRedisService` (wallet-address cache, 2 h TTL).
-- **Socket.IO** — `payment-created`, `seller-offer-update`, `purchase-request-update`.
+- **Socket.IO** — `payment-created`, `payment-update`, `template-checkout-payment-confirmed`, `seller-offer-update`, `purchase-request-update`.
 
 ## Preconditions
 
@@ -122,7 +125,11 @@ stateDiagram-v2
 
 ### Phase 4 — Frontend reaction
 
-21. The buyer's checkout page subscribes to socket events and polls `GET /api/payment/shkeeper/status/{paymentId}`. When status flips to `completed`, the UI transitions to "Payment received" and unlocks the next buyer step (await delivery).
+21. The buyer's checkout page subscribes to socket events (`payment-update`, `template-checkout-payment-confirmed`). When the status flips to `completed`, the UI transitions to "Payment received" and unlocks the next buyer step (await delivery).
+
+    > [!warning] ⚠️ No HTTP polling endpoint — socket events only
+    > `GET /api/payment/shkeeper/status/:paymentId` **does not exist** — there is no polling route in `shkeeperRoutes.ts`. Status transitions must be observed via Socket.IO events (`payment-update`, `template-checkout-payment-confirmed`). Any frontend code path that polls this URL will always receive 404. Remove HTTP polling and rely solely on the socket subscription.
+
 22. The seller's dashboard receives `seller-offer-update` `payment-completed` and surfaces the green "Order paid — start preparing" banner.
 
 ## Sequence diagram
@@ -169,7 +176,7 @@ sequenceDiagram
     BE->>IO: emit seller-{winner} 'payment-completed'
     BE->>IO: emit seller-{loser_i} 'offer-rejected'
     BE-->>SK: 202 OK
-    IO-->>FE: status updated
+    IO-->>FE: payment-update / status updated
     IO-->>S: dashboard updates
     FE-->>B: "Payment received ✓"
 ```
@@ -180,8 +187,21 @@ sequenceDiagram
 |---|---|---|---|
 | `POST` | `/api/payment/shkeeper/create` | Create pay-in intent | `shkeeperRoutes.ts` → `shkeeperService.createPayInIntent` |
 | `POST` | `/api/payment/shkeeper/webhook` | Receive SHKeeper webhook | `shkeeperWebhook.handleShkeeperWebhook` |
-| `GET` | `/api/payment/shkeeper/status/:paymentId` | Frontend polling | `shkeeperRoutes.ts` |
-| `GET` | `/api/payment/fetch-tx/:paymentId` | Manual transaction lookup | `paymentRoutes.ts` |
+| `POST` | `/api/payment/:id/release` | Release escrow to seller | `paymentRoutes.ts` |
+| `POST` | `/api/payment/:id/release/confirm` | Confirm escrow release | `paymentRoutes.ts` |
+| `POST` | `/api/payment/:id/refund` | Refund to buyer | `paymentRoutes.ts` |
+| `POST` | `/api/payment/:id/refund/confirm` | Confirm buyer refund | `paymentRoutes.ts` |
+| `POST` | `/api/payment/payments/:id/fetch-tx` | Manual transaction lookup | `paymentRoutes.ts` |
+| ~~`GET /api/payment/shkeeper/status/:paymentId`~~ | | ⚠️ **404 — does not exist.** Use socket events instead. | — |
+
+> [!warning] ⚠️ Release/refund path correction
+> Previously documented paths included a `/shkeeper/` segment that does **not** exist in the router:
+> - ~~`POST /api/payment/shkeeper/:id/release`~~ → correct: `POST /api/payment/:id/release`
+> - ~~`POST /api/payment/shkeeper/:id/release/confirm`~~ → correct: `POST /api/payment/:id/release/confirm`
+> - ~~`POST /api/payment/shkeeper/:id/refund`~~ → correct: `POST /api/payment/:id/refund`
+> - ~~`POST /api/payment/shkeeper/:id/refund/confirm`~~ → correct: `POST /api/payment/:id/refund/confirm`
+>
+> The `/shkeeper/` infix never existed on release/refund routes. These are generic payment lifecycle endpoints shared across all providers.
 
 ## Database writes
 
@@ -195,6 +215,8 @@ sequenceDiagram
 ## Socket events emitted
 
 - **`payment-created`** (global) — broadcast on intent creation.
+- **`payment-update`** — status change notifications to the buyer's checkout page.
+- **`template-checkout-payment-confirmed`** — for template checkout flows.
 - **`seller-offer-update`** with `eventType: 'payment-completed'` → winning seller.
 - **`seller-offer-update`** with `eventType: 'offer-rejected'` → each losing seller.
 - **`purchase-request-update`** with `eventType: 'status-changed'` (via `PurchaseRequestService`) → `request-{id}`.