Skip to content
Frankensurf

When a site blocks you

Signed requests

Arrive as a verified agent with Web Bot Auth, instead of an anonymous bot.

Web Bot Auth signs each request with your key using HTTP Message Signatures (RFC 9421). Cloudflare, AWS, Akamai and Vercel can verify the signature and let a known agent through.

  • Every plain HTTP read is signed once you have a key, including each redirect.
  • The private key never leaves your machine.
  • Without a key, nothing is signed.

Set it up

Section titled “Set it up”

  1. Create a key and print its public directory.

    Terminal window
    frankensurf bot-auth-init
    frankensurf bot-auth-directory > directory.json

  2. Serve directory.json at /.well-known/http-message-signatures-directory on an HTTPS origin you control.

  3. Point Frankensurf at that origin.

    Terminal window
    export FRANKENSURF_SIGNATURE_AGENT=https://agent.example.com

  4. Register the origin with the networks that verify signed agents, such as Cloudflare’s signed agents.

What gets sent

Section titled “What gets sent”

Each request carries Signature-Agent, Signature-Input and Signature headers covering @authority and signature-agent, with a five-minute lifetime and a fresh nonce.

Options

Section titled “Options”
Option Default Description
sign_requests true Set false to skip signing for one call.
FRANKENSURF_BOT_AUTH_KEY_FILE ~/.config/frankensurf/web-bot-auth.jwk Where the private key lives.