a2a-exposed 0.6.0 → 0.7.1

package/package.json

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

package/worker/cloudflare.config.ts

@@ -48,7 +48,8 @@ const plain: Record<string, string> = {
 	UPSTREAM_CARD_URL: v("A2A_UPSTREAM_CARD_URL"), // default <upstream origin>/.well-known/agent-card.json
 	// Hosted multi-tenant gates. All empty by default, and empty is omitted, so a self-host deploy is unchanged.
 	// TENANCY=host switches the entrypoint to src/hosted.ts and adds TENANT_DO + TENANT_DIRECTORY below.
-	// QUOTAS, USAGE_SINK, WAKE_TARGET_POLICY, SIGNUP_URL and BRANDING are parsed and reserved.
+	// QUOTAS, USAGE_SINK, SIGNUP_URL and BRANDING are parsed and reserved.
+	// WAKE_TARGET_POLICY=public-https refuses a wake that is not public https (see wake-target.ts).
 	// APPROVAL_OIDC_* turn on OpenID Connect approval when issuer, client id, secret and allowlist are all set.
 	TENANCY: v("TENANCY"),
 	TENANT_DOMAIN: v("TENANT_DOMAIN"),

package/worker/deploy.env.example

@@ -35,7 +35,11 @@ WAKE_PRESET=generic
 # Optional multi-tenant gates. Leave them unset for a self-hosted inbox (`npx -y a2a-exposed@latest init`
 # never sets them). Unset means today's single-tenant Worker on D1, and the build does not export a Durable Object.
 # TENANCY=host switches the entry to the multi-tenant router and adds the TENANT_DO and TENANT_DIRECTORY bindings.
-# The other values are reserved (parsed, not enforced yet). Do not set TENANCY for a self-hosted inbox.
+# QUOTAS, USAGE_SINK, SIGNUP_URL and BRANDING are reserved (parsed, not enforced yet).
+# WAKE_TARGET_POLICY=public-https is enforced: a wake must be https to a public address. The Worker
+# connects to an address from that check. A redirect is followed only on the same origin. Leave it
+# unset for a self-hosted inbox.
+# Do not set TENANCY for a self-hosted inbox.
 # TENANCY=
 # TENANT_DOMAIN=example.com
 # DATA_REGION=eu

package/worker/src/index.ts

@@ -7,6 +7,7 @@
 import * as A from "./a2a.ts";
 import * as F from "./facade.ts";
 import { renderWake, redact, cloudflareErrorHint, defaultDebounceSeconds, defaultMaxPerHour, type WakeConfig, type WakeEvent } from "./wake.ts";
+import { fetchCheckedWake } from "./wake-target.ts";
 import * as P from "./pairing.ts";
 import * as M from "./mcp.ts";
 import { resolveTenant, type TenantContext, type WorkerBindings } from "./tenancy.ts";
@@ -114,7 +115,17 @@ async function sendWake(ctx: TenantContext, ectx: ExecutionContext, payload: Jso
 	}
 	if (!req) { log("wake_skipped", { contextId: ev.contextId, reason: "WAKE_WEBHOOK_URL unset" }); return { status: null, info: "WAKE_WEBHOOK_URL unset" }; }
 	try {
-		const r = await doFetch(ctx, ectx, req.url, { method: "POST", headers: req.headers, body: req.body });
+		let r: Response;
+		if (ctx.gates.wakeTargetPolicy === "public-https") {
+			const checked = await fetchCheckedWake(req.url, { method: "POST", headers: req.headers, body: req.body });
+			if ("refused" in checked) {
+				log("wake_refused", { preset: preset(ctx), contextId: ev.contextId, reason: checked.refused });
+				return { status: null, info: `refused: ${checked.refused}` };
+			}
+			r = checked.response;
+		} else {
+			r = await doFetch(ctx, ectx, req.url, { method: "POST", headers: req.headers, body: req.body });
+		}
 		// explain Cloudflare edge errors (tunnel connector down, Access block) without echoing the body
 		const hint = r.ok ? "" : cloudflareErrorHint(r.status, (await r.text().catch(() => "")).slice(0, 4096));
 		log("wake_sent", { preset: preset(ctx), contextId: ev.contextId, taskId: ev.taskId, status: r.status, ...(hint ? { hint } : {}) });

package/worker/src/tenancy.ts

@@ -84,7 +84,7 @@ export interface WorkerBindings extends ConfigFields {
 	QUOTAS?: string;
 	/** "d1" reserves usage metering (not applied yet). */
 	USAGE_SINK?: string;
-	/** "public-https" reserves the wake-target policy (not applied yet). */
+	/** "public-https" refuses non-https, private, and metadata wake targets. Anything else is unset. */
 	WAKE_TARGET_POLICY?: string;
 	/** https URL shown later on the landing page and over-quota errors. Parsed, not rendered yet. */
 	SIGNUP_URL?: string;

package/worker/src/wake-target.ts

@@ -0,0 +1,202 @@
+// Wake URL checks for WAKE_TARGET_POLICY=public-https. Unset stays the previous fetch
+// (any URL the operator configured, redirects followed by the platform).
+import { isPrivateHost } from "./a2a.ts";
+import { isPublicIp, net, parseHttpResponse, type PinnedSocket } from "./mcp.ts";
+
+/** DNS-over-HTTPS resolver. Same endpoint the client-metadata fetch uses. */
+export const DOH_URL = "https://cloudflare-dns.com/dns-query";
+
+/** Original request plus this many redirects. Each hop is checked before it is requested. */
+const MAX_REDIRECTS = 3;
+
+/** Host to addresses. `null` means the lookup failed and the caller must fail closed. */
+export type AddressLookup = (host: string) => Promise<string[] | null>;
+
+type Connect = NonNullable<typeof net.connect>;
+
+export type WakeDeps = {
+	lookup?: AddressLookup;
+	connect?: Connect;
+};
+
+function bareHost(host: string): string {
+	return host.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+}
+
+/** An address literal (IPv4, or IPv6 with or without brackets). Names go through DNS. */
+export function isIpLiteral(host: string): boolean {
+	const h = bareHost(host);
+	if (/^(\d{1,3}\.){3}\d{1,3}$/.test(h)) return true;
+	return h.includes(":") && /^[0-9a-f:.]+$/.test(h);
+}
+
+/**
+ * A and AAAA for `host`, CNAMEs followed by the resolver. `null` on any DNS or transport failure.
+ * An empty list is a real answer with no address (NXDOMAIN or no A/AAAA).
+ */
+export async function lookupAddresses(host: string, signal?: AbortSignal): Promise<string[] | null> {
+	const ips: string[] = [];
+	for (const type of ["A", "AAAA"]) {
+		let body: { Status?: number; Answer?: { type?: number; data?: string }[] };
+		try {
+			const res = await fetch(`${DOH_URL}?name=${encodeURIComponent(host)}&type=${type}`, {
+				headers: { accept: "application/dns-json" },
+				redirect: "manual",
+				signal,
+			});
+			if (!res.ok) return null;
+			body = await res.json();
+		} catch {
+			return null;
+		}
+		// Status 3 is NXDOMAIN. AAAA is often NXDOMAIN when A exists; that is not a failure.
+		if (body?.Status !== 0 && !(body?.Status === 3 && type === "AAAA")) return null;
+		for (const answer of Array.isArray(body.Answer) ? body.Answer : []) {
+			if (answer?.type === 1 || answer?.type === 28) ips.push(String(answer.data));
+		}
+	}
+	return ips;
+}
+
+/**
+ * Why this URL must not be requested under public-https. Empty means it may be requested.
+ * Names are resolved. Every returned address must be a public unicast address: private, loopback,
+ * link-local (including metadata), CGNAT, multicast, and documentation ranges are refused.
+ * A lookup that cannot be completed is refused.
+ */
+export async function publicWakeProblem(url: string, lookup: AddressLookup = lookupAddresses): Promise<string> {
+	const checked = await checkedWakeAddress(url, lookup);
+	return "refused" in checked ? checked.refused : "";
+}
+
+/** The address the next request must use. A name is resolved once; the returned IP is from that answer. */
+export async function checkedWakeAddress(url: string, lookup: AddressLookup = lookupAddresses): Promise<{ ip: string } | { refused: string }> {
+	let parsed: URL;
+	try { parsed = new URL(url); } catch { return { refused: "not a URL" }; }
+	if (parsed.protocol !== "https:") return { refused: "must be https" };
+	if (parsed.username || parsed.password) return { refused: "must not contain credentials" };
+	const host = parsed.hostname;
+	if (!host || isPrivateHost(host)) return { refused: "private or internal host" };
+	const bare = bareHost(host);
+	if (isIpLiteral(host)) return isPublicIp(bare) ? { ip: bare } : { refused: "private or reserved address" };
+	let ips: string[] | null;
+	try { ips = await lookup(host); } catch { return { refused: "its address could not be checked" }; }
+	if (ips == null) return { refused: "its address could not be checked" };
+	if (!ips.length) return { refused: "the host has no address" };
+	if (!ips.every((ip) => isPublicIp(ip))) return { refused: "resolves to a private or reserved address" };
+	return { ip: ips[0] };
+}
+
+function headerEntries(headers: HeadersInit | undefined): [string, string][] {
+	const out: [string, string][] = [];
+	const list = new Headers(headers);
+	list.forEach((value, key) => out.push([key, value]));
+	return out;
+}
+
+function requestBytes(method: string, url: URL, headers: HeadersInit | undefined, body: Uint8Array): Uint8Array {
+	const lines = [`${method} ${url.pathname}${url.search} HTTP/1.1`, `host: ${url.host}`];
+	for (const [key, value] of headerEntries(headers)) {
+		if (key === "host" || key === "content-length" || key === "connection" || key === "transfer-encoding") continue;
+		if (/[\r\n]/.test(key) || /[\r\n]/.test(value)) throw new Error("invalid header");
+		lines.push(`${key}: ${value}`);
+	}
+	if (body.byteLength) lines.push(`content-length: ${body.byteLength}`);
+	lines.push("connection: close");
+	const head = new TextEncoder().encode(lines.join("\r\n") + "\r\n\r\n");
+	const raw = new Uint8Array(head.byteLength + body.byteLength);
+	raw.set(head);
+	raw.set(body, head.byteLength);
+	return raw;
+}
+
+async function readSocket(sock: PinnedSocket, cap: number): Promise<Uint8Array> {
+	const reader = sock.readable.getReader();
+	const chunks: Uint8Array[] = [];
+	let n = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		n += value.byteLength;
+		if (n > cap) break;
+		chunks.push(value);
+	}
+	const raw = new Uint8Array(Math.min(n, cap));
+	let o = 0;
+	for (const chunk of chunks) {
+		const take = Math.min(chunk.byteLength, raw.byteLength - o);
+		raw.set(chunk.subarray(0, take), o);
+		o += take;
+	}
+	return raw;
+}
+
+/**
+ * HTTPS to `ip`, with TLS checked for the URL's hostname. The platform does not resolve the name again.
+ */
+async function pinnedRequest(ip: string, url: string, method: string, headers: HeadersInit | undefined, body: Uint8Array, connect: Connect): Promise<Response> {
+	const parsed = new URL(url);
+	const sock = connect({ hostname: ip, port: Number(parsed.port || 443) }, { secureTransport: "starttls" }).startTls({ expectedServerHostname: parsed.hostname });
+	try {
+		const writer = sock.writable.getWriter();
+		await writer.write(requestBytes(method, parsed, headers, body));
+		writer.releaseLock();
+		const raw = await readSocket(sock, 65536);
+		const message = parseHttpResponse(raw);
+		if (typeof message === "string") throw new Error(message);
+		const responseHeaders = new Headers();
+		for (const [key, value] of Object.entries(message.headers)) responseHeaders.set(key, value);
+		const payload = message.status === 204 || message.status === 304 ? null : message.body;
+		return new Response(payload, { status: message.status, headers: responseHeaders });
+	} finally {
+		await sock.close().catch(() => {});
+	}
+}
+
+function bodyBytes(body: BodyInit | null | undefined): Uint8Array {
+	if (body == null) return new Uint8Array();
+	if (typeof body === "string") return new TextEncoder().encode(body);
+	if (body instanceof Uint8Array) return body;
+	throw new Error("unsupported wake body");
+}
+
+/**
+ * POST (or whatever `init` says) to `url` on the address that passed the public-https check.
+ * A redirect is followed only when it stays on the same origin, and that hop is checked and pinned again.
+ * A cross-origin redirect is refused, so wake credentials are not sent to another host.
+ * 301, 302, and 303 drop the body. 307 and 308 keep it.
+ */
+export async function fetchCheckedWake(
+	url: string,
+	init: RequestInit,
+	deps: WakeDeps = {},
+): Promise<{ response: Response } | { refused: string }> {
+	const lookup = deps.lookup ?? lookupAddresses;
+	const connect = async (): Promise<Connect> => {
+		if (deps.connect) return deps.connect;
+		if (net.connect) return net.connect;
+		return (await import("cloudflare:sockets")).connect as unknown as Connect;
+	};
+	let current = url;
+	let method = (init.method || "GET").toUpperCase();
+	let body = bodyBytes(method === "GET" || method === "HEAD" ? undefined : init.body);
+	for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+		const checked = await checkedWakeAddress(current, lookup);
+		if ("refused" in checked) return checked;
+		const res = await pinnedRequest(checked.ip, current, method, init.headers, method === "GET" || method === "HEAD" ? new Uint8Array() : body, await connect());
+		const location = res.headers.get("location");
+		if (res.status < 300 || res.status >= 400 || !location) return { response: res };
+		if (hop === MAX_REDIRECTS) return { refused: "too many redirects" };
+		let next: URL;
+		try { next = new URL(location, current); } catch { return { refused: "not a URL" }; }
+		const ahead = await checkedWakeAddress(next.href, lookup);
+		if ("refused" in ahead) return ahead;
+		if (next.origin !== new URL(current).origin) return { refused: "cross-origin redirect" };
+		if (res.status === 303 || ((res.status === 301 || res.status === 302) && method !== "GET" && method !== "HEAD")) {
+			method = "GET";
+			body = new Uint8Array();
+		}
+		current = next.href;
+	}
+	return { refused: "too many redirects" };
+}

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

@@ -0,0 +1,187 @@
+// WAKE_TARGET_POLICY=public-https refuses private, metadata, and redirect-to-private wake targets.
+// Unset keeps today's fetch. Run: npm test
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import worker from "../src/index.ts";
+import { d1 } from "./d1.ts";
+import * as M from "../src/mcp.ts";
+import { fetchCheckedWake, publicWakeProblem, type AddressLookup, type WakeDeps } from "../src/wake-target.ts";
+
+const publicLookup: AddressLookup = async (host) => {
+	if (host === "hook.example" || host === "also.example") return ["1.2.3.4"];
+	if (host === "split.example") return ["1.2.3.4", "10.0.0.1"];
+	if (host === "meta.example") return ["169.254.169.254"];
+	if (host === "missing.example") return [];
+	return null;
+};
+
+test("public-https refuses private, metadata, and non-https URLs before any request", async () => {
+	const refused = [
+		"http://hook.example/wake",
+		"https://user:secret@hook.example/wake",
+		"https://127.0.0.1/wake",
+		"https://10.1.2.3/wake",
+		"https://192.168.1.1/wake",
+		"https://172.16.0.1/wake",
+		"https://100.64.0.1/wake",
+		"https://100.100.100.200/wake",
+		"https://169.254.169.254/latest/meta-data",
+		"https://[::1]/wake",
+		"https://[fe80::1]/wake",
+		"https://localhost/wake",
+		"https://metadata.google.internal/wake",
+		"https://agent.ts.net/wake",
+		"https://metadata/wake",
+		"not a url",
+	];
+	for (const url of refused) {
+		const why = await publicWakeProblem(url, publicLookup);
+		assert.notEqual(why, "", url);
+	}
+	assert.equal(await publicWakeProblem("https://hook.example/wake", publicLookup), "");
+	assert.equal(await publicWakeProblem("https://1.2.3.4/wake", publicLookup), "");
+	assert.equal(await publicWakeProblem("https://split.example/wake", publicLookup), "resolves to a private or reserved address");
+	assert.equal(await publicWakeProblem("https://meta.example/wake", publicLookup), "resolves to a private or reserved address");
+	assert.equal(await publicWakeProblem("https://missing.example/wake", publicLookup), "the host has no address");
+	assert.equal(await publicWakeProblem("https://unknown.example/wake", publicLookup), "its address could not be checked");
+});
+
+function pinned(answer: (request: string) => { status: number; location?: string }) {
+	const calls: { ip: string; sni: string; request: string }[] = [];
+	const connect: NonNullable<WakeDeps["connect"]> = (addr) => ({
+		startTls: ({ expectedServerHostname: sni }) => {
+			let req = "";
+			let respond!: (bytes: Uint8Array) => void;
+			const ready = new Promise<Uint8Array>((resolve) => { respond = resolve; });
+			const writable = new WritableStream<Uint8Array>({
+				write(chunk) {
+					req += new TextDecoder().decode(chunk);
+					if (!req.includes("\r\n\r\n")) return;
+					calls.push({ ip: addr.hostname, sni, request: req });
+					const made = answer(req);
+					const headers = [`HTTP/1.1 ${made.status} X`, "content-length: 0"];
+					if (made.location) headers.push(`location: ${made.location}`);
+					headers.push("connection: close", "", "");
+					respond(new TextEncoder().encode(headers.join("\r\n")));
+				},
+			});
+			const readable = new ReadableStream<Uint8Array>({
+				async start(controller) {
+					controller.enqueue(await ready);
+					controller.close();
+				},
+			});
+			return { readable, writable, close: async () => {} };
+		},
+	});
+	return { connect, calls };
+}
+
+test("a redirect to a private address is not connected, and the first hop uses the checked IP", async () => {
+	const socket = pinned(() => ({ status: 302, location: "http://169.254.169.254/latest/meta-data" }));
+	const result = await fetchCheckedWake("https://hook.example/wake", { method: "POST", headers: { authorization: "Bearer secret" }, body: "{}" }, { lookup: publicLookup, connect: socket.connect });
+	assert.equal(socket.calls.length, 1);
+	assert.equal(socket.calls[0].ip, "1.2.3.4");
+	assert.equal(socket.calls[0].sni, "hook.example");
+	assert.match(socket.calls[0].request, /^POST \/wake HTTP\/1\.1/);
+	assert.match(socket.calls[0].request, /authorization: Bearer secret/i);
+	assert.equal("refused" in result && result.refused, "must be https");
+});
+
+test("a cross-origin redirect is not followed, so credentials stay on the first host", async () => {
+	const socket = pinned(() => ({ status: 307, location: "https://also.example/wake" }));
+	const result = await fetchCheckedWake("https://hook.example/wake", { method: "POST", headers: { authorization: "Bearer secret" }, body: "{}" }, { lookup: publicLookup, connect: socket.connect });
+	assert.equal(socket.calls.length, 1);
+	assert.equal(socket.calls[0].ip, "1.2.3.4");
+	assert.equal("refused" in result && result.refused, "cross-origin redirect");
+});
+
+test("a same-origin redirect is pinned again and keeps the wake headers", async () => {
+	const socket = pinned((request) => request.startsWith("POST /wake ")
+		? { status: 307, location: "https://hook.example/next" }
+		: { status: 200 });
+	const result = await fetchCheckedWake("https://hook.example/wake", { method: "POST", headers: { authorization: "Bearer secret" }, body: "{}" }, { lookup: publicLookup, connect: socket.connect });
+	assert.equal(socket.calls.length, 2);
+	assert.deepEqual(socket.calls.map((call) => call.ip), ["1.2.3.4", "1.2.3.4"]);
+	assert.match(socket.calls[1].request, /^POST \/next HTTP\/1\.1/);
+	assert.match(socket.calls[1].request, /authorization: Bearer secret/i);
+	assert.equal("response" in result && result.response.status, 200);
+});
+
+const BASE = "https://agent.example.com";
+
+async function wakeTest(env: Record<string, unknown>, fetchImpl: typeof fetch) {
+	const orig = globalThis.fetch;
+	globalThis.fetch = fetchImpl;
+	try {
+		const res = await worker.fetch(new Request(BASE + "/owner/wake/test", {
+			method: "POST",
+			headers: { authorization: "Bearer owner-secret" },
+		}), env as any, { waitUntil() {}, passThroughOnException() {} } as any);
+		return res.json() as Promise<{ status: number | null; info: string }>;
+	} finally {
+		globalThis.fetch = orig;
+	}
+}
+
+test("the policy is off unless WAKE_TARGET_POLICY is exactly public-https", async () => {
+	const env = {
+		DB: d1(new URL("../migrations/", import.meta.url)),
+		PUBLIC_URL: BASE,
+		OWNER_TOKEN: "owner-secret",
+		WAKE_PRESET: "generic",
+		WAKE_WEBHOOK_URL: "http://127.0.0.1/hook",
+	};
+	const requested: string[] = [];
+	const body = await wakeTest(env, (async (url: string) => {
+		requested.push(String(url));
+		return new Response("ok", { status: 200 });
+	}) as typeof fetch);
+	assert.equal(body.status, 200);
+	assert.equal(requested.length, 1);
+	assert.match(requested[0], /^http:\/\/127\.0\.0\.1\/hook/);
+});
+
+test("public-https does not request a metadata address, and does post to a checked public host", async () => {
+	const db = () => d1(new URL("../migrations/", import.meta.url));
+	const requested: string[] = [];
+	const fetchImpl = (async (url: string | URL) => {
+		const href = String(url);
+		requested.push(href);
+		if (href.startsWith("https://cloudflare-dns.com/dns-query")) {
+			const name = new URL(href).searchParams.get("name");
+			const type = new URL(href).searchParams.get("type");
+			if (name === "hook.example" && type === "A") {
+				return new Response(JSON.stringify({ Status: 0, Answer: [{ type: 1, data: "1.2.3.4" }] }), { status: 200 });
+			}
+			return new Response(JSON.stringify({ Status: 0, Answer: [] }), { status: 200 });
+		}
+		return new Response("ok", { status: 200 });
+	}) as typeof fetch;
+
+	const blocked = await wakeTest({
+		DB: db(), PUBLIC_URL: BASE, OWNER_TOKEN: "owner-secret", WAKE_PRESET: "generic",
+		WAKE_WEBHOOK_URL: "https://169.254.169.254/latest/meta-data", WAKE_TARGET_POLICY: "public-https",
+	}, fetchImpl);
+	assert.equal(blocked.status, null);
+	assert.match(blocked.info, /refused: private or internal host/);
+	assert.equal(requested.some((url) => url.includes("169.254.169.254")), false);
+
+	requested.length = 0;
+	const socket = pinned(() => ({ status: 200 }));
+	M.net.connect = socket.connect;
+	try {
+		const allowed = await wakeTest({
+			DB: db(), PUBLIC_URL: BASE, OWNER_TOKEN: "owner-secret", WAKE_PRESET: "generic",
+			WAKE_WEBHOOK_URL: "https://hook.example/wake", WAKE_WEBHOOK_KEY: "hook-key", WAKE_TARGET_POLICY: "public-https",
+		}, fetchImpl);
+		assert.equal(allowed.status, 200);
+		assert.equal(requested.every((url) => url.startsWith("https://cloudflare-dns.com/")), true);
+		assert.equal(socket.calls.length, 1);
+		assert.equal(socket.calls[0].ip, "1.2.3.4");
+		assert.equal(socket.calls[0].sni, "hook.example");
+		assert.match(socket.calls[0].request, /authorization: Bearer hook-key/i);
+	} finally {
+		M.net.connect = null;
+	}
+});