feat(fygaro): signature-failure alerts + bankowner float monitoring

[islandbitcoin]

What & why

Two ops-hardening changes that close silent-failure gaps in the live Fygaro card-top-up path.

1. Alert on Fygaro webhook signature failures (gap closed)

verify-signature previously only baseLogger.warned on an HMAC mismatch or a missing/empty secret set. A rotated or wrong webhook secret therefore 401s every real payment while the service looks healthy — this exact gap caused hours of silent card-top-up failures during setup.

Now the two "our side is misconfigured" cases — HMAC mismatch ("we hold a secret but it didn't match") and no secrets configured at all — fire alertBridge (severity warning, source fygaro-webhook, title "Fygaro webhook signature verification failing — check the webhook secret"). A plain missing / malformed / expired signature (random internet noise) stays silent, as before. The alert carries only the public key id, never the secret.

2. Bankowner treasury float monitoring

2a — Proactive scheduled check. A new cron task (checkFygaroTreasuryFloat, registered in src/servers/cron.ts) reads the bankowner treasury USDT balance from IBEX each run (~15 min, matching the reconcile cadence) and fires a warning ("Fygaro treasury float low — top up bankowner") when it drops below a configurable floor. It self-guards on FygaroConfig.enabled and never throws — an IBEX read blip or resolver error logs and returns, so it can't crash the cron (exit 99 → CrashLoopBackOff).

2b — Distinct "float exhausted" alert on credit failure. credit-topup now maps an insufficient-treasury-balance send failure to a distinct step insufficient-treasury-float, and payment.ts raises a distinct critical ("Fygaro treasury float EXHAUSTED — top up bankowner immediately") so ops knows to top up rather than debug a bug. Every other credit failure keeps the generic "manual credit needed" critical. The row still stays Fiat Received; idempotency / record-only / never-double-spend are unchanged.

Rate-limiting via dedup keys

Three new static dedup keys — fygaroSignatureFailure, fygaroFloatLow, fygaroFloatExhausted (no per-request suffix) — so the built-in TTL suppression collapses a flood of failing requests/polls into one alert per window instead of one per event.

Config

New fygaro.float block — { floorUsd: number }, default 2000 (~4× the $500 auto-credit limit) — wired through schema.ts, schema.types.d.ts, and base-config.yaml alongside the existing fygaro config.

How the float balance is read

checkFygaroTreasuryFloat resolves the treasury wallet via getBankOwnerWalletId() (walletId is the IBEX accountId) and reads the balance with Ibex.getAccountDetails(walletId, WalletCurrency.Usdt), converting the returned USDTAmount via .asNumber(). An absent balance (drained/never-funded account) is treated as $0, correctly tripping the floor.

How the insufficient-balance case is detected

By error class, not message: credit-topup checks the send result for InsufficientIbexBalance (the flash IBEX-custodial path — ibex/errors.ts maps the IBEX "insufficient balance" ApiError) or the domain-level InsufficientBalanceError. Matching by class avoids misclassifying a generic send error with coincidental wording. No pre-flight balance read is done — mapping the failure is sufficient and adds no latency (per the task's "cleaner impl" note).

Tests

• verify-signature: mismatch fires the deduped alert; no-secrets fires it; missing / malformed header and out-of-skew timestamp do not alert; the secret never appears in the payload.
• float cron: below-floor alerts; at / above floor does not; drained-account (absent balance) → 0 → alerts; IBEX read failure and resolver throw don't crash and don't alert; disabled feature skips; default-floor fallback.
• credit-topup / payment: an IBEX/domain insufficient-balance failure yields the insufficient-treasury-float step and the distinct float-exhausted critical; other failures keep the generic alert.

yarn tsc-check, yarn eslint-check, and the full yarn test:unit all pass (176 suites, 1513 passed).

🤖 Generated with Claude Code

https://claude.ai/code/session_01NcEjF6SS3Ci5D4CzZqdPjb