fix: close 8 fund flow safety gaps — transfer locks, webhook HMAC, FX rate lock, per-corridor timeouts

[devin-ai-integration]

Summary

Closes 8 fund flow safety gaps discovered during the comprehensive audit (2 HIGH, 4 MEDIUM, 2 LOW) across Go, Rust, Python, and TypeScript. 1,078 insertions across 13 files, 0 TypeScript errors.

HIGH: Reversal + Disbursement Race Condition

Two concurrent operations on the same transfer (sender reversal + agent cash pickup) could both succeed, double-spending funds. Fixed with PostgreSQL advisory locks:

// New: server/lib/transferLock.ts
export async function withTransferLock<T>(transferRef, operationName, fn): Promise<T> {
  // pg_try_advisory_lock(hash(transferRef)) — non-blocking, no deadlocks
  const acquired = await acquireTransferLock(transferRef);
  if (!acquired) throw new Error(`Cannot ${operationName}: another operation in progress`);
  try { return await fn(); } finally { await releaseTransferLock(transferRef); }
}

// advanceTransferState("reversed") → acquires lock
// verifyAndDisburse(transferRef) → acquires same lock → mutual exclusion

HIGH: Agent Float Negative Balance

pos.cashOut and verifyAndDisburse checked balance before deducting, but two concurrent requests could both pass the check before either writes. Fixed with atomic WHERE clause:

- .set({ balance: sql`${wallets.balance} - ${amount}` })
- .where(eq(wallets.id, wallet.id))
+ .set({ balance: sql`CAST(CAST(balance AS DECIMAL(18,4)) - ${amount} AS VARCHAR)` })
+ .where(and(eq(wallets.id, wallet.id), sql`CAST(balance AS DECIMAL(18,4)) >= ${amount}`))
+ .returning({ balance: wallets.balance })
+ if (!updated) throw new TRPCError({ code: "BAD_REQUEST", message: "Insufficient float (concurrent deduction)" })

Rust: New /float-guard endpoint in rust-agent-reconciliation uses SELECT FOR UPDATE SKIP LOCKED for double-validation.

MEDIUM: FX Rate Lock (60s TTL, 0.5% max deviation)

transfer.quote → returns { rateLockToken, rateLockExpiresInSeconds: 60 }
transfer.send({ rateLockToken }) → validates deviation < 0.5%, rejects with PRECONDITION_FAILED if stale

MEDIUM: Webhook HMAC-SHA256 + Deduplication

All 5 rails (PIX, UPI, CIPS, Mojaloop, SWIFT) now verify X-Webhook-Signature header and reject duplicates via in-memory 24h dedup cache. Go mojaloop-connector signs forwarded payloads with computeWebhookHMAC(). Dev mode allows unsigned payloads (secrets prefixed dev-).

MEDIUM: Per-Corridor Stuck Transfer Timeouts

Rail	Stuck Alert	Auto-Refund	Before
Mojaloop	1h	24h	48h / 7d
PIX/UPI	2h	48h	48h / 7d
CIPS	12h	72h	48h / 7d
SWIFT	72h	168h (7d)	48h / 7d
Cash Pickup	48h	168h	48h / 7d

MEDIUM: Cash Pickup Reversal Block

advanceTransferState("reversed") now queries cash_pickup_assignments — blocks reversal if pickup is pending or already completed.

LOW: BNPL Refund Cap

refundAmount = Math.min(requestedRefund, totalPaid) — admin can no longer refund more than what was actually paid on a BNPL plan.

LOW: Savings Interest Accrual (Python)

New services/python-interest-accrual/main.py — daily APY-based compounding (flex=3.5%, locked=7%, target=5%, round_up=2.5%). Scheduled midnight UTC run, Kafka events, Prometheus metrics. POST /accrue for manual trigger.

Link to Devin session: https://app.devin.ai/sessions/64d054ae77da41e9a2b74d8593fa635c
Requested by: @munisp

[devin-ai-integration]

Original prompt from Patrick

https://drive.google.com/file/d/14K-94cZoOVgiYCUA-VympU-4_8IBqv2d/view?usp=sharing
extract the contents of the archive. List all the features of the platform

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[devin-ai-integration]

Test Results — PR #21 (8 Fund Flow Safety Fixes)

Testing approved by: User clicked "Test the app"

Summary: 71/71 vitest + 6 runtime tests passed, 0 escalations

Type	Tests	Result
TypeScript	tsc --noEmit	0 errors
Vitest (71 assertions)	Transfer lock (pg_try_advisory_lock, hash, withTransferLock, finally block), Webhook HMAC (5 rail secrets, timing-safe compare, sha256= prefix, 24h dedup, 3 header formats, dev bypass), Webhook handlers (5 rails verified, 5 dedup checks, 5× 401 responses), FX rate lock (0.5% max, 60s TTL, create/validate, expiry, currency mismatch, single-use), transfer.send integration (rateLockToken input, validateRateLock call, PRECONDITION_FAILED, quote returns token+expiry), Corridor timeouts (Mojaloop 1h, SWIFT 72h, PIX 48h auto-refund, SWIFT 168h, 8 rail configs), failureProtection integration (imports, no flat 48h, corridorTimeouts query), Cash pickup reversal block (withTransferLock import, reversed check, cash_pickup_assignments query, completed/pending block, deliveryMethod check), Pessimistic wallet debit (posAgentCashFlow atomic WHERE, agentCashPickup atomic WHERE, withTransferLock wrap, status check before disburse), BNPL refund cap (Math.min, warning log), Python interest accrual (service exists, 4 APY types, flex 3.5%/locked 7%, daily formula, min balance 100, ROUND_HALF_UP, /accrue endpoint, /health endpoint, midnight scheduler, Kafka events), Go HMAC signing (crypto imports, computeWebhookHMAC, X-Webhook-Signature header, env secret), Rust float-guard (/float-guard route, SELECT FOR UPDATE SKIP LOCKED, allowed flag, lowFloatWarning)	71/71
Runtime (live curl)	Dev server boots (health 200), PIX/UPI/CIPS/Mojaloop/SWIFT webhooks pass-through in dev mode (dev- prefixed secrets bypass HMAC), corridorTimeouts route exists (403 admin-required), transfer.quote route exists (401 auth-required), dashboard.summary works (no regression)	6/6

Key Validations

Transfer Lock: SHA-256 hash → 32-bit lock ID → pg_try_advisory_lock(lockId) → always released in finally block. Reversal and disbursement both acquire same lock on transfer reference → mutual exclusion.

Webhook HMAC: All 5 rails check X-Webhook-Signature / X-Hub-Signature-256 / X-Signature headers. Uses timingSafeEqual to prevent timing attacks. 24-hour deduplication window. Dev mode (secrets starting with dev-) allows unsigned payloads for local testing.

FX Rate Lock: Quote generates 60-second token locked to user+currency pair+rate. Send validates deviation < 0.5%. Expired/consumed tokens rejected with PRECONDITION_FAILED.

Corridor Timeouts: No more flat 48h detection — Mojaloop stuck after 1h, SWIFT stuck after 72h. Auto-refund thresholds also per-rail (24h Mojaloop, 168h SWIFT).

Pessimistic Debit: WHERE CAST(balance AS DECIMAL(18,4)) >= amount prevents negative balance even under concurrent requests. Both posAgentCashFlow and agentCashPickup use this pattern.

Rust Float Guard: SELECT FOR UPDATE SKIP LOCKED provides database-level pessimistic locking for concurrent float checks.

Python Interest Accrual: Daily APY compounding with banker's rounding (ROUND_HALF_UP). Flex=3.5%, locked=7.0%, target=5.0%, round_up=2.5%. Minimum balance ₦100. Midnight UTC scheduler with Kafka event publishing.