a2a-exposed 0.8.18 → 0.8.19

package/lib/deploy.mjs

@@ -25,7 +25,7 @@ export const CLAUDE_CODE_NOTE = [
 	"  Then open the new session from the routine's runs and confirm it ran the inbox command without errors.",
 ].join("\n");
 
-const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "generic"];
+const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "openbot", "generic"];
 // WAKE_ACCESS_*: Cloudflare Access service token for a wake URL behind Access (set by `tunnel create`, or exported
 // by hand for your own Access-protected endpoint)
 export const WAKE_SECRETS = ["WAKE_WEBHOOK_URL", "WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET", "WAKE_ACCESS_CLIENT_ID", "WAKE_ACCESS_CLIENT_SECRET"];

package/lib/main.mjs

@@ -92,9 +92,11 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
   wake set [--preset P] [--agent-id A] [--key-header H] [--key-prefix X] [--body-template JSON]
            [--cli-command CMD] [--debounce S] [--max-per-hour N]
                                 save wake settings, upload wake secrets from env, and redeploy (one step)
+                                openbot: human supplies WAKE_HMAC_SECRET via protected env/secret storage, never chat or argv
                                 --max-per-hour  hourly cap; 0 or unset is unlimited, except Claude Code,
                                                which defaults to 25 when this is unset
   wake preview                  rendered wake request (a credential is Bearer •••• or ••••, none of the secret)
+                                openbot includes a sample delivery ID and canonical signing-input description
                                 + sha256 fingerprints of the uploaded URL/key/HMAC secret; compared with
                                 local env values when WAKE_WEBHOOK_URL, WAKE_WEBHOOK_KEY, and WAKE_HMAC_SECRET
                                 are exported in this shell. match: the exported value is the one on the Worker.
@@ -116,7 +118,7 @@ anywhere on the account: the A2A endpoint itself can be on workers.dev or a cust
                                 creates nothing when you run it again. A partial tunnel stops and asks for tunnel rm.
                                 The tunnel, the Access app, and the service token are named "a2a-exposed wake <worker>".
                                 The DNS host is wake-<word>-<word>-<4 hex>.<zone> unless --tunnel-hostname is set.
-                                Export WAKE_WEBHOOK_KEY (hermes: WAKE_HMAC_SECRET) so tunnel create uploads it.
+                                Export WAKE_WEBHOOK_KEY (hermes/openbot: WAKE_HMAC_SECRET) so tunnel create uploads it.
                                 The connector machine needs cloudflared installed
                                 (https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/).
                                 Defaults: openclaw-* -> http://127.0.0.1:18789 /hooks/wake|agent, hermes -> :8644
@@ -267,7 +269,7 @@ Feedback
                                 polling), and hosted or self-hosted. --connection overrides
                                 that detection. Remove tokens from the message and from --logs.
 
-Presets: grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | generic
+Presets: grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | generic
          Which clients are tested end to end is in the client table:
          https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md#clients
 Config: ${C.CONFIG_FILE}  (override dir with --config-dir DIR or A2A_CONFIG_DIR; env vars override file values)

package/lib/status.mjs

@@ -171,8 +171,8 @@ function nextStepCore(s) {
 	if (t && !t.complete) return fail(`a previous \`tunnel create\` did not finish: run \`${CLI} tunnel rm\`, then \`${CLI} tunnel create\``);
 	if (t && !t.tokenFileOk)
 		return fail(`the tunnel's connector token file (${t.tokenFile}) is missing or empty: run \`${CLI} tunnel create\` again (it downloads the token again; nothing new is created)`);
-	const agentSecret = s.wake.preset === "hermes" ? "WAKE_HMAC_SECRET" : "WAKE_WEBHOOK_KEY";
-	const needsAgentSecret = LOCAL_PRESETS.includes(s.wake.preset) && !s.wake.hasKey && !s.wake.hasHmacSecret;
+	const agentSecret = ["hermes", "openbot"].includes(s.wake.preset) ? "WAKE_HMAC_SECRET" : "WAKE_WEBHOOK_KEY";
+	const needsAgentSecret = s.wake.preset === "openbot" ? !s.wake.hasHmacSecret : LOCAL_PRESETS.includes(s.wake.preset) && !s.wake.hasKey && !s.wake.hasHmacSecret;
 	const now = typeof s.now === "number" ? s.now : Date.now();
 	if (t && !(s.wake.hasAccessServiceToken && t.workerUrlMatches)) {
 		if (secretsPropagating(t, now) && (t.connections === 0 || t.connections == null))
@@ -184,7 +184,7 @@ function nextStepCore(s) {
 	if (t && t.connections === 0)
 		return fail(`the tunnel has ${t.state === "inactive" ? "never connected" : "no running connector"}: on the agent's machine run \`cloudflared tunnel run --token-file ${t.tokenFile}\` (outbound port 7844 must be open), then \`${CLI} wake test\``);
 	if (s.wake.configured && needsAgentSecret)
-		return fail(`the Worker sends no webhook auth, so the ${s.wake.preset} webhook will reject wakes: export ${agentSecret} (${s.wake.preset === "hermes" ? "the route secret" : "the hooks token"}), then run \`${CLI} ${t ? "tunnel create" : "wake set"}\``);
+		return fail(`the Worker sends no webhook auth, so the ${s.wake.preset} webhook will reject wakes: export ${agentSecret} (${["hermes", "openbot"].includes(s.wake.preset) ? "the route secret" : "the hooks token"}), then run \`${CLI} ${t ? "tunnel create" : "wake set"}\``);
 	// not broken, but peers can't pair until the human sets the approval password
 	const also = [];
 	if (s.pairing && s.pairing.mode === "human" && !s.pairing.passwordSet)
@@ -195,7 +195,7 @@ function nextStepCore(s) {
 	if (!s.wake.configured) {
 		const poll = "the agent must check the A2A endpoint on a schedule (Hermes and OpenClaw have copy-paste commands in the setup references)";
 		if (s.wake.preset && !LOCAL_PRESETS.includes(s.wake.preset) && s.wake.preset !== "generic")
-			return done2(`no wake webhook: export WAKE_WEBHOOK_URL and WAKE_WEBHOOK_KEY, then run \`${CLI} wake set --preset ${s.wake.preset}\`; or ${poll}`);
+			return done2(`no wake webhook: export WAKE_WEBHOOK_URL and ${agentSecret}, then run \`${CLI} wake set --preset ${s.wake.preset}\`; or ${poll}`);
 		const z = s.zones;
 		const tunnel = !z ? `a local-only webhook can use \`${CLI} tunnel create\` (needs a zone on the account)`
 			: !z.length ? "the account has no domain (zone), so the secure tunnel is not available"

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "a2a-exposed",
-	"version": "0.8.18",
+	"version": "0.8.19",
 	"description": "Give any AI agent a public A2A (Agent2Agent) endpoint: a Cloudflare Worker, a wake webhook, or scheduled checks",
 	"type": "module",
 	"bin": {

package/worker/cloudflare.config.ts

@@ -28,7 +28,7 @@ const plain: Record<string, string> = {
 	PROVIDER_ORGANIZATION: v("A2A_PROVIDER_ORGANIZATION"),
 	PROVIDER_URL: v("A2A_PROVIDER_URL"),
 	DOCUMENTATION_URL: v("A2A_DOCUMENTATION_URL"),
-	WAKE_PRESET: v("WAKE_PRESET") || "generic", // grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | generic
+	WAKE_PRESET: v("WAKE_PRESET") || "generic", // grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | generic
 	WAKE_AGENT_ID: v("WAKE_AGENT_ID"), // openclaw presets (default "main")
 	WAKE_KEY_HEADER: v("WAKE_KEY_HEADER"), // generic preset (default "authorization")
 	WAKE_KEY_PREFIX: e.WAKE_KEY_PREFIX ?? "", // generic preset; unset = "Bearer "

package/worker/scripts/stamp-version.mjs

@@ -1,4 +1,4 @@
-// Write worker/src/version.ts from cli/package.json. Publish runs `npm version` in cli/
+// Write worker/src/version.ts from cli/package.json. Release preparation runs `npm run version:set`
 // before the Worker tests and build, and prepack bundles this tree into the npm package.
 import fs from "node:fs";
 import path from "node:path";

package/worker/src/index.ts

@@ -1619,6 +1619,7 @@ async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionCont
 			fingerprints: { url: await A.fingerprint(ctx.WAKE_WEBHOOK_URL), key: await A.fingerprint(ctx.WAKE_WEBHOOK_KEY),
 				hmacSecret: await A.fingerprint(ctx.WAKE_HMAC_SECRET),
 				accessClientId: await A.fingerprint(ctx.WAKE_ACCESS_CLIENT_ID), accessClientSecret: await A.fingerprint(ctx.WAKE_ACCESS_CLIENT_SECRET) },
+			...(preset(ctx) === "openbot" ? { signingInput: "<timestamp>.<delivery-id>.<exact-body-bytes>" } : {}),
 			request: req ? redact(req) : null });
 	}
 	if (seg[0] === "wake" && seg[1] === "test" && m === "POST") {

package/worker/src/version.ts

@@ -1,2 +1,2 @@
 /** Inbox build. Keep this equal to `version` in cli/package.json. */
-export const VERSION = "0.8.18";
+export const VERSION = "0.8.19";

package/worker/src/wake.ts

@@ -46,7 +46,7 @@ export type WakeConfig = {
 
 export type WakeRequest = { url: string; method: "POST"; headers: Record<string, string>; body: string };
 
-export const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "generic"] as const;
+export const PRESETS = ["grok-bot", "claude-code", "openclaw-wake", "openclaw-agent", "hermes", "openbot", "generic"] as const;
 
 /** Default debounce window per preset (seconds), used when WAKE_DEBOUNCE_SECONDS is unset. */
 export function defaultDebounceSeconds(preset: string): number {
@@ -207,6 +207,16 @@ export async function renderWake(cfg: WakeConfig, ev: WakeEvent, opts: { nowMs?:
 			// `name` is the hook name OpenClaw filters match. It stays "A2A inbox". The wake text itself starts with "A2A endpoint:".
 			body = JSON.stringify({ message: wakeSummary(ev, cli), name: "A2A inbox", agentId: cfg.agentId || "main", sessionMode: "isolated", deliver: false });
 			break;
+		case "openbot": {
+			const ts = String(Math.floor(nowMs / 1000));
+			headers["x-openbot-timestamp"] = ts;
+			headers["x-openbot-delivery-id"] = requestId;
+			// Serialize once: the signature covers exactly the UTF-8 bytes sent to OpenBot.
+			body = JSON.stringify({ type: "a2a_wake", occurredAt: new Date(nowMs).toISOString(), data: wakePayload(ev, cli) });
+			if (cfg.hmacSecret)
+				headers["x-openbot-signature"] = `sha256=${await hmacSha256Hex(cfg.hmacSecret, `${ts}.${requestId}.${body}`)}`;
+			break;
+		}
 		case "hermes":
 			headers["x-request-id"] = requestId;
 			body = JSON.stringify(wakePayload(ev, cli));
@@ -268,7 +278,7 @@ export function cloudflareErrorHint(status: number, body: string, opts?: { tunne
 
 /** Headers a wake preview may show in full. Every other header carries a credential, whatever its name. */
 export const PREVIEW_PLAIN_HEADERS = new Set([
-	"content-type", "user-agent", "x-request-id", "idempotency-key", "anthropic-version", "x-webhook-timestamp",
+	"content-type", "user-agent", "x-request-id", "idempotency-key", "anthropic-version", "x-webhook-timestamp", "x-openbot-timestamp", "x-openbot-delivery-id",
 ]);
 
 export function previewHeaderPlain(name: string): boolean {

package/worker/test/wake-retry.test.ts

@@ -72,3 +72,31 @@ test("a 429 is due at Retry-After when the debounce is longer", async (t) => {
 	const at = await nextCronAt(resolveTenant(env), Date.now());
 	assert.ok(at != null && at >= before + 25_000 && at <= before + 35_000, `alarm ${at} is Retry-After, not the 120s debounce`);
 });
+
+test("OpenBot preview masks signing credentials and wake test accepts HTTP 202", async (t) => {
+	const env: any = { DB: d1(new URL("../migrations/", import.meta.url)), PUBLIC_URL: BASE, OWNER_TOKEN: "owner-secret",
+		WAKE_PRESET: "openbot", WAKE_WEBHOOK_URL: "https://hooks.example.com/a2a", WAKE_HMAC_SECRET: "dummy-openbot-secret" };
+	const pending: Promise<unknown>[] = [];
+	const call = (method: string, path: string) => worker.fetch(new Request(BASE + path, { method, headers: { authorization: "Bearer owner-secret" } }) as any,
+		env, { waitUntil: (p: Promise<unknown>) => pending.push(p), passThroughOnException() {} } as any);
+	const preview = await (await call("GET", "/owner/wake/preview")).json() as any;
+	assert.equal(preview.preset, "openbot");
+	assert.equal(preview.signingInput, "<timestamp>.<delivery-id>.<exact-body-bytes>");
+	assert.equal(preview.request.headers["x-openbot-delivery-id"], "preview");
+	assert.equal(preview.request.headers["x-openbot-signature"], "••••");
+	assert.ok(!JSON.stringify(preview).includes(env.WAKE_HMAC_SECRET));
+	const original = globalThis.fetch;
+	let sent = false;
+	globalThis.fetch = (async (_url: any, init: any) => {
+		sent = true;
+		assert.equal(JSON.parse(init.body).type, "a2a_wake");
+		assert.match(init.headers["x-openbot-signature"], /^sha256=[0-9a-f]{64}$/);
+		assert.ok(init.headers["x-openbot-delivery-id"]);
+		return new Response("{}", { status: 202 });
+	}) as any;
+	t.after(() => { globalThis.fetch = original; });
+	const result = await (await call("POST", "/owner/wake/test")).json() as any;
+	assert.equal(result.status, 202);
+	assert.equal(sent, true);
+	await Promise.allSettled(pending);
+});

package/worker/test/wake.test.ts

@@ -2,7 +2,7 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { createHmac } from "node:crypto";
-import { renderWake, renderTemplate, wakeSummary, redact, addAccessHeaders, cloudflareErrorHint, PRESETS, type WakeEvent } from "../src/wake.ts";
+import { renderWake, renderTemplate, wakeSummary, redact, addAccessHeaders, cloudflareErrorHint, PRESETS, wakePayload, type WakeEvent } from "../src/wake.ts";
 
 const ev: WakeEvent = {
 	contextId: "ctx-1", taskId: "t-2", taskIds: ["t-1", "t-2"], from: "peer-a",
@@ -144,6 +144,7 @@ test("Access service-token headers are added for every preset, next to the prese
 		assert.equal(r.headers["CF-Access-Client-Id"], "abc123.access", preset);
 		assert.equal(r.headers["CF-Access-Client-Secret"], "s3cr3t-value-0123456789", preset);
 		if (preset === "hermes") assert.ok(r.headers["X-Webhook-Signature-V2"], "hermes keeps its HMAC");
+		else if (preset === "openbot") assert.ok(r.headers["x-openbot-signature"], "openbot keeps its HMAC");
 		else assert.ok(r.headers["authorization"], `${preset} keeps its bearer`);
 	}
 });
@@ -180,3 +181,24 @@ test("cloudflareErrorHint explains tunnel / Access failures", () => {
 	assert.match(cloudflareErrorHint(530, "error code: 1016", { tunnel: true }), /tunnel hostname has no matching DNS record/);
 });
 
+
+// Fixed vector independently generated with Python hashlib/hmac.
+test("openbot: envelope and signature cover the exact body and delivery ID", async () => {
+	assert.ok(PRESETS.includes("openbot"));
+	const req = (await renderWake({ preset: "openbot", url: "https://hooks.example.com/a2a", hmacSecret: "openbot-test-secret", key: "unused-key" }, ev,
+		{ nowMs: 1760000000000, requestId: "delivery-1" }))!;
+	assert.deepEqual(JSON.parse(req.body), { type: "a2a_wake", occurredAt: "2025-10-09T08:53:20.000Z", data: wakePayload(ev, "npx -y a2a-exposed@latest") });
+	assert.equal(req.headers["x-openbot-timestamp"], "1760000000");
+	assert.equal(req.headers["x-openbot-delivery-id"], "delivery-1");
+	assert.equal(req.headers["x-openbot-signature"], "sha256=8d28056bd4d5f700fd49865a0cc240bd769462d6e75aac4aa15fc7051c3ecc26");
+	assert.equal(req.headers["authorization"], undefined);
+	assert.equal(req.headers["X-Webhook-Signature-V2"], undefined);
+	const preview = redact(req);
+	assert.equal(preview.headers["x-openbot-delivery-id"], "delivery-1");
+	assert.equal(preview.headers["x-openbot-timestamp"], "1760000000");
+	assert.equal(preview.headers["x-openbot-signature"], "••••");
+	assert.ok(!JSON.stringify(preview).includes("openbot-test-secret"));
+	const unicode = (await renderWake({ preset: "openbot", url: req.url, hmacSecret: "s" }, { ...ev, preview: '雪 "quoted"\ntext' },
+		{ nowMs: 1760000000000, requestId: "delivery-2" }))!;
+	assert.equal(unicode.headers["x-openbot-signature"], "sha256=" + createHmac("sha256", "s").update(`1760000000.delivery-2.${unicode.body}`).digest("hex"));
+});