Address audit design gaps: proof hardening, stream/async consistency, rate limiting, x402 cleanup

- TLS proof: requestProof rejects a proof whose claim.parameters don't match
  the request Airnode made (or that is malformed) — non-fatal; corrected the
  misleading pipeline comment; documented request-vs-response divergence.
- Streaming mode runs inside runWithContext and calls callError/callResponseSent
  like the sync path, and propagates a non-200 pipeline outcome as a plain HTTP
  error response rather than a 200 SSE frame carrying an error payload.
- The response cache is sync-mode only — async/stream neither read nor write it
  (serving a cached JSON body there would break the 202/SSE contract).
- Async store: finished requests are retained only ~60s for polling instead of
  the full 10-minute TTL, and a finished/expired slot is reclaimed when the
  store is full — MAX_PENDING is no longer a sustained-throughput cap.
- Rate limiting: opt-in server.rateLimit.trustForwardedFor uses the first
  X-Forwarded-For entry as the key (for Airnode behind a trusted reverse proxy);
  default false.
- TLS proof gateway timeout is configurable via settings.proof.timeout
  (default 30000ms).
- Dropped the vestigial x402 paymentId — the txHash dedup is the per-payment
  uniqueness guard; the signed message is now
  keccak256(encodePacked(airnode, endpointId, uint64(expiresAt))). Also
  clarified that this scheme is x402-flavoured, not the x402 wire protocol.
- buildApiRequest rejects a cookie parameter value containing ';', CR, or LF.
- FHE instance: caches the createInstance promise (concurrent first requests
  share one call), drops a rejected promise so the next request retries (also
  picks up a rotated chain key), and clears the instance on an encrypt failure.
- Documented: caching an encrypt endpoint replays the same signed ciphertext
  (only one on-chain submission lands per window); set encoding.times on
  encrypt endpoints; the canonical endpoint-ID string format.

Author: andreogle

book/docs/concepts/fhe-encryption.md

@@ -201,6 +201,14 @@ encrypted. The auction contract compares `FHE.gt(bid, reservePrice)` without rev
 - **One consumer per endpoint.** The encrypted input is bound to `encrypt.contract`, so an endpoint feeds exactly one
   consumer contract. If several contracts need the same feed, deploy a shared registry contract (the
   `ConfidentialPriceFeed` pattern) that re-shares the handle via `FHE.allow`, or define one endpoint per consumer.
+- **Avoid caching encrypt endpoints.** A [cached](/docs/config/apis#cache) response replays the same signed bytes for
+  the whole TTL — and `AirnodeVerifier` deduplicates on `keccak256(endpointId, timestamp, data)`, so only the _first_
+  on-chain submission of a cached ciphertext succeeds; the rest revert "already fulfilled". A cache on an encrypt
+  endpoint therefore both serves stale data and caps on-chain ingestion to one submission per window. Leave `cache`
+  unset unless that's actually what you want.
+- **Set `encoding.times` explicitly.** If you omit `encoding.times`, the requester controls the scale multiplier via the
+  `_times` parameter (and the endpoint ID records `times=*`). For an encrypt endpoint you almost always want a fixed
+  scale — set `times: '1'` if you mean "no scaling".
 - **Throughput.** The Zama coprocessor currently handles a limited number of input verifications per second.
   High-frequency price feeds may hit this limit.
 - **Numeric, encoded responses only.** `encrypt` requires an `encoding` block producing a single `int256`/`uint256`

book/docs/concepts/proofs.md

@@ -113,14 +113,29 @@ When a proof is successfully generated, the response includes a `proof` field:
 The `proof.signatures.attestorAddress` identifies the attestor that generated the proof. The `claimSignature` is a
 signature over the claim data that can be verified independently.
 
+## What the proof attests (and what it doesn't)
+
+The proof covers the _request_ exactly: Airnode hands the gateway the same URL, method, headers, and body it actually
+sent, and rejects any returned proof whose `claim.parameters` disagree (treated as a non-fatal failure — see below).
+
+It does **not** guarantee that the proof's _response_ equals the data Airnode signed. The attestor performs its own TLS
+session to the upstream, separate from Airnode's. For volatile data (a price that ticks between the two fetches) the
+attested response can legitimately differ from the signed payload. A future on-chain verifier that wants to bind the
+proof to the signed data must account for this — e.g. by comparing only the `responseMatches`-extracted fields and
+allowing a tolerance, not by requiring byte-for-byte equality.
+
 ## Non-fatal behavior
 
-Proof generation is **non-fatal**. If the proof gateway is unavailable, times out, or returns an error:
+Proof generation is **non-fatal**. If the proof gateway is unavailable, times out, returns an error, or returns a proof
+that doesn't match the request Airnode made:
 
 - The response is still returned without the `proof` field.
 - A `WARN` log is emitted with the failure reason.
 - The EIP-191 signature is unaffected.
 
+The gateway timeout is configurable via [`settings.proof.timeout`](/docs/config/settings#proof) (default 30s). Because
+the proof is fetched after signing on the sync path, that timeout is added to the response latency on a slow gateway.
+
 This ensures that proof infrastructure issues do not block data delivery. Consumers that require proofs should check for
 the presence of the `proof` field and reject responses without it.
 

book/docs/config/apis.md

@@ -82,27 +82,32 @@ key rotation.
 
 ### x402 (HTTP-native payment)
 
-Pay-per-request using on-chain transfers. When a client requests without payment, the server returns a 402:
+Pay-per-request using on-chain transfers. When a client requests without payment, the server returns a 402.
+
+This is an x402-_flavoured_ scheme — it borrows the HTTP 402 pay-per-request idea but is **not** the x402 wire protocol:
+clients pay on-chain first and then prove the confirmed transaction, rather than handing over a signed EIP-3009
+authorization in an `X-PAYMENT` header.
 
 ```yaml
 auth:
   type: x402
   network: 8453 # chain ID for payment
   rpc: https://mainnet.base.org
   token: '0xA0b8...' # ERC-20 address (or 0x000...0 for ETH)
-  amount: '1000000' # in token's smallest unit (e.g. 1 USDC = 1000000)
+  amount: '1000000' # token base units, integer string (e.g. 1 USDC = 1000000)
   recipient: '0x...' # operator's address
   expiry: 300000 # payment window in ms (default 5 min)
 ```
 
-Flow: client POSTs → gets 402 with payment details (including `airnode`, `endpointId`, `paymentId`, `expiresAt`) → sends
-on-chain transfer → signs `keccak256(encodePacked(airnode, endpointId, paymentId, uint64(expiresAt)))` with the payer's
-EOA → retries with `X-Payment-Proof: <json>` where the JSON is
-`{ "txHash": "0x…", "paymentId": "0x…", "expiresAt": <unix-seconds>, "signature": "0x…" }`.
+Flow: client POSTs → gets `402` with payment details (`airnode`, `endpointId`, `amount`, `token`, `network`,
+`recipient`, `expiresAt`) → sends the on-chain transfer → signs
+`keccak256(encodePacked(airnode, endpointId, uint64(expiresAt)))` with the payer's EOA → retries with
+`X-Payment-Proof: <json>` where the JSON is `{ "txHash": "0x…", "expiresAt": <unix-seconds>, "signature": "0x…" }`.
 
 The server checks that the signature recovers to the transaction's sender, that the proof has not expired, and that the
-transaction matches the configured amount and recipient. This binds the payment to a specific request so mempool
-observers cannot steal it and cross-endpoint upgrade attacks are blocked. Each tx hash can only be used once.
+transaction matches the configured amount and recipient. The signature binds the payment to a specific airnode and
+endpoint (so it can't be replayed elsewhere) and to a short `expiresAt` window. Each `txHash` is the per-payment
+uniqueness key — it can be redeemed exactly once.
 
 `expiresAt` must be a future unix-seconds timestamp no further ahead than 10 minutes; longer-lived proofs are rejected.
 
@@ -191,7 +196,8 @@ Controls how the server delivers the response:
   polls `GET /requests/{requestId}` until the status is `complete` or `failed`.
 - **`stream`** — return the signed response as a Server-Sent Event (SSE). The response has
   `Content-Type: text/event-stream`. The full pipeline runs (including plugins), and the signed result is delivered as a
-  single `data:` event with `done: true`.
+  single `data:` event with `done: true`. A pipeline error is returned as the plain HTTP error response, not an SSE
+  frame.
 
 ```yaml
 endpoints:
@@ -206,6 +212,10 @@ endpoints:
     mode: stream # return SSE events
 ```
 
+The response [cache](#cache) applies to `sync`-mode endpoints only. `async` returns a `202`+`pollUrl` and `stream`
+returns an SSE frame, so a cached plain-JSON body would break those response contracts — those modes neither read nor
+write the cache.
+
 ## Parameters
 
 Parameters define the inputs to an upstream API call. Each parameter specifies where to send its value and how it is
@@ -348,7 +358,7 @@ Produces the request body:
 
 ### Cookie parameters
 
-Sent as cookies on the upstream request:
+Sent as cookies on the upstream request, joined into a single `Cookie` header:
 
 ```yaml
 parameters:
@@ -358,6 +368,9 @@ parameters:
     secret: true
 ```
 
+Cookie values are concatenated verbatim, so a value containing `;`, CR, or LF (which would let it inject extra cookie
+pairs or split the header) is rejected — keep cookie values to ordinary cookie content.
+
 ## `responseMatches`
 
 Defines regex patterns that a TLS proof attestor checks against the API response. Required for

book/docs/config/server.md

@@ -20,15 +20,16 @@ server:
 
 ## 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       | `['*']`     | Allowed origins. Each entry is joined with `, ` in the response header.     |
-| `rateLimit`        | `object`   | No       | --          | Per-IP rate limiting. When omitted, no rate limiting is applied.            |
-| `rateLimit.window` | `number`   | Yes      | --          | Time window in milliseconds.                                                |
-| `rateLimit.max`    | `number`   | Yes      | --          | Maximum requests per IP within the window.                                  |
+| 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       | `['*']`     | Allowed origins. Each entry is joined with `, ` in the response header.                             |
+| `rateLimit`                   | `object`   | No       | --          | Per-IP rate limiting. When omitted, no rate limiting is applied.                                    |
+| `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. |
 
 ## Minimal
 
@@ -58,6 +59,11 @@ When a client exceeds the limit, the server returns `429 Too Many Requests`.
 
 The rate limiter tracks up to 10,000 unique IPs. When this limit is reached, the oldest entries are evicted.
 
+By default the client IP is the socket peer. If Airnode runs behind a reverse proxy that is the proxy's address, so
+every client would share one bucket — set `rateLimit.trustForwardedFor: true` to use the first `X-Forwarded-For` entry
+instead. Only enable this when a trusted proxy controls that header; a client-supplied `X-Forwarded-For` is otherwise
+trivially spoofable.
+
 ## CORS
 
 CORS headers are included on every response. The `OPTIONS` preflight handler returns:

book/docs/config/settings.md

@@ -58,10 +58,11 @@ settings:
     gatewayUrl: http://localhost:5177/v1/prove
 ```
 
-| Field        | Type     | Required | Description                                                  |
-| ------------ | -------- | -------- | ------------------------------------------------------------ |
-| `type`       | `string` | Yes      | Must be `'reclaim'`.                                         |
-| `gatewayUrl` | `string` | Yes      | Full URL of the proof gateway endpoint. Must be a valid URL. |
+| Field        | Type     | Required             | Description                                                                                                                                                                     |
+| ------------ | -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`       | `string` | Yes                  | Must be `'reclaim'`.                                                                                                                                                            |
+| `gatewayUrl` | `string` | Yes                  | Full URL of the proof gateway endpoint. Must be a valid URL.                                                                                                                    |
+| `timeout`    | `number` | No (default `30000`) | Gateway request timeout in milliseconds. The proof is fetched after signing on the sync path, so this latency is added to the response; a timeout just omits the `proof` field. |
 
 When enabled, Airnode requests a TLS proof from the gateway after each API call. The proof is attached to the response
 in a `proof` field alongside the signature. See [TLS Proofs](/docs/concepts/proofs) for details on how proofs work.

book/docs/consumers/http-client.md

@@ -149,13 +149,15 @@ The full pipeline runs (including plugins), and the signed result is delivered a
 
 ## x402 payment
 
+> This is an x402-_flavoured_ scheme — pay on-chain first, then prove the confirmed transaction. It is **not** the x402
+> wire protocol (no `X-PAYMENT`/EIP-3009 authorization).
+
 For endpoints with x402 auth, the first request returns 402 with payment details:
 
 ```json
 {
   "airnode": "0x...",
   "endpointId": "0x...",
-  "paymentId": "0x...",
   "amount": "1000000",
   "token": "0xA0b8...",
   "network": 8453,
@@ -164,18 +166,17 @@ For endpoints with x402 auth, the first request returns 402 with payment details
 }
 ```
 
-After sending the on-chain transfer, the payer signs an authorisation binding the payment to this specific request and
-airnode:
+After sending the on-chain transfer, the payer signs an authorisation binding the payment to this airnode and endpoint:
 
 ```
-message = keccak256(encodePacked(airnode, endpointId, paymentId, uint64(expiresAt)))
+message = keccak256(encodePacked(airnode, endpointId, uint64(expiresAt)))
 signature = EIP-191 personal-sign(message) with the EOA that sent the transaction
 ```
 
 Retry with a JSON-encoded `X-Payment-Proof` header:
 
 ```bash
-PROOF='{"txHash":"0x...","paymentId":"0x...","expiresAt":1700001000,"signature":"0x..."}'
+PROOF='{"txHash":"0x...","expiresAt":1700001000,"signature":"0x..."}'
 
 curl -X POST http://airnode.example.com/endpoints/0x... \
   -H "Content-Type: application/json" \
@@ -184,8 +185,9 @@ curl -X POST http://airnode.example.com/endpoints/0x... \
 ```
 
 The server verifies the signature recovers to the transaction sender and checks that `expiresAt` is in the future and no
-more than 10 minutes ahead. This binds the payment to the specific request so mempool observers cannot steal the call,
-and signatures cannot be reused across different airnodes, endpoints, or (after expiry) time.
+more than 10 minutes ahead. This binds the payment to the specific airnode and endpoint (signatures can't be reused
+across either, nor after expiry), and each `txHash` can be redeemed only once — that on-chain hash is the per-payment
+uniqueness key.
 
 ## Error responses
 

src/api/call.test.ts

@@ -357,6 +357,21 @@ describe('callApi', () => {
     expect((options.headers as Record<string, string>)['Cookie']).toBeUndefined();
   });
 
+  test('rejects a cookie parameter value that could inject extra cookies', async () => {
+    const api = makeApi();
+    const endpoint = makeEndpoint({
+      parameters: [{ name: 'session', in: 'cookie', required: true, secret: false }],
+    });
+
+    const semicolon = callApi(api, endpoint, { session: 'abc; evil=1' });
+    expect(semicolon).rejects.toThrow('Cookie parameter "session"');
+    await semicolon.catch(() => {});
+
+    const crlf = callApi(api, endpoint, { session: 'abc\r\nX-Injected: 1' });
+    expect(crlf).rejects.toThrow('CR, or LF');
+    await crlf.catch(() => {});
+  });
+
   test('returns null data for empty response body (204 No Content)', async () => {
     fetchMock.mockResolvedValue({
       text: () => Promise.resolve(''),

src/api/call.ts

@@ -73,7 +73,16 @@ function buildApiRequest(api: Api, endpoint: Endpoint, requestParameters: Record
   };
 
   if (cookieParameters.length > 0) {
-    const cookieString = cookieParameters.map((p) => `${p.name}=${p.value as string}`).join('; ');
+    // Cookie values are concatenated raw into the Cookie header, so a `;`, CR,
+    // or LF in a (possibly requester-supplied) value would let it inject extra
+    // cookie pairs or split the header — reject those outright. (Path/query are
+    // percent-encoded and header values are validated by fetch; only cookies
+    // are joined verbatim.)
+    const invalidCookie = cookieParameters.find((p) => /[;\r\n]/.test(String(p.value)));
+    if (invalidCookie) {
+      throw new Error(`Cookie parameter "${invalidCookie.name}" value must not contain ';', CR, or LF`);
+    }
+    const cookieString = cookieParameters.map((p) => `${p.name}=${String(p.value)}`).join('; ');
     const existing = headers['Cookie'];
     headers['Cookie'] = existing ? `${existing}; ${cookieString}` : cookieString; // eslint-disable-line functional/immutable-data
   }