@tollstile/web-bot-auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paradigm AI Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @tollstile/web-bot-auth
+
+`verifiedAgent()` is a Tollstile requirement that admits only requests signed by an agent you trust, using [Web Bot Auth](https://datatracker.ietf.org/doc/draft-ietf-webbotauth-httpsig-protocol/): [RFC 9421](https://www.rfc-editor.org/rfc/rfc9421) HTTP message signatures whose keys are published at the agent's `/.well-known/http-message-signatures-directory`.
+
+It answers *who* is calling, not whether they paid. Put it in `require` next to any rail or access policy; it runs after the payer is known and before anything is reserved, so a denied request never touches the ledger.
+
+## Install
+
+```bash
+npm install tollstile @tollstile/web-bot-auth
+```
+
+## Example
+
+```ts
+import { createTollstile, memoryLedger, testRail } from 'tollstile';
+import { paid } from '@tollstile/fetch';
+import { verifiedAgent } from '@tollstile/web-bot-auth';
+
+const toll = createTollstile({ rails: [testRail()], ledger: memoryLedger() });
+
+export default {
+  fetch: paid(
+    toll.price('$0.01', { require: [verifiedAgent({ trust: ['https://agent.example'] })] }),
+    () => Response.json({ forecast: 'clear' }),
+  ),
+};
+```
+
+A request is admitted when it carries a valid payment **and** a signature like:
+
+```http
+Signature-Agent: sig1="https://agent.example"
+Signature-Input: sig1=("@authority" "@method" "@path" "signature-agent";key="sig1");created=1767225600;expires=1767225660;keyid="<JWK thumbprint>";alg="ed25519";nonce="…";tag="web-bot-auth"
+Signature: sig1=:…:
+```
+
+Otherwise the request is denied before anything is reserved. A refused signature is `403`:
+
+```json
+{
+  "error": { "code": "requirement_failed", "retryable": false, "action": "stop", "message": "…", "detail": "signature_invalid" },
+  "requirement": "verified-agent",
+  "resource": "GET /data"
+}
+```
+
+When the agent's key directory cannot be reached right now, the response is `503` with a `Retry-After` header and `"code": "requirement_unavailable"`, `"action": "retry_later"`, `"detail": "directory_unavailable"`.
+
+Branch on `error.code` and `error.action`. `error.detail` is one of the stable snake_case identifiers below, suitable for logs and metrics.
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `trust` | required | Signature-Agent origins you accept (`["https://agent.example"]`), or `(origin) => boolean`. Only these origins' directories are ever fetched. A predicate is your SSRF boundary: the library cannot block private address ranges with Web-standard `fetch`. |
+| `maxAgeMs` | `300000` | Oldest `created` accepted. |
+| `clockSkewMs` | `5000` | Tolerance applied to `created`, `expires`, and the maximum age. |
+| `requireNonce` | `false` | Reject signatures without a `nonce`. Nonces that are present are always single-use. |
+| `cacheTtlMs` | `3600000` | Longest a directory is reused. A shorter `Cache-Control: max-age` wins, but never below one minute. |
+| `timeoutMs` | `3000` | Upper bound for one directory fetch, including the body. The fetch is also aborted when Tollstile's `providerTimeoutMs` elapses (`input.signal`). |
+| `fetch` | global `fetch` | Inject for tests or egress proxies. |
+
+## What is checked
+
+In this order, for each signature whose `tag` is `web-bot-auth` (the first that verifies wins):
+
+1. `Signature-Input` and `Signature` parse as RFC 8941 Dictionaries; only the parameters RFC 9421 defines are allowed.
+2. `created`, `expires`, and `keyid` are present; `@authority` or `@target-uri` is covered without parameters.
+3. `created` is not in the future, `expires` has not passed, and `created` is within `maxAgeMs` (each ± `clockSkewMs`).
+4. The covered Signature-Agent member: exactly one `"signature-agent";key="<member>"` for the Dictionary form, or `"signature-agent"` for the legacy sf-string form. The member must be an HTTPS origin; `type=jwks_uri` and `type=cimd` members are not resolved.
+5. The signature base is rebuilt from `context.request` only — method, URL, and headers as the server received them. A missing, duplicated, or unsupported component fails.
+6. The origin is trusted, its directory resolves, and it contains a key whose RFC 7638 thumbprint equals `keyid` (a `kid` that is not the thumbprint disqualifies the entry). RFC 9421's published test keys are refused.
+7. The algorithm follows from the key (`ed25519`, `ecdsa-p256-sha256`, `ecdsa-p384-sha384`, `rsa-pss-sha512`); a signature `alg` must agree. RSA keys must name `PS512`/`rsa-pss-sha512` in the key or the signature.
+8. A `nonce`, if present, is claimed once per directory and key until the signature could no longer be accepted.
+
+| `error.detail` | Meaning |
+|---|---|
+| `http_request_required` | MCP call, or no HTTP request in the context. MCP tool calls are never attributed to a signed HTTP request. |
+| `signature_missing` / `signature_malformed` / `tag_missing` | No usable Web Bot Auth signature. |
+| `signature_parameters_missing` / `target_not_covered` | Profile requirements not met. |
+| `signature_not_yet_valid` / `signature_expired` / `signature_too_old` | Freshness. |
+| `signature_agent_missing` / `signature_agent_not_covered` / `signature_agent_malformed` / `signature_agent_unsupported` | The Signature-Agent member cannot be attributed. |
+| `signature_base_invalid` | A covered component cannot be derived from the request. |
+| `agent_untrusted` | The origin is not in `trust`. Nothing was fetched. |
+| `directory_unavailable` (**503**) | The directory could not be reached — network or TLS error, timeout (`timeoutMs` or the provider timeout), or a 5xx — and nothing usable is cached. The request is unverified, not forbidden; retry later. |
+| `directory_invalid` | The directory answered, but not with a usable directory: a redirect, another non-200 status, over 64 KiB, more than 32 keys, or malformed JSON. The operator has to fix it. |
+| `key_not_found` / `algorithm_mismatch` / `signature_invalid` | Key selection or cryptographic verification failed. |
+| `nonce_missing` / `nonce_replayed` | Replay protection. |
+
+## Directory discovery
+
+- `GET https://<origin>/.well-known/http-message-signatures-directory` with `redirect: "manual"`; only `200` is accepted. Unreachable directories and 5xx are `directory_unavailable` (503); redirects, other statuses, bodies over 64 KiB, more than 32 keys, or malformed JSON are `directory_invalid` (403). Unsupported or malformed key entries are skipped.
+- Unavailability is returned as `{ ok: false, status: 503 }` rather than thrown as `PROVIDER_UNAVAILABLE`, so `error.detail` stays `directory_unavailable`; either way nothing is reserved.
+- Concurrent requests for the same origin share one fetch, bounded by the signal of the request that started it. At most 1,024 directories are cached.
+- A directory that resolves replaces the cached one, so a removed key stops verifying. A failed fetch of either kind is not evidence: the cached directory keeps verifying for up to 24 hours past its expiry, and the origin is not retried for 30 seconds.
+- The cache and in-flight fetches are per `verifiedAgent()` instance and per process.
+
+## Deployment notes
+
+- **Reconstruct the public URL.** `@authority` and `@target-uri` come from `request.url`. Behind a proxy, the adapter must build the URL the agent signed (e.g. Express `trust proxy`), or every signature fails.
+- **Cover more than `@authority`.** A signature over `@authority` alone can be replayed against any path until it expires. Ask agents to cover `@method` and `@path`, or require nonces.
+- **Nonce claims and retries.** A nonce is claimed before the charge is created, so a request whose handler fails cannot be retried with the same signature; agents sign each attempt.
+
+## Verification status
+
+Tested with Vitest (Node 22 WebCrypto) against:
+
+- RFC 9421 Appendix B.2.6 (ed25519), B.2.2 and B.2.3 (rsa-pss-sha512, including `@query-param` and `@query`), and the §2.2.8 query encoding examples — signature bases rebuilt byte for byte and signatures verified.
+- draft-ietf-webbotauth-httpsig-protocol-00 Appendix E.1.1, E.1.2, E.2.1, and E.2.2 (Dictionary and legacy Signature-Agent, ed25519 and rsa-pss-sha512).
+- Full requirement flows through `createTollstile` with `testRail()`, fake directories via injected `fetch`, and freshly generated ed25519, P-256, and RSA-PSS keys: untrusted origins never fetched, redirects and non-200 refused, size and key-count caps, 503 for unreachable, 5xx, `timeoutMs`, and provider-timeout (`input.signal`) failures, stale-on-failure caching and its 24-hour limit, `max-age` handling, fetch coalescing, nonce replay, and MCP fail-closed.
+
+Not verified against a live agent. To verify: sign a request with Cloudflare's reference signer ([`web-bot-auth`](https://github.com/cloudflare/web-bot-auth), `sign()` with `signatureAgentKey`), host its JWKS at `https://<your-agent>/.well-known/http-message-signatures-directory`, trust that origin, and call your endpoint — expect `200`; change one covered header and expect `403 signature_invalid`.
+
+## Not implemented
+
+- **Visa Trusted Agent Protocol.** TAP reuses RFC 9421 with tags `agent-browser-auth`/`agent-payer-auth`, `@authority` + `@path`, mandatory nonces, and an 8-minute window, but keys come from Visa's JWKS selected by `kid` rather than a Signature-Agent thumbprint, algorithm names are JOSE names or the unregistered `rsa-pss-sha256`, and Visa's reference agent emits `Signature-Input` parameters that are not valid RFC 8941 (`keyId`, spaces). A strict verifier would reject its own samples, so a `tap` option is future work pending a conformant signer and published test vectors.
+- `jwks_uri` and `cimd` Signature-Agent types, directory response signatures (Appendix B), and requests without Signature-Agent (thumbprint-only identity).
+- Exposing the verified agent identity to the handler: requirements return only pass or fail.

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { Requirement } from 'tollstile';
+
+type VerifiedAgentOptions = {
+    /**
+     * Signature-Agent origins you accept, e.g. `["https://agent.example"]`, or a predicate over the
+     * origin. Directories of other origins are never fetched.
+     */
+    readonly trust: readonly string[] | ((origin: string) => boolean);
+    /** Oldest `created` accepted, in milliseconds. Defaults to 5 minutes. */
+    readonly maxAgeMs?: number;
+    /** Tolerated clock difference with signers, in milliseconds. Defaults to 5 seconds. */
+    readonly clockSkewMs?: number;
+    /** Reject signatures without a `nonce`. Nonces that are present are always single-use. Defaults to `false`. */
+    readonly requireNonce?: boolean;
+    /** Longest a fetched directory is reused, in milliseconds; a shorter `Cache-Control: max-age` wins. Defaults to 1 hour. */
+    readonly cacheTtlMs?: number;
+    /** Upper bound for one directory fetch, in milliseconds, within Tollstile's provider timeout. Defaults to 3 seconds. */
+    readonly timeoutMs?: number;
+    /** Defaults to the global `fetch`. */
+    readonly fetch?: typeof fetch;
+};
+/**
+ * Admits only requests signed by a trusted agent under Web Bot Auth (RFC 9421 HTTP message
+ * signatures, draft-ietf-webbotauth-httpsig-protocol-00). Keys come from the agent's
+ * `/.well-known/http-message-signatures-directory`. Denies with 403 and a reason such as
+ * `signature_missing`, `signature_invalid`, `agent_untrusted`, or `key_not_found`, and with 503
+ * `directory_unavailable` when the agent's directory cannot be reached and nothing usable is cached.
+ *
+ * @example
+ * ```ts
+ * import { verifiedAgent } from "@tollstile/web-bot-auth";
+ *
+ * app.get("/data", tollstile(toll.price("$0.01", {
+ *   require: [verifiedAgent({ trust: ["https://agent.example"] })],
+ * })), handler);
+ * ```
+ */
+declare function verifiedAgent(options: VerifiedAgentOptions): Requirement;
+
+export { type VerifiedAgentOptions, verifiedAgent };

package/dist/index.js

@@ -0,0 +1,695 @@
+// src/verified-agent.ts
+import { TollstileError } from "tollstile";
+
+// src/base64.ts
+var BASE64 = /^[A-Za-z0-9+/]*={0,2}$/;
+var BASE64URL = /^[A-Za-z0-9_-]*$/;
+function decodeBase64(input) {
+  if (!BASE64.test(input)) return void 0;
+  const unpadded = input.replace(/=+$/, "");
+  if (unpadded.length % 4 === 1) return void 0;
+  return toBytes(atob(unpadded.padEnd(Math.ceil(unpadded.length / 4) * 4, "=")));
+}
+function encodeBase64(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function decodeBase64url(input) {
+  if (!BASE64URL.test(input) || input.length % 4 === 1) return void 0;
+  return decodeBase64(input.replace(/-/g, "+").replace(/_/g, "/"));
+}
+function encodeBase64url(bytes) {
+  return encodeBase64(bytes).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function toBytes(binary) {
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+
+// src/structured-fields.ts
+var KEY_START = /[a-z*]/;
+var KEY_CHAR = /[a-z0-9_\-.*]/;
+var TOKEN_START = /[A-Za-z*]/;
+var TOKEN_CHAR = /[!#$%&'*+\-.^_`|~0-9A-Za-z:/]/;
+var DIGIT = /[0-9]/;
+function parseDictionary(text) {
+  const cursor = { text, position: 0 };
+  skipSpaces(cursor);
+  const dictionary = /* @__PURE__ */ new Map();
+  while (cursor.position < text.length) {
+    const key = parseKey(cursor);
+    if (key === void 0) return void 0;
+    let member;
+    if (peek(cursor) === "=") {
+      cursor.position += 1;
+      member = parseMember(cursor);
+    } else {
+      const parameters = parseParameters(cursor);
+      member = parameters && { kind: "item", value: { type: "boolean", value: true }, parameters };
+    }
+    if (member === void 0) return void 0;
+    dictionary.set(key, member);
+    skipWhitespace(cursor);
+    if (cursor.position === text.length) break;
+    if (peek(cursor) !== ",") return void 0;
+    cursor.position += 1;
+    skipWhitespace(cursor);
+    if (cursor.position === text.length) return void 0;
+  }
+  return dictionary;
+}
+function parseItem(text) {
+  const cursor = { text, position: 0 };
+  skipSpaces(cursor);
+  const item = parseParameterizedItem(cursor);
+  skipSpaces(cursor);
+  return cursor.position === text.length ? item : void 0;
+}
+function serializeMember(member) {
+  if (member.kind === "item") return serializeBareItem(member.value) + serializeParameters(member.parameters);
+  return `(${member.items.map(serializeMember).join(" ")})${serializeParameters(member.parameters)}`;
+}
+function parseMember(cursor) {
+  if (peek(cursor) !== "(") return parseParameterizedItem(cursor);
+  cursor.position += 1;
+  const items = [];
+  for (; ; ) {
+    skipSpaces(cursor);
+    if (peek(cursor) === ")") {
+      cursor.position += 1;
+      const parameters = parseParameters(cursor);
+      return parameters && { kind: "inner-list", items, parameters };
+    }
+    const item = parseParameterizedItem(cursor);
+    if (item === void 0) return void 0;
+    items.push(item);
+    const next = peek(cursor);
+    if (next !== " " && next !== ")") return void 0;
+  }
+}
+function parseParameterizedItem(cursor) {
+  const value = parseBareItem(cursor);
+  const parameters = value && parseParameters(cursor);
+  return value && parameters && { kind: "item", value, parameters };
+}
+function parseParameters(cursor) {
+  const parameters = /* @__PURE__ */ new Map();
+  while (peek(cursor) === ";") {
+    cursor.position += 1;
+    skipSpaces(cursor);
+    const key = parseKey(cursor);
+    if (key === void 0) return void 0;
+    let value = { type: "boolean", value: true };
+    if (peek(cursor) === "=") {
+      cursor.position += 1;
+      value = parseBareItem(cursor);
+    }
+    if (value === void 0) return void 0;
+    parameters.set(key, value);
+  }
+  return parameters;
+}
+function parseKey(cursor) {
+  if (!KEY_START.test(peek(cursor))) return void 0;
+  const start = cursor.position;
+  while (KEY_CHAR.test(peek(cursor))) cursor.position += 1;
+  return cursor.text.slice(start, cursor.position);
+}
+function parseBareItem(cursor) {
+  const first = peek(cursor);
+  if (first === "-" || DIGIT.test(first)) return parseNumber(cursor);
+  if (first === '"') return parseString(cursor);
+  if (first === ":") return parseBytes(cursor);
+  if (first === "?") return parseBoolean(cursor);
+  if (TOKEN_START.test(first)) return parseToken(cursor);
+  return void 0;
+}
+function parseNumber(cursor) {
+  const match = /^(-?)(\d{1,15})(?:\.(\d{1,3}))?/.exec(cursor.text.slice(cursor.position));
+  if (match === null) return void 0;
+  const [whole, , integer = "", fraction] = match;
+  if (fraction !== void 0 && integer.length > 12) return void 0;
+  const next = cursor.text[cursor.position + whole.length];
+  if (next !== void 0 && (DIGIT.test(next) || fraction === void 0 && next === ".")) return void 0;
+  cursor.position += whole.length;
+  return fraction === void 0 ? { type: "integer", value: Number(whole) } : { type: "decimal", value: Number(whole) };
+}
+function parseString(cursor) {
+  cursor.position += 1;
+  let value = "";
+  while (cursor.position < cursor.text.length) {
+    const character = cursor.text.charAt(cursor.position);
+    cursor.position += 1;
+    if (character === '"') return { type: "string", value };
+    if (character === "\\") {
+      const escaped = cursor.text.charAt(cursor.position);
+      if (escaped !== '"' && escaped !== "\\") return void 0;
+      value += escaped;
+      cursor.position += 1;
+      continue;
+    }
+    const code = character.charCodeAt(0);
+    if (code < 32 || code > 126) return void 0;
+    value += character;
+  }
+  return void 0;
+}
+function parseToken(cursor) {
+  const start = cursor.position;
+  cursor.position += 1;
+  while (TOKEN_CHAR.test(peek(cursor))) cursor.position += 1;
+  return { type: "token", value: cursor.text.slice(start, cursor.position) };
+}
+function parseBytes(cursor) {
+  const end = cursor.text.indexOf(":", cursor.position + 1);
+  if (end === -1) return void 0;
+  const value = decodeBase64(cursor.text.slice(cursor.position + 1, end));
+  cursor.position = end + 1;
+  return value && { type: "bytes", value };
+}
+function parseBoolean(cursor) {
+  const digit = cursor.text.charAt(cursor.position + 1);
+  if (digit !== "0" && digit !== "1") return void 0;
+  cursor.position += 2;
+  return { type: "boolean", value: digit === "1" };
+}
+function serializeBareItem(item) {
+  switch (item.type) {
+    case "integer":
+      return item.value.toString();
+    case "decimal": {
+      const rounded = Math.round(item.value * 1e3) / 1e3;
+      return Number.isInteger(rounded) ? rounded.toFixed(1) : rounded.toString();
+    }
+    case "string":
+      return `"${item.value.replace(/[\\"]/g, (character) => `\\${character}`)}"`;
+    case "token":
+      return item.value;
+    case "bytes":
+      return `:${encodeBase64(item.value)}:`;
+    case "boolean":
+      return item.value ? "?1" : "?0";
+  }
+}
+function serializeParameters(parameters) {
+  let serialized = "";
+  for (const [key, value] of parameters) {
+    serialized += value.type === "boolean" && value.value ? `;${key}` : `;${key}=${serializeBareItem(value)}`;
+  }
+  return serialized;
+}
+function peek(cursor) {
+  return cursor.text.charAt(cursor.position);
+}
+function skipSpaces(cursor) {
+  while (peek(cursor) === " ") cursor.position += 1;
+}
+function skipWhitespace(cursor) {
+  while (peek(cursor) === " " || peek(cursor) === "	") cursor.position += 1;
+}
+
+// src/http-signature.ts
+var INTEGER_PARAMETERS = /* @__PURE__ */ new Set(["created", "expires"]);
+var STRING_PARAMETERS = /* @__PURE__ */ new Set(["nonce", "alg", "keyid", "tag"]);
+var FIELD_NAME = /^[!#$%&'*+\-.^_`|~0-9a-z]+$/;
+var SIGNATURE_BASE = /^[\t\n\x20-\x7e]*$/;
+function readSignatures(headers) {
+  const inputField = headers.get("signature-input");
+  const signatureField = headers.get("signature");
+  if (inputField === null || signatureField === null) return "signature_missing";
+  const inputs = parseDictionary(inputField);
+  const signatures = parseDictionary(signatureField);
+  if (inputs === void 0 || signatures === void 0) return "signature_malformed";
+  const result = [];
+  for (const [label, member] of inputs) {
+    const signature = signatures.get(label);
+    if (member.kind !== "inner-list" || signature?.kind !== "item" || signature.value.type !== "bytes") continue;
+    if (!member.items.every((component) => component.value.type === "string")) continue;
+    const parameters = readParameters(member.parameters);
+    if (parameters === void 0) continue;
+    result.push({ label, components: member.items, parameters, signature: signature.value.value, raw: member });
+  }
+  return result;
+}
+function signatureBase(request, input) {
+  const url = new URL(request.url);
+  const lines = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const component of input.components) {
+    const identifier = serializeMember(component);
+    if (seen.has(identifier)) return void 0;
+    seen.add(identifier);
+    const value = componentValue(request, url, component);
+    if (value === void 0) return void 0;
+    lines.push(`${identifier}: ${value}`);
+  }
+  lines.push(`"@signature-params": ${serializeMember(input.raw)}`);
+  const base = lines.join("\n");
+  return SIGNATURE_BASE.test(base) ? base : void 0;
+}
+function componentValue(request, url, component) {
+  const name = stringValue(component.value);
+  if (name === void 0) return void 0;
+  const parameters = [...component.parameters];
+  if (name === "@query-param") {
+    const [only2, ...rest2] = parameters;
+    if (only2 === void 0 || only2[0] !== "name" || rest2.length > 0) return void 0;
+    const wanted = stringValue(only2[1]);
+    return wanted === void 0 ? void 0 : queryParameter(url, wanted);
+  }
+  if (name.startsWith("@")) {
+    return parameters.length === 0 ? derivedComponent(request, url, name) : void 0;
+  }
+  if (!FIELD_NAME.test(name)) return void 0;
+  const field = request.headers.get(name);
+  if (field === null) return void 0;
+  if (parameters.length === 0) return field;
+  const [only, ...rest] = parameters;
+  if (only?.[0] !== "key" || rest.length > 0) return void 0;
+  const key = stringValue(only[1]);
+  const member = key === void 0 ? void 0 : parseDictionary(field)?.get(key);
+  return member === void 0 ? void 0 : serializeMember(member);
+}
+function derivedComponent(request, url, name) {
+  switch (name) {
+    case "@method":
+      return request.method;
+    case "@target-uri":
+      return url.href;
+    case "@authority":
+      return url.host;
+    case "@scheme":
+      return url.protocol.slice(0, -1);
+    case "@request-target":
+      return `${url.pathname}${url.search}`;
+    case "@path":
+      return url.pathname === "" ? "/" : url.pathname;
+    case "@query":
+      return url.search === "" ? "?" : url.search;
+    default:
+      return void 0;
+  }
+}
+function queryParameter(url, wanted) {
+  const matches = [...new URLSearchParams(url.search)].filter(([name]) => formEncode(name) === wanted);
+  const [match, duplicate] = matches;
+  return match === void 0 || duplicate !== void 0 ? void 0 : formEncode(match[1]);
+}
+function formEncode(value) {
+  return new URLSearchParams([["", value]]).toString().slice(1).replace(/\+/g, "%20");
+}
+function readParameters(parameters) {
+  const values = /* @__PURE__ */ new Map();
+  for (const [key, value] of parameters) {
+    if (INTEGER_PARAMETERS.has(key) && value.type === "integer") values.set(key, value.value);
+    else if (STRING_PARAMETERS.has(key) && value.type === "string") values.set(key, value.value);
+    else return void 0;
+  }
+  const integer = (key) => {
+    const value = values.get(key);
+    return typeof value === "number" ? value : void 0;
+  };
+  const string = (key) => {
+    const value = values.get(key);
+    return typeof value === "string" ? value : void 0;
+  };
+  return {
+    created: integer("created"),
+    expires: integer("expires"),
+    nonce: string("nonce"),
+    alg: string("alg"),
+    keyid: string("keyid"),
+    tag: string("tag")
+  };
+}
+function stringValue(item) {
+  return item.type === "string" ? item.value : void 0;
+}
+
+// src/verification-key.ts
+var SHAPES = {
+  "OKP Ed25519": { algorithm: "ed25519", names: ["ed25519", "EdDSA", "Ed25519"], members: ["crv", "kty", "x"], importParams: { name: "Ed25519" } },
+  "EC P-256": {
+    algorithm: "ecdsa-p256-sha256",
+    names: ["ecdsa-p256-sha256", "ES256"],
+    members: ["crv", "kty", "x", "y"],
+    importParams: { name: "ECDSA", namedCurve: "P-256" }
+  },
+  "EC P-384": {
+    algorithm: "ecdsa-p384-sha384",
+    names: ["ecdsa-p384-sha384", "ES384"],
+    members: ["crv", "kty", "x", "y"],
+    importParams: { name: "ECDSA", namedCurve: "P-384" }
+  },
+  RSA: { algorithm: "rsa-pss-sha512", names: ["rsa-pss-sha512", "PS512"], members: ["e", "kty", "n"], importParams: { name: "RSA-PSS", hash: "SHA-512" } }
+};
+var VERIFY_PARAMS = {
+  ed25519: { name: "Ed25519" },
+  "ecdsa-p256-sha256": { name: "ECDSA", hash: "SHA-256" },
+  "ecdsa-p384-sha384": { name: "ECDSA", hash: "SHA-384" },
+  "rsa-pss-sha512": { name: "RSA-PSS", saltLength: 64 }
+};
+var SIGNATURE_LENGTH = {
+  ed25519: 64,
+  "ecdsa-p256-sha256": 64,
+  "ecdsa-p384-sha384": 96
+};
+var MIN_RSA_MODULUS_BYTES = 256;
+async function readVerificationKey(entry) {
+  if (typeof entry !== "object" || entry === null || Array.isArray(entry)) return void 0;
+  const jwk = entry;
+  const shape = jwk.kty === "RSA" ? SHAPES.RSA : SHAPES[`${String(jwk.kty)} ${String(jwk.crv)}`];
+  if (shape === void 0 || "d" in jwk) return void 0;
+  if (jwk.use !== void 0 && jwk.use !== "sig") return void 0;
+  if (jwk.key_ops !== void 0 && !(Array.isArray(jwk.key_ops) && jwk.key_ops.includes("verify"))) return void 0;
+  if (jwk.alg !== void 0 && !(typeof jwk.alg === "string" && shape.names.includes(jwk.alg))) return void 0;
+  const members = {};
+  for (const member of shape.members) {
+    const value = jwk[member];
+    if (typeof value !== "string") return void 0;
+    members[member] = value;
+  }
+  if (shape.algorithm === "rsa-pss-sha512" && (decodeBase64url(members.n ?? "")?.length ?? 0) < MIN_RSA_MODULUS_BYTES) return void 0;
+  const thumbprint = await jwkThumbprint(members, shape.members);
+  if (jwk.kid !== void 0 && jwk.kid !== thumbprint) return void 0;
+  const cryptoKey = await importPublicKey(members, shape);
+  if (cryptoKey === void 0) return void 0;
+  return {
+    thumbprint,
+    algorithm: shape.algorithm,
+    explicit: jwk.alg !== void 0 || shape.algorithm !== "rsa-pss-sha512",
+    notBefore: typeof jwk.nbf === "number" ? jwk.nbf : void 0,
+    notAfter: typeof jwk.exp === "number" ? jwk.exp : void 0,
+    cryptoKey
+  };
+}
+function agreedAlgorithm(key, alg) {
+  if (alg === void 0) return key.explicit ? key.algorithm : void 0;
+  return alg === key.algorithm ? key.algorithm : void 0;
+}
+async function verifySignature(key, algorithm, base, signature) {
+  const length = SIGNATURE_LENGTH[algorithm];
+  if (length !== void 0 && signature.length !== length) return false;
+  return crypto.subtle.verify(VERIFY_PARAMS[algorithm], key.cryptoKey, signature, new TextEncoder().encode(base));
+}
+async function jwkThumbprint(members, names) {
+  const canonical = JSON.stringify(Object.fromEntries(names.map((name) => [name, members[name]])));
+  return encodeBase64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical))));
+}
+async function importPublicKey(members, shape) {
+  try {
+    return await crypto.subtle.importKey("jwk", { ...members, ext: true }, shape.importParams, false, ["verify"]);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/key-directory.ts
+var DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
+var MEDIA_TYPE = "application/http-message-signatures-directory+json";
+var MAX_BYTES = 64 * 1024;
+var MAX_KEYS = 32;
+var MAX_DIRECTORIES = 1024;
+var MIN_TTL_MS = 6e4;
+var RETRY_AFTER_FAILURE_MS = 3e4;
+var STALE_IF_ERROR_MS = 24 * 60 * 60 * 1e3;
+function keyDirectory(options) {
+  const entries = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  const remember = (origin, entry) => {
+    entries.delete(origin);
+    if (entries.size >= MAX_DIRECTORIES) {
+      const oldest = entries.keys().next();
+      if (oldest.done !== true) entries.delete(oldest.value);
+    }
+    entries.set(origin, entry);
+  };
+  const cached = (entry, at, failure) => {
+    if (entry?.keys == null || at >= entry.expiresAt + STALE_IF_ERROR_MS) return { status: failure };
+    return { status: "resolved", keys: entry.keys };
+  };
+  const fetchOnce = (origin, signal) => {
+    const pending = inFlight.get(origin);
+    if (pending !== void 0) return pending;
+    const started = fetchDirectory(origin, options, signal).finally(() => inFlight.delete(origin));
+    inFlight.set(origin, started);
+    return started;
+  };
+  return {
+    async lookup(origin, now, signal) {
+      const at = now.getTime();
+      const entry = entries.get(origin);
+      if (entry?.keys != null && at < entry.expiresAt) return { status: "resolved", keys: entry.keys };
+      if (entry?.failure != null && at < entry.retryAt) return cached(entry, at, entry.failure);
+      const fetched = await fetchOnce(origin, signal);
+      if (typeof fetched === "string") {
+        remember(origin, {
+          keys: entry?.keys ?? null,
+          expiresAt: entry?.expiresAt ?? at,
+          retryAt: at + RETRY_AFTER_FAILURE_MS,
+          failure: fetched
+        });
+        return cached(entry, at, fetched);
+      }
+      remember(origin, { keys: fetched.keys, expiresAt: at + Math.min(options.cacheTtlMs, fetched.ttlMs), retryAt: 0, failure: null });
+      return { status: "resolved", keys: fetched.keys };
+    }
+  };
+}
+async function fetchDirectory(origin, options, signal) {
+  const response = await readBounded(`${origin}${DIRECTORY_PATH}`, options, signal);
+  if (typeof response === "string") return response;
+  const document = parseJson(response.body);
+  if (typeof document !== "object" || document === null || !("keys" in document) || !Array.isArray(document.keys)) return "invalid";
+  const entries = document.keys;
+  if (entries.length > MAX_KEYS) return "invalid";
+  const keys = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const key = await readVerificationKey(entry);
+    if (key !== void 0) keys.set(key.thumbprint, key);
+  }
+  return { keys, ttlMs: Math.max(MIN_TTL_MS, maxAgeMs(response.cacheControl) ?? Number.POSITIVE_INFINITY) };
+}
+async function readBounded(url, options, signal) {
+  try {
+    const response = await options.fetch(url, {
+      method: "GET",
+      redirect: "manual",
+      headers: { accept: MEDIA_TYPE },
+      signal: AbortSignal.any([signal, AbortSignal.timeout(options.timeoutMs)])
+    });
+    if (response.status !== 200 || response.body === null) {
+      await response.body?.cancel();
+      return response.status >= 500 ? "unavailable" : "invalid";
+    }
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (declared > MAX_BYTES) {
+      await response.body.cancel();
+      return "invalid";
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.length;
+      if (total > MAX_BYTES) {
+        await reader.cancel();
+        return "invalid";
+      }
+      chunks.push(value);
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+      bytes.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return { body: new TextDecoder().decode(bytes), cacheControl: response.headers.get("cache-control") };
+  } catch {
+    return "unavailable";
+  }
+}
+function maxAgeMs(cacheControl) {
+  if (cacheControl === null) return void 0;
+  if (/(?:^|,)\s*(?:no-store|no-cache)\s*(?:,|$)/i.test(cacheControl)) return 0;
+  const match = /(?:^|,)\s*max-age\s*=\s*(\d+)\s*(?:,|$)/i.exec(cacheControl);
+  return match?.[1] === void 0 ? void 0 : Number(match[1]) * 1e3;
+}
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/agent-signature.ts
+var WEB_BOT_AUTH_TAG = "web-bot-auth";
+async function verifyAgentSignature(request, options) {
+  const signatures = readSignatures(request.headers);
+  if (typeof signatures === "string") return rejected(signatures);
+  const candidates = signatures.filter((signature) => signature.parameters.tag === WEB_BOT_AUTH_TAG);
+  if (candidates.length === 0) return rejected(signatures.length === 0 ? "signature_malformed" : "tag_missing");
+  let first;
+  for (const candidate of candidates) {
+    const result = await verifyCandidate(request, candidate, options);
+    if (result.status === "verified") return result;
+    first ??= result;
+  }
+  return first ?? rejected("signature_missing");
+}
+async function verifyCandidate(request, input, options) {
+  const { created, expires, keyid, nonce, alg } = input.parameters;
+  if (created === void 0 || expires === void 0 || keyid === void 0) return rejected("signature_parameters_missing");
+  if (created > expires) return rejected("signature_malformed");
+  if (!input.components.some(isBareTarget)) return rejected("target_not_covered");
+  const now = options.now.getTime() / 1e3;
+  const skew = options.clockSkewMs / 1e3;
+  if (created > now + skew) return rejected("signature_not_yet_valid");
+  if (now >= expires + skew) return rejected("signature_expired");
+  if (now - created > options.maxAgeMs / 1e3 + skew) return rejected("signature_too_old");
+  if (options.requireNonce && nonce === void 0) return rejected("nonce_missing");
+  const agent = coveredAgent(request, input.components);
+  if (typeof agent === "string") return rejected(agent);
+  const base = signatureBase(request, input);
+  if (base === void 0) return rejected("signature_base_invalid");
+  const resolution = await options.resolveKey(agent, keyid);
+  if (resolution.status === "rejected") return resolution;
+  const { key } = resolution;
+  if (key.notBefore !== void 0 && now + skew < key.notBefore || key.notAfter !== void 0 && now - skew >= key.notAfter) {
+    return rejected("key_not_found");
+  }
+  const algorithm = agreedAlgorithm(key, alg);
+  if (algorithm === void 0) return rejected("algorithm_mismatch");
+  if (!await verifySignature(key, algorithm, base, input.signature)) return rejected("signature_invalid");
+  return {
+    status: "verified",
+    agent,
+    keyid,
+    nonce,
+    acceptableUntil: Math.min(expires, created + options.maxAgeMs / 1e3) + skew
+  };
+}
+function coveredAgent(request, components) {
+  const field = request.headers.get("signature-agent");
+  if (field === null) return "signature_agent_missing";
+  const covering = components.filter((component) => component.value.value === "signature-agent");
+  const legacy = parseItem(field);
+  if (legacy !== void 0) {
+    if (legacy.value.type !== "string" || legacy.parameters.size > 0) return "signature_agent_malformed";
+    if (!covering.some((component) => component.parameters.size === 0)) return "signature_agent_not_covered";
+    return directoryAgent(legacy.value.value) ?? "signature_agent_malformed";
+  }
+  const members = parseDictionary(field);
+  if (members === void 0) return "signature_agent_malformed";
+  const keys = covering.flatMap((component) => {
+    const key2 = component.parameters.get("key");
+    return component.parameters.size === 1 && key2?.type === "string" ? [key2.value] : [];
+  });
+  const [key, another] = keys;
+  if (key === void 0 || another !== void 0) return "signature_agent_not_covered";
+  const member = members.get(key);
+  if (member?.kind !== "item" || member.value.type !== "string") return "signature_agent_malformed";
+  const type = member.parameters.get("type");
+  if (type !== void 0 && !(type.type === "token" && type.value === "directory")) return "signature_agent_unsupported";
+  return directoryAgent(member.value.value) ?? "signature_agent_malformed";
+}
+function directoryAgent(value) {
+  const origin = httpsOrigin(value);
+  return origin === void 0 ? void 0 : { origin, directory: `${origin}${DIRECTORY_PATH}` };
+}
+function httpsOrigin(value) {
+  if (!URL.canParse(value)) return void 0;
+  const url = new URL(value);
+  if (url.protocol !== "https:") return void 0;
+  return value === url.origin || value === `${url.origin}/` ? url.origin : void 0;
+}
+function isBareTarget(component) {
+  return (component.value.value === "@authority" || component.value.value === "@target-uri") && component.parameters.size === 0;
+}
+function rejected(reason) {
+  return { status: "rejected", reason };
+}
+
+// src/verified-agent.ts
+var TEST_KEYS = /* @__PURE__ */ new Set([
+  "poqkLGiymh_W0uP6PZFw-dvez3QJT5SolqXBCW38r0U",
+  "oD0HwocPBSfpNy5W3bpJeyFGY_IQ_YpqxSjQ3Yd-CLA",
+  "ydQXMtvbsOsZyFir-Y7A8t7fKEM1gbKPvyFkdpu4fvI"
+]);
+var NONCE_SCOPE = "web-bot-auth";
+function verifiedAgent(options) {
+  const trusted = trustPredicate(options.trust);
+  const maxAgeMs2 = duration("maxAgeMs", options.maxAgeMs, 3e5);
+  const clockSkewMs = duration("clockSkewMs", options.clockSkewMs, 5e3, true);
+  const directory = keyDirectory({
+    fetch: options.fetch ?? ((input, init) => fetch(input, init)),
+    timeoutMs: duration("timeoutMs", options.timeoutMs, 3e3),
+    cacheTtlMs: duration("cacheTtlMs", options.cacheTtlMs, 36e5)
+  });
+  const resolveKey = async (agent, keyid, now, signal) => {
+    if (!trusted(agent.origin)) return { status: "rejected", reason: "agent_untrusted" };
+    const lookup = await directory.lookup(agent.origin, now, signal);
+    if (lookup.status !== "resolved") return { status: "rejected", reason: `directory_${lookup.status}` };
+    const key = lookup.keys.get(keyid);
+    if (key === void 0 || TEST_KEYS.has(key.thumbprint)) return { status: "rejected", reason: "key_not_found" };
+    return { status: "found", key };
+  };
+  return {
+    name: "verified-agent",
+    async check({ context, claims, now, signal }) {
+      if (context.transport !== "http" || context.request === null) return deny("http_request_required");
+      const verification = await verifyAgentSignature(context.request, {
+        now,
+        maxAgeMs: maxAgeMs2,
+        clockSkewMs,
+        requireNonce: options.requireNonce ?? false,
+        resolveKey: (agent, keyid) => resolveKey(agent, keyid, now, signal)
+      });
+      if (verification.status === "rejected" && verification.reason === "directory_unavailable") {
+        return { ok: false, status: 503, reason: verification.reason };
+      }
+      if (verification.status === "rejected") return deny(verification.reason);
+      if (verification.nonce !== void 0) {
+        const key = `${verification.agent.directory} ${verification.keyid} ${verification.nonce}`;
+        const claimed = await claims.claim(NONCE_SCOPE, key, new Date(verification.acceptableUntil * 1e3));
+        if (claimed === "exists") return deny("nonce_replayed");
+      }
+      return { ok: true };
+    }
+  };
+}
+function trustPredicate(trust) {
+  if (typeof trust === "function") return trust;
+  const origins = new Set(
+    trust.map((entry) => {
+      const origin = httpsOrigin(entry);
+      if (origin === void 0) {
+        throw new TollstileError(
+          "CONFIG_INVALID",
+          `verifiedAgent() trust entry "${entry}" is not an HTTPS origin. Use the lowercase origin only, e.g. "https://agent.example".`
+        );
+      }
+      return origin;
+    })
+  );
+  if (origins.size === 0) {
+    throw new TollstileError("CONFIG_INVALID", "verifiedAgent() needs at least one trusted origin, or a trust predicate.");
+  }
+  return (origin) => origins.has(origin);
+}
+function duration(name, value, fallback, allowZero = false) {
+  if (value === void 0) return fallback;
+  if (!Number.isSafeInteger(value) || value < 0 || value === 0 && !allowZero) {
+    throw new TollstileError("CONFIG_INVALID", `verifiedAgent() ${name} must be a positive integer number of milliseconds, got ${String(value)}.`);
+  }
+  return value;
+}
+function deny(reason) {
+  return { ok: false, status: 403, reason };
+}
+export {
+  verifiedAgent
+};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@tollstile/web-bot-auth",
+  "version": "0.1.0",
+  "description": "Allow only verified AI agents: verify Web Bot Auth HTTP message signatures (RFC 9421) before an agent can pay or access a route. A Tollstile requirement.",
+  "keywords": [
+    "web-bot-auth",
+    "http-message-signatures",
+    "rfc9421",
+    "agent-identity",
+    "verified-agents",
+    "bot-authentication",
+    "ai-agents",
+    "agent-payments"
+  ],
+  "homepage": "https://tollstile.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tollstile/tollstile.git",
+    "directory": "packages/web-bot-auth"
+  },
+  "bugs": {
+    "url": "https://github.com/tollstile/tollstile/issues"
+  },
+  "author": "Paradigm AI Inc.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "tollstile": "^0.1.0"
+  },
+  "devDependencies": {
+    "tollstile": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}