config: make x402 rate limit + maxConcurrentApiCalls explicit

andreogle · andreogle · commit 81712d53f6f6 · 2026-05-14T16:51:20.000-05:00
`server.rateLimit.x402` and `settings.maxConcurrentApiCalls` are now required (no `.default()`). Hidden defaults make it hard to see what's actually running at a glance, and these tuning knobs aren't universal — operators should set them per deployment. Breaking, in line with `server.rateLimit` from c1a37c4. The x402 bucket is also now configurable per-deployment: it threads through `PipelineDependencies.rateLimit` into `AuthContext.x402RateLimit` and is honored when the per-IP bucket is checked in `checkX402`. Tests exercise both the default plumbing and a custom override. `createTestServer` and `makeConfig` (server.test.ts) deep-merge a `Partial<RateLimit>` override so call sites stay tight — tests pass `{ max: 3 }` instead of redeclaring the full shape every time. Examples, inline YAML fixtures, and book/docs/config/{server,settings} updated to include the new required fields.
diff --git a/book/docs/config/server.md b/book/docs/config/server.md
@@ -16,31 +16,40 @@ server:
   rateLimit:
     window: 60000 # ms
     max: 100 # requests per window per IP
+    x402:
+      window: 60000 # ms
+      max: 30 # x402 verification attempts per window per IP
 ```
 
 ## Fields
 
-| Field                         | Type       | Required | Default     | Description                                                                                         |
-| ----------------------------- | ---------- | -------- | ----------- | --------------------------------------------------------------------------------------------------- |
-| `port`                        | `number`   | Yes      | --          | TCP port the server listens on.                                                                     |
-| `host`                        | `string`   | No       | `'0.0.0.0'` | Bind address. Use `127.0.0.1` to restrict to localhost.                                             |
-| `cors`                        | `object`   | No       | --          | CORS configuration. When omitted, `Access-Control-Allow-Origin: *` is used.                         |
-| `cors.origins`                | `string[]` | No       | `['*']`     | Allow-list of origins. The request's `Origin` is reflected back only if it matches an entry.        |
-| `rateLimit`                   | `object`   | **Yes**  | --          | Per-IP rate limiting (required). Set `max` very high to effectively disable it.                     |
-| `rateLimit.window`            | `number`   | Yes      | --          | Time window in milliseconds.                                                                        |
-| `rateLimit.max`               | `number`   | Yes      | --          | Maximum requests per IP within the window.                                                          |
-| `rateLimit.trustForwardedFor` | `boolean`  | No       | `false`     | Use the first `X-Forwarded-For` entry as the client IP. Only enable behind a trusted reverse proxy. |
+| Field                         | Type       | Required | Default     | Description                                                                                                                |
+| ----------------------------- | ---------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `port`                        | `number`   | Yes      | --          | TCP port the server listens on.                                                                                            |
+| `host`                        | `string`   | No       | `'0.0.0.0'` | Bind address. Use `127.0.0.1` to restrict to localhost.                                                                    |
+| `cors`                        | `object`   | No       | --          | CORS configuration. When omitted, `Access-Control-Allow-Origin: *` is used.                                                |
+| `cors.origins`                | `string[]` | No       | `['*']`     | Allow-list of origins. The request's `Origin` is reflected back only if it matches an entry.                               |
+| `rateLimit`                   | `object`   | **Yes**  | --          | Per-IP rate limiting (required). Set `max` very high to effectively disable it.                                            |
+| `rateLimit.window`            | `number`   | Yes      | --          | Time window in milliseconds.                                                                                               |
+| `rateLimit.max`               | `number`   | Yes      | --          | Maximum requests per IP within the window.                                                                                 |
+| `rateLimit.trustForwardedFor` | `boolean`  | No       | `false`     | Use the first `X-Forwarded-For` entry as the client IP. Only enable behind a trusted reverse proxy.                        |
+| `rateLimit.x402`              | `object`   | **Yes**  | --          | Stricter per-IP bucket on x402 verification attempts (each one fires several chain-RPC reads). Shares `trustForwardedFor`. |
+| `rateLimit.x402.window`       | `number`   | Yes      | --          | Time window in milliseconds.                                                                                               |
+| `rateLimit.x402.max`          | `number`   | Yes      | --          | Maximum x402 verification attempts per IP within the window.                                                               |
 
 ## Minimal
 
-`port` and `rateLimit` are required:
+`port` and `rateLimit` (including the `x402` sub-block) are required:
 
 ```yaml
 server:
   port: 3000
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 ```
 
 This binds to `0.0.0.0:3000` with a default `Access-Control-Allow-Origin: *` header. If you front the airnode with your
@@ -57,6 +66,9 @@ server:
   rateLimit:
     window: 60000 # 60 seconds
     max: 100 # 100 requests per 60s per IP
+    x402:
+      window: 60000
+      max: 30 # 30 x402 verification attempts per 60s per IP
 ```
 
 When a client exceeds the limit, the server returns `429 Too Many Requests`.
@@ -68,6 +80,14 @@ every client would share one bucket — set `rateLimit.trustForwardedFor: true`
 instead. Only enable this when a trusted proxy controls that header; a client-supplied `X-Forwarded-For` is otherwise
 trivially spoofable.
 
+### x402 verification bucket
+
+`rateLimit.x402` is a separate, stricter per-IP bucket that applies only to **submitted x402 payment proofs**. Each
+verification fires several chain-RPC reads, so an unauthenticated flooder would otherwise drain the operator's RPC quota
+even at a generous global `rateLimit.max`. The 402-challenge response (sent when no proof header is present) does not
+draw from this bucket. The same client-IP key is used as the global limit, so `trustForwardedFor` applies consistently
+to both. When exceeded, the response is `401 Too many x402 verification attempts — slow down`.
+
 ## CORS
 
 CORS headers are included on every response (and on the `OPTIONS` preflight, which returns `204`):
diff --git a/book/docs/config/settings.md b/book/docs/config/settings.md
@@ -10,7 +10,7 @@ The `settings` section configures global behavior. It is placed immediately afte
 ```yaml
 settings:
   timeout: 10000 # default, ms
-  maxConcurrentApiCalls: 50 # default
+  maxConcurrentApiCalls: 50
   proof: none
   fhe: none
   plugins:
@@ -23,7 +23,7 @@ settings:
 | Field                   | Type               | Required | Default  | Description                                            |
 | ----------------------- | ------------------ | -------- | -------- | ------------------------------------------------------ |
 | `timeout`               | `number`           | No       | `10000`  | Global upstream API request timeout in milliseconds.   |
-| `maxConcurrentApiCalls` | `number`           | No       | `50`     | Process-wide ceiling on concurrent upstream API calls. |
+| `maxConcurrentApiCalls` | `number`           | **Yes**  | --       | Process-wide ceiling on concurrent upstream API calls. |
 | `proof`                 | `string \| object` | No       | `'none'` | Proof mode. See [Proof](#proof).                       |
 | `fhe`                   | `string \| object` | No       | `'none'` | FHE encryption relayer. See [FHE](#fhe).               |
 | `plugins`               | `array`            | No       | `[]`     | Plugin entries. See [Plugin Configuration](./plugins). |
diff --git a/examples/configs/complete/config.yaml b/examples/configs/complete/config.yaml
@@ -9,9 +9,13 @@ server:
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 
 settings:
   timeout: 15000
+  maxConcurrentApiCalls: 50
   proof: none # or: { type: reclaim, gatewayUrl: 'http://localhost:5177/v1/prove' }
   plugins:
     - source: ../../plugins/heartbeat.ts
diff --git a/examples/configs/fhe-encrypt/config.yaml b/examples/configs/fhe-encrypt/config.yaml
@@ -5,8 +5,12 @@ server:
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 
 settings:
+  maxConcurrentApiCalls: 50
   proof: none
   # FHE relayer connection. With `fhe` configured, any endpoint that has an
   # `encrypt` block gets its ABI-encoded value replaced with an FHE ciphertext
diff --git a/examples/configs/minimal/config.yaml b/examples/configs/minimal/config.yaml
@@ -5,8 +5,12 @@ server:
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 
 settings:
+  maxConcurrentApiCalls: 50
   proof: none
   plugins:
     - source: ../../plugins/logger.ts
diff --git a/examples/configs/reclaim-proof/config.yaml b/examples/configs/reclaim-proof/config.yaml
@@ -5,8 +5,12 @@ server:
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 
 settings:
+  maxConcurrentApiCalls: 50
   proof:
     type: reclaim
     gatewayUrl: http://localhost:5177/v1/prove
diff --git a/integration/helpers.ts b/integration/helpers.ts
@@ -40,14 +40,24 @@ function rewriteApiUrls(apis: readonly Api[]): Api[] {
 }
 
 interface TestServerOptions {
-  readonly server?: Partial<Config['server']>;
+  readonly server?: Partial<Omit<Config['server'], 'rateLimit'>> & {
+    readonly rateLimit?: Partial<Config['server']['rateLimit']>;
+  };
   readonly settings?: Partial<Config['settings']>;
   readonly plugins?: PluginRegistry;
   readonly apiOverrides?: (apis: readonly Api[]) => Api[];
 }
 
+const DEFAULT_TEST_RATE_LIMIT: Config['server']['rateLimit'] = {
+  // Effectively no limit by default; rate-limit scenarios override this.
+  window: 60_000,
+  max: 1_000_000,
+  trustForwardedFor: false,
+  x402: { window: 60_000, max: 1_000_000 },
+};
+
 async function createTestServer(options: TestServerOptions = {}): Promise<TestContext> {
-  const serverOverrides = options.server ?? {};
+  const { rateLimit: rateLimitOverride, ...serverOverrides } = options.server ?? {};
   const settingsOverrides = options.settings ?? {};
   await loadEnvFile(ENV_PATH);
 
@@ -60,8 +70,7 @@ async function createTestServer(options: TestServerOptions = {}): Promise<TestCo
     server: {
       ...parsed.server,
       port: 0,
-      // Effectively no limit by default; rate-limit scenarios override this.
-      rateLimit: { window: 60_000, max: 1_000_000, trustForwardedFor: false },
+      rateLimit: { ...DEFAULT_TEST_RATE_LIMIT, ...rateLimitOverride },
       ...serverOverrides,
     },
     settings: { ...parsed.settings, plugins: [], ...settingsOverrides },
@@ -83,6 +92,7 @@ async function createTestServer(options: TestServerOptions = {}): Promise<TestCo
     asyncStore,
     apiCallSemaphore,
     settings: testConfig.settings,
+    rateLimit: testConfig.server.rateLimit,
     handleRequest: handleEndpointRequest,
   });
 
diff --git a/integration/scenarios/s42-forwarded-for.test.ts b/integration/scenarios/s42-forwarded-for.test.ts
@@ -24,7 +24,7 @@ async function hit(baseUrl: string, forwardedFor: string): Promise<number> {
 
 describe('S42 — X-Forwarded-For rate limiting', () => {
   test('with trustForwardedFor on, each forwarded client has an independent bucket', async () => {
-    ctx = await createTestServer({ server: { rateLimit: { window: 60_000, max: 3, trustForwardedFor: true } } });
+    ctx = await createTestServer({ server: { rateLimit: { max: 3, trustForwardedFor: true } } });
 
     expect(await hit(ctx.baseUrl, '1.2.3.4')).toBe(200);
     expect(await hit(ctx.baseUrl, '1.2.3.4')).toBe(200);
@@ -38,7 +38,7 @@ describe('S42 — X-Forwarded-For rate limiting', () => {
   });
 
   test('with trustForwardedFor off, the header is ignored and all callers share one bucket', async () => {
-    ctx = await createTestServer({ server: { rateLimit: { window: 60_000, max: 3, trustForwardedFor: false } } });
+    ctx = await createTestServer({ server: { rateLimit: { max: 3 } } });
 
     expect(await hit(ctx.baseUrl, '1.1.1.1')).toBe(200);
     expect(await hit(ctx.baseUrl, '2.2.2.2')).toBe(200);
diff --git a/integration/scenarios/s8-rate-limiting.test.ts b/integration/scenarios/s8-rate-limiting.test.ts
@@ -5,7 +5,7 @@ import type { TestContext } from '../helpers';
 let ctx: TestContext;
 
 beforeAll(async () => {
-  ctx = await createTestServer({ server: { rateLimit: { window: 60_000, max: 3, trustForwardedFor: false } } });
+  ctx = await createTestServer({ server: { rateLimit: { max: 3 } } });
 });
 
 afterAll(() => {
diff --git a/src/auth.test.ts b/src/auth.test.ts
@@ -423,4 +423,26 @@ describe('x402 auth', () => {
     const ok = await authenticateRequest(makeRequest(proofHeader(stillOkProof)), otherIpCtx, x402Config);
     expect(ok.authenticated).toBe(true);
   });
+
+  test('honors a custom x402RateLimit from config', async () => {
+    setRpcClientFactory(() => fakeRpc({ txFrom: '0x000000000000000000000000000000000000bEEF', txTo: RECIPIENT }));
+    const ipCtx: AuthContext = {
+      ...CTX,
+      clientIp: '203.0.113.77', // a fresh IP, so the bucket is full
+      x402RateLimit: { window: 60_000, max: 3 },
+    };
+
+    // Burn the tight 3-token budget.
+    for (let i = 0; i < 3; i++) {
+      const txHash: Hex = `0xaa${i.toString(16).padStart(62, '0')}`;
+      const proof = await makeSignedProof({ txHash });
+      const r = await authenticateRequest(makeRequest(proofHeader(proof)), ipCtx, x402Config);
+      expect(expectError(r)).toBe('Payment verification failed');
+    }
+
+    // Fourth attempt is blocked by the configured limit.
+    const overflow = await makeSignedProof({ txHash: `0xbb${'00'.repeat(31)}` });
+    const blocked = await authenticateRequest(makeRequest(proofHeader(overflow)), ipCtx, x402Config);
+    expect(expectError(blocked)).toBe('Too many x402 verification attempts — slow down');
+  });
 });
diff --git a/src/auth.ts b/src/auth.ts
@@ -16,6 +16,9 @@ interface AuthContext {
   // programmatic test callers can omit it; production always passes it from
   // the server's `resolveClientIp(...)`. Missing IPs share one ('unknown') bucket.
   readonly clientIp?: string;
+  // Operator-tunable x402 verification rate-limit (`server.rateLimit.x402`).
+  // Optional here so programmatic callers can omit it; defaults to 30/min/IP.
+  readonly x402RateLimit?: { readonly window: number; readonly max: number };
 }
 
 interface AuthSuccess {
@@ -170,10 +173,11 @@ const usedPaymentProofs = createBoundedMap<string, PaymentProofEntry>({
 // otherwise drain the operator's RPC quota. A separate, much stricter per-IP
 // token bucket on x402 verification attempts (the global `server.rateLimit`
 // counts every route equally — `/health` probes shouldn't shrink the budget
-// available to fight off an x402 flood).
+// available to fight off an x402 flood). The window/max are operator-tunable
+// via `server.rateLimit.x402`; the defaults below apply when the caller
+// (e.g. a programmatic test) doesn't pass values through `AuthContext`.
 // =============================================================================
-const X402_RATE_LIMIT_WINDOW_MS = 60_000;
-const X402_RATE_LIMIT_MAX = 30;
+const DEFAULT_X402_RATE_LIMIT = { window: 60_000, max: 30 } as const;
 const x402AttemptBuckets = new Map<string, TokenBucket>();
 
 const ETH_ZERO_ADDRESS = '0x0000000000000000000000000000000000000000';
@@ -284,7 +288,8 @@ async function checkX402(
   // drain the operator's RPC quota. The bucket is independent of the global
   // limit; missing client IPs (programmatic callers) share an 'unknown' bucket.
   const verifierIp = context.clientIp ?? 'unknown';
-  if (!checkRateLimit(verifierIp, x402AttemptBuckets, X402_RATE_LIMIT_WINDOW_MS, X402_RATE_LIMIT_MAX)) {
+  const limit = context.x402RateLimit ?? DEFAULT_X402_RATE_LIMIT;
+  if (!checkRateLimit(verifierIp, x402AttemptBuckets, limit.window, limit.max)) {
     return { authenticated: false, error: 'Too many x402 verification attempts — slow down' };
   }
 
diff --git a/src/cli/commands/start.ts b/src/cli/commands/start.ts
@@ -68,6 +68,7 @@ export const start = new Command('start')
       asyncStore,
       apiCallSemaphore,
       settings: config.settings,
+      rateLimit: config.server.rateLimit,
       handleRequest: handleEndpointRequest,
     });
 
diff --git a/src/config/parser.test.ts b/src/config/parser.test.ts
@@ -109,7 +109,11 @@ server:
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 settings:
+  maxConcurrentApiCalls: 50
   proof: none
 apis:
   - name: Test
@@ -141,7 +145,11 @@ server:
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 settings:
+  maxConcurrentApiCalls: 50
   proof: none
 apis:
   - name: Test
@@ -164,7 +172,11 @@ server:
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 settings:
+  maxConcurrentApiCalls: 50
   proof: none
 apis:
   - name: Test
diff --git a/src/config/schema.test.ts b/src/config/schema.test.ts
@@ -13,7 +13,11 @@ server:
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 settings:
+  maxConcurrentApiCalls: 50
   proof: none
 apis:
   - name: Test
@@ -66,7 +70,10 @@ apis:
   });
 
   test('rejects a config without server.rateLimit', () => {
-    const raw = MINIMAL_CONFIG.replace('\n  rateLimit:\n    window: 60000\n    max: 100', '');
+    const raw = MINIMAL_CONFIG.replace(
+      '\n  rateLimit:\n    window: 60000\n    max: 100\n    x402:\n      window: 60000\n      max: 30',
+      ''
+    );
     expect(() => configSchema.parse(parseYaml(raw))).toThrow();
   });
 
@@ -348,7 +355,11 @@ server:
   rateLimit:
     window: 60000
     max: 100
+    x402:
+      window: 60000
+      max: 30
 settings:
+  maxConcurrentApiCalls: 50
   fhe:
     network: sepolia
     rpcUrl: https://eth-sepolia.example.com
diff --git a/src/config/schema.ts b/src/config/schema.ts
@@ -153,13 +153,25 @@ const corsSchema = z.object({
   origins: z.array(z.string().min(1)).default(['*']),
 });
 
+// Separate, stricter per-IP bucket on x402 verification attempts. Each
+// verification fires several chain-RPC reads, so an unauthenticated flooder
+// would otherwise drain the operator's RPC quota even at a generous global
+// `rateLimit.max`. The challenge response (no proof yet → 402) is unaffected;
+// only submitted proofs draw from this bucket. Same `clientIp` as the global
+// limit, so `trustForwardedFor` applies consistently.
+const x402RateLimitSchema = z.object({
+  window: z.number().int().positive(),
+  max: z.number().int().positive(),
+});
+
 const rateLimitSchema = z.object({
   window: z.number().int().positive(),
   max: z.number().int().positive(),
   // When Airnode runs behind a reverse proxy the socket peer is the proxy, so
   // every client shares one bucket. Set this only if a *trusted* proxy sets
   // `X-Forwarded-For` — its first entry is then used as the rate-limit key.
   trustForwardedFor: z.boolean().default(false),
+  x402: x402RateLimitSchema,
 });
 
 export const serverSchema = z.object({
@@ -224,7 +236,7 @@ export const settingsSchema = z.object({
   // Process-wide ceiling on concurrent upstream API calls. A burst of requests
   // can't fan out more `fetch`es than this to your (metered) APIs; over the cap,
   // a request waits up to its API `timeout` for a slot, then gets a 503.
-  maxConcurrentApiCalls: z.number().int().positive().default(50),
+  maxConcurrentApiCalls: z.number().int().positive(),
   proof: proofSchema.default('none'),
   fhe: fheSchema.default('none'),
   plugins: z.array(pluginEntrySchema).default([]),
diff --git a/src/config/validate.test.ts b/src/config/validate.test.ts
diff --git a/src/pipeline.test.ts b/src/pipeline.test.ts
diff --git a/src/pipeline.ts b/src/pipeline.ts
diff --git a/src/server.test.ts b/src/server.test.ts
