Add a fraud flag review workflow and mount the admin fraud router #985

Summary

The fraud detector persists fraud_flags with a status column, but there is no way to review a flag. The admin router that lists flags is not mounted either, and the detector worker is never started. Each scan re-keys a cluster when it gains a member, so earlier review decisions are lost. This issue mounts the router, adds audited review transitions, keeps decisions stable across cluster growth, and runs the detector on a schedule.

Background and evidence

• The router is not mounted. createAdminFraudRouter/adminFraudRouter (src/routes/admin/fraud.ts) is not referenced in src/index.ts: grep -rn adminFraudRouter src matches only its own file. GET /api/admin/fraud/flags and POST /api/admin/fraud/scan are unreachable.
• No review transition. The router only has GET /flags and POST /scan (around lines 70–106). Yet fraud_flags.status, reviewed_by and reviewed_at exist in src/db/schema.ts (around lines 223–253).
• Cluster keys drift. makeClusterKey (src/services/fraudService.ts, line 225) is the |-joined sorted member list. When one address joins a cluster, every member gets a new (cluster_key, user_id) row with status = 'open', which brings back flags an admin already dismissed.
• The detector never runs. fraudDetectorWorker (src/workers/fraudDetector.ts, line 89) is never started by the API or by a package script.
• Unbounded keys. For large clusters the key grows without limit (56 characters per member).

Scope

In scope

1. Mount adminFraudRouter at /api/admin/fraud in src/index.ts, behind the existing requireAdmin.
2. Review endpoint. Add PATCH /api/admin/fraud/flags/:id with body { status: "confirmed" | "dismissed", note?: string }, validated with zod in .strict() mode.
   • Allowed transitions: open → confirmed, open → dismissed, and confirmed → dismissed (which needs a note). Anything else returns 409 invalid_transition.
   • Set reviewed_by from the admin's address and reviewed_at = now().
   • Every transition writes createAuditLog({ action: "fraud_flag.review", beforeState, afterState }).
3. Stable decisions.
   • Change makeClusterKey to a SHA-256 of the sorted members, keeping the members in evidence.
   • In DrizzleFraudRepo.upsertFlags, when a user already has a dismissed flag whose evidence covers the same edges, insert the new row with status = 'dismissed' and a carried_from reference. Re-open it only when new edge reasons appear. Add the carried_from column through a migration.
4. Scheduled detector. Add fraud-detector and fraud-detector:dev scripts that run src/workers/fraudDetector.ts on its interval, with graceful shutdown.
5. OpenAPI and docs. Register the three admin operations in src/openapi/registry.ts, and update docs/fraud-signal.md with the review states.

Out of scope

• Enforcing holds on claims (a separate issue).
• Changes to the detection heuristics or edge weights.

Design constraints

• Authorization. Only admins may call these endpoints. Reviewer identity comes from the verified JWT, never from the request body.
• Concurrency. Transitions use UPDATE … WHERE id = $1 AND status = $expected RETURNING *, so two admins reviewing at once cannot both win.
• Idempotent scans. Re-running a scan over unchanged data writes no new rows and never changes a reviewed status.
• Rate limiting. Reuse the router's limiter and key it on the verified admin identity (see the rate-limiter keying issue).

Test plan

Extend tests/adminFraud.test.ts and tests/fraudService.test.ts.

Regression proof. Rows 1 and 6 must fail on current main (router not mounted; dismissal not carried) and pass after your change.

Acceptance criteria

• adminFraudRouter is mounted, and the PATCH endpoint exists with audited transitions.
• Every row of the test plan passes: npm test -- tests/adminFraud.test.ts tests/fraudService.test.ts tests/fraudDetector.test.ts.
• npm run lint, npx tsc -p tsconfig.json --noEmit and npm test pass, with coverage of at least 90% on the touched files.
• npm run openapi:check and npm run db:check-drift pass.

Getting started

git checkout -b feat/fraud-flag-review
npm ci
docker compose up -d db && npm run db:migrate
npm test -- tests/adminFraud.test.ts tests/fraudService.test.ts

Read these first:

• src/routes/admin/fraud.ts
• clusterize, makeClusterKey and DrizzleFraudRepo in src/services/fraudService.ts
• src/workers/fraudDetector.ts
• docs/fraud-signal.md

PR requirements

• Link this issue (Closes #<n>).
• Include the transition table in the PR description.
• Paste the test output and the coverage summary.
• Example commit: feat(fraud): mount admin router and add audited flag review transitions.

Priority rationale

Medium. The work is contained to the fraud admin surface and its repository. It adds a real workflow with concurrency-safe transitions, auditability and stable cluster identity. Without it, fraud findings cannot be acted on.