feat(backend): SEP-0009 compliance & OFAC sanctions screening middleware (#1470)

[Aj-Kayvee]

Summary

Closes #1470

Adds an opt-in compliance / sanctions screening layer to the backend so institutional payroll and regulated token distributions can prove participating wallets were screened before funds move.

What's included

• Screening middleware (backend/src/middleware/compliance.middleware.ts) guards stream creation, top-up (deposit) and withdrawal routes. Sanctioned or over-threshold addresses receive a structured 403:

  { "error": "COMPLIANCE_RESTRICTION", "message": "Address restricted under compliance policy" }

• Screening service (backend/src/services/compliance.service.ts) returns the ScreeningResult shape from the issue, supports a local denylist/allowlist provider (inline env + optional JSON sanctions feed) and an external provider (Chainalysis / TRM Labs / Elliptic style HTTPS API) with an abort-based timeout, and caches results with a configurable TTL.

• Config (backend/src/config/compliance.config.ts) — COMPLIANCE_ENFORCEMENT_ENABLED (default false, so local testing and self-hosted deployments stay permissive), risk threshold, fail-open / fail-closed mode, cache TTL and provider settings. All documented in backend/.env.example.

• Audit trail — new ComplianceAuditLog Prisma model records every blocked interaction (address, request IP, risk score, tags, action) plus a structured logger.info line. KYC submissions are audited too.

• SEP-0009 KYC — POST /v1/compliance/kyc-attestation accepts a SEP-0009 identity payload plus a cryptographic proof and stores it as a KycAttestation. POST /v1/compliance/screen and GET /v1/compliance/screen/{address} expose screening results for audit tooling.

• Migration 20260928000000_add_compliance_tables, plus regenerated OpenAPI spec and frontend API types.

• Tests — backend/tests/compliance.test.ts (31 tests) covers config parsing, allowlist/blocklist behaviour, the risk-threshold boundary, cache hits, external-provider success/failure, fail-open vs fail-closed, audit persistence and the SEP-0009 route.

Acceptance criteria

• Compliance middleware intercepts stream creation and funding routes when enabled.
• Sanctioned / high-risk addresses receive a structured 403 Forbidden response.
• Screening results are cached with a configurable TTL to minimise external API cost.
• Compliance events and blocked interactions generate structured audit logs.
• Unit and mock tests verify allowlist/blocklist behaviour and fail-open/fail-closed modes.

Base branch note

upstream/main currently does not build: backend/prisma/schema.prisma defines IndexerDeadLetterEvent twice (fails prisma validate/generate) and there are pre-existing type errors across sorobanService, health.routes, indexerService and admin.routes. Because of that, this branch is stacked on feat/ledger-reorg-fork-recovery-1468, which carries the repair commits needed to make the tree green. The compliance changes themselves are self-contained (see the file list below) and can be rebased cleanly once main is repaired.

Files changed

• backend/src/config/compliance.config.ts (new)
• backend/src/services/compliance.service.ts (new)
• backend/src/middleware/compliance.middleware.ts (new)
• backend/src/routes/v1/compliance.routes.ts (new)
• backend/tests/compliance.test.ts (new)
• backend/prisma/schema.prisma, backend/prisma/migrations/20260928000000_add_compliance_tables/
• backend/src/routes/v1/index.ts, backend/src/routes/v1/stream.routes.ts
• backend/src/config/swagger.ts, backend/swagger/flowfi.openapi.json, frontend/src/lib/api-types.generated.ts
• backend/.env.example

Verification

• npx prisma generate — pass
• npx tsc --noEmit (backend) — pass
• npx vitest run --exclude='tests/integration/**' — 490 passed / 3 skipped
• tests/compliance.test.ts — 31 passed