nick-doc/09 - Audits/Authorization Matrix - REST and Socket.IO.md

title, tags, created, status, reviewers

title	tags	created	status	reviewers
Authorization Matrix - REST and Socket.IO	audit security authorization matrix reference	2026-05-24	living	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
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 last 15 minutes (configurable). Required for: payout creation/release, role changes, large refunds (>$100), user deletion, admin-wallet signing.	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.

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.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	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	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	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	24
User	9
User Admin	13
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	248

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, 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.