@bondedhq/sdk 0.1.7 → 0.2.0

package/README.md

@@ -558,19 +558,20 @@ an episode. `mcpConfigJson(episode, options)` returns the same text.
 
 ### Agent URL
 
-In Agent URL mode Bonded `POST`s each episode to your HTTPS endpoint, signed with your agent
-secret (`bonded_as_...`, shown once when you register the URL). Registering is two steps: save
-the URL and copy the secret into your agent, then verify, when Bonded sends a signed challenge
-your endpoint must answer with a proof that it holds the secret. `createBondedHandler` is the whole
-endpoint: a standard Fetch API handler for Hono, Next.js route handlers, Bun, Deno and Cloudflare
-Workers, with a Node adapter for Express and `node:http`.
+In Agent URL mode Bonded `POST`s each episode to your HTTPS endpoint, signed with Bonded's own
+key for the wallet that saved the URL. There is no secret: your handler names its `owner`, your
+wallet, in code (it's public), and refuses calls signed for anyone else. Deploy it, save the URL
+on Bonded from that wallet, then verify: Bonded sends a signed challenge and your endpoint answers
+with its owner. `createBondedHandler` is the whole endpoint: a standard Fetch API handler for
+Hono, Next.js route handlers, Bun, Deno and Cloudflare Workers, with a Node adapter for Express
+and `node:http`.
 
 ```ts
 import { createBondedHandler, toNodeHandler } from "@bondedhq/sdk/agent-url";
 import { bondedAiSdkTools } from "@bondedhq/sdk/ai-sdk";
 
 const handler = createBondedHandler({
-  secret: process.env.BONDED_AGENT_SECRET!,
+  owner: "0xYourWallet", // the wallet you save this URL from on Bonded; public, not a secret
   version: process.env.GIT_SHA, // reported when Bonded verifies the URL; becomes the code hash
   async onEpisode(episode, { signal }) {
     const tools = await bondedAiSdkTools(episode);
@@ -590,15 +591,21 @@ expressApp.post("/bonded", toNodeHandler(handler)); // Express: mount before exp
 
 What the handler does with each request:
 
-1. **Checks the signature** before reading the message: `bonded-timestamp` (unix seconds) must be
-   within 300 seconds of the server's clock, and `bonded-signature`
-   (`v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>`, up to four while a secret rotates)
-   must match, compared in constant time. `secret` may be a list while you rotate it. A signature
-   it has accepted before is refused as a replay. Failures answer `401`, and a body that isn't one
-   of Bonded's messages `400`; nothing runs.
-2. `{ type: "verify", challenge }`: answers `200 { challenge, proof, version }`. `proof` is the
-   hex HMAC-SHA256 of `"verify." + challenge` under the secret (`agentUrlVerifyProof`), so only a
-   server holding the secret passes; an echo server doesn't.
+1. **Checks the call** before reading the message. `bonded-timestamp` (unix seconds) must be
+   within 300 seconds of the server's clock; `bonded-owner` must be your `owner` (a list works,
+   for a team); and `bonded-signature` (`v2=<key id>:<base64url Ed25519 signature>` over
+   `v2.<key id>.<timestamp>.<owner>.<raw body>`, up to four while a key rotates) must verify
+   under one of Bonded's public keys. The handler fetches those from
+   `https://www.bondedhq.xyz/.well-known/bonded-agent-keys.json` (`apiUrl` takes them from
+   another Bonded deployment instead, for a local Arena run), keeps them for a day, and fetches
+   again at once (at most once a minute) for a key it hasn't seen. A signature it has accepted before is refused as
+   a replay. Failures answer `401` (with `code: "wrong-owner"` when the call is
+   for a wallet the handler isn't set up for, so Bonded can tell you exactly that), a body that
+   isn't one of Bonded's messages `400`, and keys it can't fetch `503`; nothing runs.
+2. `{ type: "verify", challenge }`: answers `200 { challenge, owner, version }`. Bonded marks the
+   URL verified when `owner` is the wallet that saved it. The owner is only in the signed
+   headers, never the body, so an echo server can't pass, and someone who saves your URL gets
+   calls signed for their own wallet, which your handler refuses.
 3. `{ type: "episode", ... }`: answers `202` at once (Bonded waits at most 10 seconds) and runs
    `onEpisode` in the background. When it resolves, the handler posts `/done` with the
    `finalMessage` and `usage` it returned. If it throws, `/done` is still posted, saying the agent
@@ -609,10 +616,30 @@ What the handler does with each request:
 Limits: 256 KiB bodies (`maxBodyBytes`, the most Bonded sends), 8 episodes at once (`maxConcurrent`; Bonded sends one at a
 time per agent), and the same episode delivered twice runs once. On platforms that stop work when
 the response is sent, pass their `waitUntil` (as the option, or the handler's second argument).
-`signBondedRequest(secret, body)` signs a request the way Bonded does, for testing your endpoint;
-`verifyBondedSignature(...)` is the signature check on its own. Both use the scheme Bonded's
-gateway signs with, from `@bondedhq/shared/agent-url` (a small entry point without the contract ABIs,
-for edge bundles). A Python endpoint with no dependencies is in
+
+To test your endpoint, `createTestSigner()` stands in for Bonded: give the handler its `keys`, and
+`sign(owner, body)` returns the headers Bonded would send.
+
+```ts
+import { createBondedHandler, createTestSigner } from "@bondedhq/sdk/agent-url";
+
+const owner = "0x1111111111111111111111111111111111111111"; // your wallet
+const bonded = await createTestSigner();
+const handler = createBondedHandler({ owner, keys: bonded.keys, onEpisode });
+const body = JSON.stringify({ type: "verify", challenge: "a-test-challenge-0001" });
+const res = await handler(
+  new Request("http://localhost/bonded", {
+    method: "POST",
+    headers: { "content-type": "application/json", ...(await bonded.sign(owner, body)) },
+    body,
+  }),
+);
+// 200 { challenge: "a-test-challenge-0001", owner: "0x1111…1111" }
+```
+
+`verifyAgentUrlRequest(...)` is the check on its own and `answerAgentUrlVerify(...)` the verify
+answer, from `@bondedhq/shared/agent-url` (a small entry point without the contract ABIs, for
+edge bundles). A Python endpoint (the standard library and `cryptography`) is in
 [`examples/python-agent-url`](../../examples/python-agent-url/README.md).
 
 ## Vault trading tools for LangChain, LangGraph and the AI SDK

package/dist/agent-url.d.ts

@@ -1,21 +1,23 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type AgentUrlPublicKey } from "@bondedhq/shared/agent-url";
 import type { BondedBrokerageEpisode, BondedEpisode } from "./episode.js";
 import type { EpisodeUsage } from "./mcp.js";
-/** For your own handler: the proof a verify answer carries, and the whole answer. */
-export { agentUrlVerifyProof, answerAgentUrlVerify } from "@bondedhq/shared/agent-url";
-export { SIGNATURE_HEADER, SIGNATURE_TOLERANCE_SECONDS, signBondedRequest, type SignatureCheck, TIMESTAMP_HEADER, verifyBondedSignature, } from "./signature.js";
+/** For your own handler: the verify answer, and the request check. */
+export { AGENT_URL_KEYS_PATH, AgentUrlKeys, type AgentUrlPublicKey, answerAgentUrlVerify, verifyAgentUrlRequest, } from "@bondedhq/shared/agent-url";
+export { BONDED_AGENT_KEYS, BONDED_AGENT_KEYS_URL, createTestSigner, keysUrlOf, OWNER_HEADER, SIGNATURE_HEADER, SIGNATURE_TOLERANCE_SECONDS, TIMESTAMP_HEADER, } from "./signature.js";
 /**
  * Agent URL mode: instead of running the Bonded runner, an agent serves one HTTPS endpoint and
  * Bonded calls it once per episode. Every call is a signed `POST` of one JSON message:
  *
- * - `{ type: "verify", challenge }` when the URL is registered: answer
- *   `200 { challenge, proof, version? }`, where `proof` is the hex HMAC-SHA256 of
- *   `"verify." + challenge` under the secret.
+ * - `{ type: "verify", challenge }` when the URL is saved: answer
+ *   `200 { challenge, owner, version? }`, where `owner` is your wallet.
  * - `{ type: "episode", ... }` (the runner protocol's `EpisodeMessage`): answer `2xx` within
  *   10 seconds, then work: call the episode's tools and `POST {done}` when finished.
  * - `{ type: "cancel", episodeId }`: stop that episode (best effort).
  *
- * `createBondedHandler` does all of that: it checks signatures, answers challenges, acknowledges an
+ * Every call is signed by Bonded's own key and names the owner it is for; there is no secret to
+ * set. `createBondedHandler` does all of that: it checks signatures against Bonded's published
+ * keys, refuses calls for any wallet but `owner`, answers challenges, acknowledges an
  * episode at once and runs your `onEpisode` in the background, aborts it on cancel or at the
  * deadline, and posts `/done` (with the usage you return) when it resolves.
  */
@@ -34,10 +36,18 @@ export interface EpisodeContext {
 }
 export interface BondedHandlerOptions {
     /**
-     * The agent secret Bonded showed you when you registered the URL (`bonded_as_...`), or several
-     * while you rotate it (any one may match).
+     * Your wallet: the one you sign in to Bonded with and save this URL from (or several, for a
+     * team). Bonded signs each call for the wallet that saved the URL, and the handler refuses calls
+     * for anyone else, so nobody can claim your URL as theirs. It's public, not a secret.
      */
-    secret: string | string[];
+    owner: string | string[];
+    /**
+     * Another Bonded deployment to take the signing keys from (a local Arena, a staging API). Leave
+     * it out for Bonded itself: the keys then come from BONDED_AGENT_KEYS_URL.
+     */
+    apiUrl?: string;
+    /** Bonded's public keys, given directly instead of fetched (for tests: `createTestSigner`). */
+    keys?: AgentUrlPublicKey[];
     /** Runs one episode. Resolve when the agent is finished; the handler then posts `/done`. */
     onEpisode(episode: BondedEpisode, context: EpisodeContext): Promise<EpisodeOutcome | void> | EpisodeOutcome | void;
     /**
@@ -80,7 +90,7 @@ export type BondedHandler = (request: Request, context?: {
  *
  * ```ts
  * const handler = createBondedHandler({
- *   secret: process.env.BONDED_AGENT_SECRET!,
+ *   owner: "0xYourWallet",
  *   version: process.env.GIT_SHA,
  *   async onEpisode(episode, { signal }) {
  *     const tools = await bondedAiSdkTools(episode);

package/dist/agent-url.js

@@ -1,14 +1,15 @@
-import { AGENT_URL_MAX_BODY_BYTES, AGENT_URL_TOLERANCE_SECONDS, AgentUrlReplayGuard, answerAgentUrlVerify, verifyAgentUrlRequest, } from "@bondedhq/shared/agent-url";
+import { AGENT_URL_MAX_BODY_BYTES, AGENT_URL_TOLERANCE_SECONDS, AgentUrlKeys, AgentUrlReplayGuard, agentUrlSignatureKeyIds, answerAgentUrlVerify, isAgentUrlOwner, verifyAgentUrlRequest, } from "@bondedhq/shared/agent-url";
+import { BONDED_AGENT_KEYS, BONDED_AGENT_KEYS_URL, keysUrlOf } from "./signature.js";
 import { finishEpisode } from "./done.js";
-/** For your own handler: the proof a verify answer carries, and the whole answer. */
-export { agentUrlVerifyProof, answerAgentUrlVerify } from "@bondedhq/shared/agent-url";
-export { SIGNATURE_HEADER, SIGNATURE_TOLERANCE_SECONDS, signBondedRequest, TIMESTAMP_HEADER, verifyBondedSignature, } from "./signature.js";
+/** For your own handler: the verify answer, and the request check. */
+export { AGENT_URL_KEYS_PATH, AgentUrlKeys, answerAgentUrlVerify, verifyAgentUrlRequest, } from "@bondedhq/shared/agent-url";
+export { BONDED_AGENT_KEYS, BONDED_AGENT_KEYS_URL, createTestSigner, keysUrlOf, OWNER_HEADER, SIGNATURE_HEADER, SIGNATURE_TOLERANCE_SECONDS, TIMESTAMP_HEADER, } from "./signature.js";
 /**
  * An Agent URL endpoint for your agent.
  *
  * ```ts
  * const handler = createBondedHandler({
- *   secret: process.env.BONDED_AGENT_SECRET!,
+ *   owner: "0xYourWallet",
  *   version: process.env.GIT_SHA,
  *   async onEpisode(episode, { signal }) {
  *     const tools = await bondedAiSdkTools(episode);
@@ -20,15 +21,23 @@ export { SIGNATURE_HEADER, SIGNATURE_TOLERANCE_SECONDS, signBondedRequest, TIMES
  * ```
  */
 export function createBondedHandler(options) {
-    if (!options.secret || (Array.isArray(options.secret) && options.secret.length === 0))
-        throw new Error("createBondedHandler needs the agent secret");
+    const owners = Array.isArray(options.owner) ? options.owner : [options.owner];
+    if (owners.length === 0 || !owners.every((o) => typeof o === "string" && isAgentUrlOwner(o)))
+        throw new Error("createBondedHandler needs owner: your wallet address (0x…), the one you save this URL from");
+    const keyStore = options.keys
+        ? undefined
+        : new AgentUrlKeys(options.apiUrl ? keysUrlOf(options.apiUrl) : BONDED_AGENT_KEYS_URL, {
+            // The built-in keys are Bonded's own: never a fallback for another deployment's.
+            ...(options.apiUrl ? {} : { fallback: BONDED_AGENT_KEYS }),
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+            ...(options.now ? { now: options.now } : {}),
+        });
     const now = options.now ?? Date.now;
     const tolerance = options.toleranceSeconds ?? AGENT_URL_TOLERANCE_SECONDS;
     const maxBody = options.maxBodyBytes ?? AGENT_URL_MAX_BODY_BYTES;
     const maxConcurrent = options.maxConcurrent ?? 8;
     const onError = options.onError ??
         ((error, episode) => console.error(`Bonded episode ${episode.episodeId} failed:`, error));
-    const secrets = Array.isArray(options.secret) ? options.secret : [options.secret];
     /** Signatures already accepted, until they fall out of the window: replays are refused. */
     const replay = new AgentUrlReplayGuard(tolerance);
     const running = new Map();
@@ -85,8 +94,19 @@ export function createBondedHandler(options) {
         const body = await readCapped(request, maxBody);
         if (body === undefined)
             return json(413, { error: `the body is over ${maxBody} bytes` });
+        let keys;
+        try {
+            keys =
+                options.keys ??
+                    (await keyStore.get(agentUrlSignatureKeyIds(request.headers).find(Boolean)));
+        }
+        catch (error) {
+            console.error("Bonded: couldn't fetch Bonded's signing keys:", error);
+            return json(503, { error: "the agent couldn't fetch Bonded's signing keys; try again" });
+        }
         const check = await verifyAgentUrlRequest({
-            secret: options.secret,
+            owner: owners,
+            keys,
             body,
             headers: request.headers,
             nowMs: now(),
@@ -94,11 +114,15 @@ export function createBondedHandler(options) {
             replay,
         });
         if (!check.ok)
-            return json(check.status, { error: check.reason });
+            return json(check.status, {
+                error: check.reason,
+                ...(check.code ? { code: check.code } : {}),
+            });
         const message = check.message;
-        // The answer proves the secret (an HMAC of the challenge), so an echo server can't pass.
+        // The answer names the owner the call was signed for (one of ours, checked above). The verify
+        // body carries no owner, so a server that echoes it back can't pass.
         if (message.type === "verify")
-            return json(200, await answerAgentUrlVerify(await signingSecret(secrets, body, request.headers, now(), tolerance), message, options.version));
+            return json(200, answerAgentUrlVerify(check.owner, message, options.version));
         if (message.type === "cancel") {
             const controller = running.get(message.episodeId);
             controller?.abort(new Error("Bonded cancelled the episode"));
@@ -125,20 +149,6 @@ export function createBondedHandler(options) {
         return json(202, { ok: true, episodeId: message.episodeId });
     };
 }
-/**
- * Which of the secrets signed a request already verified (while a secret rotates, the verify
- * proof must be made with the one Bonded holds).
- */
-async function signingSecret(secrets, body, headers, nowMs, toleranceSeconds) {
-    if (secrets.length === 1)
-        return secrets[0];
-    for (const secret of secrets) {
-        const check = await verifyAgentUrlRequest({ secret, body, headers, nowMs, toleranceSeconds });
-        if (check.ok)
-            return secret;
-    }
-    return secrets[0];
-}
 /** A brokerage episode as the agent sees it (the same shape `fromBondedBrokerageEnv` returns). */
 function toBrokerageEpisode(message) {
     return {

package/dist/signature.d.ts

@@ -1,34 +1,50 @@
+/**
+ * Agent URL request signatures: how an agent knows a request really comes from Bonded, for its
+ * owner.
+ *
+ * Bonded signs every call to an Agent URL with its own Ed25519 key (no shared secret):
+ * - `bonded-timestamp`: unix seconds;
+ * - `bonded-owner`: the wallet that saved the URL on Bonded;
+ * - `bonded-signature`: `v2=<key id>:<base64url signature>` over
+ *   `v2.<key id>.<timestamp>.<owner>.<raw body>`.
+ *
+ * The handler checks it against Bonded's published keys (BONDED_AGENT_KEYS_URL) and refuses calls
+ * for any owner but its own. The scheme lives in @bondedhq/shared
+ * (`@bondedhq/shared/agent-url`, which the gateway signs with). Web Crypto only, so it runs in
+ * Node 22+, Bun, Deno, Cloudflare Workers and edge runtimes.
+ */
+import { type AgentUrlPublicKey } from "@bondedhq/shared/agent-url";
 export declare const SIGNATURE_HEADER = "bonded-signature";
 export declare const TIMESTAMP_HEADER = "bonded-timestamp";
+export declare const OWNER_HEADER = "bonded-owner";
 /** How far a request's timestamp may be from the agent's clock, either way. */
 export declare const SIGNATURE_TOLERANCE_SECONDS = 300;
 /**
- * Signs a body as Bonded does: the two headers to send with it. For testing your endpoint
- * locally; Bonded signs real calls itself.
+ * Where Bonded publishes the keys that sign calls to agents. It is on Bonded's own domain, not the
+ * API's host name, because this address is built into every deployed handler: the API can move
+ * without breaking them.
  */
-export declare function signBondedRequest(secret: string, body: string, timestamp?: number): Promise<{
-    "bonded-timestamp": string;
-    "bonded-signature": string;
-}>;
-export type SignatureCheck = {
-    ok: true;
-    timestamp: number;
-} | {
-    ok: false;
-    reason: string;
-};
+export declare const BONDED_AGENT_KEYS_URL = "https://www.bondedhq.xyz/.well-known/bonded-agent-keys.json";
 /**
- * Checks a request's signature only: the timestamp is within `toleranceSeconds` of now and one of
- * the header's `v1=` signatures is the body's HMAC under `secret` (or one of several secrets).
- * It doesn't look at the body or check for replays; `createBondedHandler` does both.
+ * Bonded's production keys, built in: used only when BONDED_AGENT_KEYS_URL can't be reached and
+ * no key set was fetched before, so a handler still starts then. The same set the keys address
+ * publishes (docs/AGENT-URL-SIGNED-CALLS.md, Section 6): on a key rotation, add the new public key
+ * here before a release.
  */
-export declare function verifyBondedSignature(input: {
-    secret: string | string[];
-    body: string;
-    timestamp: string | null | undefined;
-    signature: string | null | undefined;
-    /** Unix seconds. Default: now. */
-    now?: number;
-    toleranceSeconds?: number;
-}): Promise<SignatureCheck>;
+export declare const BONDED_AGENT_KEYS: AgentUrlPublicKey[];
+/** Where another Bonded deployment (a local Arena, a staging API) publishes its keys. */
+export declare const keysUrlOf: (apiUrl: string) => string;
+/**
+ * A stand-in for Bonded, for testing your endpoint locally: a fresh key, `sign` to sign a body
+ * for an owner the way Bonded does, and `keys` to give the handler (`createBondedHandler({ keys })`).
+ * Bonded signs real calls itself, with keys your handler fetches.
+ */
+export declare function createTestSigner(): Promise<{
+    keys: AgentUrlPublicKey[];
+    sign(owner: string, body: string, timestamp?: number): Promise<{
+        "bonded-timestamp": string;
+        "bonded-owner": string;
+        "bonded-signature": string;
+    }>;
+}>;
 //# sourceMappingURL=signature.d.ts.map

package/dist/signature.js

@@ -1,52 +1,59 @@
 /**
- * Agent URL request signatures: how an agent knows a request really comes from Bonded.
+ * Agent URL request signatures: how an agent knows a request really comes from Bonded, for its
+ * owner.
  *
- * Bonded signs every call to an Agent URL with the agent's secret:
+ * Bonded signs every call to an Agent URL with its own Ed25519 key (no shared secret):
  * - `bonded-timestamp`: unix seconds;
- * - `bonded-signature`: `v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>` (up to four,
- *   comma-separated, while a secret is rotated).
+ * - `bonded-owner`: the wallet that saved the URL on Bonded;
+ * - `bonded-signature`: `v2=<key id>:<base64url signature>` over
+ *   `v2.<key id>.<timestamp>.<owner>.<raw body>`.
  *
- * The scheme lives in @bondedhq/shared (`@bondedhq/shared/agent-url`, which the gateway signs with);
- * these are the SDK's names for it. Web Crypto only, so it runs in Node, Bun, Deno, Cloudflare
- * Workers and edge runtimes, and the comparison is Web Crypto's constant-time HMAC verify.
+ * The handler checks it against Bonded's published keys (BONDED_AGENT_KEYS_URL) and refuses calls
+ * for any owner but its own. The scheme lives in @bondedhq/shared
+ * (`@bondedhq/shared/agent-url`, which the gateway signs with). Web Crypto only, so it runs in
+ * Node 22+, Bun, Deno, Cloudflare Workers and edge runtimes.
  */
-import { AGENT_URL_SIGNATURE_HEADER, AGENT_URL_TIMESTAMP_HEADER, AGENT_URL_TOLERANCE_SECONDS, signAgentUrlRequest, verifyAgentUrlRequest, } from "@bondedhq/shared/agent-url";
+import { AGENT_URL_KEYS_PATH, AGENT_URL_OWNER_HEADER, AGENT_URL_SIGNATURE_HEADER, AGENT_URL_TIMESTAMP_HEADER, AGENT_URL_TOLERANCE_SECONDS, agentUrlSigner, newAgentUrlSigningKey, } from "@bondedhq/shared/agent-url";
 export const SIGNATURE_HEADER = AGENT_URL_SIGNATURE_HEADER;
 export const TIMESTAMP_HEADER = AGENT_URL_TIMESTAMP_HEADER;
+export const OWNER_HEADER = AGENT_URL_OWNER_HEADER;
 /** How far a request's timestamp may be from the agent's clock, either way. */
 export const SIGNATURE_TOLERANCE_SECONDS = AGENT_URL_TOLERANCE_SECONDS;
 /**
- * Signs a body as Bonded does: the two headers to send with it. For testing your endpoint
- * locally; Bonded signs real calls itself.
+ * Where Bonded publishes the keys that sign calls to agents. It is on Bonded's own domain, not the
+ * API's host name, because this address is built into every deployed handler: the API can move
+ * without breaking them.
  */
-export async function signBondedRequest(secret, body, timestamp = Math.floor(Date.now() / 1000)) {
-    const headers = await signAgentUrlRequest(secret, body, timestamp * 1000);
-    return {
-        "bonded-timestamp": headers[TIMESTAMP_HEADER],
-        "bonded-signature": headers[SIGNATURE_HEADER],
-    };
-}
+export const BONDED_AGENT_KEYS_URL = `https://www.bondedhq.xyz${AGENT_URL_KEYS_PATH}`;
 /**
- * Checks a request's signature only: the timestamp is within `toleranceSeconds` of now and one of
- * the header's `v1=` signatures is the body's HMAC under `secret` (or one of several secrets).
- * It doesn't look at the body or check for replays; `createBondedHandler` does both.
+ * Bonded's production keys, built in: used only when BONDED_AGENT_KEYS_URL can't be reached and
+ * no key set was fetched before, so a handler still starts then. The same set the keys address
+ * publishes (docs/AGENT-URL-SIGNED-CALLS.md, Section 6): on a key rotation, add the new public key
+ * here before a release.
  */
-export async function verifyBondedSignature(input) {
-    const result = await verifyAgentUrlRequest({
-        secret: input.secret,
-        body: input.body,
-        headers: {
-            [TIMESTAMP_HEADER]: input.timestamp ?? undefined,
-            [SIGNATURE_HEADER]: input.signature ?? undefined,
+export const BONDED_AGENT_KEYS = [
+    // The first production key, made 2026-11-14.
+    { kid: "ind7eq0xdV0-", alg: "Ed25519", x: "tWhxWPMrq6BKcQs838cUlF_5SecIG1NBy8L_IRIkSBg" },
+];
+/** Where another Bonded deployment (a local Arena, a staging API) publishes its keys. */
+export const keysUrlOf = (apiUrl) => `${apiUrl.replace(/\/+$/, "")}${AGENT_URL_KEYS_PATH}`;
+/**
+ * A stand-in for Bonded, for testing your endpoint locally: a fresh key, `sign` to sign a body
+ * for an owner the way Bonded does, and `keys` to give the handler (`createBondedHandler({ keys })`).
+ * Bonded signs real calls itself, with keys your handler fetches.
+ */
+export async function createTestSigner() {
+    const signer = await agentUrlSigner(await newAgentUrlSigningKey());
+    return {
+        keys: signer.keySet().keys,
+        async sign(owner, body, timestamp = Math.floor(Date.now() / 1000)) {
+            const headers = await signer.sign(owner, body, timestamp * 1000);
+            return {
+                "bonded-timestamp": headers[TIMESTAMP_HEADER],
+                "bonded-owner": headers[OWNER_HEADER],
+                "bonded-signature": headers[SIGNATURE_HEADER],
+            };
         },
-        ...(input.now !== undefined ? { nowMs: input.now * 1000 } : {}),
-        ...(input.toleranceSeconds !== undefined ? { toleranceSeconds: input.toleranceSeconds } : {}),
-    });
-    if (result.ok)
-        return { ok: true, timestamp: result.timestamp };
-    // 400 means the signature matched but the body isn't one of Bonded's messages.
-    if (result.status === 400)
-        return { ok: true, timestamp: Number(input.timestamp) };
-    return { ok: false, reason: result.reason };
+    };
 }
 //# sourceMappingURL=signature.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bondedhq/sdk",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Trade through a Bonded Mandate Vault and get rated by the Bonded Arena from any TypeScript agent: a typed vault client with dry runs, Sentinel checks and a mandate builder; the Arena episode's tools for LangChain, the Vercel AI SDK, ElizaOS and Coinbase AgentKit; a payment guard for pay tools (LangChain, the AI SDK, MCP, the OpenAI Agents SDK) and x402 clients; and an Agent URL handler.",
   "license": "MIT",
   "keywords": [
@@ -94,7 +94,7 @@
     "@modelcontextprotocol/sdk": "1.30.1",
     "viem": "^2.56.9",
     "zod": "^4.6.5",
-    "@bondedhq/shared": "^0.1.6"
+    "@bondedhq/shared": "^0.2.0"
   },
   "devDependencies": {
     "@coinbase/agentkit": "0.10.4",