a2a-exposed 0.7.10 → 0.7.11

package/lib/main.mjs

@@ -126,7 +126,11 @@ Pairing (OAuth 2.0 device flow, RFC 8628: agents connect without pasting tokens
                           peer then swaps the old token for the new one under the same label (older peers
                           keep the old token until their owner revokes it). --card-url: the card to name in
                           the request (default: this deployment's); a *.ts.net / LAN card is sent as
-                          informational (flagged "not publicly reachable"), a non-https one is left out
+                          informational (flagged "not publicly reachable"), a non-https one is left out.
+                          The name sent is the card named in the request (--card-url, otherwise this
+                          deployment's). --name overrides it. If that card can't be read, the name is the
+                          configured agent name, the worker name, or the public host's first label. The
+                          other inbox labels the token from that name and adds -2, -3, … when it is taken
   pair set-password --web [--ttl MIN] [--json]
                           one-time link (default 15 min, single use) where your human sets or changes the
                           approval password on a web page. Send it to them privately; never open or fill it

package/lib/pair.mjs

@@ -193,6 +193,39 @@ export function deviceEndpointsFromCard(card) {
 const slug = (s) => String(s || "").replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32).replace(/-+$/, "").toLowerCase();
 const sleep = (s) => new Promise((r) => setTimeout(r, s * 1000 * Number(process.env.A2A_POLL_SCALE || 1)));
 
+/** First DNS label of this deployment's public URL, or "" for loopback and an unusable host. */
+export function hostAlias(ownUrl) {
+	if (!ownUrl) return "";
+	try {
+		const host = new URL(ownUrl).hostname;
+		if (host === "localhost" || host === "127.0.0.1" || host === "[::1]") return "";
+		return slug(host.split(".")[0]);
+	} catch { return ""; }
+}
+
+/**
+ * client_name for a pairing request. An explicit `--name` wins, then the card named in the request
+ * (`--card-url`, otherwise this deployment's card), then the configured agent name, then the local
+ * alias (worker name, else the public host's first label).
+ */
+export function pairingClientName({ explicit = "", cardName = "", agentName = "", workerName = "", ownUrl = "" } = {}) {
+	const text = (v) => String(v || "").replace(/\s+/g, " ").trim().slice(0, 64);
+	for (const v of [explicit, cardName, agentName, workerName, hostAlias(ownUrl)]) {
+		const t = text(v);
+		if (t) return t;
+	}
+	return "a2a-exposed agent";
+}
+
+/** Name on a card URL, or "" when the card can't be read. */
+async function readCardName(url) {
+	if (!url) return "";
+	try {
+		const { status, data } = await httpJson(url, { timeout: 3000 });
+		return status === 200 && data && typeof data.name === "string" ? data.name : "";
+	} catch { return ""; }
+}
+
 async function postForm(url, params, bearer = null) {
 	let r;
 	const headers = { "content-type": "application/x-www-form-urlencoded", accept: "application/json" };
@@ -315,16 +348,19 @@ A different agent at the same URL? Pass another --alias.`);
 		`Resuming the pairing request to ${peerName} (code ${st.userCode}, link ${st.verificationUriComplete}).`);
 	else {
 		const own = baseUrl();
-		const params = { client_name: o.name || C.get("A2A_AGENT_NAME") || C.get("A2A_WORKER_NAME") || "a2a-exposed agent", client_id: C.get("A2A_WORKER_NAME") || alias };
-		const card = cardUrlToSend(o["card-url"], own, o.json);
-		if (card) params.agent_card_url = card;
+		const sentCard = cardUrlToSend(o["card-url"], own, o.json);
+		// The name is the card this request actually names. --card-url (a Tailnet card, before a public
+		// deployment exists) wins. With no override, read this deployment's card, including an http one.
+		const nameUrl = sentCard || (!o["card-url"] && /^https?:\/\//.test(own || "") ? `${own.replace(/\/$/, "")}/.well-known/agent-card.json` : "");
+		const params = { client_name: pairingClientName({ explicit: o.name, cardName: await readCardName(nameUrl), agentName: C.get("A2A_AGENT_NAME"), workerName: C.get("A2A_WORKER_NAME"), ownUrl: own }), client_id: C.get("A2A_WORKER_NAME") || alias };
+		if (sentCard) params.agent_card_url = sentCard;
 		// replacing: present the old token, so a peer that supports it swaps the token under the same label (no orphan)
 		const r = await postForm(ep.device, params, replace && oldToken ? oldToken : null);
 		if (r.status !== 200 || !r.data.device_code || !r.data.user_code) {
 			const why = r.data.error_description || r.data.error || `HTTP ${r.status}`;
-			const privateCard = !!card && (() => { try { return isPrivateHost(new URL(card).hostname); } catch { return false; } })();
+			const privateCard = !!sentCard && (() => { try { return isPrivateHost(new URL(sentCard).hostname); } catch { return false; } })();
 			die(r.status === 429 ? `${peerName} is not accepting more pairing requests right now: ${why}` : r.status === 404 ? `${peerName} has device-flow pairing disabled (${why}); ask its owner for a token`
-				: `pairing request to ${peerName} failed: ${why}${privateCard && r.status === 400 ? `. The card URL sent (${new URL(card).host}) is not publicly reachable, and inboxes may accept only public https cards: retry with --card-url set to a public card, or expose your agent through a public façade first (setup skill: "Already have A2A on a Tailnet or LAN")` : ""}`);
+				: `pairing request to ${peerName} failed: ${why}${privateCard && r.status === 400 ? `. The card URL sent (${new URL(sentCard).host}) is not publicly reachable, and inboxes may accept only public https cards: retry with --card-url set to a public card, or expose your agent through a public façade first (setup skill: "Already have A2A on a Tailnet or LAN")` : ""}`);
 		}
 		st = { base, alias, device: ep.device, token: ep.token, deviceCode: r.data.device_code, userCode: r.data.user_code,
 			verificationUri: r.data.verification_uri || "", verificationUriComplete: r.data.verification_uri_complete || r.data.verification_uri || "",

package/package.json

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

package/worker/src/pairing.ts

@@ -1,6 +1,7 @@
 // Device-flow pairing (OAuth 2.0 Device Authorization Grant, RFC 8628): pure helpers (Web Crypto only), so they run
 // in Workers and in Node's test runner. The HTTP handlers live in index.ts.
 import { isPrivateHost } from "./a2a.ts";
+import { pageStyle } from "./theme.ts";
 
 /** How every hint tells an agent to run the CLI: npx, latest release, no global install (agent sandboxes block global
  *  installs as untrusted code). WAKE_CLI_COMMAND overrides it for the owner's own wake hints only. */
@@ -223,17 +224,11 @@ export function devicePage(m: PageModel, nonce: string): string {
 	return pageShell(`Connect an agent to ${m.agentName}`, nonce, `${notice}${details}${form}${oidcForm}${ask}`);
 }
 
-const STYLE = `body{font:16px/1.5 system-ui,sans-serif;max-width:34rem;margin:2rem auto;padding:0 1rem;color:#111;background:#fafafa}
-h1{font-size:1.3rem}table{border-collapse:collapse;width:100%;margin:1rem 0}th,td{text-align:left;padding:.35rem .5rem;border-bottom:1px solid #ddd;vertical-align:top;word-break:break-all}th{width:40%;font-weight:600;word-break:normal}
-label{display:block;font-weight:600;margin:.8rem 0 .3rem}input{font:inherit;width:100%;box-sizing:border-box;padding:.5rem;border:1px solid #888;border-radius:4px}
-.b{display:flex;gap:.6rem;margin-top:1rem}button{font:inherit;padding:.5rem 1.2rem;border:0;border-radius:4px;background:#1a5fb4;color:#fff;cursor:pointer}button.d{background:#a51d2d}
-h2{font-size:1.05rem;margin-top:1.5rem}ul{padding-left:1.2rem}a{color:#1a5fb4}.n{padding:.6rem .8rem;border-radius:4px}.ok{background:#e6f4ea}.error{background:#fce8e6}.info{background:#e8f0fe}.w{font-size:.9rem;color:#444}code{background:#eee;padding:0 .2rem}`;
-
 /** The shared page frame: no scripts, no external assets, one nonce'd style block. `title` is escaped here. */
 export function pageShell(title: string, nonce: string, body: string): string {
 	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="referrer" content="no-referrer">
 <title>${esc(title)}</title><style nonce="${nonce}">
-${STYLE}
+${pageStyle()}
 </style></head><body><h1>${esc(title)}</h1>${body}</body></html>`;
 }
 

package/worker/src/theme.ts

@@ -0,0 +1,14 @@
+/**
+ * Neutral CSS for the inbox HTML pages (`/`, `/device`, `/device/setup`, MCP consent).
+ * It is inlined in one nonce'd `<style>` block. There is no external stylesheet.
+ * `WORKER_THEME` (a CSS file path) replaces this module at `cf build`. See `theme-build.mjs`.
+ */
+export const PAGE_STYLE = `body{font:16px/1.5 system-ui,sans-serif;max-width:34rem;margin:2rem auto;padding:0 1rem;color:#111;background:#fafafa}
+h1{font-size:1.3rem}table{border-collapse:collapse;width:100%;margin:1rem 0}th,td{text-align:left;padding:.35rem .5rem;border-bottom:1px solid #ddd;vertical-align:top;word-break:break-all}th{width:40%;font-weight:600;word-break:normal}
+label{display:block;font-weight:600;margin:.8rem 0 .3rem}input{font:inherit;width:100%;box-sizing:border-box;padding:.5rem;border:1px solid #888;border-radius:4px}
+.b{display:flex;gap:.6rem;margin-top:1rem}button{font:inherit;padding:.5rem 1.2rem;border:0;border-radius:4px;background:#1a5fb4;color:#fff;cursor:pointer}button.d{background:#a51d2d}
+h2{font-size:1.05rem;margin-top:1.5rem}ul{padding-left:1.2rem}a{color:#1a5fb4}.n{padding:.6rem .8rem;border-radius:4px}.ok{background:#e6f4ea}.error{background:#fce8e6}.info{background:#e8f0fe}.w{font-size:.9rem;color:#444}code{background:#eee;padding:0 .2rem}`;
+
+export function pageStyle(): string {
+	return PAGE_STYLE;
+}

package/worker/test/pairing.test.ts

@@ -288,6 +288,25 @@ test("human approval: pending, slow_down, page approve with the password, single
 	assert.equal((await s.call("POST", "/", { json: { jsonrpc: "2.0", id: 1, method: "GetTask", params: { id: "x" } }, headers: { authorization: `Bearer ${p.data.access_token}` } })).status, 401);
 });
 
+test("a pairing label comes from the client name, a second one is suffixed, and inbox from uses it", async (t) => {
+	const s = setup({ PAIRING_APPROVAL: "agent" }); t.after(s.restore);
+	const first = (await s.start({ client_name: "tester-alpha", client_id: "other-alias" }, "203.0.113.40")).data;
+	const approved = await s.owner("POST", `/owner/pairing/${first.user_code}/approve`);
+	assert.equal(approved.data.label, "tester-alpha");
+	const token = (await s.poll(first.device_code)).data.access_token;
+	const sent = await s.call("POST", "/", {
+		json: { jsonrpc: "2.0", id: 1, method: "SendMessage", params: { message: { role: "ROLE_USER", parts: [{ text: "hello" }] } } },
+		headers: { authorization: `Bearer ${token}`, "a2a-version": "1.0" },
+	});
+	assert.equal(sent.status, 200, JSON.stringify(sent.data));
+	const inbox = await s.owner("GET", "/owner/inbox");
+	assert.equal(inbox.data.length, 1);
+	assert.equal(inbox.data[0].from, "tester-alpha");
+	assert.equal(inbox.data[0].text, "hello");
+	const second = (await s.start({ client_name: "tester-alpha", client_id: "another" }, "203.0.113.41")).data;
+	assert.equal((await s.owner("POST", `/owner/pairing/${second.user_code}/approve`)).data.label, "tester-alpha-2");
+});
+
 test("labels are deduplicated; denied and expired requests; JSON bodies; bad requests", async (t) => {
 	const s = setup({ PAIRING_APPROVAL: "agent" }); t.after(s.restore);
 	await s.owner("POST", "/owner/peers", { label: "barry" });

package/worker/test/theme.test.ts

@@ -0,0 +1,85 @@
+// Neutral inbox CSS, and the build-time WORKER_THEME check. Run: npm test
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { PAGE_STYLE, pageStyle } from "../src/theme.ts";
+import { pageShell } from "../src/pairing.ts";
+import { applyWorkerTheme, assertInlineCss, cssForChecks } from "../theme-build.mjs";
+
+test("the neutral theme is inlined once and loads nothing", () => {
+	assert.equal(pageStyle(), PAGE_STYLE);
+	assert.equal(PAGE_STYLE.includes("background:#fafafa"), true);
+	assert.equal(PAGE_STYLE.includes("background:#1a5fb4"), true);
+	assert.doesNotThrow(() => assertInlineCss(PAGE_STYLE));
+	const html = pageShell("Inbox", "nonce-1", "<p>Hello</p>");
+	assert.equal(html.includes(`<style nonce="nonce-1">\n${PAGE_STYLE}\n</style>`), true);
+	assert.equal((html.match(/<style/g) || []).length, 1);
+	assert.equal(/<link|<script|<img|url\s*\(|@import/i.test(html), false);
+});
+
+test("WORKER_THEME replaces the module only when the CSS stays inline", () => {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "inbox-theme-"));
+	const file = path.join(dir, "theme.css");
+	const css = "@media (max-width: 40rem) { body { background: #fff; color: \\23 222; } }";
+	fs.writeFileSync(file, css);
+	const next = applyWorkerTheme("/work/src/theme.ts", file);
+	assert.match(next || "", /export const PAGE_STYLE = /);
+	assert.match(next || "", /background: #fff/);
+	assert.match(next || "", /\\\\23 222/);
+	assert.equal(applyWorkerTheme("/work/src/theme.ts", undefined), null);
+	assert.equal(applyWorkerTheme("/work/src/index.ts", file), null);
+
+	for (const bad of [
+		"",
+		"body { background: url(https://example.com/a.png); }",
+		"@import 'other.css';",
+		"@font-face { font-family: x; }",
+		"body { background: red; } </style><script>",
+		"body { background: expression(alert(1)); }",
+		"a { color: javascript:alert(1); }",
+		"body{background:u\\72l(https://example.com/a.png)}",
+		"body{background:\\75\\72\\6c(https://example.com/a.png)}",
+		"body{background:u\\000072l(https://example.com/a.png)}",
+		"@\\69mport \"https://example.com/x.css\"",
+		"@\\69 mport \"https://example.com/x.css\"",
+		"@\\69\\6d\\70\\6f\\72\\74 \"https://example.com/x.css\"",
+		"body{background:url/*x*/(https://example.com/a.png)}",
+		"@font\\2d face { font-family: x; }",
+		"a{\"/*\";background:url(https://example.com/a.png);content:\"*/\"}",
+		"a{content:\"foo\\\"bar\";background:url(https://example.com/a.png)}",
+		"a{content:\"foo\\\nbar\";background:url(https://example.com/a.png)}",
+		"a{content:\"url(https://example.com/a.png)\nbackground:url(https://example.com/b.png)}",
+		"body{background-image:image-set(\"https://example.com/p.png\" 1x)}",
+		"body{background-image:image(\"https://example.com/p.png\")}",
+		"body{background-image:-webkit-image-set(\"https://example.com/p.png\" 1x)}",
+		"body{background-image:image-\\73 et(\"https://example.com/p.png\" 1x)}",
+		"body{background-image:\\69mage(\"https://example.com/p.png\")}",
+		"body{background-image:image-set/*x*/(\"https://example.com/p.png\" 1x)}",
+	]) {
+		fs.writeFileSync(file, bad);
+		assert.throws(() => applyWorkerTheme("/work/src/theme.ts", file), /WORKER_THEME was refused/);
+	}
+	for (const ok of [
+		"/* url(https://example.com/a.png) */ body { color: red }",
+		"a { content: \"url(https://example.com/a.png)\" }",
+		"a { content: \"foo\\\nurl(https://example.com/a.png)\" }",
+		"body { color: \\3c }",
+		"body { background-image: linear-gradient(#fff, #000); }",
+		"a { content: \"image-set(https://example.com/p.png)\" }",
+	]) {
+		fs.writeFileSync(file, ok);
+		assert.doesNotThrow(() => applyWorkerTheme("/work/src/theme.ts", file));
+	}
+	assert.throws(() => applyWorkerTheme("/work/src/theme.ts", path.join(dir, "missing.css")), /could not be read/);
+});
+
+test("the resource check decodes escapes and keeps strings and comments closed", () => {
+	assert.match(cssForChecks("u\\72l(https://example.com/a.png)"), /url\(https:\/\/example.com\/a.png\)/);
+	assert.match(cssForChecks("@\\69 mport \"x.css\""), /@import ""/);
+	assert.equal(/url\s*\(/i.test(cssForChecks("/* url(https://example.com/a.png) */ body{color:red}")), false);
+	assert.equal(/url\s*\(/i.test(cssForChecks("a{content:\"url(https://example.com/a.png)\"}")), false);
+	assert.match(cssForChecks("a{\"/*\";background:url(https://example.com/a.png)}"), /url\(https:\/\/example.com\/a.png\)/);
+	assert.match(cssForChecks("color:\\23 222"), /color:#222/);
+});

package/worker/theme-build.mjs

@@ -0,0 +1,162 @@
+// Build-time check for WORKER_THEME. The Worker inlines the result in a nonce'd style block and
+// does not load a stylesheet, font, or image. Unsafe CSS is refused so the build stops.
+import fs from "node:fs";
+import path from "node:path";
+
+const MAX = 16384;
+
+function isHex(char) {
+	return char !== undefined && ((char >= "0" && char <= "9") || (char >= "a" && char <= "f") || (char >= "A" && char <= "F"));
+}
+
+function isCssSpace(char) {
+	return char === " " || char === "\t" || char === "\n" || char === "\r" || char === "\f";
+}
+
+function isNewline(char) {
+	return char === "\n" || char === "\r" || char === "\f";
+}
+
+function consumeNewline(css, i) {
+	if (css[i] === "\r" && css[i + 1] === "\n") return i + 2;
+	return i + 1;
+}
+
+/**
+ * One CSS escape at a backslash. A backslash before a newline is not an escape (`newline`);
+ * the caller decides whether that pair continues a string or stays in the sheet.
+ * @param {string} css
+ * @param {number} i index of the backslash
+ */
+function consumeEscape(css, i) {
+	i++;
+	if (i >= css.length) return { type: "char", char: "\uFFFD", next: i };
+	if (isNewline(css[i])) return { type: "newline", next: i };
+	if (isHex(css[i])) {
+		let hex = "";
+		while (hex.length < 6 && i < css.length && isHex(css[i])) hex += css[i++];
+		if (i < css.length && isCssSpace(css[i])) i = isNewline(css[i]) ? consumeNewline(css, i) : i + 1;
+		const codePoint = Number.parseInt(hex, 16);
+		const surrogate = codePoint >= 0xd800 && codePoint <= 0xdfff;
+		const char = codePoint === 0 || surrogate || codePoint > 0x10ffff ? "\uFFFD" : String.fromCodePoint(codePoint);
+		return { type: "char", char, next: i };
+	}
+	return { type: "char", char: css[i], next: i + 1 };
+}
+
+/**
+ * Stylesheet text with escapes decoded, comments removed, and string contents removed.
+ * Markers are recognized on the raw text, so a string cannot pretend to be a comment,
+ * and a decoded character is not read again as a quote or a comment.
+ * @param {string} css
+ */
+export function cssForChecks(css) {
+	let out = "";
+	let i = 0;
+	/** @type {"normal" | "comment" | "string"} */
+	let mode = "normal";
+	let quote = "";
+	while (i < css.length) {
+		if (mode === "comment") {
+			if (css[i] === "*" && css[i + 1] === "/") {
+				mode = "normal";
+				i += 2;
+			} else i++;
+			continue;
+		}
+		if (mode === "string") {
+			if (css[i] === "\\") {
+				const esc = consumeEscape(css, i);
+				i = esc.type === "newline" ? consumeNewline(css, esc.next) : esc.next;
+				continue;
+			}
+			if (isNewline(css[i])) {
+				mode = "normal";
+				out += "\n";
+				i = consumeNewline(css, i);
+				continue;
+			}
+			if (css[i] === quote) {
+				mode = "normal";
+				out += quote;
+				i++;
+				continue;
+			}
+			i++;
+			continue;
+		}
+		if (css[i] === "/" && css[i + 1] === "*") {
+			out += " ";
+			mode = "comment";
+			i += 2;
+			continue;
+		}
+		if (css[i] === '"' || css[i] === "'") {
+			quote = css[i];
+			out += quote;
+			mode = "string";
+			i++;
+			continue;
+		}
+		if (css[i] === "\\") {
+			const esc = consumeEscape(css, i);
+			if (esc.type === "newline") {
+				out += "\\";
+				i = esc.next;
+				continue;
+			}
+			out += esc.char;
+			i = esc.next;
+			continue;
+		}
+		out += css[i++];
+	}
+	return out;
+}
+
+/** @param {string} css */
+export function assertInlineCss(css) {
+	if (typeof css !== "string") throw new Error("the theme is not text");
+	const text = css.replace(/^\uFEFF/, "");
+	if (!text.trim()) throw new Error("the theme is empty");
+	if (text.length > MAX) throw new Error("the theme is too long");
+	if (/[<>]/.test(text)) throw new Error("the theme has a tag");
+	const parsed = cssForChecks(text);
+	if (/@import\b/i.test(parsed)) throw new Error("the theme imports a stylesheet");
+	if (/@font-face\b/i.test(parsed)) throw new Error("the theme loads a font");
+	if (/url\s*\(/i.test(parsed)) throw new Error("the theme loads a url");
+	// image() and image-set() take a string as an image source, so the address never appears as url().
+	if (/\bimage-set\s*\(/i.test(parsed) || /\bimage\s*\(/i.test(parsed)) throw new Error("the theme loads an image");
+	if (/expression\s*\(/i.test(parsed) || /javascript\s*:/i.test(parsed)) throw new Error("the theme has a script");
+	if (/-moz-binding\s*:/i.test(parsed) || /behavior\s*:/i.test(parsed)) throw new Error("the theme has a binding");
+	return text;
+}
+
+/** Module source with the same exports as `src/theme.ts`. */
+export function themeModule(css) {
+	const safe = assertInlineCss(css);
+	return `export const PAGE_STYLE = ${JSON.stringify(safe)};\nexport function pageStyle(): string {\n\treturn PAGE_STYLE;\n}\n`;
+}
+
+/**
+ * Replacement for `src/theme.ts` when `file` is set. Null leaves the neutral module in place.
+ * @param {string} id
+ * @param {string | undefined} file
+ */
+export function applyWorkerTheme(id, file) {
+	if (!file) return null;
+	const clean = id.split("?")[0].replaceAll("\\", "/");
+	if (!clean.endsWith("/src/theme.ts")) return null;
+	let css;
+	try {
+		css = fs.readFileSync(path.resolve(file), "utf8");
+	} catch {
+		throw new Error("WORKER_THEME could not be read");
+	}
+	try {
+		return themeModule(css);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : "the theme was refused";
+		throw new Error(`WORKER_THEME was refused (${reason})`);
+	}
+}

package/worker/vite.config.ts

@@ -1,6 +1,17 @@
 import { cloudflare } from "@cloudflare/vite-plugin";
 import { defineConfig } from "vite";
+import { applyWorkerTheme } from "./theme-build.mjs";
 
 export default defineConfig({
-	plugins: [cloudflare()],
+	plugins: [
+		{
+			name: "inbox-theme",
+			enforce: "pre",
+			transform(_code, id) {
+				const next = applyWorkerTheme(id, process.env.WORKER_THEME);
+				return next ? { code: next, map: null } : null;
+			},
+		},
+		cloudflare(),
+	],
 });