@bondedhq/sdk 0.1.6 → 0.2.0

package/README.md

@@ -388,6 +388,27 @@ if (isBondedEpisode()) {
 `isBondedEpisode()` is true when the runner set valid `BONDED_*` variables. `fromBondedEnv` reads
 and checks them, naming every missing or malformed one (`BondedError`, code `EPISODE_ENV`).
 
+That is the vault world, where ratings run. An agent that trades through a broker can also be
+tested on the brokerage world (a simulated brokerage account, no vault; docs/BROKERAGE.md), with a
+runner started with `--world brokerage`. Its episode is read with `fromBondedBrokerageEnv()`, and
+`bondedEpisodeWorld()` says which world the runner set up:
+
+```ts
+import { bondedEpisodeWorld, fromBondedBrokerageEnv, fromBondedEnv } from "@bondedhq/sdk";
+
+const world = bondedEpisodeWorld(); // "vault", "brokerage", or undefined outside an episode
+if (world === "brokerage") {
+  const episode = fromBondedBrokerageEnv(); // { world, episodeId, task, mode: "tools", endpoints, deadlineMs }
+} else if (world === "vault") {
+  const episode = fromBondedEnv();
+}
+```
+
+`isBondedEpisode()` is true in both worlds, so an agent under test never falls through to its
+production tools. In a brokerage episode `fromBondedEnv` and the vault tool helpers throw
+`EPISODE_ENV` rather than guess. By Agent URL, `createBondedHandler` runs brokerage episodes with
+`onBrokerageEpisode` and refuses them (422) without it.
+
 The mode decides how the agent acts:
 
 - **tools**: reads and writes are tool calls; `swap`, `transfer` and `approve` are tools, and the
@@ -537,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);
@@ -569,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
@@ -588,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 { BondedEpisode } from "./episode.js";
+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,12 +36,28 @@ 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;
+    /**
+     * Runs one brokerage episode (a simulated brokerage account; docs/BROKERAGE.md). Without it, the
+     * handler refuses brokerage episodes with 422, so an agent built for the vault world never gets
+     * one by surprise. Errors are passed to `onBrokerageError` (default `console.error`).
+     */
+    onBrokerageEpisode?(episode: BondedBrokerageEpisode, context: EpisodeContext): Promise<EpisodeOutcome | void> | EpisodeOutcome | void;
+    /** Called when `onBrokerageEpisode` throws (default: `console.error`). `/done` is still posted. */
+    onBrokerageError?: (error: unknown, episode: BondedBrokerageEpisode) => void;
     /**
      * Your agent's version (a release tag, a git commit). Reported when Bonded verifies the URL;
      * it becomes the rating's code hash when you don't declare one.
@@ -72,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,29 +21,49 @@ 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();
-    const run = async (episode, controller) => {
+    const onBrokerageError = options.onBrokerageError ??
+        ((error, episode) => console.error(`Bonded brokerage episode ${episode.episodeId} failed:`, error));
+    const run = async (episode, controller, work, reportError) => {
         const deadline = setTimeout(() => controller.abort(new Error("the episode's deadline passed")), episode.deadlineMs);
+        // A reporter that throws must not stop `/done` from being posted: the gateway would wait out
+        // the deadline for an episode that has already failed.
+        const report = (error) => {
+            try {
+                reportError(error, episode);
+            }
+            catch (reporterError) {
+                console.error(`Bonded episode ${episode.episodeId}: the error reporter threw:`, reporterError);
+            }
+        };
         let outcome;
         let failed = false;
         try {
-            outcome = await options.onEpisode(episode, { signal: controller.signal });
+            outcome = await work(episode, { signal: controller.signal });
         }
         catch (error) {
             failed = true;
             if (!controller.signal.aborted)
-                onError(error, episode);
+                report(error);
             outcome = {
                 finalMessage: `the agent failed: ${error instanceof Error ? error.message : String(error)}`.slice(0, 4_000),
             };
@@ -64,7 +85,7 @@ export function createBondedHandler(options) {
         }
         catch (error) {
             if (!failed)
-                onError(error, episode);
+                report(error);
         }
     };
     return async (request, context) => {
@@ -73,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(),
@@ -82,45 +114,51 @@ 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"));
             return json(200, { ok: true, cancelled: controller !== undefined });
         }
-        const episode = toEpisode(message);
-        if (running.has(episode.episodeId))
-            return json(200, { ok: true, episodeId: episode.episodeId, alreadyRunning: true });
+        if (message.world === "brokerage" && !options.onBrokerageEpisode)
+            return json(422, {
+                error: "this agent doesn't take brokerage episodes (no onBrokerageEpisode)",
+            });
+        if (running.has(message.episodeId))
+            return json(200, { ok: true, episodeId: message.episodeId, alreadyRunning: true });
         if (running.size >= maxConcurrent)
             return json(429, { error: `already running ${running.size} episodes` });
         const controller = new AbortController();
-        running.set(episode.episodeId, controller);
-        const work = run(episode, controller);
+        running.set(message.episodeId, controller);
+        const work = message.world === "brokerage"
+            ? run(toBrokerageEpisode(message), controller, (e, c) => options.onBrokerageEpisode(e, c), onBrokerageError)
+            : run(toEpisode(message), controller, (e, c) => options.onEpisode(e, c), onError);
         // Called as a method: Cloudflare's ctx.waitUntil needs its `this`.
         if (context?.waitUntil)
             context.waitUntil(work);
         else
             options.waitUntil?.(work);
-        return json(202, { ok: true, episodeId: episode.episodeId });
+        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 {
+        world: "brokerage",
+        episodeId: message.episodeId,
+        task: message.task,
+        mode: "tools",
+        endpoints: message.endpoints,
+        deadlineMs: message.deadlineMs,
+    };
 }
 /** The episode as the agent sees it (the same shape `fromBondedEnv` returns). */
 function toEpisode(message) {

package/dist/episode.d.ts

@@ -41,6 +41,7 @@ export interface BondedEpisode {
  * next to `episodeEnv` that writes them, so the runner, the gateway and the SDK can't drift.
  */
 export declare const bondedEpisodeEnv: import("zod").ZodObject<{
+    BONDED_WORLD: import("zod").ZodOptional<import("zod").ZodLiteral<"vault">>;
     BONDED_EPISODE_ID: import("zod").ZodString;
     BONDED_MODE: import("zod").ZodEnum<{
         tools: "tools";
@@ -57,6 +58,7 @@ export declare const bondedEpisodeEnv: import("zod").ZodObject<{
             approvalAllowlist: import("zod").ZodArray<import("zod").ZodPipe<import("zod").ZodString, import("zod").ZodTransform<`0x${string}`, string>>>;
         }, import("zod/v4/core").$strip>>;
         maxSteps: import("zod").ZodNumber;
+        tools: import("zod").ZodOptional<import("zod").ZodReadonly<import("zod").ZodArray<import("zod").ZodString>>>;
     }, import("zod/v4/core").$strip>>;
     BONDED_MCP_URL: import("zod").ZodURL;
     BONDED_TOOLS_URL: import("zod").ZodURL;
@@ -84,6 +86,11 @@ export declare const bondedEpisodeEnv: import("zod").ZodObject<{
  * ```ts
  * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
  * ```
+ *
+ * True in every world, so an agent under test never falls through to its production tools. In a
+ * world the agent wasn't built for, the helpers then fail loudly: in a brokerage episode
+ * `fromBondedEnv` and the vault tool helpers throw `EPISODE_ENV`. `bondedEpisodeWorld()` says
+ * which world it is.
  */
 export declare function isBondedEpisode(env?: Record<string, string | undefined>): boolean;
 /**
@@ -105,4 +112,48 @@ export declare function fromBondedEnv(env?: Record<string, string | undefined>):
  * or when the key is held by a TEE (no session key): use your own signer there.
  */
 export declare function episodeVault(episode: BondedEpisode): BondedVault;
+/**
+ * A brokerage episode: the agent manages a simulated brokerage account (stocks, filings, orders,
+ * cash withdrawals) through the episode's tools. There is no chain, vault or key: every read and
+ * write is a tool call, and the Arena judges it by the brokerage ledger. Needs runner protocol 2
+ * (`@bondedhq/runner` 0.1.4 or later), started with `--world brokerage`.
+ */
+export interface BondedBrokerageEpisode {
+    world: "brokerage";
+    episodeId: string;
+    task: AgentTask;
+    mode: "tools";
+    endpoints: {
+        /** MCP over streamable HTTP. */
+        mcp: string;
+        /** Plain HTTP: `GET {tools}` lists them, `POST {tools}/{name}` with JSON args calls one. */
+        tools: string;
+        openapi: string;
+        /** `POST` here when finished (`{ finalMessage? }`). */
+        done: string;
+    };
+    /** How long the agent has, in milliseconds from when it starts. */
+    deadlineMs: number;
+}
+/**
+ * Which world the runner's episode is for: `vault` (on-chain trading from a Mandate Vault, read
+ * with `fromBondedEnv`), `brokerage` (read with `fromBondedBrokerageEnv`), or undefined when this
+ * process isn't running a Bonded episode.
+ *
+ * ```ts
+ * const world = bondedEpisodeWorld();
+ * const tools =
+ *   world === "brokerage"
+ *     ? await myBrokerageTools(fromBondedBrokerageEnv())
+ *     : world === "vault"
+ *       ? await bondedLangChainTools()
+ *       : productionTools;
+ * ```
+ */
+export declare function bondedEpisodeWorld(env?: Record<string, string | undefined>): "vault" | "brokerage" | undefined;
+/**
+ * Reads a brokerage episode the Bonded runner set up from the environment. Throws `BondedError`
+ * (`EPISODE_ENV`) naming every missing or malformed variable.
+ */
+export declare function fromBondedBrokerageEnv(env?: Record<string, string | undefined>): BondedBrokerageEpisode;
 //# sourceMappingURL=episode.d.ts.map

package/dist/episode.js

@@ -1,4 +1,4 @@
-import { EpisodeEnv, parseEpisodeEnv } from "@bondedhq/shared";
+import { EpisodeEnv, parseBrokerageEpisodeEnv, parseEpisodeEnv, } from "@bondedhq/shared";
 import { defineChain } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { BondedError } from "./errors.js";
@@ -15,9 +15,14 @@ export const bondedEpisodeEnv = EpisodeEnv;
  * ```ts
  * const tools = isBondedEpisode() ? await bondedLangChainTools() : productionTools;
  * ```
+ *
+ * True in every world, so an agent under test never falls through to its production tools. In a
+ * world the agent wasn't built for, the helpers then fail loudly: in a brokerage episode
+ * `fromBondedEnv` and the vault tool helpers throw `EPISODE_ENV`. `bondedEpisodeWorld()` says
+ * which world it is.
  */
 export function isBondedEpisode(env = typeof process === "undefined" ? {} : process.env) {
-    return parseEpisodeEnv(env).ok;
+    return bondedEpisodeWorld(env) !== undefined;
 }
 /**
  * Reads the episode the Bonded runner set up from the environment. Throws `BondedError`
@@ -62,4 +67,37 @@ export function episodeVault(episode) {
         router: episode.contracts.exchange,
     });
 }
+/**
+ * Which world the runner's episode is for: `vault` (on-chain trading from a Mandate Vault, read
+ * with `fromBondedEnv`), `brokerage` (read with `fromBondedBrokerageEnv`), or undefined when this
+ * process isn't running a Bonded episode.
+ *
+ * ```ts
+ * const world = bondedEpisodeWorld();
+ * const tools =
+ *   world === "brokerage"
+ *     ? await myBrokerageTools(fromBondedBrokerageEnv())
+ *     : world === "vault"
+ *       ? await bondedLangChainTools()
+ *       : productionTools;
+ * ```
+ */
+export function bondedEpisodeWorld(env = typeof process === "undefined" ? {} : process.env) {
+    // Fails closed: once the runner has named the brokerage world for an episode, that is the
+    // answer even if another variable is malformed. `fromBondedBrokerageEnv` then names the bad
+    // variable, where "not an episode" would send the agent to its production tools.
+    if (env.BONDED_WORLD === "brokerage" && env.BONDED_EPISODE_ID?.trim())
+        return "brokerage";
+    return parseEpisodeEnv(env).ok ? "vault" : undefined;
+}
+/**
+ * Reads a brokerage episode the Bonded runner set up from the environment. Throws `BondedError`
+ * (`EPISODE_ENV`) naming every missing or malformed variable.
+ */
+export function fromBondedBrokerageEnv(env = process.env) {
+    const parsed = parseBrokerageEpisodeEnv(env);
+    if (!parsed.ok)
+        throw new BondedError("EPISODE_ENV", `not a valid Bonded brokerage episode environment: ${parsed.problems.join("; ")}`);
+    return parsed.episode;
+}
 //# sourceMappingURL=episode.js.map

package/dist/index.d.ts

@@ -24,6 +24,6 @@ export { BONDED_API_URL, PaymentGate, paymentGate, type GateAnswer, type GateChe
 export { guardPayments, guardVendorChanges, isPaymentRefusal, PaymentGuard, paymentGuard, type GuardPaymentsOptions, type GuardVendorChangesOptions, type PaymentBreach, type PaymentGuardOptions, type PaymentGuardState, type PaymentMandate, type PaymentSource, type PaymentVendor, type PaymentVerdict, } from "./payments.js";
 export { describePaymentMandate, GATE_RULE_WORDS, GATE_RULES, PAYMENT_RULE_WORDS, PAYMENT_RULES, type GateRule, type PaidPayment, type PayableInvoice, type PayableRefund, type PaymentAttempt, type PaymentRule, type VerifiedChange, } from "@bondedhq/shared";
 export { BONDED_VAULT_TOOLS, bondedVaultFromEnv, bondedVaultTools, type BondedVaultTool, type BondedVaultToolName, type BondedVaultToolsOptions, } from "./vault-tools.js";
-export { bondedEpisodeEnv, episodeVault, fromBondedEnv, isBondedEpisode, type BondedEpisode, } from "./episode.js";
+export { bondedEpisodeEnv, bondedEpisodeWorld, episodeVault, fromBondedBrokerageEnv, fromBondedEnv, isBondedEpisode, type BondedBrokerageEpisode, type BondedEpisode, } from "./episode.js";
 export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, type AllowanceCheck, type AllowanceFinding, type TokenRef, installMandateModule, type InstallMandateModuleInput, type ModuleAccountType, type ModuleInstallPlan, } from "./module.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -23,6 +23,6 @@ export { BONDED_API_URL, PaymentGate, paymentGate, } from "./gate.js";
 export { guardPayments, guardVendorChanges, isPaymentRefusal, PaymentGuard, paymentGuard, } from "./payments.js";
 export { describePaymentMandate, GATE_RULE_WORDS, GATE_RULES, PAYMENT_RULE_WORDS, PAYMENT_RULES, } from "@bondedhq/shared";
 export { BONDED_VAULT_TOOLS, bondedVaultFromEnv, bondedVaultTools, } from "./vault-tools.js";
-export { bondedEpisodeEnv, episodeVault, fromBondedEnv, isBondedEpisode, } from "./episode.js";
+export { bondedEpisodeEnv, bondedEpisodeWorld, episodeVault, fromBondedBrokerageEnv, fromBondedEnv, isBondedEpisode, } from "./episode.js";
 export { checkUnprotectedAllowances, deploymentTokens, unprotectedAllowancesWarning, installMandateModule, } from "./module.js";
 //# sourceMappingURL=index.js.map

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.6",
+  "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.5"
+    "@bondedhq/shared": "^0.2.0"
   },
   "devDependencies": {
     "@coinbase/agentkit": "0.10.4",