An agent arrives at a merchant's API claiming to be a trusted shopping assistant. The merchant has never met it before. How does the merchant know the request is genuinely from that agent — and that nobody altered the order on the way?
This page is a live, working answer. Every signature below is produced by a real Ed25519 private key held by this server, and verified by merchant code that trusts nothing except the public key it downloads for itself.
User-Agent: ShoppingAssistant/1.0
A claim, typed by the client. Anyone can send this exact string. It proves nothing, and IP allow-lists break the moment the agent changes hosting.
Signature-Input: sig1=("@method" "@authority" …)
Signature: sig1=:MEUCIQDf…:
Proof, computed with a private key the agent never shares. Forging it means breaking Ed25519. The merchant checks it with public information alone.
Web Bot Auth is not a new cryptosystem. It is a convention that stitches three existing standards together so that any bot and any server can interoperate without pre-arranging anything between them.
Signature-Agent to learn where the keys live.keyid.Everything below is live, read from this server's actual keypair. The private half sits on disk in the container and is never transmitted. The public half is what the whole internet is allowed to see.
Served at the well-known directory URL. kty, crv and x are the key itself; the rest is metadata.
loading…
keyid is derived — and why it can't be fakedThe key id is not a label the agent chooses. It is a SHA-256 hash of the key's own canonical JSON (RFC 7638 thumbprint). The merchant recomputes it from the key it downloaded. So an agent cannot publish one key and claim a different identity — the id is a fingerprint of the key material.
loading…
loading…
echo -n '{"crv":"Ed25519","kty":"OKP","x":"…"}' | openssl dgst -sha256 -binary | basenc --base64url | tr -d '='
The agent is placing a $37.00 coffee order. Follow the same request through both sides. Blue steps happen at the agent; purple steps happen at the merchant.
A signature only protects what it covers. The agent lists the parts of the request to
bind — here the method, host, path, a hash of the body, and the Signature-Agent
header. Anything left out can be altered in transit without breaking the signature.
("@method" "@authority" "@path" "content-digest" "signature-agent")
The Web Bot Auth draft's baseline is just ("@authority" "signature-agent")
— enough to prove who is calling. This demo covers more so the merchant can also
prove what was ordered. Try the Baseline coverage only scenario below to see why that matters.
To bind the order payload, the agent hashes it into a Content-Digest header
(RFC 9530) and then signs that header. Signing a hash of the body is equivalent
to signing the body, but keeps the signature base small.
Content-Digest: sha-256=:base64 of SHA-256(request body):
This is the exact byte string that gets signed — one line per covered component, and a
final @signature-params line carrying the metadata. This string is never
transmitted; both sides construct it independently.
loading…
created and expires are in there: without a
time bound, one captured request would be a permanent credential. With it, a stolen
request is useless after a few minutes.
nonce: within that window, the nonce lets the merchant
reject a second copy of the same request.
tag="web-bot-auth": it pins the signature's purpose, so a
signature made for something else cannot be repurposed as bot authentication.
Ed25519 signs those bytes directly. The result goes into three headers — this is the entire on-the-wire footprint of Web Bot Auth.
| Header | Carries |
|---|---|
Signature-Agent | Where to find the public keys. An https origin, quoted as a structured-field string. |
Signature-Input | What was covered, and the parameters — created, expires, keyid, alg, nonce, tag. |
Signature | The raw Ed25519 signature bytes, base64, wrapped in colons. |
The merchant reads Signature-Agent, appends the well-known path, and fetches
the JWKS over TLS. It then computes the thumbprint of each published key and looks for one
matching the keyid in Signature-Input.
Signature-Agent: "https://ai.abhinava.xyz"
↓
GET https://ai.abhinava.xyz/.well-known/http-message-signatures-directory
↓
for each key: SHA-256 thumbprint == keyid ?
Signature-Agent. Fetching keys over plain HTTP would let anyone on the path
substitute their own key — which is why the scheme must be https.
Using the component list from Signature-Input, the merchant reconstructs the
signature base from the request as it actually arrived — its own view of the
method, host, path and headers. Then one Ed25519 verification against the downloaded
public key decides the outcome.
Before trusting it, the merchant also checks the clock window, the nonce, the tag, and that enough of the request was covered to satisfy its own policy. All of that runs live in the next section.
Each scenario sends a real signed request to the merchant's verifier running on this server. Start with the valid one, then break a single thing at a time and watch exactly which check catches it.
Loading scenarios…
All of these are real and callable right now. The first one is the only endpoint Web Bot Auth actually requires you to publish.
| Endpoint | What it is |
|---|---|
/.well-known/http-message-signatures-directory |
The required one. The agent's public keys as a JWKS, served as
application/http-message-signatures-directory+json. The response signs itself
with tag="http-message-signatures-directory", so a merchant can confirm the
key list came from the key holder. |
/api/agent/identity | This agent's JWK, its keyid, and the exact canonical JSON the thumbprint was computed over. |
/api/agent/sample-request | A freshly signed request you can replay with curl. Valid for 5 minutes. |
POST /api/merchant/checkout | The protected resource. Accepts only requests that pass full Web Bot Auth verification; returns the step-by-step trace either way. |
/api/merchant/policy | What this merchant requires — which components must be signed, clock skew, lifetime limits. |
/api/demo/run?scenario=… | Runs any scenario server-side and returns the whole trace as JSON. |
Generated fresh when this page loaded — the signature expires five minutes later, after which you'll get expired. Each one works exactly once; a second run gives replayed_nonce.
loading…
Node 18+, no dependencies. Publish the printed JWK at your own domain's well-known path and the merchant will verify against your key.
import { generateKeyPairSync, createHash, sign, randomBytes } from 'node:crypto';
const { publicKey, privateKey } = generateKeyPairSync('ed25519');
const { kty, crv, x } = publicKey.export({ format: 'jwk' });
// keyid = RFC 7638 thumbprint: SHA-256 over canonical {crv,kty,x}
const kid = createHash('sha256')
.update(JSON.stringify({ crv, kty, x }))
.digest('base64url');
const ORIGIN = 'https://your-agent.example'; // where YOUR jwks is published
const body = JSON.stringify({ hello: 'merchant' });
const digest = `sha-256=:${createHash('sha256').update(body).digest('base64')}:`;
const created = Math.floor(Date.now() / 1000);
const params = `;created=${created};expires=${created + 300};keyid="${kid}"`
+ `;alg="ed25519";nonce="${randomBytes(64).toString('base64')}"`
+ `;tag="web-bot-auth"`;
const covered = '("@method" "@authority" "@path" "content-digest" "signature-agent")';
// The signature base: one line per component, params last, joined with \n, no trailing newline.
const base = [
'"@method": POST',
'"@authority": ai.abhinava.xyz',
'"@path": /api/merchant/checkout',
`"content-digest": ${digest}`,
`"signature-agent": "${ORIGIN}"`,
`"@signature-params": ${covered}${params}`
].join('\n');
const sig = sign(null, Buffer.from(base), privateKey).toString('base64');
console.log(JSON.stringify({ keys: [{ kty, crv, x, kid, use: 'sig' }] }, null, 2));
console.log({
'Signature-Agent': `"${ORIGIN}"`,
'Content-Digest': digest,
'Signature-Input': `sig1=${covered}${params}`,
'Signature': `sig1=:${sig}:`
});
Signature-Input (build it once, reuse it);
the signature base is joined with \n and has no trailing newline;
and @authority is the host the request is addressed to — if you sign
localhost:8080 but a proxy presents ai.abhinava.xyz, verification fails.
| Parameter | Required | Purpose |
|---|---|---|
created | Yes | Unix seconds when signed. A merchant rejects values implausibly far in the future (clock skew allowance, typically ±5 min). |
expires | Yes | Unix seconds after which the signature must be refused. Keep it short; the draft recommends no more than 24 hours, minutes are better. |
keyid | Yes | Base64url RFC 7638 thumbprint of the signing key. The merchant recomputes this from the published JWK rather than trusting it. |
alg | Recommended | "ed25519". Fast, small signatures, no parameter-choice footguns. |
nonce | Recommended | Random, never reused. 64 bytes recommended. Enables replay rejection within the validity window. |
tag | Yes | "web-bot-auth". Binds the signature to this purpose so it can't be lifted from another context. |
| Component | Binds |
|---|---|
@authority | The host being addressed. Stops a signature captured by one site being replayed against another. Required by the draft. |
signature-agent | The key directory URL. Must be signed if sent — otherwise an attacker could redirect the merchant to a directory of their own. |
@method | Stops a signed GET being replayed as a DELETE. |
@path | Stops a signature for one route being reused on another. |
content-digest | The request body. Without it the signature says nothing about the payload — the order can be rewritten in flight. |
Content-Digest)web-bot-auth profile