233 lines
11 KiB
Markdown
233 lines
11 KiB
Markdown
# 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
|
|
|