[teethaking]

---

Summary

Two improvements for the Veil backend naira rails — a canonical fake provider module that is the single source of truth for provider response shapes (replacing per-test ad-hoc fetch mocks), with an end-to-end test walking the full onramp flow, and rate limits on the three creating routes that were unthrottled despite spending provider rate budget and consuming one-per-lifetime NIN attempts.

Closes #246
Closes #245

---

What changed

#246 — Fake Provider and End-to-End Naira Rail Tests

src/tests/fakeNgnProvider.ts (new — the single source of truth)

• Implements the documented provider endpoints and their documented failure responses: provision, verify, quote, order, webhook, and settle
• All documented response shapes are defined here and only here — correcting the fake corrects every suite that imports it at once
• Intercepts global.fetch (the existing suite pattern) so no real network call can escape to the provider — enforced, not assumed
• Exposes controls to configure which step should fail and with which documented error code

Existing suites migrated

• All existing suites that previously used per-test ad-hoc fetch mock shapes now import their mocks from fakeNgnProvider — no test asserts against a shape its author imagined independently of the documented one

End-to-end test (src/tests/ngnRailE2E.test.ts — new)

• Walks the full onramp against the fake: provision → verify → quote → order → webhook arrives → order reaches terminal state
• Asserts the full happy path end to end in one coherent flow

Failure-path tests

• A test covers a failure at each step using the documented error codes from the fake — provision failure, verify failure, quote failure, order failure, webhook delivery failure
• All failures use the fake's documented codes — no invented shapes

No test reaches the real provider

• fakeNgnProvider intercepts global.fetch at the module level; any test that forgot to import it and attempted a real fetch would fail rather than silently reaching mainnet

---

#245 — Rate Limits on Creating Routes

Rate limits added to

• POST /ngn/customers — per-IP and per-customer-reference
• POST /ngn/customers/kyc — per-IP and per-customer-reference (protects the one-per-lifetime NIN attempt)
• POST /ngn/onramp/orders — per-IP and per-customer-reference

Design

• Per-reference scoping: one abusive caller with many references (the threat shape) is throttled per reference, not just per IP
• Refusal response is distinguishable from the provider's own 429 — our refusal uses a distinct error code and body shape so a user is not told the provider rejected them when it was us
• Limits are configurable via environment variables without a redeploy — defaults are set comfortably inside the provider's documented limits, with the justification noted in the config comment

Tests

• Each creating route has a test that exhausts the limit and asserts the next request is refused
• Per-reference limit is tested independently of the per-IP limit — one reference over limit while another is not
• Our 429 response body is asserted to differ from the shape the fake provider returns for its own 429

---

How to verify

npm test

• Confirm all existing suites pass with the migrated fake mocks (no ad-hoc shapes remaining)
• Run the E2E test and confirm the full provision → verify → quote → order → webhook → settle flow passes against the fake
• Confirm failure-path tests cover each step with documented error codes
• Exhaust the rate limit on POST /ngn/customers/kyc and assert the refusal response is distinguishable from a provider 429
• Exhaust the per-reference limit for one reference and confirm a different reference is not blocked
• Confirm src/tests/openapiCoverage.test.ts is still red on main — this PR does not touch it

---

Checklist

• fakeNgnProvider.ts is the single source of truth for provider response shapes
• All documented endpoints and failure modes implemented in the fake
• global.fetch interception enforced at module level — no test can reach the real provider
• All existing suites migrated from ad-hoc fetch mocks to fakeNgnProvider
• End-to-end test covers full happy path: provision → verify → quote → order → webhook → settle
• Failure-path test covers each step using documented error codes
• Rate limits added to POST /ngn/customers, POST /ngn/customers/kyc, POST /ngn/onramp/orders
• Limits scoped per-IP and per-customer-reference
• Our 429 refusal is distinguishable from the provider's own 429 in the response body
• Limits configurable via env vars without redeploy — defaults justified in config comment
• Per-reference limit tested independently of per-IP limit
• npm test green (openapiCoverage.test.ts pre-existing failure on main is not introduced by this PR)
• Closes There is no end-to-end test of the naira rails, because there is nothing to test against #246, Closes Lookups are rate-limited; the routes that move money are not #245

[drips-wave]

@teethaking Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

[Miracle656]

Rebase needed — #261 landed, consolidating the two Linq HTTP clients into a single src/linq/http.ts. Anything touching src/linq/client.ts or the old call() in src/linq/onramp.ts will conflict.

What changed, so the rebase is predictable:

• One client. src/linq/http.ts is now the only module that names LINQ_BASE_URL, the provider host or the X-API-Key header — and there are guard tests asserting that, so a second client cannot grow back.
• LinqError kept all its fields, including existingCustomerRef, which I added yesterday for Linq's email_already_in_use response.
• #250 also landed and fixed main's Typecheck & build, so you should inherit a green one.

Also worth knowing: Integration tests is red on main itself — tests/integration/api.test.ts, the Postgres read path, expected undefined to be 2, failing since at least 10-16. Not yours, and not a reason to hold a rebase.

Push and I will pick it up.

[teethaking]

@Miracle656

[Miracle656]

Needs a rebase — src/indexer.ts conflicts with work that landed after you branched, in three places around loop lifecycle:

<<<<<<< HEAD
  for (const loop of loops.values()) loop.stopped = true;
  for (const timer of restartTimers.values()) clearTimeout(timer);
=======
  for (const timer of restartTimers) clearTimeout(timer);

main now tracks loops in a map with a stopped flag and keyed restart timers; your branch has the older set-based timers. Take main's side for the lifecycle and reapply your changes on top — the newer version exists so a loop cannot outlive _resetIndexerLoops and keep polling between test cases.

Also note #251 landed and corrected the native XLM SAC constants in that same file. DEFAULT_XLM_SAC_MAINNET was holding testnet's SAC and DEFAULT_XLM_SAC_TESTNET a contract that is neither network's, so mainnet native XLM was never being indexed. Make sure the rebase keeps main's values and the derivation test beside them.

Both halves of this are things I want

The fake provider is the one that matters most. Linq has no sandbox — every call against the real API moves real money, which is why the whole /ngn surface is mainnet-gated at the router. That makes a canonical fake the only way to exercise the rails end to end, and making it the single source of truth for response shapes is better than the per-test fetch mocks it replaces: ad-hoc mocks drift apart, and then each test is asserting against a slightly different idea of what the provider sends.

Rate limits on the creating routes is the other half, and it is overdue. POST /ngn/onramp/orders is the one route with no local limiter — we established that when a tester hit a 429 and we could not tell Linq's rate limit from our own, because both matched the same regex. Worse, the KYC route spends a one-per-lifetime NIN attempt: an unthrottled route there does not cost quota, it costs a person their ability to verify.

So the shape is right. Rebase on current main and I will review it properly — nothing is queued ahead of it.

Integration tests is red on main itself (Postgres read path, since at least 10-16) and is not yours.

[Miracle656]

The feature is one I want badly, and I'll say why below — but the branch doesn't build, and the cause is the same mistake in two files.

Duplicate merges, in indexer.ts and accounts.test.ts

src/indexer.ts declares restartTimers twice:

154:const restartTimers = new Map<Network, ReturnType<typeof setTimeout>>();   // yours
252:const restartTimers = new Set<NodeJS.Timeout>();                           // already on main

and then runs both cleanups back to back in _resetIndexerLoops:

for (const timer of restartTimers.values()) clearTimeout(timer);   // Map form
restartTimers.clear();
for (const timer of restartTimers) clearTimeout(timer);            // Set form
restartTimers.clear();

main already had a crash-restart timer registry. Your branch adds a second one beside it instead of using it, which is a duplicate identifier and, at line 703, an unbalanced brace:

src/indexer.ts(703,1): error TS1005: '}' expected.

src/__tests__/routes/accounts.test.ts has the same shape. You add:

jest.mock("../../rpc", () => ({
  getLatestLedger: jest.fn().mockResolvedValue(1_000_000),

— unclosed — immediately above the jest.mock("../../rpc", ...) that is already there on main, with the same purpose and a fuller comment explaining the stale-read middleware's RPC probe. That one even uses ...jest.requireActual, which yours drops. The file stops parsing at line 22.

Both look like a merge where main's version and your version were both kept rather than reconciled. Worth re-reading the diff for your own branch against current main before pushing — git diff main...HEAD on the two files makes it obvious, and npm run typecheck finds it in one command without reading anything.

I removed the accounts.test.ts fragment locally to see what was behind it, and indexer.ts was waiting.

The feature is genuinely valuable, so please do come back to it

A fake Linq provider is the single most useful test fixture this repo could have. Linq has no sandbox — it is mainnet-gated, so every real exercise of the naira rails moves actual money against a real NIN-verified customer. That has meant the offramp, onramp and bills paths are the least testable code in the repo and simultaneously the only code that can lose someone's money. An in-process fake that speaks the provider's shapes changes what we can assert without spending naira to find out.

Rate limits on money-moving routes are the other half, and they matter more than usual here because all Veil users share one provider key. I hit 429 rate_limited from four manual probes of /ngn/onramp/rate while reviewing another PR today, so the allowance is tighter than it looks and protecting it at our own edge rather than discovering it at Linq's is right.

Two things to know when you rebase, both landed today:

• POST /ngn/onramp/orders now refuses any coin but xlm (coin_not_available), because Linq told us they hold liquidity for XLM and not USDC. GET /ngn/onramp/rate deliberately still quotes both — the mobile client probes it as a liveness check. If your fake provider models the coin set, model that asymmetry too.
• POST /offramp/orders now stores a requestHash and answers a concurrent duplicate as a replay rather than a 500.

Integration tests is red on main (Postgres read path, since at least 10-16) and is not yours.

Re-request review once npm run typecheck is clean — I'll prioritise it.

https://claude.ai/code/session_01USgemLt4Rnz4SGB1Srf3GB

[Miracle656]

Merged. This is a lot of good work — 675 lines of fake provider and a 602-line end-to-end suite, and it takes the test count from 1,026 to 1,070.

The duplicate restartTimers is resolved, and your own commit message names the cause better than I did: "reconcile the merges that kept both versions instead of one". That is exactly what repeated base merges had done to src/indexer.ts, and it is worth remembering, because the same mechanism produces the same bug every time and it never shows up as a conflict.

Verified before merging:

tsc --noEmit   clean
jest           69 suites, 1070 tests passing

One line changed on the way in: I dropped --forceExit from the test script. I checked rather than assumed — the new e2e suite exits clean under --detectOpenHandles, and the full suite without the flag exits 0 in 95 seconds. So nothing needed it.

I'd rather not keep it, and the reason is specific to this PR: --forceExit is the flag that stops jest ever telling you something did not clean up. This change adds a fake HTTP server and timers to the suite — the exact code where a leaked handle is most likely to appear later, and where you would most want to hear about it. If it was papering over a hang you actually hit, say so and I will look at the real cause with you; #207 is open on shutdown tidiness and that is the right home for it.

One consequence worth noting: #282 asks for something that proves the fake provider still matches the real one. Until today that was hypothetical. Now that this fake exists and the e2e suite depends on it, it is the natural follow-up — a fake that drifts from the real Linq is worse than no fake, because it passes.