a2a-exposed 0.7.15 → 0.7.16

package/lib/main.mjs

@@ -191,8 +191,8 @@ Control plane account (only when that deployment's login is on)
                                 page. Creating an agent shows the owner token once. The agent page rotates
                                 that token after a confirmation and a recent sign-in. The new token is
                                 shown once on that agent's page. The previous one stops working immediately.
-                                The token is shown only when the stored hash is still that token.
-                                Deleting an agent asks for its name and a recent sign-in. A self-hosted inbox has no such delete.
+                                The token is shown only when the stored hash is still that token. A Copy button sits next to it. Without JavaScript the value still copies.
+                                Deleting an agent asks for its name and a recent sign-in. The account page says how many slots remain. A self-hosted inbox has no such delete.
                                 That page is not stored.
                                 FREE_AGENT_LIMIT=2 caps a free account at 2 agents. An account's own limit overrides it.
                                 Unset, there is no limit. The database rejects another insert.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "a2a-exposed",
-	"version": "0.7.15",
+	"version": "0.7.16",
 	"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/approval-oidc.ts

@@ -342,6 +342,37 @@ async function verifyIdToken(token: string, jwks: { keys?: any[] }, expect: { is
 	return { subject: typeof claims.sub === "string" ? claims.sub : String(claims.email) };
 }
 
+type OidcCallback = { kind: OidcKind; state: string; code: string | null; error: string | null };
+type OpenedOidc = { row: any; userCode: string | null } | (FinishResult & { ok: false });
+
+/** Local callback checks. `consume` deletes the sign-in row; a probe leaves it for the real GET. */
+async function openOidc(ctx: TenantContext, o: OidcCallback, consume: boolean): Promise<OpenedOidc> {
+	const state = o.state || "";
+	if (!/^[A-Za-z0-9_-]{20,128}$/.test(state)) return { ok: false, error: "This sign-in expired or was already used. Nothing was approved.", reason: "state", userCode: null };
+	const row: any = consume
+		? await ctx.DB.prepare("DELETE FROM oidc_txns WHERE state = ? RETURNING *").bind(state).first()
+		: await ctx.DB.prepare("SELECT * FROM oidc_txns WHERE state = ?").bind(state).first();
+	if (!row || row.kind !== o.kind) return { ok: false, error: "This sign-in expired or was already used. Nothing was approved.", reason: "state", userCode: null };
+	const userCode = row.user_code || null;
+	if (Date.now() >= row.expires_ms) return { ok: false, error: "This sign-in expired. Nothing was approved.", reason: "expired", userCode };
+	if (o.error || !o.code) return { ok: false, error: "Sign-in was cancelled. Nothing was approved.", reason: "cancelled", userCode };
+	if (!approvalPolicy(ctx.gates.approvalOidc).oidc || !ctx.approvalClientSecret())
+		return { ok: false, error: "OpenID Connect approval is not configured.", reason: "config", userCode };
+	return { row, userCode };
+}
+
+export type ReadOidcResult = (FinishResult & { ok: false }) | { ok: true; pending: true; userCode: string | null };
+
+/**
+ * What a callback can know without spending it. The sign-in row stays, and the identity provider is not called,
+ * so a HEAD probe cannot approve or burn the one-time state.
+ */
+export async function readOidc(ctx: TenantContext, o: OidcCallback): Promise<ReadOidcResult> {
+	const opened = await openOidc(ctx, o, false);
+	if ("ok" in opened) return opened;
+	return { ok: true, pending: true, userCode: opened.userCode };
+}
+
 /**
  * Complete a sign-in. The state row is deleted on every callback, including failure, so it cannot be replayed.
  * The CSRF cookie is not read here: SameSite=Strict is dropped on the cross-site return from the identity
@@ -350,23 +381,21 @@ async function verifyIdToken(token: string, jwks: { keys?: any[] }, expect: { is
 export async function finishOidc(ctx: TenantContext, o: {
 	kind: OidcKind; redirectUri: string; state: string; code: string | null; error: string | null;
 }): Promise<FinishResult> {
-	const state = o.state || "";
-	if (!/^[A-Za-z0-9_-]{20,128}$/.test(state)) return { ok: false, error: "This sign-in expired or was already used. Nothing was approved.", reason: "state", userCode: null };
-	const row: any = await ctx.DB.prepare("DELETE FROM oidc_txns WHERE state = ? RETURNING *").bind(state).first();
-	if (!row || row.kind !== o.kind) return { ok: false, error: "This sign-in expired or was already used. Nothing was approved.", reason: "state", userCode: null };
-	const userCode = row.user_code || null;
-	if (Date.now() >= row.expires_ms) return { ok: false, error: "This sign-in expired. Nothing was approved.", reason: "expired", userCode };
-	if (o.error || !o.code) return { ok: false, error: "Sign-in was cancelled. Nothing was approved.", reason: "cancelled", userCode };
+	const opened = await openOidc(ctx, o, true);
+	if ("ok" in opened) return opened;
+	const { row, userCode } = opened;
+	const code = o.code;
+	if (!code) return { ok: false, error: "Sign-in was cancelled. Nothing was approved.", reason: "cancelled", userCode };
 	const gate = ctx.gates.approvalOidc;
 	const secret = ctx.approvalClientSecret();
-	if (!approvalPolicy(gate).oidc || !secret) return { ok: false, error: "OpenID Connect approval is not configured.", reason: "config", userCode };
+	if (!secret) return { ok: false, error: "OpenID Connect approval is not configured.", reason: "config", userCode };
 	let disc: Discovery;
 	try { disc = await discover(ctx, gate.issuer); }
 	catch { return { ok: false, error: UNREACHABLE, reason: "discovery", userCode }; }
 	let idToken = "";
 	try {
 		const body = new URLSearchParams({
-			grant_type: "authorization_code", code: o.code, redirect_uri: o.redirectUri,
+			grant_type: "authorization_code", code, redirect_uri: o.redirectUri,
 			client_id: gate.clientId, client_secret: secret, code_verifier: row.verifier,
 		});
 		const res = await idpFetch(ctx, disc.token_endpoint, {

package/worker/src/index.ts

@@ -911,7 +911,7 @@ function ownerTaskView(t: Json): Json {
 	};
 }
 
-async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionContext, path: string, url: URL, trusted = false): Promise<Response> {
+async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionContext, path: string, url: URL, trusted = false, head = false): Promise<Response> {
 	// trusted: an in-process call. MCP tools use ownerCall (paths fixed in the tool code). The hosted
 	// owner() RPC uses runOwnerRpc, which has its own allowlist. A request from the network is never trusted.
 	if (!trusted && !(await isOwner(ctx, req.headers.get("authorization")))) return json({ error: "unauthorized" }, 401);
@@ -949,13 +949,16 @@ async function handleOwner(req: Request, ctx: TenantContext, ectx: ExecutionCont
 			const lastUser = [...t.history].reverse().find((x: Json) => x.role === "user") || {};
 			out.push({ taskId: t.id, contextId: t.contextId, from: t._peer, state: t.status.state, updated: t.status.timestamp, text: A.textOf(lastUser) });
 		}
-		// the owner has now seen these tasks: drop pending wakes that only cover them
-		const seen = new Set(out.map((o) => o.taskId));
-		const pend = await ctx.DB.prepare("SELECT context_id, pending_json FROM wakes WHERE pending_json IS NOT NULL").all();
-		for (const p of pend.results as Json[]) {
-			const ids: string[] = JSON.parse(p.pending_json).taskIds || [];
-			if (ids.length && ids.every((i) => seen.has(i)))
-				await ctx.DB.prepare("UPDATE wakes SET pending_json = NULL, pending_since_ms = NULL WHERE context_id = ? AND pending_json = ?").bind(p.context_id, p.pending_json).run();
+		// the owner has now seen these tasks: drop pending wakes that only cover them.
+		// HEAD returns the same status and headers and does not mark the inbox seen.
+		if (!head) {
+			const seen = new Set(out.map((o) => o.taskId));
+			const pend = await ctx.DB.prepare("SELECT context_id, pending_json FROM wakes WHERE pending_json IS NOT NULL").all();
+			for (const p of pend.results as Json[]) {
+				const ids: string[] = JSON.parse(p.pending_json).taskIds || [];
+				if (ids.length && ids.every((i) => seen.has(i)))
+					await ctx.DB.prepare("UPDATE wakes SET pending_json = NULL, pending_since_ms = NULL WHERE context_id = ? AND pending_json = ?").bind(p.context_id, p.pending_json).run();
+			}
 		}
 		return json(out);
 	}
@@ -1206,6 +1209,15 @@ const pairingCleanup = (ctx: TenantContext, now: number) => [
 	ctx.DB.prepare("DELETE FROM oidc_txns WHERE expires_ms < ?").bind(now),
 ];
 
+/**
+ * True when this call is past `limit`. HEAD peeks: the counter is not incremented, and a count already at the cap
+ * is past it, which is the decision one more increment would make.
+ */
+async function overLimit(ctx: TenantContext, key: string, windowS: number, limit: number, head: boolean): Promise<boolean> {
+	const n = await bump(ctx, key, windowS, head);
+	return head ? n >= limit : n > limit;
+}
+
 /** Fixed-window counter: increments and returns the count for `key` in the current window (peek: no increment). */
 async function bump(ctx: TenantContext, key: string, windowS: number, peek = false): Promise<number> {
 	const now = Date.now(), start = Math.floor(now / (windowS * 1000));
@@ -1402,7 +1414,7 @@ function cookie(req: Request, name: string): string {
 }
 
 /** GET/POST /device: the owner approves or denies a request with the approval password (no scripts, strict CSP). */
-async function devicePage(req: Request, ctx: TenantContext, url: URL): Promise<Response> {
+async function devicePage(req: Request, ctx: TenantContext, url: URL, head = false): Promise<Response> {
 	const nonce = P.randomB64(), ip = clientIp(req);
 	const csrfName = "a2a_device_csrf";
 	let csrf = cookie(req, csrfName);
@@ -1417,7 +1429,7 @@ async function devicePage(req: Request, ctx: TenantContext, url: URL): Promise<R
 	};
 	const show = async (raw: string | null, notice?: P.PageModel["notice"]) => {
 		model.notice = notice;
-		if (raw && (await bump(ctx, `look:ip:${ip || "?"}`, P.LIMITS.lookupsWindowS)) > P.LIMITS.lookupsPerIp) {
+		if (raw && await overLimit(ctx, `look:ip:${ip || "?"}`, P.LIMITS.lookupsWindowS, P.LIMITS.lookupsPerIp, head)) {
 			model.askCode = true;
 			model.notice = { kind: "error", text: "Too many code lookups from this address. Try again in a few minutes." };
 			return;
@@ -1511,7 +1523,7 @@ async function devicePage(req: Request, ctx: TenantContext, url: URL): Promise<R
 }
 
 /** GET /device/oidc/callback: the identity provider returns here. State is the CSRF; the cookie is not re-checked. */
-async function deviceOidcCallback(req: Request, ctx: TenantContext, url: URL): Promise<Response> {
+async function deviceOidcCallback(req: Request, ctx: TenantContext, url: URL, head = false): Promise<Response> {
 	const nonce = P.randomB64();
 	const pw = await approvalPassword(ctx);
 	const model: P.PageModel = { agentName: ctx.AGENT_NAME || "this A2A inbox", mode: pairingMode(ctx), cli: cliCommand(ctx), csrf: P.randomB64(), passwordSet: !!pw, ...approvalPageBits(ctx) };
@@ -1520,10 +1532,31 @@ async function deviceOidcCallback(req: Request, ctx: TenantContext, url: URL): P
 		h["set-cookie"] = `a2a_device_csrf=${model.csrf}; Path=/device; Secure; HttpOnly; SameSite=Strict; Max-Age=3600`;
 		return new Response(P.devicePage(model, nonce), { status, headers: h });
 	};
-	const done = await O.finishOidc(ctx, {
-		kind: "device", redirectUri: `${oauthUrls(ctx).page}/oidc/callback`,
+	const callback = {
+		kind: "device" as const, redirectUri: `${oauthUrls(ctx).page}/oidc/callback`,
 		state: url.searchParams.get("state") || "", code: url.searchParams.get("code"), error: url.searchParams.get("error"),
-	});
+	};
+	// HEAD must not delete the sign-in or approve. A still-open sign-in answers with the device page (200, the status a
+	// completed approval uses) and does not say approved. The browser GET still finishes it.
+	if (head) {
+		const seen = await O.readOidc(ctx, callback);
+		if (!seen.ok) {
+			if (seen.userCode) {
+				const pending = await pendingRequest(ctx, seen.userCode);
+				if (pending && pending.status === "pending" && Date.now() < pending.expires_ms) model.request = pageRequest(pending);
+			}
+			model.notice = { kind: "error", text: seen.error };
+			return send(400);
+		}
+		const pending = seen.userCode ? await pendingRequest(ctx, seen.userCode) : null;
+		if (pending && pending.status === "pending" && Date.now() < pending.expires_ms) {
+			model.request = pageRequest(pending);
+			return send(200);
+		}
+		model.notice = { kind: "error", text: "Nothing was approved." };
+		return send(409);
+	}
+	const done = await O.finishOidc(ctx, callback);
 	if (!done.ok) {
 		log("oidc_rejected", { kind: "device", reason: done.reason });
 		if (done.userCode) {
@@ -1559,7 +1592,7 @@ async function liveSetup(ctx: TenantContext, token: string): Promise<{ rec: Setu
 }
 
 /** GET/POST /device/setup: set or change the approval password from a one-time link. Same frame and CSRF as /device. The form posts only to this host, so form-action stays 'self'. */
-async function setupPage(req: Request, ctx: TenantContext, url: URL): Promise<Response> {
+async function setupPage(req: Request, ctx: TenantContext, url: URL, head = false): Promise<Response> {
 	const nonce = P.randomB64(), ip = clientIp(req);
 	const csrfName = "a2a_device_csrf";
 	let csrf = cookie(req, csrfName);
@@ -1577,7 +1610,7 @@ async function setupPage(req: Request, ctx: TenantContext, url: URL): Promise<Re
 		model.notice = { kind: "error", text };
 		return send(status);
 	};
-	if ((await bump(ctx, `setup:ip:${ip || "?"}`, P.LIMITS.setupWindowS)) > P.LIMITS.setupPerIp) {
+	if (await overLimit(ctx, `setup:ip:${ip || "?"}`, P.LIMITS.setupWindowS, P.LIMITS.setupPerIp, head)) {
 		log("password_setup_rate_limited", { ip });
 		return invalid(429, "Too many attempts from this address. Try again in a few minutes.");
 	}
@@ -1871,7 +1904,7 @@ async function pinnedGet(ip: string, url: string, max: number, signal: AbortSign
  *  Document (fetched with SSRF guards: public https host other than this Worker whose A/AAAA records are all public
  *  (DNS-over-HTTPS), connected to at that checked IP (no DNS rebinding), no redirects, no credentials, 5 s, 5 KB; cached for its
  *  max-age; failures and invalid documents are not cached). `ip` rate-limits fetches (not cached lookups). */
-async function resolveClient(ctx: TenantContext, id: string, ip?: string): Promise<{ client?: Json; error?: string }> {
+async function resolveClient(ctx: TenantContext, id: string, ip?: string, head = false): Promise<{ client?: Json; error?: string }> {
 	if (!id) return { error: "client_id is required" };
 	if (!/^https:\/\//i.test(id)) {
 		const c: Json = await ctx.DB.prepare("SELECT * FROM oauth_clients WHERE client_id = ?").bind(id).first();
@@ -1882,6 +1915,12 @@ async function resolveClient(ctx: TenantContext, id: string, ip?: string): Promi
 	const now = Date.now();
 	const hit: Json = await ctx.DB.prepare("SELECT * FROM oauth_client_metadata WHERE client_id = ? AND expires_ms > ?").bind(id, now).first();
 	if (hit) return { client: { ...hit, cimd: true } };
+	// HEAD does not fetch the document or spend the lookup limit. A cache miss is the same refusal as a failed fetch.
+	if (head) {
+		if (ip !== undefined && await overLimit(ctx, `cimd:ip:${ip || "?"}`, 3600, M.CIMD.fetchesPerIpPerHour, true))
+			return { error: "Too many client metadata lookups from this address. Try again later." };
+		return { error: "The client's metadata document could not be fetched." };
+	}
 	if (ip !== undefined && (await bump(ctx, `cimd:ip:${ip || "?"}`, 3600)) > M.CIMD.fetchesPerIpPerHour)
 		return { error: "Too many client metadata lookups from this address. Try again later." };
 	const signal = AbortSignal.timeout(M.CIMD.timeoutMs);
@@ -1920,11 +1959,11 @@ async function resolveClient(ctx: TenantContext, id: string, ip?: string): Promi
 type AuthzCheck = { fatal?: string; error?: string; description?: string; client?: Json; redirect?: string; params: Record<string, string> };
 
 /** Validate an authorization request. fatal: show an error page (no trustworthy redirect); error: redirect back with it. */
-async function checkAuthorize(ctx: TenantContext, q: Record<string, string>, ip: string): Promise<AuthzCheck> {
+async function checkAuthorize(ctx: TenantContext, q: Record<string, string>, ip: string, head = false): Promise<AuthzCheck> {
 	const params: Record<string, string> = {};
 	for (const k of ["response_type", "client_id", "redirect_uri", "state", "code_challenge", "code_challenge_method", "scope", "resource"])
 		if (typeof q[k] === "string" && q[k] !== "") params[k] = q[k].slice(0, 2048);
-	const rc = await resolveClient(ctx, params.client_id || "", ip);
+	const rc = await resolveClient(ctx, params.client_id || "", ip, head);
 	if (!rc.client) return { fatal: rc.error!, params };
 	const client = rc.client;
 	const uris: string[] = JSON.parse(client.redirect_uris_json || "[]");
@@ -1948,7 +1987,7 @@ function redirectWith(ctx: TenantContext, redirect: string, q: Record<string, st
 }
 
 /** GET/POST /oauth/authorize: the owner approves an MCP client with the approval password (same lockout as /device). */
-async function authorizePage(req: Request, ctx: TenantContext, url: URL): Promise<Response> {
+async function authorizePage(req: Request, ctx: TenantContext, url: URL, head = false): Promise<Response> {
 	const nonce = P.randomB64(), ip = clientIp(req);
 	const csrfName = "a2a_mcp_csrf";
 	let csrf = cookie(req, csrfName);
@@ -1959,7 +1998,7 @@ async function authorizePage(req: Request, ctx: TenantContext, url: URL): Promis
 		try { form = P.parseParams(await readBody(req, { ...ctx, MAX_BODY: "16384" }), "application/x-www-form-urlencoded"); } catch { /* empty */ }
 	}
 	const q = req.method === "GET" ? Object.fromEntries(url.searchParams) : form;
-	const c = await checkAuthorize(ctx, q, ip);
+	const c = await checkAuthorize(ctx, q, ip, head);
 	const pw = await approvalPassword(ctx);
 	const page = (status: number, body: string, formOrigins: string[] = []) => {
 		// Approve and deny 302 to the client. OpenID Connect 302s to the issuer. Chrome checks both against form-action.
@@ -2030,13 +2069,20 @@ async function issueMcpCode(ctx: TenantContext, clientName: string, redirect: st
  * The identity provider navigates here with a GET. The code redirect is that navigation's 302, not a form post, so form-action does not apply to the client origin.
  * The error page has no form.
  */
-async function mcpOidcCallback(req: Request, ctx: TenantContext, url: URL): Promise<Response> {
+async function mcpOidcCallback(req: Request, ctx: TenantContext, url: URL, head = false): Promise<Response> {
 	const nonce = P.randomB64();
 	const fail = (status: number, text: string) => new Response(P.pageShell("Connect an MCP client", nonce, `<p class="n error">${P.esc(text)}</p>`), { status, headers: P.pageHeaders(nonce) });
-	const done = await O.finishOidc(ctx, {
-		kind: "mcp", redirectUri: `${oauthUrls(ctx).authorize}/oidc/callback`,
+	const callback = {
+		kind: "mcp" as const, redirectUri: `${oauthUrls(ctx).authorize}/oidc/callback`,
 		state: url.searchParams.get("state") || "", code: url.searchParams.get("code"), error: url.searchParams.get("error"),
-	});
+	};
+	// The successful GET is a 302 that carries a newly issued code. HEAD does not issue that code or delete the sign-in,
+	// so it stays on the not-approved page. The browser GET still completes the redirect.
+	if (head) {
+		const seen = await O.readOidc(ctx, callback);
+		return fail(400, seen.ok ? "Nothing was approved." : seen.error);
+	}
+	const done = await O.finishOidc(ctx, callback);
 	if (!done.ok) {
 		log("oidc_rejected", { kind: "mcp", reason: done.reason });
 		return fail(400, done.error);
@@ -2462,26 +2508,38 @@ async function handleMcp(req: Request, ctx: TenantContext, ectx: ExecutionContex
 	return rpcError(id, M.ERR.METHOD_NOT_FOUND, `method not found: ${msg.method}`);
 }
 
-async function handle(req: Request, ctx: TenantContext, ectx: ExecutionContext): Promise<Response> {
+/** Hosted cards disappear when the agent is deleted. There is no purge binding, so the public max-age is short. Self-host has no such delete. */
+function cardCacheControl(ctx: TenantContext): string {
+	return ctx.mode === "host" ? "public, max-age=60" : "public, max-age=300";
+}
+
+/** Same status and headers as the GET response, with an empty body. The body is discarded, not copied. */
+async function emptyHead(res: Response): Promise<Response> {
+	try { await res.body?.cancel(); } catch { /* the status and headers still answer the HEAD */ }
+	return new Response(null, { status: res.status, headers: res.headers });
+}
+
+async function handle(req: Request, ctx: TenantContext, ectx: ExecutionContext, head = false): Promise<Response> {
+	if (req.method === "HEAD") return emptyHead(await handle(new Request(req.url, { method: "GET", headers: req.headers }), ctx, ectx, true));
 	const url = new URL(req.url);
 	const path = url.pathname;
 	try {
 		if (req.method === "GET" && path === "/.well-known/agent-card.json")
-			return json(await agentCard(ctx), 200, { "access-control-allow-origin": "*", "cache-control": "public, max-age=300" });
+			return json(await agentCard(ctx), 200, { "access-control-allow-origin": "*", "cache-control": cardCacheControl(ctx) });
 		// legacy discovery path (A2A 0.2): the 0.3-shaped card that clients of that era parse
 		if (req.method === "GET" && path === "/.well-known/agent.json")
-			return json(agentCard03(ctx, await agentCard(ctx)), 200, { "access-control-allow-origin": "*", "cache-control": "public, max-age=300" });
+			return json(agentCard03(ctx, await agentCard(ctx)), 200, { "access-control-allow-origin": "*", "cache-control": cardCacheControl(ctx) });
 		if (req.method === "GET" && path === "/health") return json({ ok: true, publicUrl: ctx.PUBLIC_URL, mode: proxyMode(ctx) ? "proxy" : "inbox", mcp: mcpOn(ctx) });
 		if (path === "/mcp") return mcpOn(ctx) ? await handleMcp(req, ctx, ectx, url) : json({ error: "not_found", error_description: "the MCP server is turned off on this inbox (MCP=off)" }, 404);
 		if (mcpOn(ctx)) {
 			if (req.method === "GET" && path === "/.well-known/oauth-protected-resource/mcp") return json(mcpResourceMetadata(ctx), 200, { "access-control-allow-origin": "*" });
 			if (req.method === "GET" && path === "/.well-known/oauth-authorization-server") return json(oauthMetadata(ctx), 200, { "access-control-allow-origin": "*" });
 			if (req.method === "POST" && path === "/oauth/register") return await registerClient(req, ctx);
-			if (req.method === "GET" && path === "/oauth/authorize/oidc/callback") return await mcpOidcCallback(req, ctx, url);
-			if ((req.method === "GET" || req.method === "POST") && path === "/oauth/authorize") return await authorizePage(req, ctx, url);
+			if (req.method === "GET" && path === "/oauth/authorize/oidc/callback") return await mcpOidcCallback(req, ctx, url, head);
+			if ((req.method === "GET" || req.method === "POST") && path === "/oauth/authorize") return await authorizePage(req, ctx, url, head);
 			if (req.method === "POST" && path === "/oauth/revoke") return await revokeEndpoint(req, ctx);
 			if (req.method === "POST" && path === "/oauth/token") return await tokenEndpoint(req, ctx);
-			if (path === "/device/setup" && (req.method === "GET" || req.method === "POST")) return await setupPage(req, ctx, url);
+			if (path === "/device/setup" && (req.method === "GET" || req.method === "POST")) return await setupPage(req, ctx, url, head);
 		}
 		if (path === "/.well-known/oauth-authorization-server" || path === "/.well-known/oauth-protected-resource" || path.startsWith("/oauth/") || path === "/device" || path === "/device/setup" || path === "/device/oidc/callback") {
 			if (!pairingOn(ctx)) return json({ error: "not_found", error_description: "device-flow pairing is disabled on this inbox (PAIRING_APPROVAL=off); ask its operator for a token" }, 404);
@@ -2489,14 +2547,14 @@ async function handle(req: Request, ctx: TenantContext, ectx: ExecutionContext):
 			if (req.method === "GET" && path === "/.well-known/oauth-protected-resource") return json(protectedResourceMetadata(ctx), 200, { "access-control-allow-origin": "*" });
 			if (req.method === "POST" && path === "/oauth/device_authorization") return await deviceAuthorization(req, ctx, ectx);
 			if (req.method === "POST" && path === "/oauth/token") return await tokenEndpoint(req, ctx);
-			if (path === "/device" && (req.method === "GET" || req.method === "POST")) return await devicePage(req, ctx, url);
-			if (req.method === "GET" && path === "/device/oidc/callback") return await deviceOidcCallback(req, ctx, url);
-			if (path === "/device/setup" && (req.method === "GET" || req.method === "POST")) return await setupPage(req, ctx, url);
+			if (path === "/device" && (req.method === "GET" || req.method === "POST")) return await devicePage(req, ctx, url, head);
+			if (req.method === "GET" && path === "/device/oidc/callback") return await deviceOidcCallback(req, ctx, url, head);
+			if (path === "/device/setup" && (req.method === "GET" || req.method === "POST")) return await setupPage(req, ctx, url, head);
 			return json({ error: "not found" }, 404);
 		}
 		if (req.method === "POST" && (path === "/" || path === "/a2a" || path === "/a2a/v1")) return await handleRpc(req, ctx, ectx);
 		if (req.method === "POST" && path === "/push") return await handlePush(req, ctx, ectx);
-		if (path === "/owner" || path.startsWith("/owner/")) return await handleOwner(req, ctx, ectx, path, url);
+		if (path === "/owner" || path.startsWith("/owner/")) return await handleOwner(req, ctx, ectx, path, url, false, head);
 		if ((req.method === "GET" || req.method === "HEAD") && path === "/") return await landing(req, ctx, url);
 		return json({ error: "not found" }, 404);
 	} catch (e: any) {

package/worker/test/approval-oidc.test.ts

@@ -369,6 +369,37 @@ test("email allowlist matches and a hosted tenant uses its own approval, not the
 	assert.equal(s.tokenBodies.at(-1)!.client_secret, "tenant-secret");
 });
 
+test("HEAD on an OpenID Connect callback leaves the sign-in unused", async (t) => {
+	const s = setup(oidcEnv); t.after(s.restore);
+	const d = await s.start();
+	const { post } = await s.postOidc(d.data.user_code);
+	assert.equal(post.status, 302, post.text);
+	const loc = new URL(post.headers.get("location")!);
+	const state = loc.searchParams.get("state")!;
+	s.setClaims(() => claims({ nonce: loc.searchParams.get("nonce")! }));
+	const head = await s.call("HEAD", `/device/oidc/callback?code=auth-code&state=${state}`);
+	assert.equal(head.status, 200);
+	assert.equal(head.text, "");
+	assert.match(head.headers.get("content-type") || "", /^text\/html/);
+	assert.equal(s.tokenBodies.length, 0);
+	assert.equal(s.DB.db.prepare("SELECT COUNT(*) AS n FROM oidc_txns WHERE state = ?").get(state)!.n, 1);
+	const back = await s.call("GET", `/device/oidc/callback?code=auth-code&state=${state}`);
+	assert.equal(back.status, 200, back.text);
+	assert.match(back.text, /Approved/);
+	assert.equal(s.tokenBodies.length, 1);
+
+	const again = await s.start();
+	const started = await s.postOidc(again.data.user_code);
+	const state2 = new URL(started.post.headers.get("location")!).searchParams.get("state")!;
+	const denied = await s.call("HEAD", `/device/oidc/callback?error=access_denied&state=${state2}`);
+	assert.equal(denied.status, 400);
+	assert.equal(denied.text, "");
+	assert.equal(s.DB.db.prepare("SELECT COUNT(*) AS n FROM oidc_txns WHERE state = ?").get(state2)!.n, 1);
+	const still = await s.call("GET", `/device/oidc/callback?error=access_denied&state=${state2}`);
+	assert.equal(still.status, 400);
+	assert.equal(s.DB.db.prepare("SELECT COUNT(*) AS n FROM oidc_txns WHERE state = ?").get(state2)!.n, 0);
+});
+
 test("MCP consent offers Continue with the issuer and the callback issues the authorization code", async (t) => {
 	const s = setup(oidcEnv); t.after(s.restore);
 	const reg = await s.call("POST", "/oauth/register", { json: { client_name: "Claude", redirect_uris: ["https://claude.ai/api/mcp/auth_callback"] } });
@@ -386,7 +417,15 @@ test("MCP consent offers Continue with the issuer and the callback issues the au
 	const loc = new URL(post.headers.get("location")!);
 	assert.equal(loc.search.includes("st-1"), false, "the MCP state is not the identity provider's state");
 	s.setClaims(() => claims({ nonce: loc.searchParams.get("nonce")! }));
-	const back = await s.call("GET", `/oauth/authorize/oidc/callback?code=auth-code&state=${loc.searchParams.get("state")}`);
+	const state = loc.searchParams.get("state")!;
+	const head = await s.call("HEAD", `/oauth/authorize/oidc/callback?code=auth-code&state=${state}`);
+	assert.equal(head.status, 400);
+	assert.equal(head.text, "");
+	assert.equal(head.headers.get("location"), null);
+	assert.equal(s.tokenBodies.length, 0);
+	assert.equal(s.DB.db.prepare("SELECT COUNT(*) AS n FROM oidc_txns WHERE state = ?").get(state)!.n, 1);
+	assert.equal(s.DB.db.prepare("SELECT COUNT(*) AS n FROM oauth_codes").get()!.n, 0);
+	const back = await s.call("GET", `/oauth/authorize/oidc/callback?code=auth-code&state=${state}`);
 	assert.equal(back.status, 302, back.text);
 	const callbackError = await s.call("GET", "/oauth/authorize/oidc/callback?error=access_denied");
 	assert.equal(callbackError.status, 400);

package/worker/test/hosted.test.ts

@@ -181,6 +181,17 @@ test("per-tenant SQLite: directory, config push, and isolation", async (t) => {
 	await kv.put("tenant:bobby", JSON.stringify({ id: "id-bobby", status: "active", region: "", version: 1 }));
 
 	const card = async (name: string, headers?: HeadersInit) => (await mf.dispatchFetch(`https://${name}.example.com/.well-known/agent-card.json`, { headers })).json() as Promise<{ name: string }>;
+	const aliceCard = await mf.dispatchFetch("https://alice.example.com/.well-known/agent-card.json");
+	assert.equal(aliceCard.headers.get("cache-control"), "public, max-age=60");
+	assert.equal((await aliceCard.json() as { name: string }).name, "Alice");
+	const aliceHead = await mf.dispatchFetch("https://alice.example.com/.well-known/agent-card.json", { method: "HEAD" });
+	assert.equal(aliceHead.status, 200);
+	assert.equal(await aliceHead.text(), "");
+	assert.equal(aliceHead.headers.get("content-type"), "application/json");
+	assert.equal(aliceHead.headers.get("cache-control"), "public, max-age=60");
+	const aliceLegacy = await mf.dispatchFetch("https://alice.example.com/.well-known/agent.json", { method: "HEAD" });
+	assert.equal(aliceLegacy.status, 200);
+	assert.equal(await aliceLegacy.text(), "");
 	assert.equal((await card("alice")).name, "Alice");
 	assert.equal((await card("bobby")).name, "Bob");
 	assert.equal((await card("alice", { "x-a2a-tenant": JSON.stringify({ name: "bob", config: { AGENT_NAME: "Bob" } }) })).name, "Alice");

package/worker/test/mcp.test.ts

@@ -578,11 +578,23 @@ test("metadata advertises CIMD and RFC 9207 iss; DCR accepts application_type; n
 test("Client ID Metadata Documents: fetched, validated, cached; consent shows the client_id host; tokens and refresh work", async (t) => {
 	const s = setup(); t.after(s.restore);
 	s.cimd["/oauth/metadata.json"] = { body: cimdDoc(), headers: { "cache-control": "max-age=600" } };
+	const challenge = await M.s256(b64url(crypto.getRandomValues(new Uint8Array(32))));
+	const probe = new URLSearchParams({ response_type: "code", client_id: CIMD_ID, redirect_uri: CLAUDE_CB, state: "s1", code_challenge: challenge, code_challenge_method: "S256" });
+	const head = await s.call("HEAD", `/oauth/authorize?${probe}`);
+	assert.equal(head.status, 400);
+	assert.equal(head.text, "");
+	assert.equal(s.cimdFetches.length, 0, "HEAD does not fetch client metadata");
+	assert.equal(s.DB.db.prepare("SELECT COUNT(*) AS n FROM oauth_client_metadata").get()!.n, 0);
+	assert.equal(s.DB.db.prepare("SELECT COUNT(*) AS n FROM pairing_rate WHERE key LIKE 'cimd:%'").get()!.n, 0);
 	const r = await authorizeWith(s, CIMD_ID, { resource: `${BASE}/mcp` });
 	assert.equal(r.page.status, 200, r.page.text);
 	assert.match(r.page.text, /CIMD Client/);
 	assert.match(r.page.text, /Client identity published at<\/th><td>client\.example\.org/);
 	assert.equal(s.cimdFetches.length, 1);
+	const cached = await s.call("HEAD", `/oauth/authorize?${new URLSearchParams(r.q)}`);
+	assert.equal(cached.status, 200);
+	assert.equal(cached.text, "");
+	assert.equal(s.cimdFetches.length, 1, "a cached document is not fetched again for HEAD");
 	assert.equal(s.cimdFetches[0].ip, "93.184.216.34", "connected to the DNS-checked address (pinned: no rebinding)");
 	assert.equal(s.cimdFetches[0].sni, "client.example.org", "TLS verified for the client_id host");
 	assert.equal(s.cimdFetches[0].port, 443);

package/worker/test/pairing.test.ts

@@ -62,6 +62,65 @@ function setup(over: Record<string, string> = {}) {
 	return { env, DB, wakes, call, owner, start, poll, decidePage, restore: () => { globalThis.fetch = origFetch; } };
 }
 
+test("HEAD answers like GET with an empty body, and a self-hosted card stays cached for 5 minutes", async (t) => {
+	const s = setup();
+	t.after(s.restore);
+	const get = await s.call("GET", "/.well-known/agent-card.json");
+	assert.equal(get.status, 200);
+	assert.equal(get.headers.get("cache-control"), "public, max-age=300");
+	const head = await s.call("HEAD", "/.well-known/agent-card.json");
+	assert.equal(head.status, 200);
+	assert.equal(head.text, "");
+	assert.equal(head.headers.get("cache-control"), "public, max-age=300");
+	assert.match(head.headers.get("content-type") ?? "", /^application\/json/);
+	const legacy = await s.call("HEAD", "/.well-known/agent.json");
+	assert.equal(legacy.status, 200);
+	assert.equal(legacy.text, "");
+	assert.equal(legacy.headers.get("cache-control"), "public, max-age=300");
+	const health = await s.call("HEAD", "/health");
+	assert.equal(health.status, 200);
+	assert.equal(health.text, "");
+	assert.match(health.headers.get("content-type") ?? "", /^application\/json/);
+	const missing = await s.call("HEAD", "/no-such-route");
+	assert.equal(missing.status, 404);
+	assert.equal(missing.text, "");
+	const owner = await s.call("HEAD", "/owner/peers");
+	assert.equal(owner.status, 401);
+	assert.equal(owner.text, "");
+});
+
+test("HEAD does not spend setup or pairing lookup limits", async (t) => {
+	const s = setup();
+	t.after(s.restore);
+	const link = (await s.owner("POST", "/owner/pairing/password-link", {})).data;
+	const path = new URL(link.url).pathname + new URL(link.url).search;
+	const ip = "192.0.2.20";
+	for (let i = 0; i < P.LIMITS.setupPerIp; i++) {
+		const h = await s.call("HEAD", path, { ip });
+		assert.equal(h.status, 200, h.text);
+		assert.equal(h.text, "");
+	}
+	assert.equal(s.DB.db.prepare("SELECT COUNT(*) AS n FROM pairing_rate WHERE key = ?").get(`setup:ip:${ip}`)!.n, 0);
+	for (let i = 0; i < P.LIMITS.setupPerIp; i++) assert.equal((await s.call("GET", path, { ip })).status, 200);
+	const blocked = await s.call("HEAD", path, { ip });
+	assert.equal(blocked.status, 429);
+	assert.equal(blocked.text, "");
+	assert.equal((s.DB.db.prepare("SELECT count FROM pairing_rate WHERE key = ?").get(`setup:ip:${ip}`) as { count: number }).count, P.LIMITS.setupPerIp);
+	assert.equal((await s.call("GET", path, { ip })).status, 429);
+
+	const d = await s.start(undefined, "192.0.2.21");
+	const look = `/device?user_code=${d.data.user_code}`;
+	for (let i = 0; i < P.LIMITS.lookupsPerIp; i++) {
+		const h = await s.call("HEAD", look, { ip: "192.0.2.21" });
+		assert.equal(h.status, 200);
+		assert.equal(h.text, "");
+	}
+	const page = await s.call("GET", look, { ip: "192.0.2.21" });
+	assert.equal(page.status, 200);
+	assert.match(page.text, /Barry Bot/);
+	assert.equal(page.text.includes("Too many code lookups"), false);
+});
+
 test("pairing helpers: user codes, labels, requester text, params, password hashing", async () => {
 	for (let i = 0; i < 200; i++) assert.match(P.newUserCode(), /^[BCDFGHJKLMNPQRSTVWXZ]{4}[2-9]{4}$/);
 	assert.equal(P.formatUserCode("WDJB4827"), "WDJB-4827");
@@ -753,4 +812,10 @@ test("owner log lists history without data_json and does not clear a pending wak
 	const inbox = await s.owner("GET", "/owner/inbox");
 	assert.equal(inbox.status, 200);
 	assert.equal(s.DB.db.prepare("SELECT pending_json FROM wakes WHERE context_id = ?").get("ctx-keep")?.pending_json, null);
+	const again = JSON.stringify({ taskIds: [taskId] });
+	s.DB.db.prepare("UPDATE wakes SET pending_json = ?, pending_since_ms = ? WHERE context_id = ?").run(again, Date.now(), "ctx-keep");
+	const head = await s.owner("HEAD", "/owner/inbox");
+	assert.equal(head.status, 200);
+	assert.equal(head.text, "");
+	assert.equal(s.DB.db.prepare("SELECT pending_json FROM wakes WHERE context_id = ?").get("ctx-keep")?.pending_json, again);
 });