nick-doc/.taskmaster/reports/task-2-7-doc-alignment-report.md

Task 2.7 — Documentation & Code Alignment Report

Date: 2026-05-24
Auditor: Kimi Code CLI (subagent)
Scope: nick-doc/ technical documentation vs. backend/src/ runtime code

---

1. Files Reviewed

Data Models (nick-doc/02 - Data Models/)

• Data Model Overview.md
• Payment.md
• PurchaseRequest.md
• User.md
• Dispute.md
• Chat.md (spot-checked)

API Reference (nick-doc/03 - API Reference/)

• API Overview.md
• Payment API.md
• Dispute API.md
• Marketplace API.md (spot-checked)
• Authentication API.md (spot-checked)

Architecture (nick-doc/01 - Architecture/)

• Backend Architecture.md
• Security Architecture.md
• System Architecture.md

Flows (nick-doc/04 - Flows/)

• Escrow Flow.md
• Dispute Flow.md
• Payment Flow - SHKeeper.md
• Payment Flow - DePay & Web3.md

Backend Code

• backend/src/models/*.ts (all)
• backend/src/app.ts (bootstrap, middleware, route mounting)
• backend/src/services/payment/decentralizedPaymentRoutes.ts
• backend/src/services/payment/shkeeper/shkeeperRoutes.ts
• backend/src/services/payment/paymentControllerRoutes.ts
• backend/src/services/marketplace/controllerRoutes.ts
• backend/src/services/marketplace/routes.ts
• backend/src/services/auth/passkeyService.ts

---

2. Discrepancies Found

2.1 Missing modules (documented but not implemented)

Module	Doc claims	Reality in code
Dispute	backend/src/services/dispute/, backend/src/models/Dispute.ts, /api/disputes	None exist. No directory, no model, no routes, no controller.
Blog	services/blog/blogRoutes.ts	Does not exist.
Points	services/points/pointsRoutes.ts, Points API	Does not exist.
Admin	services/admin/adminRoutes.ts, Admin API	Does not exist.
Review	Review.md data model	backend/src/models/Review.ts does not exist.
PointTransaction	PointTransaction.md data model	backend/src/models/PointTransaction.ts does not exist.
LevelConfig	LevelConfig.md data model	backend/src/models/LevelConfig.ts does not exist.
ShopSettings	ShopSettings.md data model	backend/src/models/ShopSettings.ts does not exist.
BlogPost	BlogPost.md data model	backend/src/models/BlogPost.ts does not exist.

2.2 Data-model enum mismatches

Model	Field	Doc value	Code value	Severity
Payment	provider	shkeeper / other	shkeeper / request.network / request-network / other	Medium
Payment	escrowState	6 values	8 values (+ cancelled, + partial)	Medium
Payment	metadata	SHKeeper fields only	Also has requestNetworkRequestId, requestNetworkPaymentReference, requestNetworkSecurePaymentUrl, requestNetworkData	Low
Payment API	Status list	Missing confirmed and processing in the "Status model" prose	Code has full 7-value enum incl. confirmed, processing	Medium

2.3 User-model fields documented but missing from schema

The User.md table describes referralCode, referredBy, points.{total,available,used,level}, and referralStats.{totalReferrals,activeReferrals,totalEarned}. These fields do not exist in backend/src/models/User.ts (line count stops at 201; no referral or points subdocuments). The associated unique/sparse indexes are also absent.

2.4 Authentication requirements (post-remediation drift)

Several endpoints in Payment API.md were documented as unauthenticated but the code now enforces authenticateToken (and in some cases authorizeRoles):

Endpoint	Doc auth	Code auth	Fix applied
POST /api/payment/decentralized/save	No	Bearer JWT + ownership	✅ Updated doc
PUT /api/payment/decentralized/update	No	Bearer JWT + ownership	✅ Updated doc
GET /api/payment/decentralized/history/:userId	No	Bearer JWT + requireOwnershipOrAdmin	✅ Updated doc
POST /api/payment/decentralized/verify/:paymentId	No	Bearer JWT + ownership	✅ Updated doc
POST /api/payment/decentralized/verify-all-pending	No (cron)	Bearer JWT + admin	✅ Updated doc

Additionally, the legacy routes.ts marketplace router applies authenticateToken globally, but app.ts mounts the controller router (controllerRoutes.ts) which exposes public read endpoints. The docs correctly describe the controller-router behaviour.

2.5 Rate limiting

All architecture and API docs stated rate limiting was disabled (app.ts:227). After remediation it is enabled with four tiers:

• Global: 100 req / 15 min
• Auth: 10 req / 15 min
• Payment: 30 req / 15 min
• AI: 20 req / 15 min

2.6 Socket.IO authentication

Docs described Socket.IO as an open real-time channel. In reality app.ts now enforces:

• JWT verification on every connection (io.use(jwt.verify(...))).
• Strict room-membership checks (join-user-room, join-request-room, join-chat-room, etc.) that reject cross-user or unauthorized joins.

2.7 Passkey hardening

passkeyService.ts now implements:

• Single-use challenge consumption (consumeChallenge deletes immediately after read).
• 5-minute challenge TTL with periodic cleanup.
• Explicit expiry error messages.
• This was not documented in the Security Architecture or Authentication API docs.

2.8 Endpoint path errors in flow docs

• Payment Flow - DePay & Web3.md referenced POST /api/payment/decentralized/create which does not exist; the actual endpoint is POST /api/payment/decentralized/save.
• Same doc referenced POST /api/payment/decentralized/verify which does not exist; the actual endpoint is POST /api/payment/decentralized/verify/:paymentId.

2.9 Backend Architecture route table omissions

The original table:

• Listed /api/payment/payout as a top-level mount; it is actually nested under /api/payment/shkeeper/payout*.
• Listed /api/file; the actual mount is /api/files.
• Omitted /api/trezor, /api/email, /api/payment/decentralized, and /api/payment/request-network.

---

3. Fixes Applied

Data Models

1. Payment.md

   • Expanded provider enum to match code (request.network, request-network).
   • Expanded escrowState enum to include cancelled, partial.
   • Added Request Network metadata fields to the schema table.
   • Updated "Status model" prose to include confirmed and processing.

2. User.md

   • Added [!warning] blocks on referralCode, referredBy, points, and referralStats fields marking them as not yet implemented.
   • Corrected index line references and added a note about missing indexes.

3. Dispute.md

   • Added a prominent [!warning] that backend/src/models/Dispute.ts does not exist and the schema reflects intended design only.

4. Data Model Overview.md

   • Added a scope warning listing documented models that lack Mongoose schema files.
   • Noted the two undocumented models that exist in code (FundsLedgerEntry.ts, TrezorAccount.ts).

API Reference

5. API Overview.md

   • Rewrote "Rate limiting" section to describe the four active tiers.
   • Rewrote "Real-time channel" section to document Socket.IO JWT enforcement and room-membership checks.
   • Marked Dispute API, Blog API, Admin API, and Points API as "planned, not yet implemented".

6. Payment API.md

   • Updated auth requirements for all decentralized endpoints to reflect authenticateToken enforcement.
   • Updated status/escrowState enums.

7. Dispute API.md

   • Added a top-level [!warning] that the module is not implemented.
   • Rewrote introductory sentences to use conditional language ("would be", "planned").

Architecture

8. Backend Architecture.md

   • Updated middleware chain note: rate limiting is now enabled.
   • Updated route table to reflect actual mounts, mark missing services, and add omitted routes (/api/files, /api/trezor, /api/email, /api/payment/decentralized, /api/payment/request-network).
   • Changed solid dependency arrows from dispute and points to dotted lines in the Mermaid diagram to indicate planned-but-not-implemented status.

9. Security Architecture.md

   • Updated "Rate limiting & abuse" section to reflect enabled tiers.
   • Checked off "Enable rate-limit middleware" and "Enforce Socket.IO JWT authentication" in the hardening checklist.

Flows

10. Escrow Flow.md

    • Updated escrowState enum prose to include cancelled and partial.
    • Added Cancelled state to the Mermaid state diagram.

11. Dispute Flow.md

    • Added a [!warning] block next to backend file references stating none exist.

12. Payment Flow - DePay & Web3.md

    • Changed POST /api/payment/decentralized/create → POST /api/payment/decentralized/save with auth note.
    • Changed POST /api/payment/decentralized/verify → POST /api/payment/decentralized/verify/:paymentId with auth note.

Changelog

13. nick-doc/00 - Overview/Introduction.md
    • Inserted a 2026-05-24 audit-remediation callout at the top summarising auth enforcement, rate limiting, passkeys, Web3 verification, Socket.IO auth, and dispute status.

---

4. Remaining Gaps

The following items were identified but not fully resolved (out of scope for a pure doc-alignment task or require code implementation):

1. Missing models still documented — Dispute, BlogPost, Review, PointTransaction, LevelConfig, and ShopSettings remain in the docs with warnings. A future subtask should either implement the models or move the docs to a "Planned" archive folder.
2. Missing services still documented — Dispute API, Blog API, Admin API, Points API still have markdown pages. Same recommendation as above.
3. User referral/points fields — The User.ts schema is missing the documented referral and points subdocuments. Either the schema needs to be extended or the fields should be removed from User.md once a final product decision is made.
4. Frontend docs not audited — This subtask focused on backend alignment. nick-doc/05 - Design System/ and frontend/src/ docs were not reviewed.
5. OpenAPI / generated spec — The openapi.json referenced in Backend Architecture.md was not regenerated or audited.
6. FundsLedgerEntry & TrezorAccount — These models exist in backend/src/models/ but have no documentation notes yet. They should be added to Data Model Overview.md in a future pass.

---

5. Acceptance Criteria Verification

Criterion	Status	Evidence
Data model enums in docs match backend models	✅	Payment.md provider & escrowState enums aligned; User.md enum values verified against User.ts.
API reference auth requirements reflect post-remediation state	✅	Decentralized payment endpoints now correctly list Bearer JWT; rate limiting section updated.
Flow docs do not describe unauthenticated financial endpoints	✅	DePay flow updated to show auth on save and verify/:paymentId.
Report file created	✅	This file.
No incorrect references to non-existent dispute modules remain	✅	All dispute references now carry [!warning] blocks and conditional language.

---

End of report.