# Request Signing

> How Everruns signs outbound HTTP requests with Ed25519 signatures per RFC 9421, enabling target servers to verify bot identity

Source: <https://everruns.com/docs/features/request-signing/>

When an AI agent fetches web content, the receiving server has no way to distinguish it from an anonymous scraper. **Request signing** solves this by attaching a cryptographic signature to every outbound HTTP request, letting target servers verify who is making the request and choose to grant or deny access based on that identity.

Everruns implements [Web Bot Auth](https://datatracker.ietf.org/doc/draft-ietf-webbotauth-httpsig-protocol/), the IETF working-group profile of [RFC 9421 HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421), using Ed25519 signatures.

## Background

### The Problem

Traditional bot identification relies on `User-Agent` strings, which are trivially spoofed. IP-based allow lists are brittle and don’t scale. There is no standard way for a web bot to prove its identity to a server.

### HTTP Message Signatures (RFC 9421)

RFC 9421 defines a general mechanism for signing HTTP messages. A sender selects components of the request (method, authority, specific headers) and signs them with a private key. The signature and a description of what was signed are transmitted as structured headers:

```plaintext
Signature: sig=:base64-encoded-signature:
Signature-Input: sig=("@authority");created=1735689600;expires=1735689900;
                  keyid="JWK-thumbprint";alg="ed25519";nonce="random";
                  tag="web-bot-auth"
```

The receiving server reconstructs the same signature base from the request, fetches the sender’s public key, and verifies the signature. Replay protection requires the receiver to enforce the `created`/`expires` window and reject reused nonces within that window. A signature and random `nonce` alone do not prevent replay.

### Web Bot Auth

The [Web Bot Auth draft](https://datatracker.ietf.org/doc/draft-ietf-webbotauth-httpsig-protocol/) builds on RFC 9421 specifically for bot identification:

* **Algorithm**: Ed25519 (fast, small keys, no parameter choices)
* **Covered components**: `@authority` (the target domain) at minimum
* **Key identity**: [JWK Thumbprint](https://www.rfc-editor.org/rfc/rfc7638) (SHA-256 hash of the canonical public key representation)
* **Signature tag**: `"web-bot-auth"`, distinguishes bot-auth signatures from other uses of RFC 9421
* **Discovery**: the `Signature-Agent` header names the https URL where the bot’s public keys can be found

### Key Discovery

The same draft defines how target servers find a bot’s public keys:

```plaintext
GET <signature-agent-origin>/.well-known/http-message-signatures-directory
```

This returns a [JSON Web Key Set (JWKS)](https://www.rfc-editor.org/rfc/rfc7517#section-5) containing the bot’s Ed25519 public keys. The target server uses the `kid` field to match the key against the `keyid` in the incoming signature.

![Request Signing Flow](https://everruns.com/docs/_astro/request-signing-flow.C8LhE-yq_WOQ84.svg)

## How It Works in Everruns

Request signing is a server-wide feature owned by the egress layer, the part of Everruns every outbound tenant request passes through. When it is configured, requests made by the `web_fetch` tool and by `curl` in the Bashkit shell are signed. Each redirect hop is signed for its own host. Other outbound traffic, such as LLM providers, MCP servers and sandbox networking, is not signed.

Everruns follows the IETF working-group draft [draft-ietf-webbotauth-httpsig-protocol](https://datatracker.ietf.org/doc/draft-ietf-webbotauth-httpsig-protocol/) and stays compatible with Cloudflare’s verifier.

### Signing (outbound)

1. A tool builds a request and asks the egress layer for platform signing.

2. The egress layer applies the deployment’s network policy. Refused requests are never signed.

3. For an `https://` request, it adds three headers:

   * `Signature-Agent`: the deployment’s origin as a quoted string, for example `"https://app.example.com"`.
   * `Signature-Input`: covers `@method`, `@authority`, `@path` and `signature-agent`, with `created`, `expires` (5 minutes by default), `keyid`, `alg="ed25519"`, a random `nonce` and `tag="web-bot-auth"`.
   * `Signature`: the Ed25519 signature, encoded as standard base64.

4. Plain `http://` requests are sent unsigned, because a signature on an unencrypted connection can be replayed by anyone on the path. A request that already carries its own `Signature` header keeps it.

### Key directory (inbound)

Everruns serves its public keys at `/.well-known/http-message-signatures-directory`. This endpoint:

* is **public** and needs no authentication
* returns a JWKS with media type `application/http-message-signatures-directory+json`
* signs the response once per key, covering `@authority;req` and `Content-Digest`, with `tag="http-message-signatures-directory"`, so the key set cannot be re-served under another host
* is cacheable for a day and allows cross-origin reads

Example response:

```http
HTTP/1.1 200 OK
Content-Type: application/http-message-signatures-directory+json
Cache-Control: public, max-age=86400
Content-Digest: sha-256=:...:
Signature-Input: binding0=("@authority";req "content-digest");created=...;expires=...;keyid="...";tag="http-message-signatures-directory"
Signature: binding0=:...:


{"keys":[{"kty":"OKP","crv":"Ed25519","kid":"<JWK thumbprint>","x":"<public key>","use":"sig"}]}
```

### What target servers see

| Header            | Purpose                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| `Signature`       | The Ed25519 signature over the covered components                      |
| `Signature-Input` | What was signed: components, timestamps, key ID, algorithm, nonce, tag |
| `Signature-Agent` | Quoted https origin whose well-known directory holds the key           |

Target servers that support Web Bot Auth can:

1. Extract the `keyid` from `Signature-Input`
2. Fetch the directory from the `Signature-Agent` origin’s well-known path
3. Verify the signature
4. Apply access policies based on the verified identity

Servers that don’t support it simply ignore the extra headers.

## Verifying Signatures (Server Side)

If you operate a server that receives requests from Everruns agents, here’s how to verify them.

### Verification steps

1. **Check the tag**: parse `Signature-Input` and confirm `tag="web-bot-auth"`. Ignore signatures with other tags.
2. **Check timestamps**: reject if `created` is in the future or `expires` is in the past. A 5-minute clock skew tolerance is reasonable.
3. **Fetch the public key**: take the `Signature-Agent` origin (strip the surrounding quotes) and fetch `<origin>/.well-known/http-message-signatures-directory`. Find the key matching the `keyid` from `Signature-Input`. Cache the JWKS (keys rotate infrequently).
4. **Reconstruct the signature base**: build the canonical representation per [RFC 9421 Section 2.5](https://www.rfc-editor.org/rfc/rfc9421#section-2.5) using the covered components listed in `Signature-Input`.
5. **Verify**: use Ed25519 to verify the signature against the reconstructed base and the fetched public key.

### Python example

```python
import base64
import hashlib
import time
import httpx
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey


def verify_bot_auth(request) -> bool:
    """Verify a web-bot-auth signature on an incoming request."""


    # 1. Parse Signature-Input header
    sig_input = request.headers.get("signature-input", "")
    if 'tag="web-bot-auth"' not in sig_input:
        return False  # not a bot-auth signature


    # Extract parameters from sig_input
    # sig=("@authority" "signature-agent");created=...;expires=...;keyid="...";...
    params = parse_signature_params(sig_input)


    # 2. Check timestamps
    now = int(time.time())
    if params["created"] > now + 300 or params["expires"] < now:
        return False  # expired or future-dated


    # 3. Fetch public key from the Signature-Agent origin ("https://...")
    agent_origin = request.headers.get("signature-agent", "").strip('"')
    if not agent_origin.startswith("https://"):
        return False
    jwks_url = f"{agent_origin}/.well-known/http-message-signatures-directory"
    jwks = httpx.get(jwks_url).json()
    key_data = next(k for k in jwks["keys"] if k.get("kid") == params["keyid"])
    public_key_bytes = base64.urlsafe_b64decode(key_data["x"] + "==")
    public_key = Ed25519PublicKey.from_public_bytes(public_key_bytes)


    # 4. Reconstruct signature base (RFC 9421 Section 2.5)
    #    Covered components are listed in parentheses in Signature-Input
    sig_base = build_signature_base(request, params)


    # 5. Verify
    signature = base64.b64decode(
        request.headers["signature"].split(":")[1]  # sig=:base64:
    )
    try:
        public_key.verify(signature, sig_base.encode())
        return True
    except Exception:
        return False
```

### Node.js example

```javascript
import { createPublicKey, verify } from "node:crypto";


async function verifyBotAuth(request) {
  const sigInput = request.headers["signature-input"] || "";
  if (!sigInput.includes('tag="web-bot-auth"')) return false;


  const params = parseSignatureParams(sigInput);


  // Check timestamps (5-minute tolerance)
  const now = Math.floor(Date.now() / 1000);
  if (params.created > now + 300 || params.expires < now) return false;


  // Fetch public key
  const origin = (request.headers["signature-agent"] || "").replace(/^"|"$/g, "");
  if (!origin.startsWith("https://")) return false;
  const res = await fetch(
    `${origin}/.well-known/http-message-signatures-directory`
  );
  const jwks = await res.json();
  const jwk = jwks.keys.find((k) => k.kid === params.keyid);


  const key = createPublicKey({ key: jwk, format: "jwk" });


  // Reconstruct signature base and verify
  const sigBase = buildSignatureBase(request, params);
  const signature = Buffer.from(
    request.headers["signature"].split(":")[1],
    "base64"
  );


  return verify(null, Buffer.from(sigBase), key, signature);
}
```

> **Note:** The `parseSignatureParams` and `buildSignatureBase` helpers follow the structured fields parsing rules from [RFC 8941](https://www.rfc-editor.org/rfc/rfc8941) and the signature base construction from [RFC 9421 Section 2.5](https://www.rfc-editor.org/rfc/rfc9421#section-2.5). Libraries like [httpbis-message-signatures](https://pypi.org/project/httpbis-message-signatures/) (Python) and [@httpbis/message-signatures](https://www.npmjs.com/package/@httpbis/message-signatures) (Node.js) handle both.

## Configuration

Request signing is configured with environment variables. Set the same values on the server and on every worker: workers sign, and the server publishes the directory.

### Environment variables

| Variable                       | Required | Default          | Description                                                                                                   |
| ------------------------------ | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `BOT_AUTH_SIGNING_KEY_SEED`    | yes      | –                | Base64url-encoded 32-byte Ed25519 seed. Unset disables signing and serves an empty directory.                 |
| `BOT_AUTH_SIGNATURE_AGENT_URL` | no       | `PUBLIC_APP_URL` | https origin that serves the key directory, sent as `Signature-Agent`. Signing stays off when neither is set. |
| `BOT_AUTH_PUBLISHED_KEY_SEEDS` | no       | –                | Comma-separated seeds listed in the directory but not used to sign, for key rotation                          |
| `BOT_AUTH_VALIDITY_SECS`       | no       | `300`            | Request signature lifetime in seconds                                                                         |

### Generate a signing key

```bash
python3 -c "import os, base64; print(base64.urlsafe_b64encode(os.urandom(32)).rstrip(b'=').decode())"
```

Keep the seed in your secret store. Anyone holding it can sign as your deployment.

### Enable signing

```bash
export BOT_AUTH_SIGNING_KEY_SEED="your-base64url-seed-here"
export BOT_AUTH_SIGNATURE_AGENT_URL="https://agents.yourcompany.com"
```

The origin must route `/.well-known/http-message-signatures-directory` to the Everruns server, outside any bot challenge, so verifiers can always fetch it.

### Verify it’s working

```bash
curl -si https://agents.yourcompany.com/.well-known/http-message-signatures-directory
```

The response should list one key and carry `Signature` and `Signature-Input` headers.

### Register with Cloudflare

Sites behind Cloudflare treat signed requests as a verified bot only after registration. In the Cloudflare dashboard, open the Bot Submission Form, choose **Request Signature** as the verification method, and enter your directory URL. See [Cloudflare’s Web Bot Auth guide](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/).

### Rotate the key

1. Generate a new seed and add it to `BOT_AUTH_PUBLISHED_KEY_SEEDS`. Deploy, then wait at least a day so verifiers refresh their cached directory.
2. Swap the seeds: the new seed becomes `BOT_AUTH_SIGNING_KEY_SEED`, the old one moves to `BOT_AUTH_PUBLISHED_KEY_SEEDS`. Deploy.
3. After another day, remove the old seed.

If a seed leaks, skip the waiting: replace it and remove the old one right away. Verifiers stop accepting the old key once their cached directory expires.

## Standards

| Standard                                                                                                           | Role                                                                                                                                                      |
| ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [RFC 9421, HTTP Message Signatures](https://www.rfc-editor.org/rfc/rfc9421)                                        | Core signing mechanism, how to sign and verify HTTP requests                                                                                              |
| [RFC 8941, Structured Field Values](https://www.rfc-editor.org/rfc/rfc8941)                                        | Encoding format for `Signature` and `Signature-Input` headers                                                                                             |
| [RFC 7638, JWK Thumbprint](https://www.rfc-editor.org/rfc/rfc7638)                                                 | How the `keyid` is computed from the public key                                                                                                           |
| [RFC 7517, JSON Web Key (JWK)](https://www.rfc-editor.org/rfc/rfc7517)                                             | Format of the keys in the JWKS response                                                                                                                   |
| [RFC 8037, Ed25519 in JOSE](https://www.rfc-editor.org/rfc/rfc8037)                                                | Ed25519 key representation in JWK format                                                                                                                  |
| [draft-ietf-webbotauth-httpsig-protocol](https://datatracker.ietf.org/doc/draft-ietf-webbotauth-httpsig-protocol/) | Web Bot Auth: the bot profile of RFC 9421, `Signature-Agent`, and the key directory. Replaces the earlier draft-meunier architecture and directory drafts |

## See Also

* [Cloudflare: Web Bot Auth for bot operators](https://developers.cloudflare.com/bots/reference/bot-verification/web-bot-auth/)