a2a-exposed 0.8.33 → 0.8.34

package/lib/link-finish.mjs

@@ -1,11 +1,71 @@
 import crypto from "node:crypto";
 import path from "node:path";
 import os from "node:os";
+import { domainToASCII } from "node:url";
+import { isIP } from "node:net";
 import { CliError } from "./a2a.mjs";
 import { controlOrigin } from "./account.mjs";
 import * as C from "./config.mjs";
 import { readSigningSecret, validateSecretSource, writeTokenFile, startConnector, connectorCommand } from "./local-link.mjs";
 
+// Keep JSON diagnostics local: never serialize arbitrary service fields or errors.
+function resultShape(ok, code, next, details = {}) {
+	return { ok, code, reason: null, field: null, phase: null, status: null, hostname: null, next, ...details };
+}
+function linkError(code, next, details = {}) {
+	const error = new CliError(next);
+	error.result = resultShape(false, code, next, details);
+	return error;
+}
+const presetNext = "Pass --preset ID selected from hosted capabilities --json before requesting approval.";
+
+export function normalizeHostname(value) {
+	const invalid = (reason, next) => { throw linkError("invalid_hostname", next, { field: "hostname", reason, phase: "validation" }); };
+	if (typeof value !== "string" || !value.trim()) invalid("required", "Pass --hostname with a full DNS hostname on your Cloudflare domain.");
+	let hostname = value.trim();
+	if (/[\s\\\x00-\x1f\x7f]/.test(hostname)) invalid("characters", "--hostname must not contain whitespace, control characters or backslashes.");
+	if (hostname.includes("://")) {
+		if (!/^https:\/\//i.test(hostname)) invalid("scheme", "--hostname accepts a DNS hostname or an HTTPS URL.");
+		// Inspect authority before URL normalization can remove a default port or path.
+		const authority = hostname.slice(8).split(/[/?#]/, 1)[0];
+		if (authority.includes("@")) invalid("credentials", "--hostname must not contain URL credentials.");
+		if (authority.includes(":")) invalid("port", "--hostname must not contain a port.");
+		if (/[?#]/.test(hostname)) invalid("query_fragment", "--hostname must not contain a query or fragment.");
+		const suffix = hostname.slice(8 + authority.length);
+		if (suffix && suffix !== "/") invalid("path", "--hostname HTTPS URLs must have no path beyond /.");
+		hostname = authority;
+	} else {
+		if (hostname.includes("@")) invalid("credentials", "--hostname must not contain URL credentials.");
+		if (hostname.includes(":")) invalid("port", "--hostname must not contain a scheme or port; use an HTTPS URL or a DNS hostname.");
+		if (/[/?#]/.test(hostname)) invalid("path", "--hostname must not contain a path, query or fragment.");
+	}
+	// IDNA also normalizes Unicode dot separators. Remove exactly one root dot.
+	hostname = domainToASCII(hostname).toLowerCase().replace(/\.$/, "");
+	if (isIP(hostname) || /^\d+(?:\.\d+)*$/.test(hostname)) invalid("ip_address", "--hostname must be a DNS hostname, not an IP address.");
+	if (!hostname || hostname.length > 253 || !hostname.split(".").every(label => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)))
+		invalid("dns_labels", "--hostname needs DNS labels of 1–63 letters, digits or hyphens, with no empty labels or leading/trailing hyphens (253 characters maximum).");
+	if (!hostname.includes(".") || !/^(?:[a-z]{2,63}|xn--[a-z0-9-]{1,59})$/.test(hostname.split(".").at(-1)))
+		invalid("domain", "--hostname must be a full DNS hostname with a valid domain suffix.");
+	return hostname;
+}
+
+export function linkUsage() {
+	throw linkError("usage", "Use hosted link create --agent NAME --hostname HOST --origin URL --path PATH --preset ID [--json], or hosted link finish --agent NAME --preset ID [--json]; choose exactly one protected --secret-file FILE, --secret-env VAR, or --secret-from hermes. List choices with hosted list --json and hosted capabilities --json.", { phase: "validation" });
+}
+
+export async function linkOutput(run, o = {}) {
+	try {
+		const result = await run();
+		if (o.json) console.log(JSON.stringify(resultShape(true, result.saved ? "saved" : "connector_saved",
+			result.saved ? "The connector connected; the wake test passed and settings were saved." : "Start cloudflared with the saved token file, then run hosted link finish with --preset ID for fresh approval.",
+			{ phase: result.saved ? "wake-test" : "connector", hostname: result.hostname, ...result })));
+	} catch (error) {
+		if (!o.json) throw error;
+		console.log(JSON.stringify(error.result || resultShape(false, "local_failure", "Hosted link setup did not finish. Check the local secret source, token-file permissions and cloudflared, then request fresh approval.")));
+		process.exitCode = 1;
+	}
+}
+
 const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const ERRORS = {
 	expired_token: "The link request expired. Start a new one with hosted link create.",
@@ -70,7 +130,7 @@ const VALIDATION_MESSAGES = new Set([
 	"Use an http or https origin with no path or credentials.",
 	"Use a path beginning with /, with no query or fragment.",
 ]);
-const DOMAIN = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
+const DOMAIN = /^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+(?:[a-z]{2,63}|xn--[a-z0-9-]{1,59})$/;
 function validationDetail(body, hostname) {
 	if (typeof body?.message !== "string") return "";
 	if (VALIDATION_MESSAGES.has(body.message)) return body.message.replace(/ and try again\.$/, ".");
@@ -105,12 +165,17 @@ function failure(status, body, { command, hostname }, phase = "requests") {
 		: `The link request expired. Start a new one with hosted link ${command}.`;
 	if (code === "invalid_request" && phase === "token") guidance = `The approval polling request was refused. Run hosted link ${command} again for fresh approval.`;
 	const message = detail || guidance.replace(/run finish/gi, (match) => `${match.startsWith("R") ? "Run" : "run"} ${command}`);
-	return new CliError(`link ${command} failed${hostname ? ` for ${hostname}` : ""} (${code}); ${message}`);
+	const reason = ["hostname_format", "origin_format", "path_format", "hostname_invalid", "preset_invalid", "origin_invalid", "path_invalid", "apex_hostname", "outside_zone", "existing_dns", "existing_tunnel"].includes(body?.reason) ? body.reason : known(body?.reason) ? body.reason : null;
+	const field = ["hostname", "origin", "path", "preset"].includes(body?.field) ? body.field : null;
+	const provisionPhase = ["cleanup", "hostname", "zone", "existing_dns", "existing_tunnel"].includes(body?.phase) ? body.phase : null;
+	return linkError(code.startsWith("HTTP ") ? `http_${status}` : code,
+		`link ${command} failed${hostname ? ` for ${hostname}` : ""} (${code}); ${message}`,
+		{ reason, field, phase: code === "provision_failed" && provisionPhase ? provisionPhase : phase, status: code === "provision_failed" && Number.isInteger(body?.status) && body.status >= 100 && body.status <= 599 ? body.status : status, hostname: hostname || null });
 }
 
 export function savedLinkSession(origin, session = C.controlSession(), command = "finish") {
 	if (controlOrigin(session.origin) !== origin || !session.token)
-		throw new CliError(`sign in to this service first: run login --control-url <service-origin>, then rerun hosted link ${command}; environment sessions require both CONTROL_URL and CONTROL_TOKEN`);
+		throw linkError("login_required", `sign in to this service first: run login --control-url <service-origin>, then rerun hosted link ${command}; environment sessions require both CONTROL_URL and CONTROL_TOKEN`, { phase: "validation" });
 	return session.token;
 }
 
@@ -118,18 +183,16 @@ const CREATE_FIELDS = ["hostname", "origin", "path", "preset"];
 
 function createPlan(o) {
 	for (const key of CREATE_FIELDS) {
-		if (typeof o[key] !== "string" || !o[key]) throw new CliError(`hosted link create requires --${key}`);
+		if (typeof o[key] !== "string" || !o[key]) throw linkError("required", `hosted link create requires --${key}${key === "preset" ? "; " + presetNext : ""}`, { field: key, reason: "required", phase: "validation" });
 	}
-	const hostname = o.hostname.trim().toLowerCase();
-	if (!/^(?=.{1,253}$)([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(hostname))
-		throw new CliError("--hostname must be a DNS hostname on your Cloudflare domain");
+	const hostname = normalizeHostname(o.hostname);
 	let origin;
-	try { origin = new URL(o.origin); } catch { throw new CliError("--origin must be an http or https origin"); }
+	try { origin = new URL(o.origin); } catch { throw linkError("invalid_origin", "--origin must be an http or https origin", { field: "origin", phase: "validation" }); }
 	if (!/^https?:$/.test(origin.protocol) || origin.username || origin.password || origin.pathname !== "/" || origin.search || origin.hash)
-		throw new CliError("--origin must be an http or https origin with no path or credentials");
+		throw linkError("invalid_origin", "--origin must be an http or https origin with no path or credentials", { field: "origin", phase: "validation" });
 	if (!o.path.startsWith("/") || o.path.startsWith("//") || /[\s?#\\\x00-\x1f\x7f]/.test(o.path) || o.path.length > 1000)
-		throw new CliError("--path must begin with / and have no query, fragment or whitespace");
-	if (!/^[a-z][a-z0-9-]{0,63}$/.test(o.preset)) throw new CliError("--preset must be a wake preset id");
+		throw linkError("invalid_path", "--path must begin with / and have no query, fragment or whitespace", { field: "path", phase: "validation" });
+	if (!/^[a-z][a-z0-9-]{0,63}$/.test(o.preset)) throw linkError("preset", presetNext, { field: "preset", reason: o.preset === undefined || o.preset === "" ? "required" : "preset_invalid", phase: "validation" });
 	return { hostname, origin: origin.origin, path: o.path, preset: o.preset };
 }
 
@@ -138,12 +201,12 @@ export function createLink(o, deps) {
 	// Catch a wrong local route before asking the owner to create any resources.
 	validateSecretSource(o);
 	if (o["secret-from"] === "hermes" && (create.preset !== "hermes" || !/^\/webhooks\/[A-Za-z0-9_-]+$/.test(create.path) || (o.route && create.path !== `/webhooks/${o.route}`)))
-		throw new CliError("Hermes route does not match the create path and preset");
+		throw linkError("route_mismatch", "Hermes route does not match the create path and preset", { field: "path", phase: "validation" });
 	return setupLink(o, deps, create);
 }
 
 export function finishLink(o, deps) {
-	if (CREATE_FIELDS.filter((key) => key !== "preset").some((key) => o[key] !== undefined)) throw new CliError("creation options require hosted link create; finish only reuses an existing link");
+	if (CREATE_FIELDS.filter((key) => key !== "preset").some((key) => o[key] !== undefined)) throw linkError("usage", "creation options require hosted link create; finish only reuses an existing link", { phase: "validation" });
 	return setupLink(o, deps);
 }
 
@@ -156,10 +219,10 @@ async function setupLink(o, {
 	validateSecretSource(o);
 	const context = { command: create ? "create" : "finish", hostname: create?.hostname };
 	const agent = o.agent;
-	if (typeof agent !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}$/.test(agent)) throw new CliError("--agent must be an agent name (letters, digits, underscores or hyphens)");
-	if (o.preset !== undefined && (typeof o.preset !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(o.preset))) throw new CliError("--preset must be a wake preset id");
+	if (typeof agent !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,62}$/.test(agent)) throw linkError("agent", "--agent must be an agent name (letters, digits, underscores or hyphens); select it with hosted list --json", { field: "agent", phase: "validation" });
+	if (typeof o.preset !== "string" || !/^[a-z][a-z0-9-]{0,63}$/.test(o.preset)) throw linkError("preset", presetNext, { field: "preset", reason: o.preset === undefined || o.preset === "" ? "required" : "preset_invalid", phase: "validation" });
 	const origin = controlOrigin(o["control-url"]);
-	if (!origin) throw new CliError("--control-url must be an https origin with no path");
+	if (!origin) throw linkError("control_url", "--control-url must be an https origin with no path", { field: "control-url", phase: "validation" });
 	const session = sessionToken(origin, undefined, context.command);
 	const request = async (endpoint, body, grant, timeout = 15000) => {
 		let response;
@@ -174,7 +237,7 @@ async function setupLink(o, {
 			const parsed = JSON.parse(text);
 			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
 			return { response, body: parsed };
-		} catch { throw new CliError(`link ${context.command} request failed; check the connection and run ${context.command} again for fresh approval`); }
+		} catch { throw linkError("unavailable", `link ${context.command} request failed; check the connection and run ${context.command} again for fresh approval`, { phase: endpoint, hostname: context.hostname || null }); }
 	};
 	const verifier = crypto.randomBytes(32).toString("base64url");
 	const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
@@ -182,9 +245,9 @@ async function setupLink(o, {
 	if (started.response.status !== 201) throw failure(started.response.status, started.body, context);
 	const setup = started.body;
 	let approval;
-	try { approval = new URL(setup.approve_url); } catch { throw new CliError("invalid approval response"); }
+	try { approval = new URL(setup.approve_url); } catch { throw linkError("invalid_response", "invalid approval response", { phase: "requests" }); }
 	if (approval.origin !== origin || approval.username || approval.password || typeof setup.request_id !== "string" || !setup.request_id || typeof setup.user_code !== "string" || !/^[A-Za-z0-9-]{4,32}$/.test(setup.user_code))
-		throw new CliError("invalid approval response");
+		throw linkError("invalid_response", "invalid approval response", { phase: "requests" });
 	write(`${setup.approve_url}\n${setup.user_code}`);
 	const deadline = now() + Math.min(600, Math.max(1, Number(setup.expires_in) || 600)) * 1000;
 	let interval = Math.min(60, Math.max(5, Number(setup.interval) || 5)), authorized;
@@ -200,21 +263,22 @@ async function setupLink(o, {
 	if (!authorized) throw failure(410, { error: "expired_token" }, context, "token");
 	const { grant, link } = authorized;
 	if (typeof grant !== "string" || !/^[\x21-\x7e]+$/.test(grant) || grant.length > 4096 || link?.agent !== agent || typeof link.path !== "string" || !link.path.startsWith("/") || typeof link.preset !== "string" || typeof link.hostname !== "string" || typeof link.origin !== "string")
-		throw new CliError("invalid approved link response");
+		throw linkError("invalid_response", "invalid approved link response", { phase: "token" });
 	if (create && CREATE_FIELDS.some((key) => link[key] !== create[key]))
-		throw new CliError("approved link differs from the requested creation plan; no connector or signing secret was transferred");
-	const preset = o.preset ?? link.preset;
-	if (!/^[a-z][a-z0-9-]{0,63}$/.test(preset)) throw new CliError("approved link has no valid preset; rerun finish with --preset <id> before requesting fresh approval");
+		throw linkError("plan_mismatch", "approved link differs from the requested creation plan; no connector or signing secret was transferred", { phase: "token", hostname: context.hostname || null });
+	const hostname = normalizeHostname(link.hostname);
+	context.hostname = hostname;
+	const preset = o.preset;
 	// Resolve and validate the source before spending the one-time connector delivery.
 	const secret = readSecret(o, { ...link, preset });
 	const connector = await request("connector", {}, grant);
 	if (!connector.response.ok) throw failure(connector.response.status, connector.body, context, "connector");
-	if (typeof connector.body.connector_token !== "string" || !connector.body.connector_token.trim() || /\s/.test(connector.body.connector_token)) throw new CliError("invalid connector response; run finish again for fresh approval");
+	if (typeof connector.body.connector_token !== "string" || !connector.body.connector_token.trim() || /\s/.test(connector.body.connector_token)) throw linkError("invalid_response", "invalid connector response; run finish again for fresh approval", { phase: "connector" });
 	const tokenFile = path.resolve(o["token-file"] || path.join(os.homedir(), ".a2a-exposed", "links", `${agent}.token`));
 	saveToken(tokenFile, connector.body.connector_token);
 	if (o["no-run"]) {
 		write(connectorCommand(tokenFile));
-		return { saved: false, connectorStarted: false };
+		return { saved: false, connectorStarted: false, hostname };
 	}
 	await runConnector(tokenFile);
 	let connected = false;
@@ -226,21 +290,21 @@ async function setupLink(o, {
 		if (status.body.connector === "connected" && Number.isInteger(status.body.connections) && status.body.connections > 0) { connected = true; break; }
 		await sleep(Math.min(3000, Math.max(0, connectDeadline - now())));
 	}
-	if (!connected) throw new CliError("connector did not report connected within 60 seconds; check cloudflared and run finish again for fresh approval");
+	if (!connected) throw linkError("connector_timeout", "connector did not report connected within 60 seconds; check cloudflared and run finish again for fresh approval", { phase: "status", hostname });
 	const tested = await request("wake-test", { signing_secret: secret, preset }, grant);
 	// These 409 codes come from saveWakeSettings after a successful wake test.
 	const saveRejected = tested.response.status === 409 && ["url", "preset", "header", "key", "unavailable", "unreadable", "conflict", "failed"].includes(tested.body.error);
 	if (!tested.response.ok && !saveRejected) throw failure(tested.response.status, tested.body, context, "grant");
 	if (saveRejected || (tested.body.result === "ok" && tested.body.saved !== true)) {
 		write("wake_result=not-saved");
-		throw new CliError("The test wake was delivered, but the settings were not saved. Save them in Wake settings on the website, then test again. The saved connector token remains on disk.");
+		throw linkError("not_saved", "The test wake was delivered, but the settings were not saved. Save them in Wake settings on the website, then test again. The saved connector token remains on disk.", { phase: "wake-test", status: tested.response.status, hostname });
 	}
 	if (tested.body.result !== "ok") {
 		const { result, message } = wakeFailure(tested.body.result);
 		write(`wake_result=${result}`);
-		throw new CliError(message);
+		throw linkError("wake_failed", message, { reason: result, phase: "wake-test", status: tested.response.status, hostname });
 	}
 	write("wake_result=ok");
 	write("Connector connected. Wake test passed and settings saved.");
-	return { saved: true, connectorStarted: true };
+	return { saved: true, connectorStarted: true, hostname };
 }

package/lib/main.mjs

@@ -13,7 +13,7 @@ import * as hosted from "./hosted.mjs";
 import * as upd from "./update.mjs";
 import * as fb from "./feedback.mjs";
 import * as un from "./uninstall.mjs";
-import { finishLink, createLink } from "./link-finish.mjs";
+import { finishLink, createLink, linkOutput, linkUsage } from "./link-finish.mjs";
 
 const VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
@@ -232,7 +232,8 @@ Inbox (owner side)
                                            history and continue with send. Then pending pairing
                                            requests (tell your human; the dashboard URL when MANAGE_URL is set;
                                            --json: rows on stdout, requests on stderr). Follows every page; past
-                                           10000 pages it errors instead of a short list
+                                           10000 pages it errors instead of a short list. Reading marks returned replies
+                                           seen and clears matching pending wakes; task state is unchanged
   show <taskId>                            full task JSON
   working <taskId>                         mark task working
   reply <taskId> (--text T | --stdin) [--state completed|input-required|rejected|failed|working]
@@ -446,6 +447,7 @@ export async function main(argv) {
 	try {
 		parsed = parseArgs({ args: rest, options: SPEC[name] || {}, allowPositionals: true, strict: true });
 	} catch (e) {
+		if (name === "hosted" && rest.includes("link") && rest.some(value => ["create", "finish"].includes(value)) && rest.includes("--json")) return linkOutput(linkUsage, { json: true });
 		if (e && e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
 			const flag = (String(e.message).match(/'([^']+)'/) || [])[1] || "that flag";
 			if (flag === "-y") throw new CliError("unknown flag -y. To skip a prompt, pass --yes.");
@@ -512,8 +514,8 @@ export async function main(argv) {
 		}
 		case "hosted": {
 			if (p.length === 1 && ["capabilities", "list", "create", "names", "capacity"].includes(p[0])) return hosted.output(() => hosted[p[0]](o), o);
-			if (p.length !== 2 || p[0] !== "link" || !["finish", "create"].includes(p[1])) throw new CliError("usage: hosted link create --agent NAME --hostname HOST --origin URL --path PATH --preset ID (--secret-file FILE | --secret-env VAR | --secret-from hermes); or hosted link finish --agent NAME (--secret-file FILE | --secret-env VAR | --secret-from hermes)");
-			return (p[1] === "create" ? createLink : finishLink)({ ...o, "control-url": o["control-url"] || C.get("CONTROL_URL") });
+			if (p.length !== 2 || p[0] !== "link" || !["finish", "create"].includes(p[1])) return linkOutput(linkUsage, o);
+			return linkOutput(() => (p[1] === "create" ? createLink : finishLink)({ ...o, "control-url": o["control-url"] || C.get("CONTROL_URL") }), o);
 		}
 		case "signup":
 		case "login": {

package/package.json

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

package/worker/src/index.ts

@@ -602,12 +602,12 @@ const agentCard = (ctx: TenantContext): Promise<Json> => (proxyMode(ctx) ? facad
 
 /** The same agent as an A2A 0.3 AgentCard (served at the legacy /.well-known/agent.json for 0.2/0.3 clients): top-level
  *  url + preferredTransport + protocolVersion, OpenAPI-style securitySchemes and `security`. 0.3 has no device-code
- *  flow, so the pairing scheme only points to the RFC 8414 metadata (oauth2MetadataUrl) and is not a requirement. */
+ *  flow, so only bearer authentication is advertised; pairing discovery stays on the 1.0 card. */
 function agentCard03(ctx: TenantContext, c: Json): Json {
 	const base = ctx.PUBLIC_URL.replace(/\/$/, "");
-	const schemes: Json = { bearer: { type: "http", scheme: "bearer", description: c.securitySchemes.bearer.httpAuthSecurityScheme.description } };
-	if (pairingOn(ctx)) schemes.pairing = { type: "oauth2", description: c.securitySchemes.pairing.oauth2SecurityScheme.description,
-		flows: {}, oauth2MetadataUrl: oauthUrls(ctx).metadata };
+	const schemes: Json = { bearer: { type: "http", scheme: "bearer", description: pairingOn(ctx)
+		? `Per-peer bearer token: from device-flow pairing described at ${base}/.well-known/agent-card.json (A2A 1.0), or issued by the agent's operator`
+		: c.securitySchemes.bearer.httpAuthSecurityScheme.description } };
 	const card: Json = {
 		protocolVersion: "0.3.0", name: c.name, description: c.description, url: base + "/", preferredTransport: "JSONRPC",
 		additionalInterfaces: [{ url: base + "/", transport: "JSONRPC" }], version: c.version,
@@ -2663,7 +2663,7 @@ async function devicePage(req: Request, ctx: TenantContext, ectx: ExecutionConte
 			model.askCode = true;
 			model.codeValue = raw || "";
 			if (raw && !notice) {
-				let text = "That is not a valid code (it looks like WDJB-4827).";
+				let text = "Enter four consonants, a hyphen, and four digits.";
 				if (code && !r) { lookupStatus = 404; text = PAIRING_NOT_FOUND; }
 				else if (r && r.status !== "pending") text = `That request was already ${r.status === "denied" ? "denied" : "approved"}.`;
 				else if (code && r) { lookupStatus = 404; text = PAIRING_EXPIRED; }
@@ -2683,6 +2683,11 @@ async function devicePage(req: Request, ctx: TenantContext, ectx: ExecutionConte
 		await show(form.user_code || null, { kind: "error", text: "This form expired or came from another site. Reload the page and try again." });
 		return send(403);
 	}
+	// Code entry is a lookup only; approval and denial remain separate CSRF-protected submissions.
+	if (form.decision === "lookup") {
+		await show(form.user_code || null);
+		return send(lookupStatus);
+	}
 	const code = P.normUserCode(form.user_code);
 	if (!code) { await show(form.user_code || null); return send(400); }
 	// Deny needs no password: it grants nothing, and the worst a holder of the code can do is cancel a pending request

package/worker/src/mcp.ts

@@ -319,8 +319,8 @@ const str = (description: string, extra: Schema = {}): Schema => ({ type: "strin
 const ro = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
 
 export const TOOLS: { name: string; title: string; description: string; inputSchema: Schema; outputSchema?: Schema; annotations: Schema }[] = [
-	{ name: "inbox", title: "Inbox", annotations: ro,
-		description: `Open tasks other agents sent to this A2A endpoint (state submitted or working), oldest first, one page at a time, plus a reply to a message you sent (kind "outbound") until this inbox lists it, plus pending pairing requests. When the result says more tasks are waiting, call inbox again with the cursor before you stop. Handle each inbound task, then answer it with reply. A reply to a message you sent: read it with history, and continue that conversation with send. ${RULES}`,
+	{ name: "inbox", title: "Inbox", annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+		description: `Open tasks other agents sent to this A2A endpoint (state submitted or working), oldest first, one page at a time, plus a reply to a message you sent (kind "outbound") until this inbox lists it, plus pending pairing requests. Reading this page marks returned replies seen and clears matching pending wakes; task state is unchanged. When the result says more tasks are waiting, call inbox again with the cursor before you stop. Handle each inbound task, then answer it with reply. A reply to a message you sent: read it with history, and continue that conversation with send. ${RULES}`,
 		inputSchema: { type: "object", properties: {
 			contextId: str("Only this conversation"),
 			from: str("Only this peer (the wake's from). The same context id can be a different peer's conversation"),

package/worker/src/pairing.ts

@@ -224,7 +224,8 @@ export type PageModel = {
 };
 
 export function devicePage(m: PageModel, nonce: string): string {
-	const notice = m.notice ? `<p class="n ${m.notice.kind}">${esc(m.notice.text)}</p>` : "";
+	const errorAttrs = m.notice?.kind === "error" ? ` aria-invalid="true" aria-describedby="device-error"` : "";
+	const notice = m.notice ? `<p${errorAttrs ? ` id="device-error" role="alert"` : ""} class="n ${m.notice.kind}">${esc(m.notice.text)}</p>` : "";
 	if (m.settled) {
 		const title = m.settled === "approved" ? "Approved" : "Denied";
 		return pageShell(title, nonce, `${notice}<p>You can close this page.</p>`);
@@ -253,14 +254,14 @@ export function devicePage(m: PageModel, nonce: string): string {
 	const passwordOn = m.passwordEnabled !== false;
 	const form = r && passwordOn && m.passwordSet ? `<form method="post" action="/device">
 <input type="hidden" name="csrf" value="${esc(m.csrf)}"><input type="hidden" name="user_code" value="${esc(formatUserCode(r.userCode))}">
-<label for="pw">Approval password (needed to approve; deny works without it)</label><input id="pw" name="password" type="password" autocomplete="current-password" required maxlength="1024" autofocus>
+<label for="pw">Approval password (needed to approve; deny works without it)</label><input id="pw" name="password" type="password"${errorAttrs} autocomplete="current-password" required maxlength="1024" autofocus>
 <div class="b"><button name="decision" value="approve" type="submit">Approve</button><button name="decision" value="deny" type="submit" class="d" formnovalidate>Deny</button></div>
 </form>` : r && passwordOn && !m.passwordSet ? noPassword + denyOnly : r ? denyOnly : "";
 	const oidcForm = m.oidc && r ? `<form method="post" action="/device">
 <input type="hidden" name="csrf" value="${esc(m.csrf)}"><input type="hidden" name="user_code" value="${esc(formatUserCode(r.userCode))}">
 <div class="b"><button name="decision" value="oidc" type="submit">Approve with ${esc(m.oidc.label)}</button></div>
 </form>` : "";
-	const ask = m.askCode ? `<p class="w">The connecting agent prints this code when it runs <code>${esc(`${m.cli} connect <url>`)}</code>. It looks like WDJB-4827.</p><form method="get" action="/device"><label for="uc">Code</label><input id="uc" name="user_code" value="${esc(m.codeValue || "")}" placeholder="WDJB-4827" autocomplete="off" autocapitalize="characters" required maxlength="16" autofocus><div class="b"><button type="submit">Continue</button></div></form>` : "";
+	const ask = m.askCode ? `<p class="w">The connecting agent prints this code when it runs <code>${esc(`${m.cli} connect <url>`)}</code>. Use four consonants, a hyphen, and four digits.</p><form method="post" action="/device"><input type="hidden" name="csrf" value="${esc(m.csrf)}"><input type="hidden" name="decision" value="lookup"><label for="uc">Code</label><input id="uc" name="user_code" value="${esc(m.codeValue || "")}" placeholder="XXXX-0000"${errorAttrs} spellcheck="false" autocomplete="off" autocapitalize="characters" required maxlength="16" autofocus><div class="b"><button type="submit">Continue</button></div></form>` : "";
 	return pageShell(`Connect an agent to ${m.agentName}`, nonce, `${notice}${details}${form}${oidcForm}${ask}`);
 }
 

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.33";
+export const VERSION = "0.8.34";

package/worker/test/facade.test.ts

@@ -195,6 +195,8 @@ test("proxy mode: the served cards are the upstream's, rewritten to the public U
 	const c03 = (await s.call("GET", "/.well-known/agent.json")).data;
 	assert.equal(c03.url, BASE + "/");
 	assert.equal(c03.name, "Jean");
+	assert.deepEqual(Object.keys(c03.securitySchemes), ["bearer"], "0.3 façade omits unsupported pairing flow");
+	assert.deepEqual(c03.security, [{ bearer: [] }]);
 	assert.deepEqual(F.cardLeaks(c03, BASE, [TAILNET]), []);
 	// the card fetch carried the façade's upstream credentials (Access service token + bearer)
 	const cf = s.calls.find((c) => c.url.endsWith("/card-a.json"));

package/worker/test/mcp.test.ts

@@ -851,6 +851,11 @@ test("parseHttpResponse: status, headers, content-length and chunked bodies; mal
 });
 
 test("inbox tool clears wakes only for the page it returns, and a later call can fetch the rest", async (t) => {
+	const inbox = M.TOOLS.find(tool => tool.name === "inbox")!;
+	assert.equal(inbox.annotations.readOnlyHint, false, "inbox acknowledges reads");
+	assert.equal(inbox.annotations.destructiveHint, false, "acknowledgement preserves tasks");
+	assert.match(inbox.description, /marks returned replies seen and clears matching pending wakes/);
+	assert.equal(M.TOOLS.find(tool => tool.name === "history")!.annotations.readOnlyHint, true);
 	const s = setup({ WAKE_DEBOUNCE_SECONDS: "3600" });
 	t.after(s.restore);
 	const a = await s.connect();

package/worker/test/pairing.test.ts

@@ -65,6 +65,66 @@ function setup(over: Record<string, string> = {}) {
 	return { env, DB, wakes, call, owner, start, poll, decidePage, restore: () => { globalThis.fetch = origFetch; } };
 }
 
+test("device code entry posts a CSRF-protected lookup without making a pairing decision", async (t) => {
+	const s = setup(); t.after(s.restore);
+	const d = (await s.start()).data;
+	const entry = await s.call("GET", "/device");
+	assert.match(entry.text, /<form method="post" action="\/device">/);
+	assert.doesNotMatch(entry.text, /method="get"|placeholder="WDJB-4827"|aria-invalid/);
+	assert.match(entry.text, /placeholder="XXXX-0000"/);
+	assert.match(entry.text, /spellcheck="false" autocomplete="off" autocapitalize="characters"/);
+	assert.match(entry.text, /name="decision" value="lookup"/);
+	const cookie = entry.headers.get("set-cookie")!.split(";")[0];
+	const csrf = /name="csrf" value="([^"]+)"/.exec(entry.text)![1];
+	const lookup = (code: string, overrides = {}) => s.call("POST", "/device", {
+		form: { csrf, decision: "lookup", user_code: code }, cookie, headers: { origin: BASE }, ...overrides,
+	});
+	const page = await lookup(d.user_code.toLowerCase());
+	assert.equal(page.status, 200, page.text);
+	assert.equal(page.headers.get("location"), null, "no redirect puts the code in a URL");
+	assert.match(page.text, /Barry Bot/);
+	assert.match(page.text, /name="decision" value="deny"/);
+	assert.doesNotMatch(page.text, /aria-invalid/);
+	assert.equal((await s.poll(d.device_code)).data.error, "authorization_pending");
+	assert.equal(s.DB.db.prepare("SELECT status FROM device_requests").get()!.status, "pending");
+	assert.equal((await lookup(d.user_code, { cookie: "" })).status, 403);
+	assert.equal((await lookup(d.user_code, { headers: { origin: "https://evil.example" } })).status, 403);
+	assert.equal((await lookup(d.user_code, { form: { decision: "lookup", user_code: d.user_code } })).status, 403);
+	const invalid = await lookup("<bad>");
+	assert.equal(invalid.status, 200);
+	assert.match(invalid.text, /value="&lt;bad&gt;"/);
+	assert.match(invalid.text, /<input id="uc"[^>]*aria-invalid="true" aria-describedby="device-error"/);
+	assert.match(invalid.text, /<p id="device-error" role="alert"[^>]*>Enter four consonants/);
+	assert.equal((await lookup("BCDF-2345")).status, 404);
+	advance(3601);
+	const expired = await lookup(d.user_code);
+	assert.equal(expired.status, 404);
+	assert.match(expired.text, /aria-describedby="device-error"/);
+	assert.match(expired.text, /expired/i);
+});
+
+test("POST code lookups keep the existing IP limit", async (t) => {
+	const s = setup(); t.after(s.restore);
+	const g = await s.call("GET", "/device");
+	const cookie = g.headers.get("set-cookie")!.split(";")[0];
+	const csrf = /name="csrf" value="([^"]+)"/.exec(g.text)![1];
+	const lookup = () => s.call("POST", "/device", { form: { csrf, decision: "lookup", user_code: "BCDF-2345" }, cookie, headers: { origin: BASE } });
+	for (let i = 0; i < P.LIMITS.lookupsPerIp; i++) assert.equal((await lookup()).status, 404);
+	const limited = await lookup();
+	assert.match(limited.text, /Too many code lookups/);
+	assert.match(limited.text, /<input id="uc"[^>]*aria-invalid="true" aria-describedby="device-error"/);
+});
+
+test("wrong approval passwords identify the password input and error text", async (t) => {
+	const s = setup(); t.after(s.restore);
+	assert.equal((await s.owner("PUT", "/owner/pairing/password", await passwordRecord())).status, 200);
+	const d = (await s.start()).data;
+	const page = await s.decidePage(d.user_code, "wrong password", "approve");
+	assert.equal(page.status, 403);
+	assert.match(page.text, /<input id="pw"[^>]*aria-invalid="true" aria-describedby="device-error"/);
+	assert.match(page.text, /<p id="device-error" role="alert"[^>]*>Wrong password/);
+});
+
 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);
@@ -208,8 +268,8 @@ test("/.well-known/agent.json serves an A2A 0.3 card (url, preferredTransport, p
 	assert.deepEqual([old.name, old.version], ["Test Inbox", "1.0.0"]);
 	assert.deepEqual(old.capabilities, { streaming: false, pushNotifications: true, stateTransitionHistory: false });
 	assert.deepEqual(old.securitySchemes.bearer, { type: "http", scheme: "bearer", description: old.securitySchemes.bearer.description });
-	assert.equal(old.securitySchemes.pairing.type, "oauth2");
-	assert.equal(old.securitySchemes.pairing.oauth2MetadataUrl, `${BASE}/.well-known/oauth-authorization-server`);
+	assert.deepEqual(Object.keys(old.securitySchemes), ["bearer"], "0.3 has no device-code OAuth flow");
+	assert.match(old.securitySchemes.bearer.description, /device-flow pairing described at https:\/\/agent\.example\.com\/\.well-known\/agent-card\.json/);
 	assert.deepEqual(old.security, [{ bearer: [] }]);
 	assert.deepEqual(old.skills, [{ id: "s1", name: "S1", description: "d", tags: [] }], "0.3 requires tags");
 	assert.equal(old.supportedInterfaces, undefined, "no 1.0-only fields");
@@ -903,7 +963,7 @@ test("device page copy: code hint, expiry, token scope, settled result, A2A endp
 	const base = { agentName: "this A2A endpoint", mode: "human" as const, cli: "a2a", csrf: "c".repeat(24), passwordSet: true };
 	const bare = P.devicePage({ ...base, askCode: true }, "n");
 	assert.match(bare, /The connecting agent prints this code when it runs <code>a2a connect &lt;url&gt;<\/code>/);
-	assert.match(bare, /It looks like WDJB-4827/);
+	assert.match(bare, /four consonants, a hyphen, and four digits/);
 	assert.match(bare, /<title>Connect an agent to this A2A endpoint<\/title>/);
 	const req = { userCode: "WDJB4827", clientName: "Barry", clientId: "barry", agentCardUrl: "http://127.0.0.1/card", ip: "192.0.2.1", country: "", createdMs: now, expiresMs: now + 20_000 };
 	const page = P.devicePage({ ...base, request: req }, "n");
@@ -934,7 +994,7 @@ test("device page copy: code hint, expiry, token scope, settled result, A2A endp
 	const s = setup(); t.after(s.restore);
 	const empty = await s.call("GET", "/device");
 	assert.match(empty.text, /prints this code when it runs/);
-	assert.match(empty.text, /WDJB-4827/);
+	assert.match(empty.text, /placeholder="XXXX-0000"/);
 	const named = setup({ AGENT_NAME: "" }); t.after(named.restore);
 	const title = await named.call("GET", "/device");
 	assert.match(title.text, /Connect an agent to this A2A endpoint/);