Fix audit findings: plugin budgets, fail-closed hooks, secret params, dup IDs, dead config, input validation

- Per-request plugin budgets: PluginRegistry.beginRequest() mints a
  RequestPlugins with its own budget map, so concurrent requests no longer
  clobber each other's allowances (was a shared mutable map reset per request).
- Mutation hooks fail-closed on a thrown error (onHttpRequest rejects;
  onBeforeApiCall/onAfterApiCall/onBeforeSign drop), matching the documented
  contract instead of silently skipping a broken plugin.
- Secret-param detection runs before env interpolation: a `fixed: ${VAR}`
  parameter is now flagged `secret: true` in parseConfig so the resolved value
  stays out of the public endpoint ID (the implicit `${...}` check in
  isSecretParameter was dead post-interpolation).
- buildEndpointMap throws on colliding endpoint IDs and validateConfig reports
  them, instead of new Map() silently last-wins.
- Removed the unimplemented `cache.delay` field from the schema, docs, and
  example config.
- parseRequestBody rejects a non-object `parameters` (400) but passes nested
  values through untouched so body parameters can still be nested JSON;
  resolveEncoding ignores non-string `_type`/`_path`/`_times` (clean 400, not a
  502); body-size check counts bytes. Documented the limitation.
- x402 `amount` must be a non-negative integer string (config error, not a
  BigInt throw at request time).

Author: andreogle

book/docs/config/apis.md

@@ -139,10 +139,10 @@ cache:
 | Field    | Type     | Required | Description                                                |
 | -------- | -------- | -------- | ---------------------------------------------------------- |
 | `maxAge` | `number` | Yes      | Cache TTL in milliseconds for responses. Positive integer. |
-| `delay`  | `number` | No       | Delay in milliseconds before cached responses are served.  |
 
 `maxAge` controls response caching — repeated `POST /endpoints/{id}` requests with the same parameters return the cached
-response until the TTL expires.
+response until the TTL expires. A cached response replays the same signature and timestamp, so within `maxAge` every
+caller (and every on-chain submission) gets the identical signed payload.
 
 ## Endpoint-level fields
 
@@ -222,6 +222,20 @@ parameters:
     default: usd
 ```
 
+:::note Parameter values in requests
+
+Clients send parameter values in the request body as `{"parameters": {"name": value, ...}}`. `parameters` must be a JSON
+**object** (a non-object value is rejected with `400`). The individual values are handled per parameter `in`:
+
+- `query`, `path`, `header`, `cookie` — the value is coerced to a string. **Pass a string** (or a number/boolean);
+  passing a nested object or array here produces a stringified placeholder, not what you want.
+- `body` — the value is serialized whole into the upstream request body, so **nested JSON is supported and expected**
+  here (e.g. a JSON-RPC `params: [{ "to": "0x...", "data": "0x..." }, "latest"]`).
+
+In short: only `body` parameters may be nested; everything else should be a primitive.
+
+:::
+
 ### Parameter fields
 
 | Field         | Type                          | Required | Default | Description                                                    |

examples/configs/complete/config.yaml

@@ -47,7 +47,6 @@ apis:
           times: '1e18'
         cache:
           maxAge: 30000
-          delay: 60000 # public responses delayed by 60s (OEV window)
         description: Get the current price of a coin
 
       - name: coinMarketData

src/config/parser.test.ts

@@ -1,4 +1,5 @@
 import { beforeAll, describe, expect, test } from 'bun:test';
+import { deriveEndpointId } from '../endpoint';
 import { loadEnvFile } from './env';
 import { interpolateEnvironment, parseConfig } from './parser';
 
@@ -99,6 +100,84 @@ describe('parseConfig', () => {
     expect(() => parseConfig('not: valid: yaml: [')).toThrow();
   });
 
+  test('flags parameters with env-backed fixed values as secret', () => {
+    process.env['SECRET_PARAM_VALUE'] = 'super-secret-key';
+    const raw = `
+version: '1.0'
+server:
+  port: 3000
+settings:
+  proof: none
+apis:
+  - name: Test
+    url: https://api.example.com
+    endpoints:
+      - name: getData
+        path: /data
+        parameters:
+          - name: apikey
+            in: query
+            fixed: \${SECRET_PARAM_VALUE}
+          - name: coin
+            in: query
+            required: true
+`;
+    const params = parseConfig(raw).apis[0]?.endpoints[0]?.parameters;
+    const apikey = params?.find((p) => p.name === 'apikey');
+    expect(apikey?.fixed).toBe('super-secret-key'); // resolved from the environment
+    expect(apikey?.secret).toBe(true); // and marked secret so it stays out of the endpoint ID
+    expect(params?.find((p) => p.name === 'coin')?.secret).toBe(false);
+  });
+
+  test('env-backed fixed params do not change the endpoint ID', () => {
+    process.env['SECRET_PARAM_VALUE'] = 'super-secret-key';
+    const withSecretParam = `
+version: '1.0'
+server:
+  port: 3000
+settings:
+  proof: none
+apis:
+  - name: Test
+    url: https://api.example.com
+    endpoints:
+      - name: getData
+        path: /data
+        parameters:
+          - name: apikey
+            in: query
+            fixed: \${SECRET_PARAM_VALUE}
+          - name: coin
+            in: query
+            required: true
+`;
+    const withoutSecretParam = `
+version: '1.0'
+server:
+  port: 3000
+settings:
+  proof: none
+apis:
+  - name: Test
+    url: https://api.example.com
+    endpoints:
+      - name: getData
+        path: /data
+        parameters:
+          - name: coin
+            in: query
+            required: true
+`;
+    const apiWith = parseConfig(withSecretParam).apis[0];
+    const apiWithout = parseConfig(withoutSecretParam).apis[0];
+    const endpointWith = apiWith?.endpoints[0];
+    const endpointWithout = apiWithout?.endpoints[0];
+    if (!apiWith || !endpointWith || !apiWithout || !endpointWithout) {
+      throw new Error('config did not parse as expected');
+    }
+    expect(deriveEndpointId(apiWith, endpointWith)).toBe(deriveEndpointId(apiWithout, endpointWithout));
+  });
+
   test('interpolates header values from environment variables', async () => {
     const raw = await loadExample();
     const config = parseConfig(raw);

src/config/parser.ts

@@ -14,8 +14,52 @@ export function interpolateEnvironment(raw: string): string {
   });
 }
 
+// =============================================================================
+// Secret parameter detection (must run before interpolation)
+//
+// A parameter whose `fixed` value references an env var (e.g. `fixed: ${API_KEY}`)
+// is treated as secret: its resolved value is excluded from the endpoint ID. This
+// has to be detected on the *un-interpolated* config — once `${VAR}` has been
+// replaced with the value, there is nothing left to recognise. Interpolation only
+// rewrites scalar text (it never adds, removes, or reorders keys), so each
+// parameter occupies the same position in the raw and interpolated parses, and we
+// can mark `secret: true` on the corresponding entry in the interpolated tree.
+// =============================================================================
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function asArray(value: unknown): readonly unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+function markEnvBackedFixedParamsSecret(raw: unknown, interpolated: unknown): void {
+  const rawApis = asArray(asRecord(raw)?.['apis']);
+  const apis = asArray(asRecord(interpolated)?.['apis']);
+  // eslint-disable-next-line functional/no-loop-statements
+  for (const [apiIndex, rawApi] of rawApis.entries()) {
+    const rawEndpoints = asArray(asRecord(rawApi)?.['endpoints']);
+    const endpoints = asArray(asRecord(apis[apiIndex])?.['endpoints']);
+    // eslint-disable-next-line functional/no-loop-statements
+    for (const [endpointIndex, rawEndpoint] of rawEndpoints.entries()) {
+      const rawParams = asArray(asRecord(rawEndpoint)?.['parameters']);
+      const params = asArray(asRecord(endpoints[endpointIndex])?.['parameters']);
+      // eslint-disable-next-line functional/no-loop-statements
+      for (const [paramIndex, rawParam] of rawParams.entries()) {
+        const fixed = asRecord(rawParam)?.['fixed'];
+        if (typeof fixed !== 'string' || !fixed.startsWith('${')) continue;
+        const target = asRecord(params[paramIndex]);
+        if (target) target['secret'] = true; // eslint-disable-line functional/immutable-data
+      }
+    }
+  }
+}
+
 export function parseConfig(raw: string): Config {
   const interpolated = interpolateEnvironment(raw);
   const data: unknown = parse(interpolated);
+  markEnvBackedFixedParamsSecret(parse(raw), data);
   return configSchema.parse(data);
 }

src/config/schema.test.ts

@@ -129,6 +129,24 @@ apis:
     expect(auth.expiry).toBe(300_000);
   });
 
+  test('rejects a non-numeric x402 amount', () => {
+    const raw = MINIMAL_CONFIG.replace(
+      'url: https://api.example.com',
+      `url: https://api.example.com
+    auth:
+      type: x402
+      network: 8453
+      rpc: https://mainnet.base.org
+      token: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'
+      amount: '1 USDC'
+      recipient: '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'`
+    );
+    expect(() => configSchema.parse(parseYaml(raw))).toThrow();
+
+    const withDecimal = raw.replace("amount: '1 USDC'", "amount: '1.5'");
+    expect(() => configSchema.parse(parseYaml(withDecimal))).toThrow();
+  });
+
   test('validates auth as array (multi-method)', () => {
     const raw = MINIMAL_CONFIG.replace(
       'url: https://api.example.com',
@@ -197,7 +215,7 @@ apis:
     expect(result.apis[0]?.endpoints[0]?.cache).toEqual({ maxAge: 5000 });
   });
 
-  test('validates cache with delay', () => {
+  test('strips unknown cache keys', () => {
     const raw = MINIMAL_CONFIG.replace(
       'path: /test',
       `path: /test
@@ -206,7 +224,7 @@ apis:
           delay: 60000`
     );
     const result = configSchema.parse(parseYaml(raw));
-    expect(result.apis[0]?.endpoints[0]?.cache).toEqual({ maxAge: 5000, delay: 60_000 });
+    expect(result.apis[0]?.endpoints[0]?.cache).toEqual({ maxAge: 5000 });
   });
 
   test('validates parameters with secret flag', () => {

src/config/schema.ts

@@ -73,7 +73,10 @@ const x402ClientAuthSchema = z.object({
   network: z.number().int().positive(),
   rpc: z.url(),
   token: evmAddressSchema,
-  amount: z.string().min(1),
+  // Base-unit integer amount (e.g. wei, or token base units) — kept as a string
+  // to preserve precision and parsed with BigInt at request time, so it must be
+  // a plain non-negative integer with no decimal point, sign, or units.
+  amount: z.string().regex(/^\d+$/, 'Must be a non-negative integer string (token base units)'),
   recipient: evmAddressSchema,
   expiry: z.number().int().positive().default(300_000),
 });
@@ -92,7 +95,6 @@ export const clientAuthSchema = z.union([clientAuthMethodSchema, z.array(clientA
 // =============================================================================
 export const cacheSchema = z.object({
   maxAge: z.number().int().positive(),
-  delay: z.number().int().nonnegative().optional(),
 });
 
 // =============================================================================

src/config/validate.test.ts

@@ -146,6 +146,29 @@ apis:
     expect(result.errors[0]).toContain('Duplicate API name');
   });
 
+  test('rejects endpoints with identical specifications (colliding endpoint IDs)', () => {
+    const yaml = `
+version: '1.0'
+server:
+  port: 3000
+settings:
+  proof: none
+apis:
+  - name: Test
+    url: https://api.example.com
+    endpoints:
+      - name: first
+        path: /data
+      - name: second
+        path: /data
+`;
+    const result = validateConfig(yaml);
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.errors.some((e) => e.includes('identical specifications'))).toBe(true);
+  });
+
   // ===========================================================================
   // Multiple errors
   // ===========================================================================

src/config/validate.ts

@@ -1,6 +1,7 @@
 import { goSync } from '@api3/promise-utils';
 import { parse } from 'yaml';
 import type { z } from 'zod/v4';
+import { deriveEndpointId } from '../endpoint';
 import { interpolateEnvironment } from './parser';
 import { configSchema } from './schema';
 
@@ -42,7 +43,19 @@ function crossFieldErrors(config: z.infer<typeof configSchema>): readonly string
       ? [`Duplicate plugin source(s): ${[...new Set(duplicatePluginSources)].join(', ')}`]
       : [];
 
-  return [...apiNameErrors, ...endpointNameErrors, ...pluginErrors];
+  // Two endpoints with identical specifications derive the same endpoint ID,
+  // which would silently shadow one another in the endpoint map.
+  const endpointEntries = config.apis.flatMap((api) =>
+    api.endpoints.map((endpoint) => ({ id: deriveEndpointId(api, endpoint), label: `${api.name}/${endpoint.name}` }))
+  );
+  const endpointIds = endpointEntries.map((e) => e.id);
+  const duplicateEndpointIds = endpointIds.filter((id, i, all) => all.indexOf(id) !== i);
+  const endpointIdErrors = [...new Set(duplicateEndpointIds)].map((id) => {
+    const labels = endpointEntries.filter((e) => e.id === id).map((e) => e.label);
+    return `Endpoints with identical specifications (same endpoint ID ${id}): ${labels.join(', ')}`;
+  });
+
+  return [...apiNameErrors, ...endpointNameErrors, ...pluginErrors, ...endpointIdErrors];
 }
 
 // =============================================================================

src/endpoint.test.ts

@@ -259,4 +259,29 @@ describe('buildEndpointMap', () => {
     const map = buildEndpointMap(config);
     expect(map.size).toBe(3);
   });
+
+  test('throws when two endpoints derive the same ID', () => {
+    const api = makeApi({
+      url: 'https://api.example.com',
+      // Same path + method + (no) params + (no) encoding → identical endpoint ID.
+      endpoints: [makeEndpoint({ name: 'first', path: '/data' }), makeEndpoint({ name: 'second', path: '/data' })],
+    });
+
+    expect(() => buildEndpointMap(makeConfig([api]))).toThrow(/same endpoint ID/);
+  });
+
+  test('throws when endpoints across different APIs with the same url collide', () => {
+    const api1 = makeApi({
+      name: 'A',
+      url: 'https://shared.example.com',
+      endpoints: [makeEndpoint({ name: 'x', path: '/p' })],
+    });
+    const api2 = makeApi({
+      name: 'B',
+      url: 'https://shared.example.com',
+      endpoints: [makeEndpoint({ name: 'y', path: '/p' })],
+    });
+
+    expect(() => buildEndpointMap(makeConfig([api1, api2]))).toThrow(/same endpoint ID/);
+  });
 });

src/endpoint.ts

@@ -59,15 +59,28 @@ function deriveEndpointId(api: Api, endpoint: Endpoint): Hex {
 
 // =============================================================================
 // Endpoint map
+//
+// Two endpoints with identical specifications (URL, path, method, parameters,
+// encoding, encryption) derive the same ID. Building the map silently with
+// `new Map(entries)` would let the later one shadow the earlier — so we detect
+// the collision and fail loudly instead.
 // =============================================================================
 function buildEndpointMap(config: Config): ReadonlyMap<Hex, ResolvedEndpoint> {
   const entries = config.apis.flatMap((api) =>
-    api.endpoints.map((endpoint) => {
-      const endpointId = deriveEndpointId(api, endpoint);
-      return [endpointId, { api, endpoint }] as const;
-    })
+    api.endpoints.map((endpoint) => [deriveEndpointId(api, endpoint), { api, endpoint }] as const)
   );
 
+  const ids = entries.map(([id]) => id);
+  const duplicateId = ids.find((id, index) => ids.indexOf(id) !== index);
+  if (duplicateId) {
+    const colliding = entries
+      .filter(([id]) => id === duplicateId)
+      .map(([, resolved]) => `"${resolved.api.name}/${resolved.endpoint.name}"`);
+    throw new Error(
+      `Endpoints ${colliding.join(' and ')} derive the same endpoint ID ${duplicateId} — their specifications are identical`
+    );
+  }
+
   return new Map(entries);
 }