audit: 2026-05-30 full-codebase audit — report, issues, docs, runbooks
Full-codebase-audit 2026-05-30 outputs: - Audit report: 09 - Audits/Full Codebase Audit - 2026-05-30.md - 81 issue files ISSUE-055..135 (decisions + 1 skipped no-brainer). - Scanner docs from scratch (was zero): architecture, data model, API ref, payment flow, operations runbook + repo README. - Doc-sync updates across API reference, data models, flows, design system. - Secret Rotation Runbook (08 - Operations) for the exposed credentials. - Reusable workflow guide (07 - Development) + .claude/workflows/full-codebase-audit.js. Issues remain status:open intentionally — the code fixes are uncommitted-then-committed working-tree changes per repo and aren't "resolved" until merged/deployed. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Siavash Sameni
@@ -5,18 +5,21 @@ tags: [api, dispute, reference]
|
||||
|
||||
# Dispute API
|
||||
|
||||
> **Last updated:** 2026-05-29 — aligned with code (see [Doc vs Code Audit Report](../09%20-%20Audits/Doc%20vs%20Code%20Audit%20Report%20-%202026-05-29.md))
|
||||
> **Last updated:** 2026-05-30 — resolver role added, role guards applied to assign/status/resolve (commits b9e0f6a, 1d881c5)
|
||||
|
||||
> [!note] Current implementation
|
||||
> The Dispute module now has a Mongoose model, controller routes, dashboard routes, and release-hold helper routes mounted under `/api/disputes`. Keep this page aligned with both `backend/src/routes/disputeRoutes.ts` and `backend/src/services/dispute/disputeRoutes.ts`.
|
||||
> The Dispute module has two distinct router families. Keep this page aligned with both `backend/src/routes/disputeRoutes.ts` and `backend/src/services/dispute/disputeRoutes.ts`.
|
||||
|
||||
Endpoints live under `/api/disputes/*`. `backend/src/routes/disputeRoutes.ts` delegates to `DisputeController` (`backend/src/controllers/disputeController.ts`) for CRUD/triage. `backend/src/services/dispute/disputeRoutes.ts` provides lightweight release-hold endpoints (`raise`, `resolve`, `status`) used by escrow release gating. The routers apply `authenticateToken` globally — every endpoint requires `Bearer JWT`.
|
||||
Endpoints live under two prefixes:
|
||||
|
||||
> [!warning] Route shadowing — both dispute routers are mounted at `/api/disputes`
|
||||
> The dashboard router is mounted **first** in `app.ts`. Its `POST /:id/resolve` intercepts requests before the admin-guarded release-hold router's resolve handler. Confirm which handler will run before wiring automation to either resolve endpoint.
|
||||
- `/api/disputes/*` — `backend/src/routes/disputeRoutes.ts` delegates to `DisputeController` (`backend/src/controllers/disputeController.ts`) for CRUD/triage. All routes apply `authenticateToken` globally.
|
||||
- `/api/disputes/pr/*` — `backend/src/services/dispute/disputeRoutes.ts` provides lightweight release-hold endpoints (`raise`, `resolve`, `status`) used by escrow release gating. Previously mounted at `/api/disputes`, causing route shadowing (ISSUE-003). **Remounted at `/api/disputes/pr` in commit `1d881c5`** — all release-hold calls must use this new prefix.
|
||||
|
||||
> [!danger] Security issues — see individual endpoint notes below
|
||||
> Several endpoints that are documented as admin-only have **no role guard** in the current codebase. Any authenticated user can call them. These are noted per-endpoint.
|
||||
> [!success] Route shadowing resolved (ISSUE-003)
|
||||
> The release-hold router was remounted from `/api/disputes` to `/api/disputes/pr`. Both routers now have independent paths and neither shadows the other.
|
||||
|
||||
> [!note] Resolver role
|
||||
> A new `resolver` role was added (commit `fce8a19`). Resolvers can view and resolve disputes but have no other platform privileges. They are granted the same access as `admin` on all dispute-triage operations listed below.
|
||||
|
||||
> [!note] Real-time events
|
||||
> All socket events from `DisputeService` are currently **TODO stubs**. No real-time events fire from dispute mutations. Notifications are delivered via `POST /api/notifications` → `new-notification` socket event only.
|
||||
@@ -48,16 +51,18 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
|
||||
- Notifies the counter-party via `POST /api/notifications` (`new-notification` socket event).
|
||||
- Pauses any in-flight payout (sets a hold flag on the related [[Payment]]).
|
||||
|
||||
### POST /api/disputes/:purchaseRequestId/raise
|
||||
### POST /api/disputes/pr/:purchaseRequestId/raise
|
||||
|
||||
**Description:** Lightweight release-hold endpoint that marks a purchase request and related payments as disputed. Exists in the backend but has no corresponding frontend action.
|
||||
**Description:** Lightweight release-hold endpoint that marks a purchase request and related payments as disputed. No corresponding frontend UI action.
|
||||
**Auth required:** Bearer JWT (buyer who owns the request or admin)
|
||||
**Request body:** `{ reason?: string }`
|
||||
**Response 200:** `{ success, message, data }`
|
||||
|
||||
### GET /api/disputes/:purchaseRequestId/status
|
||||
> **Path note:** Previously served at `/api/disputes/:purchaseRequestId/raise`. Moved to `/api/disputes/pr/:purchaseRequestId/raise` in commit `1d881c5` (ISSUE-003 fix).
|
||||
|
||||
**Description:** Returns release-hold flags for a purchase request, including whether release is currently blocked. Exists in the backend but has no corresponding frontend action.
|
||||
### GET /api/disputes/pr/:purchaseRequestId/status
|
||||
|
||||
**Description:** Returns release-hold flags for a purchase request, including whether release is currently blocked. No corresponding frontend UI action.
|
||||
**Auth required:** Bearer JWT (buyer, preferred seller, or admin)
|
||||
|
||||
## Read
|
||||
@@ -79,7 +84,7 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
|
||||
### GET /api/disputes/statistics
|
||||
|
||||
**Description:** Aggregated counts (open, by reason, average resolution time) for admin dashboards.
|
||||
**Auth required:** Bearer JWT (any authenticated user — backend applies `authenticateToken` only, no role restriction)
|
||||
**Auth required:** Bearer JWT (`admin` or `resolver` — `authorizeRoles('admin', 'resolver')` is applied)
|
||||
**Response 200:** `{ success, data: { open, byReason, avgResolutionHours, ... } }`
|
||||
|
||||
### GET /api/disputes/:id
|
||||
@@ -92,10 +97,8 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
|
||||
|
||||
### POST /api/disputes/:id/assign
|
||||
|
||||
**Description:** Assign an admin moderator to the dispute. Sets `assignedAdminId` and transitions status to `in_progress`.
|
||||
**Auth required:** Bearer JWT
|
||||
|
||||
> ⚠️ **SECURITY — NO ROLE GUARD:** Despite being documented as admin-only, there is no role guard on this endpoint. Any authenticated user can self-assign as mediator on any dispute.
|
||||
**Description:** Assign an admin or resolver moderator to the dispute. Sets `assignedAdminId` and transitions status to `in_progress`.
|
||||
**Auth required:** Bearer JWT (`admin` or `resolver`)
|
||||
|
||||
**Request body:** `{ adminId: string }`
|
||||
**Side effects:** Notifies all participants.
|
||||
@@ -103,18 +106,14 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
|
||||
### PATCH /api/disputes/:id/status
|
||||
|
||||
**Description:** Generic status update (e.g. close without resolution).
|
||||
**Auth required:** Bearer JWT
|
||||
|
||||
> ⚠️ **SECURITY — NO ROLE GUARD:** There is no role guard on this endpoint. Any authenticated user can change dispute status despite documentation claiming admin-only access.
|
||||
**Auth required:** Bearer JWT (`admin` or `resolver`)
|
||||
|
||||
**Request body:** `{ status: string; note?: string }`
|
||||
|
||||
### POST /api/disputes/:id/resolve
|
||||
|
||||
**Description:** Final adjudication. Records the decision and triggers the appropriate escrow action.
|
||||
**Auth required:** Bearer JWT
|
||||
|
||||
> ⚠️ **SECURITY — NO ROLE GUARD:** This is the dashboard router's resolve handler (mounted first). There is no role guard. Any authenticated user can resolve a dispute, including issuing `action=ban_seller`.
|
||||
**Auth required:** Bearer JWT (`admin` or `resolver`)
|
||||
|
||||
> ⚠️ **ROUTE SHADOWING:** Because the dashboard router is mounted before the admin-guarded release-hold router, this handler intercepts all `POST /api/disputes/:id/resolve` requests. The admin-guarded release-hold resolve endpoint is unreachable at this path.
|
||||
|
||||
@@ -131,13 +130,14 @@ Model: [[Dispute]]. A dispute references a [[PurchaseRequest]] plus optional [[P
|
||||
- `action === "refund"` → create/approve the corresponding refund instruction through the ledger-gated payment release/refund flow.
|
||||
- `action === "no_action"` or seller-favorable outcome → clear hold only after release checks pass.
|
||||
- Notifies both participants and updates [[PurchaseRequest]] status to `disputed_resolved`.
|
||||
- **ISSUE-004 fix (commit `1d881c5`):** `DisputeService.resolveDispute` now calls `releaseHoldResolve()` on the linked `purchaseRequestId`, clearing the escrow hold so payment release is unblocked automatically after resolution.
|
||||
|
||||
### POST /api/disputes/:purchaseRequestId/resolve
|
||||
### POST /api/disputes/pr/:purchaseRequestId/resolve
|
||||
|
||||
**Description:** Lightweight release-hold endpoint that clears the disputed hold flags on a purchase request and related payments.
|
||||
**Auth required:** Bearer JWT (admin)
|
||||
|
||||
> ⚠️ **ROUTE SHADOWING:** This endpoint is on the release-hold router which is mounted **after** the dashboard router. The dashboard router's `POST /:id/resolve` matches first, making this handler unreachable in practice. See the route shadowing warning at the top of this page.
|
||||
> **Path note:** Previously unreachable due to route shadowing. Moved to `/api/disputes/pr/:purchaseRequestId/resolve` (commit `1d881c5`, ISSUE-003 fix). This endpoint is now reachable.
|
||||
|
||||
**Response 200:** `{ success, message, data }`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user