a2a-exposed 0.8.33 → 0.8.35

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.35",
 	"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/hosted.ts

@@ -163,9 +163,6 @@ export class TenantStore extends DurableObject<WorkerBindings> {
 		// config_json is ignored, and a blob that cannot be opened leaves those fields unset.
 		if (row.secretsEnc) {
 			const opened = await openWakeSecrets(parsed.secretsKey || "", row.tenantId, row.secretsEnc);
-			if (!opened) {
-				console.log(JSON.stringify({ ts: new Date().toISOString(), event: "wake_secrets_unreadable", tenant: row.tenantId }));
-			}
 			for (const key of WAKE_SECRET_KEYS) {
 				const value = opened?.[key];
 				if (value) config[key] = value;

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,
@@ -1233,14 +1233,21 @@ async function withMovedHeader(ctx: TenantContext, res: Response): Promise<Respo
 	return new Response(res.body, { status: res.status, statusText: res.statusText, headers });
 }
 
+/** Every hosted credential sealed by peerKey must retain the previous key during rotation. */
+async function openPeerSecret(ctx: TenantContext, aad: string, sealed: string): Promise<string | null> {
+	for (const key of await ctx.peerReadKeys()) {
+		const opened = await M.openPeerTokenWithKey(key, aad, sealed);
+		if (opened !== null) return opened;
+	}
+	return null;
+}
+
 type PairingIdentity = { publicKey: string; privateKey: string };
 
 async function readIdentity(ctx: TenantContext): Promise<PairingIdentity | null | "unreadable"> {
 	const row: Json = await ctx.DB.prepare("SELECT value FROM settings WHERE key = ?").bind(Addr.IDENTITY_SETTING).first();
 	if (!row?.value) return null;
-	const key = await ctx.peerKey();
-	if (!key) return "unreadable";
-	const opened = await M.openPeerTokenWithKey(key, Addr.IDENTITY_AAD, row.value);
+	const opened = await openPeerSecret(ctx, Addr.IDENTITY_AAD, row.value);
 	if (!opened) return "unreadable";
 	try {
 		const parsed = JSON.parse(opened);
@@ -1411,8 +1418,7 @@ async function planReverse(ctx: TenantContext, alias: string): Promise<{ kind: "
 async function openReverse(ctx: TenantContext, label: string): Promise<string | null> {
 	const row: Json = await ctx.DB.prepare("SELECT token_enc, source, revoked_at FROM peers WHERE label = ?").bind(label).first();
 	if (!row || row.revoked_at || row.source !== "reverse" || !row.token_enc) return null;
-	const key = await ctx.peerKey();
-	return key ? await M.openPeerTokenWithKey(key, label, row.token_enc) : null;
+	return openPeerSecret(ctx, label, row.token_enc);
 }
 
 async function storeReverse(ctx: TenantContext, label: string, token: string, clientName: string, reissue = false): Promise<void> {
@@ -1544,8 +1550,7 @@ async function replyPeer(ctx: TenantContext, label: string): Promise<{ alias: st
 		 WHERE o.alias = ? AND o.token_enc IS NOT NULL AND p.revoked_at IS NULL`,
 	).bind(label).first();
 	if (!row) return null;
-	const key = await ctx.peerKey();
-	const token = key ? await M.openPeerTokenWithKey(key, row.alias, row.token_enc) : null;
+	const token = await openPeerSecret(ctx, row.alias, row.token_enc);
 	return token ? { alias: row.alias, url: row.url, token, identityKey: Addr.cleanPublicKey(row.identity_key), announced: row.source === "announce" } : null;
 }
 
@@ -2663,7 +2668,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 +2688,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
@@ -3528,8 +3538,7 @@ async function outboundPeer(ctx: TenantContext, alias: string): Promise<{ alias:
 	if (!r) throw new ToolError(`no peer "${alias}" synced to this A2A endpoint. On the machine with the CLI: ${cliCommand(ctx)} peers sync ${alias}`);
 	let token: string | null = null;
 	if (r.token_enc) {
-		const peerKey = await ctx.peerKey();
-		token = peerKey ? await M.openPeerTokenWithKey(peerKey, alias, r.token_enc) : null;
+		token = await openPeerSecret(ctx, alias, r.token_enc);
 		if (!token) throw new ToolError(`the stored token for "${alias}" can't be read (the owner token was rotated since it was synced): run ${cliCommand(ctx)} peers sync ${alias} again`);
 	}
 	return { alias, url: r.url, token };

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/tenancy.ts

@@ -11,6 +11,7 @@
 // and an allowlist are all set (approval-oidc.ts).
 
 import * as A from "./a2a.ts";
+import { tenantSecretsMaterials } from "./wake-secrets.ts";
 
 /** Subset of D1 used by the handlers. A Durable Object adapter satisfies the same shape. */
 export interface SqlDb {
@@ -489,10 +490,20 @@ export class TenantContext implements ConfigFields {
 		return this.#peerKey;
 	}
 
+	/** Read-only keys for hosted outbound tokens during rotation; self-host keeps OWNER_TOKEN semantics. */
+	async peerReadKeys(): Promise<CryptoKey[]> {
+		const active = await this.peerKey();
+		if (!active) return [];
+		if (this.mode === "single") return [active];
+		const previous = tenantSecretsMaterials(this.#secretsKey || "").slice(1);
+		return [active, ...await Promise.all(previous.map((material) => derivePeerKey(material, peerKeyInfoForTenant(this.id))))];
+	}
+
 	async #derivePeerKey(): Promise<CryptoKey | null> {
 		if (this.mode === "single") return this.#ownerToken ? derivePeerKey(this.#ownerToken) : null;
 		if (!this.#secretsKey || !this.id) return null;
-		return derivePeerKey(this.#secretsKey, peerKeyInfoForTenant(this.id));
+		const material = tenantSecretsMaterials(this.#secretsKey)[0];
+		return material ? derivePeerKey(material, peerKeyInfoForTenant(this.id)) : null;
 	}
 }
 

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.35";

package/worker/src/wake-secrets.ts

@@ -36,8 +36,47 @@ export const MAX_WAKE_PLAIN = (() => {
 	return n;
 })();
 
-/** `v1.` + base64(12-byte iv) + `.` + base64(utf-8 plaintext + 16-byte tag). */
-export const MAX_WAKE_SEALED = 3 + 16 + 1 + Math.ceil((MAX_WAKE_PLAIN * 3 + 16) * 4 / 3);
+/** Longest envelope: `v2.<64-char kid>.<iv>.<ciphertext>`. */
+export const MAX_WAKE_SEALED = 3 + 64 + 1 + 16 + 1 + Math.ceil((MAX_WAKE_PLAIN * 3 + 16) * 4 / 3);
+
+/** A bounded keyring lives in the existing secret binding, never in public config. */
+export interface TenantSecretsKeyring {
+	active: string;
+	keys: Record<string, string>;
+	legacy: boolean;
+}
+
+/** Raw keys preserve v1 writes for a reader-first rollout. JSON keyrings enable v2 writes. */
+export function tenantSecretsKeyring(input: string): TenantSecretsKeyring | null {
+	if (!input) return null;
+	if (!input.trimStart().startsWith("{")) return { active: "", keys: { "": input }, legacy: true };
+	if (input.length > 65536) return null;
+	try {
+		const value = JSON.parse(input);
+		if (!value || value.v !== 2 || typeof value.active !== "string" ||
+			!value.keys || typeof value.keys !== "object" || Array.isArray(value.keys) ||
+			Object.keys(value).some((name) => !["v", "active", "keys"].includes(name))) return null;
+		const entries = Object.entries(value.keys);
+		if (entries.length < 1 || entries.length > 2 || !Object.hasOwn(value.keys, value.active)) return null;
+		for (const [kid, key] of entries) {
+			if (!/^[A-Za-z0-9_-]{1,64}$/.test(kid) || typeof key !== "string" || !key.trim() || key.length > 4096) return null;
+		}
+		return { active: value.active, keys: value.keys, legacy: false };
+	} catch { return null; }
+}
+
+/** Current material first, then the single read-only rotation key. No caller may log these values. */
+export function tenantSecretsMaterials(input: string): string[] {
+	const ring = tenantSecretsKeyring(input);
+	if (!ring) return [];
+	return [ring.keys[ring.active], ...Object.entries(ring.keys).filter(([kid]) => kid !== ring.active).map(([, key]) => key)];
+}
+
+function unreadable(): null {
+	// Only a fixed event: ciphertext, key ids, credentials and tenant identifiers never enter logs.
+	console.error(JSON.stringify({ event: "wake_secrets_unreadable", level: "error" }));
+	return null;
+}
 
 function b64(bytes: Uint8Array): string {
 	let raw = "";
@@ -77,21 +116,24 @@ function payloadOf(secrets: WakeSecrets): Record<string, string> | null {
 	return payload;
 }
 
-/** `v1.<iv>.<ciphertext>`, or null when the key or a value is unusable. */
+/** `v2.<kid>.<iv>.<ciphertext>` for keyrings; raw keys keep v1 writes until rollout completes. */
 export async function sealWakeSecrets(ikm: string, tenantId: string, secrets: WakeSecrets): Promise<string | null> {
-	const key = await derive(ikm, tenantId);
+	const ring = tenantSecretsKeyring(ikm);
+	const key = ring ? await derive(ring.keys[ring.active], tenantId) : null;
 	const payload = payloadOf(secrets);
 	if (!key || !payload) return null;
 	const json = JSON.stringify(payload);
 	const encoded = new TextEncoder().encode(json);
 	if (json.length > MAX_WAKE_PLAIN || encoded.length > MAX_WAKE_PLAIN * 3) return null;
+	const prefix = ring!.legacy ? "v1" : `v2.${ring!.active}`;
+	const aad = ring!.legacy ? tenantId : `${prefix}\0${tenantId}`;
 	const iv = crypto.getRandomValues(new Uint8Array(12));
 	const ct = new Uint8Array(await crypto.subtle.encrypt(
-		{ name: "AES-GCM", iv, additionalData: new TextEncoder().encode(tenantId) },
+		{ name: "AES-GCM", iv, additionalData: new TextEncoder().encode(aad) },
 		key,
 		encoded,
 	));
-	const sealed = `v1.${b64(iv)}.${b64(ct)}`;
+	const sealed = `${prefix}.${b64(iv)}.${b64(ct)}`;
 	return sealed.length <= MAX_WAKE_SEALED ? sealed : null;
 }
 
@@ -101,28 +143,47 @@ export async function sealWakeSecrets(ikm: string, tenantId: string, secrets: Wa
  */
 export async function openWakeSecrets(ikm: string, tenantId: string, sealed: string | null | undefined): Promise<WakeSecrets | null> {
 	if (sealed == null || sealed === "") return {};
-	if (sealed.length > MAX_WAKE_SEALED) return null;
-	const key = await derive(ikm, tenantId);
-	if (!key) return null;
-	const [version, iv, ct, extra] = sealed.split(".");
-	if (version !== "v1" || !iv || !ct || extra !== undefined) return null;
-	try {
-		const plain = new TextDecoder().decode(await crypto.subtle.decrypt(
-			{ name: "AES-GCM", iv: unb64(iv), additionalData: new TextEncoder().encode(tenantId) },
-			key,
-			unb64(ct),
-		));
-		if (plain.length > MAX_WAKE_PLAIN) return null;
-		const parsed = JSON.parse(plain) as unknown;
-		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-		const out: WakeSecrets = {};
-		for (const name of WAKE_SECRET_KEYS) {
-			const value = (parsed as Record<string, unknown>)[name];
-			if (typeof value !== "string" || !value || value.length > MAX_WAKE_VALUE) continue;
-			out[name] = value;
-		}
-		return out;
-	} catch {
-		return null;
+	if (typeof sealed !== "string" || sealed.length > MAX_WAKE_SEALED) return unreadable();
+	const ring = tenantSecretsKeyring(ikm);
+	if (!ring || !tenantId) return unreadable();
+	const parts = sealed.split(".");
+	const version = parts[0];
+	const kid = version === "v2" ? parts[1] : "";
+	if (version !== "v1" && version !== "v2") return unreadable();
+	if (parts.length !== (version === "v2" ? 4 : 3)) return unreadable();
+	const [iv, ct] = parts.slice(version === "v2" ? 2 : 1);
+	if (!iv || !ct || (version === "v2" && (ring.legacy || !Object.hasOwn(ring.keys, kid)))) return unreadable();
+	const materials = version === "v2" ? [ring.keys[kid]] : tenantSecretsMaterials(ikm);
+	const aad = version === "v2" ? `v2.${kid}\0${tenantId}` : tenantId;
+	for (const material of materials) {
+		try {
+			const key = await derive(material, tenantId);
+			if (!key) continue;
+			const ivBytes = unb64(iv);
+			if (ivBytes.length !== 12) return unreadable();
+			const plain = new TextDecoder().decode(await crypto.subtle.decrypt(
+				{ name: "AES-GCM", iv: ivBytes, additionalData: new TextEncoder().encode(aad) },
+				key,
+				unb64(ct),
+			));
+			if (plain.length > MAX_WAKE_PLAIN) return unreadable();
+			const parsed = JSON.parse(plain) as unknown;
+			if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return unreadable();
+			const out: WakeSecrets = {};
+			for (const name of WAKE_SECRET_KEYS) {
+				const value = (parsed as Record<string, unknown>)[name];
+				if (typeof value !== "string" || !value || value.length > MAX_WAKE_VALUE) continue;
+				out[name] = value;
+			}
+			return out;
+		} catch { /* Try the previous key only for an unlabelled v1 blob. */ }
 	}
+	return unreadable();
+}
+
+/** Pure maintenance helper. The caller must CAS the original blob and queue the new tenant config. */
+export async function rewrapWakeSecrets(ikm: string, tenantId: string, sealed: string): Promise<string | null> {
+	if (!sealed) return null;
+	const secrets = await openWakeSecrets(ikm, tenantId, sealed);
+	return secrets ? sealWakeSecrets(ikm, tenantId, secrets) : null;
 }

package/worker/test/address.test.ts

@@ -7,6 +7,7 @@ import { dispatch, runOwnerRpc } from "../src/index.ts";
 import { redactExport, exportRows } from "../src/export.ts";
 import { hostedTenantContext, type DoNamespace, type KvNamespace, type TenantContext, type WorkerBindings } from "../src/tenancy.ts";
 import { d1 } from "./d1.ts";
+import { openPeerTokenWithKey } from "../src/mcp.ts";
 
 const MIGRATIONS = new URL("../migrations/", import.meta.url);
 const ectx = { waitUntil(p: Promise<unknown>) { p.catch(() => {}); }, passThroughOnException() {} };
@@ -70,7 +71,14 @@ async function world(t: { after: (fn: () => void) => void }) {
 	};
 	const owner = (ctx: TenantContext, accountId: string, method: string, path: string, body?: unknown) =>
 		runOwnerRpc(ctx, ectx as never, { accountId, method, path, ...(body === undefined ? {} : { body }) });
-	return { alice, bob, carol, call, owner };
+	const rotate = async (agent: typeof alice, secretsKey: string) => {
+		agent.ctx = hostedTenantContext({ ...env, TENANT_SECRETS_KEY: secretsKey }, {
+			id: agent.ctx.id, db: agent.db, publicUrl: agent.ctx.PUBLIC_URL,
+			ownerTokenHash: await sha256(agent.ownerToken), status: "active", config: { AGENT_NAME: "fixture" },
+		});
+		byId.set(agent.ctx.id, agent.ctx);
+	};
+	return { alice, bob, carol, call, owner, rotate };
 }
 
 async function pair(bob: { ctx: TenantContext; ownerToken: string }, call: (ctx: TenantContext, path: string, init?: RequestInit) => Promise<{ status: number; data: any }>, identity?: string) {
@@ -474,3 +482,53 @@ test("export omits the sealed pairing identity and a stored return token", async
 	assert.equal(JSON.stringify(redacted).includes(ident.privateKey), false);
 	assert.equal(JSON.stringify(redacted).includes("sealed-return"), false);
 });
+
+
+test("hosted key rotation preserves identity proofs, reverse tokens and direct replies", async (t) => {
+	const { alice, carol, call, owner, rotate } = await world(t as never);
+	const ident = await Addr.generateIdentity();
+	const putIdentity = () => call(alice.ctx, "/owner/identity", {
+		method: "PUT", headers: { authorization: `Bearer ${alice.ownerToken}`, "content-type": "application/json" },
+		body: JSON.stringify(ident),
+	});
+	assert.equal((await putIdentity()).status, 200);
+	const paired = await pair(carol, call, ident.publicKey);
+	assert.equal((await owner(alice.ctx, "acct-alice", "PUT", `/owner/outbound-peers/${paired.label}`, { url: carol.ctx.PUBLIC_URL, token: paired.access })).status, 200);
+	const announce = () => owner(alice.ctx, "acct-alice", "POST", "/owner/peers/announce", { to: paired.label });
+	const firstAnnouncement = await announce();
+	assert.equal(firstAnnouncement.body.results[0].status, "updated", JSON.stringify(firstAnnouncement.body));
+	const reverseBefore = await alice.db.prepare("SELECT token_hash, token_enc FROM peers WHERE label = ? AND source = 'reverse'").bind(paired.label).first() as { token_hash: string; token_enc: string };
+	assert.ok(reverseBefore.token_enc);
+	const identityBefore = await alice.db.prepare("SELECT value FROM settings WHERE key = ?").bind(Addr.IDENTITY_SETTING).first() as { value: string };
+	const ring = JSON.stringify({ v: 2, active: "current", keys: { previous: "platform-key", current: "new-platform-key" } });
+	await rotate(alice, ring);
+	await rotate(carol, ring);
+	const cardUrl = Addr.cardUrlFor(alice.ctx.PUBLIC_URL);
+	const card = await call(alice.ctx, "/.well-known/agent-card.json");
+	assert.equal(await Addr.cardProves(card.data, ident.publicKey, cardUrl), true, "the stored old-key identity still signs the card");
+	assert.deepEqual(await alice.db.prepare("SELECT value FROM settings WHERE key = ?").bind(Addr.IDENTITY_SETTING).first(), identityBefore, "a public read never rewrites identity storage");
+	const taskId = await send(carol.ctx, paired.access, "rotation question", "ctx-rotation");
+	const reply = await owner(carol.ctx, "acct-carol", "POST", "/owner/mcp/reply", { taskId, text: "rotation answer", state: "completed" });
+	assert.equal(reply.body.structuredContent.status, "delivered", JSON.stringify(reply.body));
+	assert.equal((await announce()).body.results[0].status, "updated", "the old-key identity and outbound token remain usable");
+	const reverseAfter = await alice.db.prepare("SELECT token_hash, token_enc FROM peers WHERE label = ? AND source = 'reverse'").bind(paired.label).first() as typeof reverseBefore;
+	assert.equal(reverseAfter.token_hash, reverseBefore.token_hash, "rotation must preserve the existing return token");
+	assert.notEqual(reverseAfter.token_enc, reverseBefore.token_enc);
+	assert.ok(await openPeerTokenWithKey((await alice.ctx.peerKey())!, paired.label, reverseAfter.token_enc), "authorized announcement reseals the same reverse token with the active key");
+	// Existing owner-only identity installation reseals the SAME validated identity; it never regenerates it.
+	const unauthorized = await call(alice.ctx, "/owner/identity", { method: "PUT", headers: { "content-type": "application/json" }, body: JSON.stringify(ident) });
+	assert.equal(unauthorized.status, 401);
+	const resealed = await putIdentity();
+	assert.equal(resealed.status, 200);
+	assert.equal(resealed.data.publicKey, ident.publicKey);
+	assert.equal(JSON.stringify(resealed.data).includes(ident.privateKey), false);
+	const onlyCurrent = JSON.stringify({ v: 2, active: "current", keys: { current: "new-platform-key" } });
+	await rotate(alice, onlyCurrent);
+	const retiredCard = await call(alice.ctx, "/.well-known/agent-card.json");
+	assert.equal(await Addr.cardProves(retiredCard.data, ident.publicKey, cardUrl), true, "owner reseal keeps the identity readable after retirement");
+	const identityAfter = await alice.db.prepare("SELECT value FROM settings WHERE key = ?").bind(Addr.IDENTITY_SETTING).first() as { value: string };
+	assert.notEqual(identityAfter.value, identityBefore.value);
+	const other = await Addr.generateIdentity();
+	const replacement = await call(alice.ctx, "/owner/identity", { method: "PUT", headers: { authorization: `Bearer ${alice.ownerToken}`, "content-type": "application/json" }, body: JSON.stringify(other) });
+	assert.equal(replacement.status, 409, "rotation never authorizes replacing the identity");
+});

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/hosted.test.ts

@@ -933,8 +933,10 @@ test("self-host workerd: human mode owner token approves, the device poll return
 
 test("sealed upstream and wake Access credentials reach only their tenant context in workerd", async (t) => {
 	const received: { origin: string; bearer: string | null; id: string | null; secret: string | null }[] = [];
+	const keys = { previous: "platform-secret", current: "next-platform-secret" };
+	const keyring = (active: string) => JSON.stringify({ v: 2, active, keys });
 	const mf = await start({
-		bindings: { TENANCY: "host", TENANT_DOMAIN: "example.com", TENANT_SECRETS_KEY: "platform-secret" },
+		bindings: { TENANCY: "host", TENANT_DOMAIN: "example.com", TENANT_SECRETS_KEY: keyring("current") },
 		durableObjects: { TENANT_DO: { className: "TenantStore", useSQLite: true } },
 		outboundService: async (request: Request) => {
 			received.push({ origin: new URL(request.url).origin, bearer: request.headers.get("authorization"), id: request.headers.get("cf-access-client-id"), secret: request.headers.get("cf-access-client-secret") });
@@ -966,9 +968,22 @@ test("sealed upstream and wake Access credentials reach only their tenant contex
 	assert.equal(preview.status, 200);
 	assert.equal((preview.body as { hasAccessServiceToken: boolean }).hasAccessServiceToken, true);
 	for (const value of Object.values(secrets)) assert.equal(JSON.stringify([facade.body, preview.body]).includes(value), false);
+	let version = 1;
+	for (const active of ["previous", "current"]) {
+		const v2 = await sealWakeSecrets(keyring(active), "sealed-tenant", secrets);
+		assert.ok(v2?.startsWith(`v2.${active}.`));
+		assert.equal((await push(++version, v2)).applied, true);
+		const facadeV2 = await stub.owner({ accountId: "dummy-owner", method: "GET", path: "/owner/facade" });
+		assert.equal((facadeV2.body as { hasUpstreamToken: boolean }).hasUpstreamToken, true);
+		assert.equal(received.at(-1)?.bearer, "Bearer dummy-bearer");
+		const wakeV2 = await stub.owner({ accountId: "dummy-owner", method: "GET", path: "/owner/wake/preview" });
+		assert.equal((wakeV2.body as { hasAccessServiceToken: boolean }).hasAccessServiceToken, true);
+		for (const value of Object.values(secrets)) assert.equal(JSON.stringify([facadeV2.body, wakeV2.body]).includes(value), false);
+	}
+
 	const otherTenantBlob = await sealWakeSecrets("platform-secret", "another-tenant", secrets);
 	assert.ok(otherTenantBlob);
-	assert.equal((await push(2, otherTenantBlob)).applied, true);
+	assert.equal((await push(++version, otherTenantBlob)).applied, true);
 	const rejected = await stub.owner({ accountId: "dummy-owner", method: "GET", path: "/owner/facade" });
 	assert.equal((rejected.body as { hasUpstreamToken: boolean }).hasUpstreamToken, false);
 	assert.equal((rejected.body as { hasUpstreamAccessServiceToken: boolean }).hasUpstreamAccessServiceToken, false);

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/owner-mcp.test.ts

@@ -95,6 +95,17 @@ test("hosted control plane send, reply, and mark_working", async (t) => {
 	assert.equal(viaHttp.text.includes("tok-alpha"), false);
 	assert.equal(peerCalls.at(-1)!.body.params.message.parts[0].text, "from the owner token");
 
+	// A hosted rotation keeps stored outbound tokens readable through the actual owner send path.
+	const rotating = hostedTenantContext({ ...env, TENANT_SECRETS_KEY: JSON.stringify({
+		v: 2, active: "next", keys: { old: "platform-key", next: "next-platform-key" },
+	}) }, { id: "ten_carol", db: DB, publicUrl: BASE, ownerTokenHash: hash, status: "active" });
+	const afterRotation = await runOwnerRpc(rotating, ectx as any, {
+		accountId: "acct_carol", method: "POST", path: "/owner/mcp/send", body: { to: "alpha", text: "after rotation" },
+	});
+	assert.equal(afterRotation.status, 200);
+	assert.equal((afterRotation.body as any).isError, false, JSON.stringify(afterRotation.body));
+	assert.equal(peerCalls.at(-1)!.auth, "Bearer tok-alpha");
+
 	const withBody = await runOwnerRpc(ctx, ectx as any, { accountId: "acct_carol", method: "GET", path: "/owner/peers", body: { label: "bob" } });
 	assert.equal(withBody.status, 400);
 	assert.equal((withBody.body as { error?: string }).error, "this call takes no body");

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/);

package/worker/test/tenancy.test.ts

@@ -268,3 +268,20 @@ test("fetch path: gates set or unset, the self-host Worker still answers from OW
 	const no = await call({ ...base, ...gates }, "/owner/inbox", { authorization: "Bearer platform-key" });
 	assert.equal(no.status, 401);
 });
+
+test("hosted peer token keys follow the active ring key and keep the previous key for reads", async () => {
+	const make = (key: string, id = "ten_a") => hostedTenantContext(selfEnv({ TENANT_SECRETS_KEY: key }), { id, db: dummy, publicUrl: BASE });
+	const old = make("old-platform-key");
+	const ring = JSON.stringify({ v: 2, active: "current", keys: { previous: "old-platform-key", current: "new-platform-key" } });
+	const rotating = make(ring);
+	const oldToken = await sealPeerTokenWithKey((await old.peerKey())!, "alpha", "fixture-old-token");
+	const keys = await rotating.peerReadKeys();
+	assert.equal(keys.length, 2);
+	assert.equal(await openPeerTokenWithKey(keys[0], "alpha", oldToken), null);
+	assert.equal(await openPeerTokenWithKey(keys[1], "alpha", oldToken), "fixture-old-token");
+	const newToken = await sealPeerTokenWithKey((await rotating.peerKey())!, "alpha", "fixture-new-token");
+	assert.equal(await openPeerTokenWithKey((await make("new-platform-key").peerKey())!, "alpha", newToken), "fixture-new-token");
+	for (const key of await make(ring, "ten_b").peerReadKeys()) assert.equal(await openPeerTokenWithKey(key, "alpha", oldToken), null);
+	assert.deepEqual(await make('{"v":2}').peerReadKeys(), []);
+	assert.equal((await resolveTenant(selfEnv()).peerReadKeys()).length, 1);
+});