nick-doc/PRD - Platform Audit Remediation Plan (2026-05-24).md

PRD: Platform Audit Remediation Plan (2026-05-24)

Scope

• Source audit: 09 - Audits/Platform Logical Audit - 2026-05-24.md
• Target: backend hardening and consistency fixes first, then doc/runtime alignment.
• Assessed date: 2026-05-24

Audit validity check (code-backed vs docs-only)

• Code-confirmed valid findings:

  • Unauthenticated financial/auth-sensitive routes are exposed (/api/payment/*, /api/ai/*, legacy notification routes).
  • Passkey flow uses stubbed credential handling and in-memory challenge storage.
  • PaymentCoordinator does not currently enforce dispute holds.
  • Web3 verifier relies primarily on receipt.status.
  • Socket.IO user-room joins are client-controlled.
  • Rate limiting is explicitly disabled in backend/src/app.ts.

• Partially validated / inconsistent findings:

  • Dispute module appears absent in the checked backend tree (backend/src does not contain services/dispute/routes/disputeRoutes/controllers/disputeController), so many dispute-specific audit checks cannot be confirmed against code but indicate a documentation-runtime mismatch.
  • The REST/API/flow docs mention endpoints that differ from available implementation in some places; these should be normalized as part of a separate alignment pass.

---

PRD 1: Secure unauthenticated endpoints and data-owner enforcement (P0)

Problem

• backend/src/services/payment/decentralizedPaymentRoutes.ts exposes mutation endpoints (/save, /update, /verify, /verify-all-pending) without auth.
• backend/src/services/ai/aiRoutes.ts has public generation endpoints (/generate, /analyze, /translate, /assist) with no auth.
• backend/src/services/notification/routes.ts lets clients specify userId and mutate/read without ownership checks, and routes are mounted publicly via app.use("/api", notificationRoutes) in backend/src/app.ts.

Acceptance criteria

• Every endpoint in decentralizedPaymentRoutes.ts, aiRoutes.ts, and legacy notificationRoutes.ts requires:
  • authenticateToken
  • owner/admin role check where applicable
• Notification endpoints do not accept arbitrary userId; derive userId from authenticated principal.
• Payment history and mutation endpoints enforce requestor ownership or admin/authorized role.

Risk assessment

• Threat: Financial/private data tampering or privacy breach by unauthenticated callers.
• Likelihood: High.
• Impact: Critical (funding fraud, PII leakage, cost abuse).
• Mitigation: Introduce router-level middleware and standardized auth helper.
• Residual risk: Medium if any integration jobs call these endpoints (document required with service tokens or service role).

Delivery plan

1. Add route-level authenticateToken to all routes in files above.
2. Introduce ownership guard utilities for:
   • history/:userId and payment listing/history filters
   • notification queries/updates
3. Restrict AI calls to authenticated users with per-user rate budget.
4. Add audit logs for denied access and suspicious payloads.
5. Update API docs for auth requirements.

Owner / dependencies

• Owner: Backend security + payments teams.
• Depends on: token standards in backend/src/shared/middleware/auth.

---

PRD 2: Production-grade Passkey/WebAuthn flow (P0)

Problem

• backend/src/services/auth/passkeyService.ts stores passkey challenge data in an in-memory Map and inserts 'simulated-public-key' during registration.
• Refresh token is generated on authentication but never persisted to user.refreshTokens[], making token rotation behavior inconsistent with the rest of auth flows.

Acceptance criteria

• Replace stubbed registration/verification with real WebAuthn verification.
• Back challenges by shared storage (Redis or equivalent), not in-process memory.
• Persist verified refresh tokens and rotate according to normal auth policy.
• Reject reused/expired challenges and malformed assertions with deterministic errors.

Risk assessment

• Threat: Credential spoofing, replay attacks, and broken session continuity.
• Likelihood: High.
• Impact: Critical (account takeover / authentication bypass).
• Mitigation: Add @simplewebauthn/server (or equivalent) + Redis-backed nonce store + strict verification.
• Residual risk: Medium (device/browser compatibility edge-cases).

Delivery plan

1. Replace verifyRegistration and verifyAuthentication with attestation/assertion verification.
2. Swap storedChallenges map for distributed storage with TTL.
3. Add persistent refresh token append in passkey login flow.
4. Add regression tests for sign-in/sign-up and challenge expiry.

Owner / dependencies

• Owner: Auth team.
• Depends on: Redis infra, passkey frontend challenge handling.

---

PRD 3: Enforce dispute hold before payout/release operations (P1)

Problem

• No dispute implementation files are present in the checked backend for enforcement paths, yet escrow release can still proceed in payment logic without a blocking hold.
• backend/src/services/marketplace/routes.ts release endpoint (/purchase-requests/:id/release-payment) executes without a dispute gate.
• backend/src/services/payment/paymentCoordinator.ts applies sequencing and dedupe logic but has no dispute state guard.

Acceptance criteria

• Introduce explicit hold mechanism on Payment (or new disputeStatus/holdReason field).
• All release/refund flows check hold state before state mutation.
• Release endpoint returns clear 409/423 response when disputed.
• Backfill/reporting distinguishes dispute-blocked payments.

Risk assessment

• Threat: Funds released before dispute resolution.
• Likelihood: Medium (documented behavior gap).
• Impact: Critical (financial loss / trust erosion).
• Mitigation: Centralize payout/refund state checks in coordinator and services, not UI-only logic.
• Residual risk: Medium (existing open disputes may need manual reconciliation).

Delivery plan

1. Add disputed/disputeHoldReason fields (and migration plan) to Payment.
2. Add hold checks in:
   • backend/src/services/marketplace/routes.ts admin release flow
   • backend/src/services/payment/shkeeper/shkeeperService.ts and payout flows
   • backend/src/services/payment/paymentCoordinator.ts before completion transitions.
3. Create an internal service contract for setting/releasing hold after dispute open/resolve.
4. Add guard tests for blocked release and allowed release post-override.

Owner / dependencies

• Owner: Escrow/payment platform team.
• Depends on: dispute subsystem availability / status source-of-truth.

---

PRD 4: Strengthen DePay/Web3 verification semantics (P1)

Problem

• backend/src/services/payment/decentralizedPaymentService.ts verifies only receipt.status === '0x1', without validating destination token, recipient, and amount mapping.

Acceptance criteria

• Verification loads the transaction receipt + logs + token-decoding and validates:
  • correct recipient address (toAddress)
  • expected token contract (token)
  • minimum amount with decimals.
• Reject/flag ambiguous payloads and store verifier evidence in Payment.metadata.
• Add idempotency/duplicate handling for repeated verification requests.

Risk assessment

• Threat: Fraudulent transaction proofing and false-positive confirmations.
• Likelihood: Medium.
• Impact: High (unauthorized balance movement/false completion).
• Mitigation: Strict recipient/token/amount checks + explicit failure reason mapping.
• Residual risk: Medium (chain/protocol variance).

Delivery plan

1. Extend verifier schema for expected transfer contract/address/decimals.
2. Decode ERC-20 Transfer event and compare against expected values.
3. Mark and persist verificationFingerprint to prevent replay/double-processing.
4. Return canonical failure reasons for observability.

Owner / dependencies

• Owner: Payments + blockchain service team.
• Depends on: RPC/provider reliability and token ABI metadata.

---

PRD 5: Lock Socket.IO user room joins to authenticated context (P2)

Problem

• backend/src/app.ts allows join-user-room, join-buyer-room, and join-seller-room events from arbitrary input IDs with no identity binding.

Acceptance criteria

• Server derives room membership from validated socket identity after token handshake.
• Reject mismatched room join attempts with server-side authorization checks.
• Preserve real-time event behavior for legitimate users.

Risk assessment

• Threat: Event channel interception and privacy leakage.
• Likelihood: Medium.
• Impact: High (notifications/messages for wrong user).
• Mitigation: Server-authorized socket-to-user mapping and middleware verification.
• Residual risk: Low (requires active socket auth and client migration).

Delivery plan

1. Add token validation middleware on socket connection.
2. Replace client-sent ID room joins with authenticated identity joins.
3. Add per-room join/emit checks in critical publishers.
4. Add monitoring for room-join failures and suspicious activity.

Owner / dependencies

• Owner: Real-time platform team.
• Depends on: frontend socket auth handshake updates.

---

PRD 6: Re-enable and scope rate limiting for public-sensitive paths (P2)

Problem

• backend/src/app.ts has comments and code indicating rate limiting is disabled globally.

Acceptance criteria

• Re-enable limiter at edge level with sensible defaults.
• Use stricter quotas for auth/financial/AI endpoints.
• Keep lightweight paths (public listings, static read APIs) at higher budgets.

Risk assessment

• Threat: Brute-force/log abuse, AI cost exhaustion, webhook abuse.
• Likelihood: High.
• Impact: Medium-High (operational availability and cost).
• Mitigation: Endpoint-tiered limiter with trusted network exceptions and observability.
• Residual risk: Medium (false positives on legitimate spikes).

Delivery plan

1. Restore global limiter with default relaxed values.
2. Add stricter route-level windows for /api/auth/*, /api/payment/*, /api/ai/*.
3. Add alerts on repeated 429s and limit misconfigurations.

Owner / dependencies

• Owner: Platform infrastructure/security team.

---

Documentation and API alignment follow-up (P2)

• Where docs refer to backend/src/services/dispute/* and backend/src/services/dispute/disputeRoutes.ts, either implement that module or update architecture/API/docs to current repository reality.
• Normalize enum/action naming across:
  • 02 - Data Models/*
  • 03 - API Reference/*
  • 04 - Flows/*

---

Delivery sequencing suggestion

1. PRD 1 (security/auth)
2. PRD 6 (rate limiting)
3. PRD 2 (passkeys)
4. PRD 4 (verification trust)
5. PRD 5 (socket hardening)
6. PRD 3 (dispute hold controls)
7. Documentation/API alignment