# 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