708 lines
74 KiB
Markdown
708 lines
74 KiB
Markdown
---
|
|
title: Authorization Matrix - REST and Socket.IO
|
|
tags: [audit, security, authorization, matrix, reference]
|
|
created: 2026-05-24
|
|
status: living
|
|
reviewers: [backend, security]
|
|
---
|
|
|
|
# Authorization Matrix - REST and Socket.IO
|
|
|
|
**Purpose:** Canonical reference mapping every REST endpoint and Socket.IO event to its required access level, ownership checks, state preconditions, rate-limit tier, and audit-log requirement. Implementation tasks reference individual rows by ID.
|
|
|
|
**How to read this document:**
|
|
- Each row is a discrete authorization rule identified by a unique ID (e.g., `AUTH-R001`).
|
|
- "Current State" reflects the documented and audited behavior as of 2026-05-24, based on [[Platform Logical Audit - 2026-05-24]], [[Backend Stack Security and Refactor Assessment - 2026-05-24]], and [[Threat Model - Amanat Escrow Platform]].
|
|
- "Required State" is what this matrix mandates for launch. Gaps are enumerated in Section 4.
|
|
- `[VERIFY]` indicates uncertainty from documentation alone; the implementation must be inspected.
|
|
|
|
**Cross-references:**
|
|
- [[Threat Model - Amanat Escrow Platform]] -- T03 (Socket.IO room join), T09 (admin privilege escalation), T21 (unauthenticated data exfiltration)
|
|
- [[Security Architecture]] -- current auth/role model, rate limiting
|
|
- [[Backend Architecture]] -- route registration, middleware chain
|
|
- [[Real-time Layer]] -- Socket.IO rooms and events
|
|
- [[Security Ownership and Launch Decision Criteria]] -- launch checklist items 2.1-2.6
|
|
|
|
---
|
|
|
|
## Section 1: Access Level Definitions
|
|
|
|
| Access Level | Criteria | Enforcement Mechanism |
|
|
|---|---|---|
|
|
| **Public** | No authentication required. No `req.user`. | No middleware. Rate-limited at IP level. |
|
|
| **Authenticated** | Valid Bearer JWT. `req.user = { id, email, role }` is populated. | `authenticateToken` middleware on route. |
|
|
| **Owner** | Authenticated + `req.user.id` matches the resource owner. Ownership is determined per resource type: (a) User profile/addresses/wallet: `user._id === req.params.userId`; (b) PurchaseRequest: `request.buyerId === req.user.id`; (c) SellerOffer: `offer.sellerId === req.user.id`; (d) Payment: `payment.buyerId === req.user.id || payment.sellerId === req.user.id`; (e) Chat: `chat.participants.includes(req.user.id)`; (f) Notification: `notification.userId === req.user.id`; (g) Dispute: `dispute.buyerId === req.user.id || dispute.sellerId === req.user.id`; (h) RequestTemplate: `template.sellerId === req.user.id`; (i) BlogPost: N/A (admin-only writes); (j) File: uploader ownership via metadata association. | `authenticateToken` + ownership query in controller/service. |
|
|
| **Buyer** | Authenticated + user is the buyer on the specific purchase request (i.e., `request.buyerId === req.user.id`). | `authenticateToken` + service-layer buyer check. |
|
|
| **Seller** | Authenticated + user is the selected seller on the purchase request (`request.selectedOffer.sellerId === req.user.id`) or has a seller role making an offer. | `authenticateToken` + service-layer seller check. |
|
|
| **Admin** | Authenticated + `req.user.role === 'admin'`. All admin actions MUST be audit-logged. | `authenticateToken` + `roleGuard('admin')` or `authorizeRoles('admin')`. |
|
|
| **Support** | Authenticated + `req.user.role === 'support'`. Read-only access to user data, dispute records, and chat. Can reset passwords and escalate to admin. Cannot modify financial records or release funds. | `authenticateToken` + `roleGuard('support')`. Controller must enforce read-only constraint. |
|
|
| **Service** | Internal service-to-service calls. Authenticated via shared secret (`X-Internal-Secret` header) or restricted to localhost network. Not user-facing. | Custom middleware verifying internal header or `req.ip === '127.0.0.1'`. |
|
|
| **Step-up** | Admin + re-authenticated within configured window (default 5 minutes). Required for high-risk admin actions (role changes, user deletion, payout/release, manual overrides, sensitive wallet operations). | `authenticateToken` + `roleGuard('admin')` + step-up timestamp check from Redis session. |
|
|
| **HMAC** | No user auth. Verified via HMAC-SHA256 signature on raw body using `SHKEEPER_WEBHOOK_SECRET`. Signature-verified, not identity-verified. | `express.raw()` body parser + timing-safe HMAC comparison. |
|
|
|
|
---
|
|
|
|
## Section 2: REST Endpoint Authorization Matrix
|
|
|
|
### Rate-Limit Tiers (reference)
|
|
|
|
| Tier | Limit | Scope | Applies to |
|
|
|---|---|---|---|
|
|
| Tier 1 (strict) | 5 req / 5 min / IP | Login, register, password reset, verification | Auth mutation paths |
|
|
| Tier 2 (auth-financial) | 20 req / 15 min / user | Payment operations, AI calls, file uploads | Financial and cost-bearing |
|
|
| Tier 3 (moderate) | 60 req / 15 min / user | Chat messages, notifications, marketplace writes | User interaction |
|
|
| Tier 4 (relaxed) | 200 req / 15 min / IP | Public reads, browsing | Public data access |
|
|
| Tier 5 (webhook) | Provider-specific; signature-verified | SHKeeper inbound webhooks | External callbacks |
|
|
| Tier 6 (admin) | 60 req / 15 min / user | Admin write operations | Admin mutations |
|
|
|
|
### 2.1 Auth Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| AUTH-R001 | POST | /api/auth/register | Public | None | None | Tier 1 | No | No rate limit. Code logged to stdout. T07. | Public + Tier 1 + remove code logging | Triggers email send. |
|
|
| AUTH-R002 | POST | /api/auth/verify-email-code | Public | None | TempVerification exists and not expired | Tier 1 | No | No rate limit. T07. | Public + Tier 1 | Creates User + issues JWT. |
|
|
| AUTH-R003 | GET | /api/auth/verify-email/:token | Public | None | Token not expired | Tier 1 | No | Legacy path. | Public + Tier 1 | Legacy URL-based verification. |
|
|
| AUTH-R004 | POST | /api/auth/resend-verification | Public | None | User/TempVerification exists | Tier 1 | No | No rate limit. T07. | Public + Tier 1 | Email cost abuse vector. |
|
|
| AUTH-R005 | POST | /api/auth/force-verify-user | Service | None | NODE_ENV=development only | Tier 1 | Yes | No auth gate. Exposed in production. | Disable in production builds | Dev-only. Must be removed from prod. |
|
|
| AUTH-R006 | POST | /api/auth/login | Public | None | Account not locked | Tier 1 | Yes (failure) | Redis lockout exists. No global rate limit. T12. | Public + Tier 1 + audit failure | Lockout after N failures. |
|
|
| AUTH-R007 | POST | /api/auth/refresh-token | Public | Token belongs to user | Refresh token valid and not revoked | Tier 1 | No | No rate limit. | Public + Tier 1 | Rotation detects reuse. |
|
|
| AUTH-R008 | POST | /api/auth/logout | Authenticated | Token belongs to user | None | Tier 3 | No | Auth enforced. | Authenticated | Clears Redis session. |
|
|
| AUTH-R009 | POST | /api/auth/google/signup | Public | None | Google ID token valid | Tier 1 | No | No rate limit. | Public + Tier 1 | Creates user if new email. |
|
|
| AUTH-R010 | POST | /api/auth/google/signin | Public | None | Google ID token valid, user exists | Tier 1 | No | No rate limit. | Public + Tier 1 | Returns JWT for existing user. |
|
|
| AUTH-R011 | POST | /api/auth/passkey/authenticate/challenge | Public | None | None | Tier 1 | No | Stubbed implementation. T10. | Disable or fix | Passkeys are broken per T10. |
|
|
| AUTH-R012 | POST | /api/auth/passkey/authenticate | Public | None | Challenge valid (in-memory) | Tier 1 | No | In-memory challenge store breaks at scale. T10. | Disable or fix | Public key is stub string. |
|
|
| AUTH-R013 | POST | /api/auth/passkey/register/challenge | Authenticated | None | None | Tier 1 | No | Auth required. | Authenticated | Challenge in process memory. |
|
|
| AUTH-R014 | POST | /api/auth/passkey/register | Authenticated | None | Challenge valid | Tier 1 | No | Auth required. | Authenticated | Stores stub public key. |
|
|
| AUTH-R015 | GET | /api/auth/passkey/list | Authenticated | Owner | None | Tier 3 | No | Auth required. | Authenticated | Returns caller's passkeys. |
|
|
| AUTH-R016 | DELETE | /api/auth/passkey/:passkeyId | Authenticated | Owner | Passkey belongs to user | Tier 3 | Yes | Auth required. | Authenticated + audit | |
|
|
| AUTH-R017 | POST | /api/auth/request-password-reset | Public | None | User with email exists | Tier 1 | No | Redis rate limit exists. Code logged to stdout. T22. | Public + Tier 1 + remove code logging | Always returns success to avoid enumeration. |
|
|
| AUTH-R018 | POST | /api/auth/reset-password | Public | None | Reset token valid and not expired | Tier 1 | Yes | No rate limit. | Public + Tier 1 + audit | Wipes refresh tokens. |
|
|
| AUTH-R019 | POST | /api/auth/reset-password-with-code | Public | None | Code valid and not expired | Tier 1 | Yes | No rate limit. | Public + Tier 1 + audit | Alternative reset path. |
|
|
| AUTH-R020 | POST | /api/auth/change-password | Authenticated | Owner | Current password correct | Tier 3 | Yes | Auth enforced. | Authenticated + audit | Clears all refresh tokens. |
|
|
| AUTH-R021 | GET | /api/auth/profile | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Returns full user doc. |
|
|
| AUTH-R022 | PUT | /api/auth/profile | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| AUTH-R023 | POST | /api/auth/update-profile | Authenticated | Owner | None | Tier 3 | No | Auth enforced. Legacy alias. | Authenticated | Duplicate of R022. |
|
|
| AUTH-R024 | DELETE | /api/auth/account | Authenticated | Owner | Password re-verified | Tier 3 | Yes | Auth + password required. | Authenticated + audit | Permanent deletion. |
|
|
| AUTH-R025 | POST | /api/auth/step-up | Admin | None | Valid challenge context or credentials | Tier 6 | Yes | Not implemented | Admin + Step-up | Required by ADR for high-risk admin actions. Creates 5-minute elevated session in Redis. |
|
|
| AUTH-R026 | GET | /api/auth/sessions | Authenticated | Owner | Current refresh session exists | Tier 3 | Yes | Not implemented | Authenticated | Returns active sessions with device, IP, and session age. |
|
|
| AUTH-R027 | POST | /api/auth/revoke-session | Authenticated | Owner | Target session belongs to user | Tier 3 | Yes | Not implemented | Authenticated + audit | Revokes one session by sessionTokenHash. |
|
|
| AUTH-R028 | POST | /api/auth/revoke-all-sessions | Authenticated | Owner | Multiple active sessions loaded | Tier 3 | Yes | Not implemented | Authenticated + audit | Revokes all sessions except current. |
|
|
|
|
### 2.2 User Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| USER-R001 | GET | /api/user/profile | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | New controller path. |
|
|
| USER-R002 | PUT | /api/user/profile | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| USER-R003 | GET | /api/users/profile | Authenticated | Owner | None | Tier 3 | No | Auth enforced. Legacy. | Authenticated | Legacy alias. |
|
|
| USER-R004 | GET | /api/users/profile/:userId | Authenticated | Owner or Admin | None | Tier 3 | No | Auth enforced. Public/private split based on isPublic flag. | Authenticated | Returns limited fields for non-owners. |
|
|
| USER-R005 | GET | /api/user/wallet-address | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Returns stored wallet. |
|
|
| USER-R006 | PATCH | /api/user/wallet-address | Authenticated | Owner | Signature verification passes | Tier 3 | Yes | Auth enforced. EIP-191 verify. | Authenticated + audit | Financial implications. |
|
|
| USER-R007 | GET | /api/users/contacts | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Role-filtered contact list. |
|
|
| USER-R008 | GET | /api/users/search | Authenticated | None | q.length >= 2 | Tier 3 | No | Auth enforced. | Authenticated | Returns max 20 results. |
|
|
| USER-R009 | GET | /api/users | Authenticated | None | None | Tier 3 | No | Auth enforced. No admin gate. [VERIFY] | Authenticated | Paginated user directory. Should restrict non-admin to limited fields. |
|
|
|
|
### 2.3 User Admin Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| UADM-R001 | POST | /api/user/admin/create | Admin | None | Email not taken | Tier 6 | Yes | Inline role check. [VERIFY] consistent enforcement. | Admin + Step-up + audit | Creates user with arbitrary role. T09. |
|
|
| UADM-R002 | DELETE | /api/user/admin/:userId | Admin | Cannot delete self or other admins | Target user exists | Tier 6 | Yes | Inline role check. | Admin + Step-up + audit | Hard delete. T09. |
|
|
| UADM-R003 | PATCH | /api/user/admin/:userId/status | Admin | None | Target user exists | Tier 6 | Yes | Inline role check. | Admin + audit | Activate/suspend. |
|
|
| UADM-R004 | PATCH | /api/user/admin/:userId/toggle-status | Admin | None | Target user exists | Tier 6 | Yes | Inline role check. | Admin + audit | Flip active/suspended. |
|
|
| UADM-R005 | PATCH | /api/user/admin/:userId/role | Admin | None | Target user exists; valid role | Tier 6 | Yes | Inline role check. | Admin + Step-up + audit | Role change is high-risk. T09. |
|
|
| UADM-R006 | GET | /api/user/admin/list | Admin | None | None | Tier 6 | No | Inline role check. | Admin | Paginated user directory. |
|
|
| UADM-R007 | GET | /api/user/admin/:userId/dependencies | Admin | None | Target user exists | Tier 6 | No | Inline role check. | Admin | Pre-delete check. |
|
|
| UADM-R008 | GET | /api/users/admin/stats | Admin | None | None | Tier 6 | No | Inline role check. | Admin | Aggregated stats. |
|
|
| UADM-R009 | GET | /api/users/admin/:userId | Admin | None | Target user exists | Tier 6 | No | Inline role check. | Admin | Full user detail. |
|
|
| UADM-R010 | PUT | /api/users/admin/:userId | Admin | None | Target user exists | Tier 6 | Yes | Inline role check. | Admin + audit | Mass update user. |
|
|
| UADM-R011 | PUT | /api/users/admin/update/:email | Admin | None | User with email exists | Tier 6 | Yes | Inline role check. | Admin + audit | Mass update by email. |
|
|
| UADM-R012 | PATCH | /api/users/admin/:userId/password | Admin | None | Target user exists | Tier 6 | Yes | Inline role check. | Admin + Step-up + audit | Wipes all sessions. |
|
|
| UADM-R013 | POST | /api/users/admin/:userId/resend-verification | Admin | None | User not already verified | Tier 6 | Yes | Inline role check. | Admin + audit | Triggers email. |
|
|
|
|
### 2.3A Admin Approval Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| APV-R001 | GET | /api/admin/approvals | Admin | None | None | Tier 6 | Yes | Not implemented | Admin + Step-up | Pending approval queue for high-value actions. |
|
|
| APV-R002 | POST | /api/admin/approvals/{id}/confirm | Admin | None | Approval exists, status = PENDING, approver != creator | Tier 6 | Yes | Not implemented | Admin + Step-up + audit | Confirms pending approval and executes action. |
|
|
| APV-R003 | POST | /api/admin/approvals/{id}/reject | Admin | None | Approval exists, status = PENDING | Tier 6 | Yes | Not implemented | Admin + Step-up + audit | Rejects pending approval and records reason. |
|
|
|
|
### 2.4 Address Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| ADDR-R001 | GET | /api/addresses | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Lists caller's addresses. |
|
|
| ADDR-R002 | POST | /api/addresses | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | First auto-primary. |
|
|
| ADDR-R003 | PUT | /api/addresses/:addressId | Authenticated | Owner | Address belongs to user | Tier 3 | No | Auth enforced. 404 if not owned. | Authenticated | |
|
|
| ADDR-R004 | DELETE | /api/addresses/:addressId | Authenticated | Owner | Address belongs to user | Tier 3 | No | Auth enforced. | Authenticated | Promotes next primary. |
|
|
| ADDR-R005 | PATCH | /api/addresses/:addressId/primary | Authenticated | Owner | Address belongs to user | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
|
|
### 2.5 Purchase Request Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| PR-R001 | POST | /api/marketplace/purchase-requests | Buyer | None | None | Tier 3 | No | Auth enforced. | Authenticated (Buyer) | Emits to sellers room. |
|
|
| PR-R002 | POST | /api/marketplace/purchase-requests/bulk | Buyer | None | None | Tier 3 | No | Auth enforced. | Authenticated (Buyer) | Template checkout. |
|
|
| PR-R003 | GET | /api/marketplace/purchase-requests | Authenticated | None (filtered by role) | None | Tier 3 | No | Auth enforced. | Authenticated | Buyers see own; sellers see routed; admins see all. |
|
|
| PR-R004 | GET | /api/marketplace/purchase-requests/my | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Shortcut for caller's requests. |
|
|
| PR-R005 | GET | /api/marketplace/purchase-requests/:id | Public | None | None | Tier 4 | No | No auth. Public read for shareable links. | Public | Exposes request data to unauthenticated users. Consider limiting fields. |
|
|
| PR-R006 | PATCH | /api/marketplace/purchase-requests/:id | Owner (Buyer) | buyerId match | Status in [draft, pending] | Tier 3 | No | Auth enforced. Owner check via controller. | Owner (Buyer) | |
|
|
| PR-R007 | PATCH | /api/marketplace/purchase-requests/:id/status | Owner or Admin | buyerId match or admin | Valid state transition | Tier 3 | Yes | Auth enforced. Owner or admin. | Owner or Admin + audit | State machine must enforce transitions. |
|
|
| PR-R008 | DELETE | /api/marketplace/purchase-requests/:id | Owner (Buyer) | buyerId match | No committed payment | Tier 3 | Yes | Auth enforced. Owner check. | Owner (Buyer) + audit | Must verify no payment attached. |
|
|
| PR-R009 | GET | /api/marketplace/purchase-requests/:id/workflow-steps | Public | None | None | Tier 4 | No | No auth. | Public | Returns workflow metadata. |
|
|
| PR-R010 | GET | /api/marketplace/purchase-requests/:id/payment-status | Authenticated | Buyer or Seller or Admin | None | Tier 3 | No | Auth enforced. | Authenticated | Returns payment + escrow state. |
|
|
| PR-R011 | POST | /api/marketplace/purchase-requests/:id/sync-payment-status | Authenticated | Buyer or Seller | Request has payment | Tier 3 | No | Auth enforced. | Authenticated | Triggers provider re-check. |
|
|
| PR-R012 | POST | /api/marketplace/purchase-requests/:id/confirm-payment | Buyer | buyerId match | Payment exists | Tier 3 | No | Auth enforced. | Authenticated (Buyer) | Legacy endpoint. |
|
|
| PR-R013 | POST | /api/marketplace/purchase-requests/:id/release-payment | Admin | None | Payment funded; escrowState=funded | Tier 6 | Yes | Auth enforced. Admin check. | Admin + Step-up + audit | Escrow release. T06: must check no active dispute. |
|
|
| PR-R014 | PUT | /api/marketplace/purchase-requests/:id/delivery | Seller (selected) | sellerId match on selectedOffer | Status in [payment, processing, delivery] | Tier 3 | No | Auth enforced. Seller check. | Authenticated (Seller) | Shipping details. |
|
|
| PR-R015 | POST | /api/marketplace/requests/:id/start-delivery | Seller (selected) | sellerId match | Status = processing | Tier 3 | No | Auth enforced. Seller check. | Authenticated (Seller) | Emits status update. |
|
|
| PR-R016 | PATCH | /api/marketplace/purchase-requests/:id/confirm-delivery | Buyer | buyerId match | Status in [delivery] | Tier 3 | No | Auth enforced. Buyer check. | Authenticated (Buyer) | Should NOT allow pre-delivery confirmation. T20. |
|
|
| PR-R017 | POST | /api/marketplace/purchase-requests/:id/final-approval | Buyer | buyerId match | Status = delivered | Tier 3 | Yes | Auth enforced. | Authenticated (Buyer) + audit | Triggers escrow release. |
|
|
| PR-R018 | GET | /api/marketplace/buyers/:buyerId/purchase-requests | Authenticated | None (admin/seller view) | None | Tier 3 | No | Auth enforced. | Authenticated | Admin or seller view of buyer history. |
|
|
|
|
### 2.6 Delivery Code Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| DC-R001 | POST | /api/marketplace/purchase-requests/:id/delivery-code/generate | Buyer | buyerId match | Status = delivery | Tier 3 | No | Auth enforced. Buyer check. | Authenticated (Buyer) | |
|
|
| DC-R002 | POST | /api/marketplace/purchase-requests/:id/delivery-code/verify | Seller (selected) | sellerId match on selectedOffer | Status = delivery; code not expired | Tier 1 | Yes | Auth enforced. NO rate limit on attempts. T20. | Authenticated (Seller) + Tier 1 | Max 5 attempts per 15 min per request. |
|
|
| DC-R003 | GET | /api/marketplace/purchase-requests/:id/delivery-code | Authenticated | Buyer or Seller | None | Tier 3 | No | Auth enforced. | Authenticated | Returns code metadata. |
|
|
| DC-R004 | GET | /api/marketplace/purchase-requests/:id/delivery-code/status | Authenticated | Buyer or Seller | None | Tier 3 | No | Auth enforced. | Authenticated | Returns validity state. |
|
|
|
|
### 2.7 Seller Offer Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| OFF-R001 | POST | /api/marketplace/purchase-requests/:id/offers | Seller | None (any seller can offer) | Request status = pending or in_negotiation | Tier 3 | No | Auth enforced. Seller role. | Authenticated (Seller) | Emits to buyer room. |
|
|
| OFF-R002 | PUT | /api/marketplace/purchase-requests/:id/offers | Seller | Offer belongs to seller | Offer status = pending | Tier 3 | No | Auth enforced. Legacy. | Authenticated (Seller) | Legacy alias. |
|
|
| OFF-R003 | GET | /api/marketplace/purchase-requests/:id/offers | Public | None | None | Tier 4 | No | No auth. | Public | Exposes all offers for a request. |
|
|
| OFF-R004 | GET | /api/marketplace/purchase-requests/:id/has-offer | Seller | None | None | Tier 3 | No | Auth enforced. Seller role. | Authenticated (Seller) | Helper for seller UI. |
|
|
| OFF-R005 | GET | /api/marketplace/purchase-requests/:id/offers/:sellerId | Public | None | None | Tier 4 | No | No auth. | Public | Specific seller's offer. |
|
|
| OFF-R006 | PATCH | /api/marketplace/offers/:id | Owner (Seller) | offer.sellerId match | offer.status = pending | Tier 3 | No | Auth enforced. Owner check. | Owner (Seller) | Must reject if status != pending. T19. |
|
|
| OFF-R007 | DELETE | /api/marketplace/offers/:id | Owner (Seller) | offer.sellerId match | offer.status = pending | Tier 3 | No | Auth enforced. Owner check. | Owner (Seller) | Withdraw offer. |
|
|
| OFF-R008 | PUT | /api/marketplace/offers/:id/status | Admin | None | Valid status transition | Tier 6 | Yes | Auth enforced. No admin gate documented. [VERIFY] | Admin + audit | Direct status mutation. T09. |
|
|
| OFF-R009 | POST | /api/marketplace/purchase-requests/:id/select-offer | Buyer | buyerId match | Request has offers; no payment yet | Tier 3 | Yes | Auth enforced. | Authenticated (Buyer) + audit | Triggers payment intent. |
|
|
| OFF-R010 | POST | /api/marketplace/offers/:id/accept | Buyer | buyerId match | Legacy compatibility | Tier 3 | No | Auth enforced. Legacy. | Authenticated (Buyer) | Legacy alias for select-offer. |
|
|
|
|
### 2.8 Request Template Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| TPL-R001 | POST | /api/marketplace/request-templates | Seller | None | None | Tier 3 | No | Auth enforced. Seller role. | Authenticated (Seller) | Creates template. |
|
|
| TPL-R002 | GET | /api/marketplace/request-templates | Seller | Owner | None | Tier 3 | No | Auth enforced. Seller's own templates. | Authenticated (Seller) | Paginated. |
|
|
| TPL-R003 | GET | /api/marketplace/request-templates/stats | Seller | Owner | None | Tier 3 | No | Auth enforced. | Authenticated (Seller) | Aggregate stats. |
|
|
| TPL-R004 | GET | /api/marketplace/request-templates/:id | Seller | Owner | Template exists | Tier 3 | No | Auth enforced. Owner check. | Authenticated (Seller) | |
|
|
| TPL-R005 | PUT | /api/marketplace/request-templates/:id | Seller | Owner | Template exists | Tier 3 | No | Auth enforced. Owner check. | Authenticated (Seller) | |
|
|
| TPL-R006 | DELETE | /api/marketplace/request-templates/:id | Seller | Owner | Template exists | Tier 3 | No | Auth enforced. Owner check. | Authenticated (Seller) | |
|
|
| TPL-R007 | PATCH | /api/marketplace/request-templates/:id/toggle-status | Seller | Owner | Template exists | Tier 3 | No | Auth enforced. Owner check. | Authenticated (Seller) | |
|
|
| TPL-R008 | GET | /api/marketplace/request-templates/public/:shareableLink | Public | None | Template active and not expired | Tier 4 | No | No auth. Public read. | Public | Shop preview page. |
|
|
| TPL-R009 | POST | /api/marketplace/request-templates/:shareableLink/convert | Buyer | None | Template active and not expired | Tier 3 | No | Auth enforced. | Authenticated (Buyer) | Creates PurchaseRequest. |
|
|
| TPL-R010 | POST | /api/marketplace/request-templates/batch-convert | Buyer | None | Templates active and not expired | Tier 3 | No | Auth enforced. | Authenticated (Buyer) | Cart checkout. |
|
|
| TPL-R011 | POST | /api/marketplace/request-templates/complete-payment | Authenticated | Buyer | Requests exist; payment data provided | Tier 3 | No | Auth enforced. | Authenticated | Marks batch requests as paid. |
|
|
|
|
### 2.9 Shop Settings Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| SHOP-R001 | GET | /api/marketplace/shop/settings/:sellerId | Public | None | None | Tier 4 | No | No auth. Public read. | Public | Shop landing page. |
|
|
| SHOP-R002 | GET | /api/marketplace/shop/settings | Seller | Owner | None | Tier 3 | No | Auth enforced. Seller role. | Authenticated (Seller) | Own settings. |
|
|
| SHOP-R003 | PUT | /api/marketplace/shop/settings | Seller | Owner | None | Tier 3 | No | Auth enforced. Seller role. | Authenticated (Seller) | |
|
|
|
|
### 2.10 Category and Seller Directory Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| CAT-R001 | GET | /api/marketplace/categories | Public | None | None | Tier 4 | No | No auth. | Public | |
|
|
| CAT-R002 | GET | /api/marketplace/categories/tree | Public | None | None | Tier 4 | No | No auth. | Public | Nested tree. |
|
|
| CAT-R003 | GET | /api/marketplace/categories/:id | Public | None | Category exists | Tier 4 | No | No auth. | Public | |
|
|
| CAT-R004 | GET | /api/marketplace/sellers | Public | None | None | Tier 4 | No | No auth. | Public | Seller directory. |
|
|
| CAT-R005 | GET | /api/marketplace/request-templates/sellers | Public | None | None | Tier 4 | No | No auth. | Public | Sellers with active templates. |
|
|
| CAT-R006 | GET | /api/marketplace/request-templates/sellers/:sellerId | Public | None | Seller has active templates | Tier 4 | No | No auth. | Public | Shop profile page. |
|
|
|
|
### 2.11 Review Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| REV-R001 | GET | /api/marketplace/reviews/:subjectType/:subjectId | Public | None | Reviews enabled by seller | Tier 4 | No | No auth. | Public | Paginated. |
|
|
| REV-R002 | GET | /api/marketplace/reviews/:subjectType/:subjectId/summary | Public | None | Reviews enabled | Tier 4 | No | No auth. | Public | Stats only. |
|
|
| REV-R003 | POST | /api/marketplace/reviews | Authenticated | None (one review per user per subject) | Subject exists; reviews enabled; no duplicate | Tier 3 | No | Auth enforced. | Authenticated | Computes isVerifiedBuyer. |
|
|
|
|
### 2.12 Payment Routes (General)
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| PAY-R001 | POST | /api/payment/configuration | Public | None | None | Tier 4 | No | No auth. | Public | Returns widget config. |
|
|
| PAY-R002 | GET | /api/payment/health | Public | None | None | Tier 4 | No | No auth. | Public | Health probe. |
|
|
| PAY-R003 | GET | /api/payment/shkeeper/config | Public | None | None | Tier 4 | No | No auth. CORS *. | Public | SHKeeper widget config. |
|
|
| PAY-R004 | POST | /api/payment | Authenticated | Buyer or Admin | purchaseRequestId, sellerOfferId valid | Tier 2 | Yes | Auth enforced. | Authenticated + audit | Manual payment creation. |
|
|
| PAY-R005 | PUT | /api/payment/:id | Authenticated | Owner or Admin | Payment exists | Tier 2 | Yes | Auth enforced. | Authenticated + audit | Status mutation. |
|
|
| PAY-R006 | GET | /api/payment | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Caller's payments. |
|
|
| PAY-R007 | GET | /api/payment/:id | Authenticated | Owner or Admin | Payment exists | Tier 3 | No | Auth enforced. [VERIFY] ownership | Authenticated | |
|
|
| PAY-R008 | GET | /api/payment/:id/debug | Admin | None | Payment exists | Tier 6 | No | Auth enforced. Admin intended. [VERIFY] | Admin | Debug bundle. |
|
|
| PAY-R009 | GET | /api/payment/user/:userId | Authenticated | Owner or Admin | User exists | Tier 3 | No | Auth enforced. Ownership check [VERIFY]. | Authenticated | Payments for user. |
|
|
| PAY-R010 | GET | /api/payment/stats | Authenticated | Owner or Admin | None | Tier 3 | No | Auth enforced. | Authenticated | Aggregated stats. |
|
|
| PAY-R011 | GET | /api/payment/stats/:userId | Authenticated | Owner or Admin | User exists | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| PAY-R012 | GET | /api/payment/export | Authenticated | Owner | None | Tier 3 | Yes | Auth enforced. | Authenticated + audit | Financial data export. |
|
|
| PAY-R013 | GET | /api/payment/export/:userId | Admin | None | User exists | Tier 6 | Yes | Auth enforced. Admin check [VERIFY]. | Admin + audit | Export other user's payments. |
|
|
| PAY-R014 | POST | /api/payment/payments/cleanup-pending | Admin | None | None | Tier 6 | Yes | Auth enforced. Admin. | Admin + audit | Deletes stale payments. |
|
|
| PAY-R015 | POST | /api/payment/payments/:id/fetch-tx | Admin | None | Payment exists | Tier 6 | No | Auth enforced. [VERIFY] admin gate. | Admin | Re-queries chain. |
|
|
| PAY-R016 | POST | /api/payment/payments/auto-fetch-missing | Admin | None | None | Tier 6 | No | Auth enforced. [VERIFY] admin gate. | Admin | Batch backfill. |
|
|
| PAY-R017 | POST | /api/payment/callback | Service | paymentRef match | None | Tier 5 | Yes | No user auth. paymentRef-based. | Service | Generic callback. [VERIFY] security of paymentRef. |
|
|
| PAY-R018 | POST | /api/payment/verify | Authenticated | Buyer | Payment exists | Tier 2 | Yes | Auth enforced. | Authenticated (Buyer) + audit | Frontend Web3 verification. |
|
|
|
|
### 2.13 Payment Routes (SHKeeper Pay-in)
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| SHK-R001 | POST | /api/payment/shkeeper/intents | Authenticated (Buyer) | Buyer on the purchase request | Request and offer exist; no existing payment | Tier 2 | Yes | Auth enforced. Buyer check. | Authenticated (Buyer) + audit | Creates pay-in intent. |
|
|
| SHK-R002 | POST | /api/payment/shkeeper/webhook | HMAC | None | Signature valid; payment exists | Tier 5 | Yes | HMAC verification. Returns 202 on all errors. T02. | HMAC + proper error codes + audit | Must return 400/500 not just 202. |
|
|
| SHK-R003 | POST | /api/payment/shkeeper/confirm-transaction | Authenticated | Buyer | Payment exists; not already completed | Tier 2 | Yes | Auth enforced. | Authenticated (Buyer) + audit | Manual fallback. |
|
|
| SHK-R004 | POST | /api/payment/shkeeper/test | Service | None | NODE_ENV=development | Tier 1 | No | No auth. Dev only. | Disable in production | T01, T11. |
|
|
| SHK-R005 | POST | /api/payment/shkeeper/callback-test | Service | None | NODE_ENV=development | Tier 1 | No | No auth. Dev only. | Disable in production | Echo endpoint. |
|
|
| SHK-R006 | GET | /api/payment/shkeeper/callback-test | Service | None | NODE_ENV=development | Tier 1 | No | No auth. Dev only. | Disable in production | GET equivalent. |
|
|
| SHK-R007 | POST | /api/payment/shkeeper/create-test-payment | Service | None | NODE_ENV=development | Tier 1 | No | NO AUTH. Exposed in production. T11, T21. | Disable in production | Injects fake payment records. |
|
|
| SHK-R008 | POST | /api/payment/shkeeper/trigger-webhook | Authenticated | None | None | Tier 2 | No | Auth enforced. | Authenticated | Sends fake webhook. Dev tool. |
|
|
| SHK-R009 | GET | /api/payment/shkeeper/wallet-monitor/status | Public | None | None | Tier 4 | No | No auth. | Public | Monitor state. |
|
|
| SHK-R010 | GET | /api/payment/shkeeper/auto-webhook/status | Public | None | None | Tier 4 | No | No auth. | Public | Fallback monitor state. |
|
|
| SHK-R011 | GET | /api/payment/shkeeper/webhook-stats | Admin | None | None | Tier 6 | No | Auth enforced. Admin. | Admin | Webhook telemetry. |
|
|
|
|
### 2.14 Payment Routes (SHKeeper Release/Refund)
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| REL-R001 | POST | /api/payment/shkeeper/:id/release | Admin | None | Payment funded; no active dispute (T06); escrowState=funded | Tier 6 | Yes | Auth enforced. Admin. NO dispute check. T06. | Admin + Step-up + dispute check + audit, + two-person approval for payout > 1000 USD equivalent (see APV-R002/APV-R003) | Builds release tx payload. |
|
|
| REL-R002 | POST | /api/payment/shkeeper/:id/release/confirm | Admin | None | Release tx pending; valid txHash | Tier 6 | Yes | Auth enforced. Admin. | Admin + Step-up + audit | Confirms release on-chain. |
|
|
| REL-R003 | POST | /api/payment/shkeeper/:id/refund | Admin | None | Payment funded; no active dispute; escrowState=funded | Tier 6 | Yes | Auth enforced. Admin. NO dispute check. T06. | Admin + Step-up + dispute check + audit, + two-person approval for payout > 1000 USD equivalent (see APV-R002/APV-R003) | Builds refund tx. |
|
|
| REL-R004 | POST | /api/payment/shkeeper/:id/refund/confirm | Admin | None | Refund tx pending; valid txHash | Tier 6 | Yes | Auth enforced. Admin. | Admin + Step-up + audit | Confirms refund on-chain. |
|
|
|
|
### 2.15 Payment Routes (SHKeeper Payout)
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| PO-R001 | POST | /api/payment/shkeeper/payout | Admin | None | No existing pending payout for same escrow | Tier 6 | Yes | Auth enforced. Admin. | Admin + Step-up + audit, + two-person approval for payout > 1000 USD equivalent (see APV-R002/APV-R003) | Creates payout task. T05. |
|
|
| PO-R002 | GET | /api/payment/shkeeper/payout/status/:taskId | Authenticated | Owner or Admin | Task exists | Tier 3 | No | Auth enforced. | Authenticated | Poll payout status. |
|
|
| PO-R003 | POST | /api/payment/shkeeper/payout/webhook | HMAC | None | Signature valid | Tier 5 | Yes | HMAC verification. | HMAC + audit | Payout state changes. |
|
|
|
|
### 2.16 Payment Routes (Decentralized / Web3)
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| DEC-R001 | POST | /api/payment/decentralized/save | Authenticated (Buyer) | Buyer on referenced purchase request | Request exists | Tier 2 | Yes | NO AUTH. T11, T21. Critical gap. | Authenticated (Buyer) + audit | Persists Web3 payment. |
|
|
| DEC-R002 | GET | /api/payment/decentralized/status/:paymentId | Authenticated | Owner or Admin | Payment exists | Tier 3 | No | NO AUTH. T21. | Authenticated | Payment status. |
|
|
| DEC-R003 | PUT | /api/payment/decentralized/update | Authenticated (Buyer) | Buyer on referenced purchase request | Payment exists | Tier 2 | Yes | NO AUTH. T11. | Authenticated (Buyer) + audit | Updates payment status/confirmations. |
|
|
| DEC-R004 | GET | /api/payment/decentralized/receiver | Public | None | None | Tier 4 | No | No auth. Public escrow address. | Public | Returns escrow wallet. |
|
|
| DEC-R005 | GET | /api/payment/decentralized/history/:userId | Authenticated | Owner or Admin | User exists | Tier 3 | No | NO AUTH. T21. Critical gap. | Authenticated | Payment history. |
|
|
| DEC-R006 | POST | /api/payment/decentralized/verify/:paymentId | Authenticated | Buyer or Admin | Payment exists; pending status | Tier 2 | Yes | NO AUTH. T01, T11. | Authenticated + audit | Re-verifies on chain. Must decode Transfer event. |
|
|
| DEC-R007 | POST | /api/payment/decentralized/verify-all-pending | Admin | None | None | Tier 6 | Yes | NO AUTH. T11. | Admin + audit | Batch verification. |
|
|
| DEC-R008 | POST | /api/payment/decentralized/admin-payout | Admin | None | Valid request; valid wallet | Tier 6 | Yes | Auth enforced. Admin. | Admin + Step-up + audit | Direct wallet payout. |
|
|
|
|
### 2.17 Marketplace Payment Routes (Legacy)
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| MPAY-R001 | POST | /api/marketplace/payments | Authenticated | Buyer | Valid request/offer | Tier 2 | Yes | Auth enforced. | Authenticated + audit | Legacy. Prefer PAY-R004. |
|
|
| MPAY-R002 | GET | /api/marketplace/payments | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Legacy. |
|
|
| MPAY-R003 | GET | /api/marketplace/payments/:paymentId | Authenticated | Owner or Admin | Payment exists | Tier 3 | No | Auth enforced. | Authenticated | Legacy. |
|
|
| MPAY-R004 | PATCH | /api/marketplace/payments/:paymentId | Authenticated | Owner or Admin | Payment exists | Tier 2 | Yes | Auth enforced. | Authenticated + audit | Legacy. |
|
|
| MPAY-R005 | POST | /api/marketplace/payments/verify | Authenticated (Buyer) | Buyer on purchase request | Valid request/offer | Tier 2 | Yes | Auth enforced. | Authenticated (Buyer) + audit | Legacy Web3 verification. |
|
|
|
|
### 2.18 Chat Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| CHAT-R001 | POST | /api/chat | Authenticated | None | 2+ participant IDs | Tier 3 | No | Auth enforced. | Authenticated | Creates chat. |
|
|
| CHAT-R002 | POST | /api/chat/purchase-request | Authenticated | Buyer or Seller on request | Request exists | Tier 3 | No | Auth enforced. | Authenticated | Idempotent. |
|
|
| CHAT-R003 | POST | /api/chat/support | Authenticated | None | None | Tier 3 | No | Auth enforced. | Authenticated | Support chat. |
|
|
| CHAT-R004 | GET | /api/chat | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Caller's chats. |
|
|
| CHAT-R005 | GET | /api/chat/stats | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Aggregate counts. |
|
|
| CHAT-R006 | GET | /api/chat/:id/info | Authenticated | Participant | Chat exists; user in participants | Tier 3 | No | Auth enforced. Participant check. | Authenticated | Chat metadata. |
|
|
| CHAT-R007 | PATCH | /api/chat/:id/archive | Authenticated | Participant | Chat exists | Tier 3 | No | Auth enforced. | Authenticated | Toggle archive. |
|
|
| CHAT-R008 | POST | /api/chat/:id/participants | Authenticated | Creator or Admin | Chat is group type | Tier 3 | No | Auth enforced. | Authenticated | Add participant. |
|
|
| CHAT-R009 | DELETE | /api/chat/:id/participants/:participantId | Authenticated | Creator or Admin | Chat is group type | Tier 3 | No | Auth enforced. | Authenticated | Remove participant. |
|
|
| CHAT-R010 | GET | /api/chat/:id/messages | Authenticated | Participant | Chat exists | Tier 3 | No | Auth enforced. Participant check. | Authenticated | Paginated messages. |
|
|
| CHAT-R011 | POST | /api/chat/:id/messages | Authenticated | Participant | Chat exists | Tier 3 | No | Auth enforced. Participant check. | Authenticated | Send text message. |
|
|
| CHAT-R012 | POST | /api/chat/:id/messages/file | Authenticated | Participant | Chat exists; file within limits | Tier 2 | No | Auth enforced. Participant check. | Authenticated | File attachment. |
|
|
| CHAT-R013 | PATCH | /api/chat/:id/messages/read | Authenticated | Participant | Chat exists | Tier 3 | No | Auth enforced. | Authenticated | Mark as read. |
|
|
| CHAT-R014 | PUT | /api/chat/:id/messages/:messageId | Authenticated | Message author | Message exists; within edit window | Tier 3 | No | Auth enforced. Author check. | Authenticated | Edit message. |
|
|
| CHAT-R015 | DELETE | /api/chat/:id/messages/:messageId | Authenticated | Author or Admin | Message exists | Tier 3 | No | Auth enforced. Author or admin. | Authenticated | Soft-delete. |
|
|
|
|
### 2.19 Notification Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| NOTIF-R001 | GET | /api/notifications | Authenticated | Owner | None | Tier 3 | No | Controller route: auth enforced. Legacy route: NO AUTH, ?userId= param. T21. | Authenticated | Legacy router must be removed or gated. |
|
|
| NOTIF-R002 | GET | /api/notifications/unread-count | Authenticated | Owner | None | Tier 3 | No | Controller route: auth enforced. | Authenticated | |
|
|
| NOTIF-R003 | GET | /api/notifications/:id | Authenticated | Owner | Notification belongs to user | Tier 3 | No | Controller route: auth enforced. | Authenticated | |
|
|
| NOTIF-R004 | PATCH | /api/notifications/:id/read | Authenticated | Owner | Notification belongs to user | Tier 3 | No | Controller: auth. Legacy: { userId } in body. T21. | Authenticated | Legacy path must be removed. |
|
|
| NOTIF-R005 | PATCH | /api/notifications/mark-all-read | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| NOTIF-R006 | PATCH | /api/notifications/bulk/mark-read | Authenticated | Owner | All IDs belong to user | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| NOTIF-R007 | DELETE | /api/notifications/:id | Authenticated | Owner | Notification belongs to user | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| NOTIF-R008 | DELETE | /api/notifications/bulk/delete | Authenticated | Owner | All IDs belong to user | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| NOTIF-R009 | POST | /api/notifications | Authenticated | None (creates for any userId) | None | Tier 3 | Yes | Controller: auth. Legacy: OPEN. T21. | Authenticated (Admin or Service) + audit | Should restrict who can create notifications for other users. |
|
|
|
|
### 2.20 Dispute Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| DIS-R001 | POST | /api/disputes | Authenticated | Buyer or Seller on request | Request exists; no open dispute for same request | Tier 3 | Yes | Auth enforced. Participant check. | Authenticated + audit | Must set escrowState=disputed. T06. |
|
|
| DIS-R002 | GET | /api/disputes | Authenticated | Owner or Admin | None | Tier 3 | No | Auth enforced. | Authenticated | Own disputes or all (admin). |
|
|
| DIS-R003 | GET | /api/disputes/statistics | Admin | None | None | Tier 6 | No | Auth enforced. Admin. | Admin | Dashboard data. |
|
|
| DIS-R004 | GET | /api/disputes/:id | Authenticated | Participant or Admin | Dispute exists | Tier 3 | No | Auth enforced. Participant or admin check. | Authenticated | |
|
|
| DIS-R005 | POST | /api/disputes/:id/assign | Admin | None | Dispute exists; status=open | Tier 6 | Yes | Auth enforced. Admin. | Admin + audit | Assigns moderator. |
|
|
| DIS-R006 | PATCH | /api/disputes/:id/status | Admin | None | Valid status transition | Tier 6 | Yes | Auth enforced. Admin. | Admin + audit | Status update. |
|
|
| DIS-R007 | POST | /api/disputes/:id/resolve | Admin | None | Dispute in under_review status; no pending payout | Tier 6 | Yes | Auth enforced. Admin. | Admin + Step-up + audit | Triggers escrow release/refund. T06. |
|
|
| DIS-R008 | POST | /api/disputes/:id/evidence | Authenticated | Participant or Admin | Dispute exists; not closed | Tier 3 | No | Auth enforced. Participant or admin check. | Authenticated | Attach evidence. |
|
|
|
|
### 2.21 AI Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| AI-R001 | POST | /api/ai/generate | Authenticated | None | None | Tier 2 | No | NO AUTH. T08. Cost abuse. | Authenticated | OpenAI cost-bearing. |
|
|
| AI-R002 | POST | /api/ai/analyze | Authenticated | None | None | Tier 2 | No | NO AUTH. T08. | Authenticated | Moderation/sentiment. |
|
|
| AI-R003 | POST | /api/ai/translate | Authenticated | None | None | Tier 2 | No | NO AUTH. T08. | Authenticated | Translation. |
|
|
| AI-R004 | POST | /api/ai/assist | Authenticated | None | None | Tier 2 | No | NO AUTH. T08. | Authenticated | Conversational assistant. |
|
|
|
|
### 2.22 Blog Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| BLOG-R001 | GET | /api/blog/posts | Public | None | None | Tier 4 | No | No auth. Public. | Public | Paginated. |
|
|
| BLOG-R002 | GET | /api/blog/posts/featured | Public | None | None | Tier 4 | No | No auth. | Public | |
|
|
| BLOG-R003 | GET | /api/blog/posts/recent | Public | None | None | Tier 4 | No | No auth. | Public | |
|
|
| BLOG-R004 | GET | /api/blog/posts/search | Public | None | q.length >= 2 | Tier 4 | No | No auth. | Public | |
|
|
| BLOG-R005 | GET | /api/blog/posts/:slug | Public | None | Post published | Tier 4 | No | No auth. Increments viewsCount on GET. | Public | Move view count to separate beacon. |
|
|
| BLOG-R006 | GET | /api/blog/admin/posts | Admin | None | None | Tier 6 | No | Auth enforced. Admin. | Admin | Includes drafts. |
|
|
| BLOG-R007 | GET | /api/blog/admin/posts/:id | Admin | None | Post exists | Tier 6 | No | Auth enforced. Admin. | Admin | |
|
|
| BLOG-R008 | POST | /api/blog/posts | Admin | None | None | Tier 6 | Yes | Auth enforced. Admin. | Admin + audit | Create post. |
|
|
| BLOG-R009 | PUT | /api/blog/posts/:id | Admin | None | Post exists | Tier 6 | Yes | Auth enforced. Admin. | Admin + audit | Update post. |
|
|
| BLOG-R010 | DELETE | /api/blog/posts/:id | Admin | None | Post exists | Tier 6 | Yes | Auth enforced. Admin. | Admin + audit | Hard delete. |
|
|
|
|
### 2.23 Points Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| PTS-R001 | GET | /api/points/my-points | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Balance and level. |
|
|
| PTS-R002 | GET | /api/points/transactions | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Paginated ledger. |
|
|
| PTS-R003 | GET | /api/points/referrals | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | Referral history. |
|
|
| PTS-R004 | GET | /api/points/levels | Authenticated | None | None | Tier 3 | No | Auth enforced. Data is non-sensitive. | Authenticated | Level config list. |
|
|
| PTS-R005 | GET | /api/points/leaderboard | Authenticated | None | None | Tier 3 | No | Auth enforced. | Authenticated | Top referrers. |
|
|
| PTS-R006 | POST | /api/points/redeem | Authenticated | Owner | Sufficient balance | Tier 2 | Yes | Auth enforced. | Authenticated + audit | Redeems points. |
|
|
| PTS-R007 | POST | /api/points/generate-referral-code | Authenticated | Owner | None | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| PTS-R008 | POST | /api/points/admin/add | Admin | None | Target user exists; amount valid | Tier 6 | Yes | Auth enforced. Admin. | Admin + audit | Grant/deduct points. |
|
|
|
|
### 2.24 File Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| FILE-R001 | POST | /api/files/upload/avatar | Authenticated | Owner | File within size/type limits | Tier 2 | No | Auth enforced. | Authenticated | |
|
|
| FILE-R002 | POST | /api/files/upload/file | Authenticated | Owner | File within limits | Tier 2 | No | Auth enforced. | Authenticated | Generic upload. |
|
|
| FILE-R003 | POST | /api/files/upload/files | Authenticated | Owner | Up to 5 files; within limits | Tier 2 | No | Auth enforced. | Authenticated | Multi-file. |
|
|
| FILE-R004 | POST | /api/files/upload/request-template-images | Authenticated (Seller) | Owner | Up to 10 images; valid types | Tier 2 | No | Auth enforced. Seller role. | Authenticated (Seller) | Template images. |
|
|
| FILE-R005 | POST | /api/files/upload/blog-images | Admin | None | Up to 10 images; valid types | Tier 2 | No | Auth enforced. [VERIFY] admin gate. | Admin | Blog images. |
|
|
| FILE-R006 | DELETE | /api/files/delete | Authenticated | Owner (uploader) | File exists; path within uploads/ | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| FILE-R007 | GET | /api/files/info/:filePath | Authenticated | None | File exists | Tier 3 | No | Auth enforced. | Authenticated | |
|
|
| FILE-R008 | GET | /api/files/stats | Admin | None | None | Tier 6 | No | Auth enforced. Admin gating planned. | Admin | Upload statistics. |
|
|
| FILE-R009 | GET | /uploads/* | Public | None | File exists | Tier 4 | No | No auth. Static serving. | Public | No auth on file access. Sensitive dispute evidence is accessible. |
|
|
|
|
### 2.25 Admin Data Cleanup Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| ADM-R001 | GET | /api/admin/cleanup/stats | Admin | None | None | Tier 6 | No | Auth + role enforced. | Admin | Collection stats. |
|
|
| ADM-R002 | GET | /api/admin/cleanup/collections | Admin | None | None | Tier 6 | No | Auth + role enforced. | Admin | Collection list. |
|
|
| ADM-R003 | POST | /api/admin/cleanup/clean | Admin | None | confirm="DELETE_ALL_DATA" for real execution | Tier 6 | Yes | Auth + role enforced. | Admin + Step-up + audit | Bulk delete. |
|
|
| ADM-R004 | DELETE | /api/admin/cleanup/user/:userId | Admin | Cannot delete self | confirm=DELETE_USER_DATA | Tier 6 | Yes | Auth + role enforced. | Admin + Step-up + audit | GDPR deletion. |
|
|
| ADM-R005 | POST | /api/admin/cleanup/temp | Admin | None | None | Tier 6 | Yes | Auth + role enforced. | Admin + audit | Purge temp data. |
|
|
| ADM-R006 | POST | /api/admin/cleanup/seed-templates | Admin | None | None | Tier 6 | No | Auth + role enforced. | Admin | Re-seed templates. |
|
|
| ADM-R007 | POST | /api/admin/cleanup/seed-all | Admin | None | None | Tier 6 | No | Auth + role enforced. | Admin | Full seed. |
|
|
|
|
### 2.26 Health and Discovery Routes
|
|
|
|
| ID | Method | Path | Access Level | Ownership Check | State Preconditions | Rate-Limit Tier | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| SYS-R001 | GET | /health | Public | None | None | Tier 4 | No | Public. | Public | Docker healthcheck. |
|
|
| SYS-R002 | GET | /api | Public | None | None | Tier 4 | No | Public. | Public | API discovery. |
|
|
|
|
---
|
|
|
|
## Section 3: Socket.IO Event Authorization Matrix
|
|
|
|
### 3.1 Connection and Handshake Events
|
|
|
|
| ID | Event Name | Direction | Access Level | Room Membership | Payload Restrictions | Rate-Limit | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| SOCK-E001 | `connection` | Client -> Server | Authenticated | None at connect; rooms joined after | JWT in handshake.auth.token | N/A | No | JWT verified; invalid token disconnects. [VERIFY] enforcement. | Authenticated | Server sets socket.data.user. |
|
|
| SOCK-E002 | `disconnect` | Client -> Server | Authenticated | All rooms left | None | N/A | No | No user-offline broadcast. | Authenticated | Should emit user-status-change offline. |
|
|
|
|
### 3.2 Room Join Events
|
|
|
|
| ID | Event Name | Direction | Access Level | Room Membership | Payload Restrictions | Rate-Limit | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| SOCK-E003 | `join-user-room` | Client -> Server | Authenticated | `user-{userId}` | userId MUST equal socket.data.user.id | Tier 3 | No | Client-supplied userId. Server verification UNCERTAIN. T03. | Server-derived; remove client event | Server should auto-join on handshake. T03. |
|
|
| SOCK-E004 | `join-request-room` | Client -> Server | Authenticated | `request-{requestId}` | User must be participant (buyer or selected seller) of request | Tier 3 | No | Client-supplied requestId. Server verification UNCERTAIN. T03. | Authenticated + participant check | Must verify user is buyer/seller on request. |
|
|
| SOCK-E005 | `leave-request-room` | Client -> Server | Authenticated | Leaves `request-{requestId}` | User must currently be in room | Tier 3 | No | Client-supplied. [VERIFY] auth. | Authenticated | |
|
|
| SOCK-E006 | `join-seller-room` | Client -> Server | Authenticated (Seller) | `seller-{sellerId}` + `sellers` | sellerId MUST equal socket.data.user.id; user role must include seller | Tier 3 | No | Client-supplied sellerId. Server verification UNCERTAIN. T03. | Server-derived from JWT role + id | Auto-join if role=seller. |
|
|
| SOCK-E007 | `leave-seller-room` | Client -> Server | Authenticated (Seller) | Leaves both | Must currently be in room | Tier 3 | No | Client-supplied. | Authenticated | |
|
|
| SOCK-E008 | `join-buyer-room` | Client -> Server | Authenticated (Buyer) | `buyer-{buyerId}` + `buyers` | buyerId MUST equal socket.data.user.id; user role must include buyer | Tier 3 | No | Client-supplied buyerId. Server verification UNCERTAIN. T03. | Server-derived from JWT role + id | Auto-join if role=buyer. |
|
|
| SOCK-E009 | `leave-buyer-room` | Client -> Server | Authenticated (Buyer) | Leaves both | Must currently be in room | Tier 3 | No | Client-supplied. | Authenticated | |
|
|
| SOCK-E010 | `join-chat-room` | Client -> Server | Authenticated | `chat-{chatId}` | User must be in chat.participants | Tier 3 | No | Client-supplied chatId. Server verification UNCERTAIN. T03. | Authenticated + participant check | Must verify membership. |
|
|
| SOCK-E011 | `leave-chat-room` | Client -> Server | Authenticated | Leaves `chat-{chatId}` | Must currently be in room | Tier 3 | No | Client-supplied. | Authenticated | |
|
|
|
|
### 3.3 Chat Events
|
|
|
|
| ID | Event Name | Direction | Access Level | Room Membership | Payload Restrictions | Rate-Limit | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| SOCK-E012 | `typing-start` | Client -> Server | Authenticated | Must be in `chat-{chatId}` | chatId, userId, userName; userId must match socket | Tier 3 | No | No auth documented on event handler. | Authenticated + room member | Broadcasts to chat room. |
|
|
| SOCK-E013 | `typing-stop` | Client -> Server | Authenticated | Must be in `chat-{chatId}` | chatId, userId; userId must match socket | Tier 3 | No | No auth documented. | Authenticated + room member | |
|
|
|
|
### 3.4 Presence Events
|
|
|
|
| ID | Event Name | Direction | Access Level | Room Membership | Payload Restrictions | Rate-Limit | Audit Log | Current State | Required State | Notes |
|
|
|---|---|---|---|---|---|---|---|---|---|---|
|
|
| SOCK-E014 | `user-online` | Client -> Server | Authenticated | Joins `user-{userId}` | userId must match socket.data.user.id | Tier 3 | No | Client-supplied. Broadcasts user-status-change. | Authenticated | Should be server-derived. |
|
|
|
|
### 3.5 Server-to-Client Events (Emission Authorization)
|
|
|
|
Server-to-client events are emitted by backend services after REST-level authorization. The socket layer does NOT re-authorize emissions; it relies on room membership to limit audience. This table documents which rooms receive which events and what data they contain.
|
|
|
|
| ID | Event Name | Direction | Emitted By | Target Rooms | Payload Sensitivity | Audit Log | Notes |
|
|
|---|---|---|---|---|---|---|---|
|
|
| SOCK-E015 | `new-notification` | Server -> Client | NotificationService | `user-{recipientId}` | Contains notification body; PII if notification content includes it | No | Relies on correct room membership. |
|
|
| SOCK-E016 | `unread-count-update` | Server -> Client | NotificationService | `user-{userId}` | Low (count only) | No | |
|
|
| SOCK-E017 | `new-purchase-request` | Server -> Client | PurchaseRequestService | `sellers` | Contains request details; some fields may be sensitive | No | Broadcast to all sellers. |
|
|
| SOCK-E018 | `new-offer` | Server -> Client | SellerOfferService | `buyer-{buyerId}` | Contains offer price; financial data | No | |
|
|
| SOCK-E019 | `seller-offer-update` | Server -> Client | SellerOfferService | `seller-{sellerId}` + global on payment | Contains offer status and payment info | No | Global emit leaks data. |
|
|
| SOCK-E020 | `purchase-request-update` | Server -> Client | PurchaseRequestService | `request-{requestId}` | Contains status and tx hashes | No | |
|
|
| SOCK-E021 | `request-cancelled` | Server -> Client | PurchaseRequestService | `user-{buyerId}`, `user-{sellerId}` | Contains request ID | No | |
|
|
| SOCK-E022 | `transaction-completed` | Server -> Client | MarketplaceController | `user-{buyerId}`, `user-{sellerId}` | Contains amount and currency | No | |
|
|
| SOCK-E023 | `delivery-code-generated` | Server -> Client | DeliveryService | `request-{requestId}` | Contains 6-digit code. HIGH sensitivity. | No | Code exposed to room; only seller should see it. |
|
|
| SOCK-E024 | `delivery-update` | Server -> Client | DeliveryService | `request-{requestId}` | Contains carrier/tracking | No | |
|
|
| SOCK-E025 | `delivery-confirmed` | Server -> Client | DeliveryService | `request-{requestId}` | Contains request ID only | No | |
|
|
| SOCK-E026 | `buyer-confirmed-delivery` | Server -> Client | DeliveryService | `user-{sellerId}` | Contains buyerId | No | |
|
|
| SOCK-E027 | `payment-created` | Server -> Client | PaymentService | Global | Contains paymentId, amount, currency, parties | No | Global emit leaks financial metadata. |
|
|
| SOCK-E028 | `payment-received` | Server -> Client | PaymentRoutes | `user-{sellerId}` | Contains amount, buyerId | No | |
|
|
| SOCK-E029 | `payment-update` | Server -> Client | PaymentCoordinator | Global + room-specific | Contains status, escrowState, txHash | No | Global emit is too broad. |
|
|
| SOCK-E030 | `payout-created` | Server -> Client | PayoutService | Global | Contains payoutId, sellerId, amount | No | Global emit. Should be targeted. |
|
|
| SOCK-E031 | `payout-completed` | Server -> Client | PayoutService | Global, `user-{sellerId}` | Contains txHash | No | |
|
|
| SOCK-E032 | `payout-updated` | Server -> Client | PayoutService | Global | Contains status | No | |
|
|
| SOCK-E033 | `new-message` | Server -> Client | ChatService | `chat-{chatId}` | Contains message content; potentially sensitive | No | |
|
|
| SOCK-E034 | `messages-read` | Server -> Client | ChatService | `chat-{chatId}` | Low (read receipt) | No | |
|
|
| SOCK-E035 | `message-edited` | Server -> Client | ChatService | `chat-{chatId}` | Contains new content | No | |
|
|
| SOCK-E036 | `message-deleted` | Server -> Client | ChatService | `chat-{chatId}` | Low (messageId) | No | |
|
|
| SOCK-E037 | `participants-added` | Server -> Client | ChatService | `chat-{chatId}` | Contains user IDs | No | |
|
|
| SOCK-E038 | `participant-removed` | Server -> Client | ChatService | `chat-{chatId}` | Contains user ID | No | |
|
|
| SOCK-E039 | `user-typing` | Server -> Client | Socket handler | `chat-{chatId}` | Contains userId, userName | No | |
|
|
| SOCK-E040 | `user-status-change` | Server -> Client | Socket handler | Broadcast | Contains userId, lastSeen | No | |
|
|
| SOCK-E041 | `level-up` | Server -> Client | PointsService | `user-{userId}` | Low (level info) | No | |
|
|
| SOCK-E042 | `referral-reward` | Server -> Client | PointsService | `user-{referrerId}` | Contains points earned | No | |
|
|
| SOCK-E043 | `referral-signup` | Server -> Client | AuthController | `user-{referrerId}` | Contains referred user info | No | |
|
|
| SOCK-E044 | `template-checkout-payment-confirmed` | Server -> Client | PaymentCoordinator | Global + `template-checkout-{id}` | Contains paymentId, requestIds | No | Global emit. |
|
|
| SOCK-E045 | `template-checkout-payment-pending` | Server -> Client | PaymentCoordinator | Global | Contains checkoutId | No | Global emit. |
|
|
| SOCK-E046 | `template-checkout-payment-failed` | Server -> Client | PaymentCoordinator | Global | Contains checkoutId, reason | No | Global emit. |
|
|
|
|
---
|
|
|
|
## Section 4: Current Gaps and Required Fixes
|
|
|
|
### 4.1 CRITICAL -- Authentication Missing but Required
|
|
|
|
| Gap ID | Endpoint / Event | Threat IDs | Description | Impact |
|
|
|---|---|---|---|---|
|
|
| GAP-C001 | POST /api/payment/decentralized/save | T11, T21 | No authentication. Anyone can persist Web3 payment records. | Payment fraud; data poisoning |
|
|
| GAP-C002 | PUT /api/payment/decentralized/update | T11 | No authentication. Anyone can update decentralized payment status/confirmations. | Payment status manipulation |
|
|
| GAP-C003 | GET /api/payment/decentralized/history/:userId | T21 | No authentication. Anyone can read any user's payment history. | Privacy breach; data exfiltration |
|
|
| GAP-C004 | POST /api/payment/decentralized/verify/:paymentId | T01, T11 | No authentication. Anyone can trigger chain re-verification. | DoS; payment fraud if verification is flawed |
|
|
| GAP-C005 | POST /api/payment/decentralized/verify-all-pending | T11 | No authentication. Anyone can trigger batch verification. | DoS; resource exhaustion |
|
|
| GAP-C006 | GET /api/payment/decentralized/status/:paymentId | T21 | No authentication. Payment status exposed. | Information disclosure |
|
|
| GAP-C007 | POST /api/payment/shkeeper/create-test-payment | T11, T21 | No authentication. Injects fake payment records. | Data poisoning in production |
|
|
| GAP-C008 | POST /api/ai/generate | T08 | No authentication. Unlimited OpenAI cost abuse. | Financial cost; DoS |
|
|
| GAP-C009 | POST /api/ai/analyze | T08 | No authentication. | Financial cost |
|
|
| GAP-C010 | POST /api/ai/translate | T08 | No authentication. | Financial cost |
|
|
| GAP-C011 | POST /api/ai/assist | T08 | No authentication. | Financial cost |
|
|
| GAP-C012 | POST /api/auth/force-verify-user | T09 | No authentication gate. Bypasses email verification. | Account takeover |
|
|
| GAP-C013 | POST /api/payment/shkeeper/test | T11 | No authentication in production. | Test data in production |
|
|
| GAP-C014 | POST /api/payment/shkeeper/callback-test | T11 | No authentication in production. | Test data in production |
|
|
| GAP-C015 | GET /api/payment/shkeeper/callback-test | T11 | No authentication in production. | Test data in production |
|
|
| GAP-C016 | Legacy notification router (mounted without auth) | T21 | Accepts ?userId= query parameter for notification read/modify. | Privacy breach; notification manipulation |
|
|
| GAP-C017 | Socket.IO room join events | T03 | Client-supplied userId/requestId/chatId; server verification uncertain. Any authenticated user may subscribe to any other user's rooms. | Private data exfiltration; real-time surveillance |
|
|
|
|
### 4.2 CRITICAL -- Ownership Check Missing but Required
|
|
|
|
| Gap ID | Endpoint / Event | Threat IDs | Description | Impact |
|
|
|---|---|---|---|---|
|
|
| GAP-C018 | PATCH /api/marketplace/offers/:id (post-acceptance) | T19 | updateOffer does not enforce status check. Seller can change price after acceptance. | Financial fraud |
|
|
| GAP-C019 | POST /api/payment/shkeeper/:id/release | T06 | No check for active dispute before release. Escrow released during active dispute. | Fund loss |
|
|
| GAP-C020 | POST /api/payment/shkeeper/:id/refund | T06 | Same as above for refund. | Fund loss |
|
|
| GAP-C021 | Web3 payment verification (BSCTransactionVerifier) | T01 | Only checks receipt.status, does not verify recipient address, token contract, or amount. | Payment fraud |
|
|
|
|
### 4.3 HIGH -- Rate Limiting Missing but Required
|
|
|
|
| Gap ID | Endpoint / Event | Threat IDs | Description | Impact |
|
|
|---|---|---|---|---|
|
|
| GAP-H001 | Global rate limiting disabled | T12 | express-rate-limit disabled in app.ts. All endpoints unprotected. | All abuse vectors open |
|
|
| GAP-H002 | POST /api/auth/register | T07 | No rate limit. Email spam. | SMTP cost; reputation damage |
|
|
| GAP-H003 | POST /api/auth/resend-verification | T07 | No rate limit. Email spam. | SMTP cost |
|
|
| GAP-H004 | POST /api/auth/login | T12 | Redis lockout exists but no IP-level rate limit. | Brute force |
|
|
| GAP-H005 | POST /api/marketplace/purchase-requests/:id/delivery-code/verify | T20 | No rate limit on 6-digit code verification. 900K combinations brute-forceable. | Delivery fraud |
|
|
| GAP-H006 | POST /api/ai/* (all four) | T08 | No rate limit. No per-user budget. | OpenAI cost explosion |
|
|
| GAP-H007 | POST /api/payment/decentralized/* | T11 | No rate limit even when auth is added. | Database flooding |
|
|
| GAP-H008 | POST /api/chat/:id/messages | T12 | No rate limit on chat messages. | Chat spam |
|
|
|
|
### 4.4 HIGH -- State Precondition Check Missing but Required
|
|
|
|
| Gap ID | Endpoint / Event | Threat IDs | Description | Impact |
|
|
|---|---|---|---|---|
|
|
| GAP-H009 | POST /api/disputes (dispute creation) | T06 | Does not set escrowState=disputed. No escrow hold on dispute creation. | Funds released during dispute |
|
|
| GAP-H010 | PATCH /api/marketplace/purchase-requests/:id/confirm-delivery | T20 | Buyer can confirm delivery before seller ships (manual fast-track). | Escrow released without delivery |
|
|
| GAP-H011 | PUT /api/marketplace/offers/:id/status | T09 | No documented admin-only enforcement on direct status mutation. | Unauthorized offer manipulation |
|
|
|
|
### 4.5 MEDIUM -- Audit Logging Missing but Required
|
|
|
|
| Gap ID | Endpoint / Event | Description | Impact |
|
|
|---|---|---|---|
|
|
| GAP-M001 | All admin routes (user management) | No structured audit log for admin user management actions. | No accountability for admin actions |
|
|
| GAP-M002 | POST /api/payment/shkeeper/:id/release | No append-only audit log for escrow release. | No financial audit trail |
|
|
| GAP-M003 | POST /api/payment/shkeeper/:id/refund | No append-only audit log for escrow refund. | No financial audit trail |
|
|
| GAP-M004 | POST /api/payment/shkeeper/payout | No append-only audit log for payout creation. | No financial audit trail |
|
|
| GAP-M005 | POST /api/disputes/:id/resolve | No append-only audit log for dispute resolution. | No dispute resolution trail |
|
|
| GAP-M006 | PATCH /api/user/admin/:userId/role | No audit log for role changes. | No accountability |
|
|
| GAP-M007 | DELETE /api/user/admin/:userId | No audit log for user deletion. | No accountability |
|
|
| GAP-M008 | POST /api/points/admin/add | No structured audit log for manual point grants. | No points audit trail |
|
|
| GAP-M009 | POST /api/auth/change-password | No audit log for password changes. | No security event trail |
|
|
| GAP-M010 | Global emit events (payment-created, payment-update, payout-created, etc.) | Sensitive financial data broadcast globally via Socket.IO. Should be targeted. | Data overexposure |
|
|
|
|
### 4.6 Socket.IO-Specific Gaps
|
|
|
|
| Gap ID | Issue | Threat IDs | Description | Impact |
|
|
|---|---|---|---|---|
|
|
| GAP-S001 | No handshake JWT authentication | T03 | Socket Events doc states "no token-based handshake" -- ownership checked at REST layer only. | Unauthenticated socket connections |
|
|
| GAP-S002 | Client-driven room joins | T03 | All join-* events accept arbitrary IDs. Server must verify socket.data.user.id matches. | Eavesdropping on other users |
|
|
| GAP-S003 | delivery-code-generated event to request room | T03 | 6-digit code emitted to request room where both buyer and seller are present. Code should only go to seller. | Buyer can intercept own code |
|
|
| GAP-S004 | Global payment events | T03, T21 | payment-created, payment-update, payout-created emitted globally. Financial data exposed to all connected sockets. | Data overexposure |
|
|
| GAP-S005 | No socket event rate limiting | T12 | No per-event rate limiting on typing, messages, or room joins. | Socket spam; DoS |
|
|
| GAP-S006 | No offline status tracking | -- | No userId-to-socketId mapping stored; no offline broadcast on disconnect. | Stale presence data |
|
|
|
|
---
|
|
|
|
## Section 5: Implementation Priority
|
|
|
|
### P0 -- Fix Immediately (Blocks Launch)
|
|
|
|
These gaps allow unauthenticated or unauthorized access to financial data or fund manipulation. They must be resolved before any public deployment.
|
|
|
|
| Priority | Gap IDs | Work Required | Threat IDs | Estimated Effort |
|
|
|---|---|---|---|---|
|
|
| P0-1 | GAP-C001, C002, C003, C004, C005, C006 | Add Bearer JWT auth to all /api/payment/decentralized/* endpoints. Add ownership check (buyer on referenced purchase request, or admin). | T11, T21 | 1-2 days |
|
|
| P0-2 | GAP-C007, C013, C014, C015 | Remove or disable test/demo endpoints in production builds. Add NODE_ENV gate that returns 404 in production. | T11 | 0.5 days |
|
|
| P0-3 | GAP-C008, C009, C010, C011 | Add Bearer JWT auth to all /api/ai/* endpoints. Add per-user daily token budget. | T08 | 0.5 days |
|
|
| P0-4 | GAP-C012 | Remove /api/auth/force-verify-user from production builds or gate behind NODE_ENV + admin role. | T09 | 0.5 hours |
|
|
| P0-5 | GAP-C016 | Remove legacy notification router or add authenticateToken to all its routes. Ensure controller router wins for all shared paths. | T21 | 1 day |
|
|
| P0-6 | GAP-C019, C020, H009 | Add escrowState=disputed check before release/refund. DisputeService.createDispute must set escrow hold. PaymentCoordinator must enforce it. | T06 | 1 day |
|
|
| P0-7 | GAP-C021 | Decode Transfer event in BSCTransactionVerifier. Verify recipient==ESCROW_WALLET, value>=expectedAmount, token contract matches. | T01 | 1 day |
|
|
| P0-8 | GAP-C017, S001, S002 | Require JWT in Socket.IO handshake. Server auto-joins user-{decoded.id}. For role rooms, derive from decoded.role. For chat rooms, verify participants. Remove client-driven join-* events. | T03 | 2-3 days |
|
|
| P0-9 | GAP-H001 | Enable global rate limiting in app.ts. Configure tiered limits per Section 2. | T12 | 0.5 days |
|
|
|
|
### P1 -- Fix Before Launch
|
|
|
|
These gaps involve missing ownership checks, rate limits on authentication paths, and state precondition enforcement. They represent significant security risks but are slightly lower priority than unauthenticated financial access.
|
|
|
|
| Priority | Gap IDs | Work Required | Threat IDs | Estimated Effort |
|
|
|---|---|---|---|---|
|
|
| P1-1 | GAP-C018 | Reject PATCH /api/marketplace/offers/:id if offer.status !== 'pending'. Snapshot offer amount at payment creation. | T19 | 0.5 days |
|
|
| P1-2 | GAP-H002, H003 | Add Tier 1 rate limiting on /api/auth/register, resend-verification. 5 req/5 min/IP. | T07 | 0.5 days |
|
|
| P1-3 | GAP-H004 | Add Tier 1 rate limiting on /api/auth/login. 5 req/5 min/IP. Existing Redis lockout remains. | T12 | 0.5 days |
|
|
| P1-4 | GAP-H005 | Add Redis-backed rate limit on delivery code verify. 5 attempts/15 min/request. | T20 | 0.5 days |
|
|
| P1-5 | GAP-H006 | Add Tier 2 rate limiting on /api/ai/*. 20 req/15 min/user. | T08 | 0.5 days |
|
|
| P1-6 | GAP-H008 | Add Tier 3 rate limiting on /api/chat/:id/messages. 60 req/15 min/user. | T12 | 0.5 days |
|
|
| P1-7 | GAP-H010 | Restrict delivery confirmation to status=delivery only. Remove manual fast-track or require admin override. | T20 | 0.5 days |
|
|
| P1-8 | GAP-H011 | Add roleGuard('admin') to PUT /api/marketplace/offers/:id/status. | T09 | 0.5 hours |
|
|
| P1-9 | GAP-S003 | Emit delivery-code-generated only to seller, not to entire request room. | T03 | 0.5 hours |
|
|
| P1-10 | GAP-S004 | Change payment-created, payment-update, payout-created from global emit to targeted room emits (user-{buyerId}, user-{sellerId}). | T03, T21 | 1 day |
|
|
| P1-11 | GAP-S005 | Add per-socket rate limiting for high-frequency events (typing, messages). | T12 | 1 day |
|
|
|
|
### P2 -- Fix Post-Launch
|
|
|
|
These gaps involve audit logging and presence tracking. They are important for operational security and compliance but do not represent immediate attack vectors.
|
|
|
|
| Priority | Gap IDs | Work Required | Estimated Effort |
|
|
|---|---|---|---|
|
|
| P2-1 | GAP-M001, M002, M003, M004, M005 | Implement append-only audit log collection for all admin actions, payment mutations, dispute resolutions. Include actor, target, action, before/after diff, request ID. | 3-5 days |
|
|
| P2-2 | GAP-M006, M007, M008 | Add structured audit logging for role changes, user deletions, manual point grants. | 1 day |
|
|
| P2-3 | GAP-M009 | Add audit logging for password changes and account deletions. | 0.5 days |
|
|
| P2-4 | GAP-M010 | Audit all global emit events; convert to targeted room emits where possible. | 1 day |
|
|
| P2-5 | GAP-S006 | Implement userId-to-socketId mapping. Emit user-status-change offline on disconnect. | 0.5 days |
|
|
| P2-6 | GAP-H007 | Add rate limiting on /api/payment/decentralized/* once auth is in place. | 0.5 days |
|
|
|
|
---
|
|
|
|
## Section 6: Summary Statistics
|
|
|
|
### REST Endpoint Count
|
|
|
|
| Route Group | Endpoints |
|
|
|---|---|
|
|
| Auth | 28 |
|
|
| User | 9 |
|
|
| User Admin | 13 |
|
|
| Admin Approval | 3 |
|
|
| Address | 5 |
|
|
| Purchase Request | 18 |
|
|
| Delivery Code | 4 |
|
|
| Seller Offer | 10 |
|
|
| Request Template | 11 |
|
|
| Shop Settings | 3 |
|
|
| Category / Seller Directory | 6 |
|
|
| Review | 3 |
|
|
| Payment (General) | 18 |
|
|
| Payment (SHKeeper Pay-in) | 11 |
|
|
| Payment (SHKeeper Release/Refund) | 4 |
|
|
| Payment (SHKeeper Payout) | 3 |
|
|
| Payment (Decentralized) | 8 |
|
|
| Marketplace Payment (Legacy) | 5 |
|
|
| Chat | 15 |
|
|
| Notification | 9 |
|
|
| Dispute | 8 |
|
|
| AI | 4 |
|
|
| Blog | 10 |
|
|
| Points | 8 |
|
|
| File | 9 |
|
|
| Admin Cleanup | 7 |
|
|
| System | 2 |
|
|
| **Total REST Endpoints** | **255** |
|
|
|
|
### Socket.IO Event Count
|
|
|
|
| Category | Events |
|
|
|---|---|
|
|
| Connection/Handshake | 2 |
|
|
| Room Join/Leave | 9 |
|
|
| Chat Events | 2 |
|
|
| Presence Events | 1 |
|
|
| Server-to-Client | 32 |
|
|
| **Total Socket Events** | **46** |
|
|
|
|
### Gap Summary
|
|
|
|
| Severity | Count | Gap IDs |
|
|
|---|---|---|
|
|
| CRITICAL (auth missing) | 17 | GAP-C001 through GAP-C017 |
|
|
| CRITICAL (ownership missing) | 4 | GAP-C018 through GAP-C021 |
|
|
| HIGH (rate limit missing) | 8 | GAP-H001 through GAP-H008 |
|
|
| HIGH (state precondition missing) | 3 | GAP-H009 through GAP-H011 |
|
|
| MEDIUM (audit log missing) | 10 | GAP-M001 through GAP-M010 |
|
|
| Socket.IO specific | 6 | GAP-S001 through GAP-S006 |
|
|
| **Total Gaps** | **48** | |
|
|
|
|
### Priority Distribution
|
|
|
|
| Priority | Gap Count | Work Estimate |
|
|
|---|---|---|
|
|
| P0 (blocks launch) | 9 work items covering 24 gaps | ~8-10 days |
|
|
| P1 (before launch) | 11 work items covering 11 gaps | ~5-6 days |
|
|
| P2 (post-launch) | 6 work items covering 13 gaps | ~7-8 days |
|
|
|
|
---
|
|
|
|
*This document was produced on 2026-05-24 as part of the Amanat authorization audit. It must be updated when: new endpoints are added, existing endpoint access levels change, new Socket.IO events are introduced, or the role model is extended. Implementation tasks should reference specific AUTH-R, USER-R, UADM-R, APV-R, ADDR-R, PR-R, DC-R, OFF-R, TPL-R, SHOP-R, CAT-R, REV-R, PAY-R, SHK-R, REL-R, PO-R, DEC-R, MPAY-R, CHAT-R, NOTIF-R, DIS-R, AI-R, BLOG-R, PTS-R, FILE-R, ADM-R, SYS-R, and SOCK-E IDs from this matrix.*
|