a2a-exposed 0.8.4 → 0.8.5

package/lib/main.mjs

@@ -10,6 +10,7 @@ import * as pair from "./pair.mjs";
 import * as account from "./account.mjs";
 import * as upd from "./update.mjs";
 import * as fb from "./feedback.mjs";
+import * as un from "./uninstall.mjs";
 
 const VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
@@ -83,8 +84,12 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
                                                which defaults to 25 when this is unset
   wake preview                  rendered wake request (a credential is Bearer •••• or ••••, none of the secret)
                                 + sha256 fingerprints of the uploaded URL/key/HMAC secret; compared with
-                                local env values if exported
-  wake fingerprint              fingerprints (first 12 hex of sha256) of WAKE_* in the local environment
+                                local env values when WAKE_WEBHOOK_URL, WAKE_WEBHOOK_KEY, and WAKE_HMAC_SECRET
+                                are exported in this shell. match: the exported value is the one on the Worker.
+                                DIFFERENT: they differ (absent from this shell, or still propagating, about
+                                15 to 40 seconds after wake set, wake unset, or tunnel create). Wait about
+                                30 seconds and run it again
+  wake fingerprint              fingerprints (first 12 hex of sha256) of WAKE_* exported in this shell
   wake test                     send a test wake now and print the HTTP status
   wake unset                    remove wake secrets (fall back to polling)
 
@@ -96,10 +101,24 @@ anywhere on the account: the inbox itself can be on workers.dev or a custom host
                                 the Worker sends that token (CF-Access-Client-Id/Secret) on every wake.
                                 Wake hostname: wake-<random>.<zone>, on the inbox hostname's zone, else the account's
                                 only zone; with several zones pass --tunnel-zone. Safe to re-run (no duplicates).
+                                The tunnel, the Access app, and the service token are named "a2a-exposed wake <worker>".
+                                The DNS host is wake-<words>-<hex>.<zone> unless --tunnel-hostname is set.
+                                Export WAKE_WEBHOOK_KEY (hermes: WAKE_HMAC_SECRET) so tunnel create uploads it.
+                                The connector machine needs cloudflared installed
+                                (https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/).
                                 Defaults: openclaw-* -> http://127.0.0.1:18789 /hooks/wake|agent, hermes -> :8644
-                                (pass --tunnel-path /webhooks/<name>). Token -> <config dir>/tunnel-token (chmod 600)
+                                (pass --tunnel-path /webhooks/<name>). Token -> <config dir>/tunnel-token (chmod 600).
+                                Worker secrets show up in about 15 to 40 seconds
   tunnel status                 tunnel/Access/Worker state + probes (bare request blocked? connector up?)
-  tunnel rm                     delete Worker wake secrets, DNS record, tunnel, Access app + service token
+  tunnel rm                     delete the DNS record, the tunnel, the Access app, and the service token
+                                (each printed by name), plus Worker secrets WAKE_ACCESS_CLIENT_ID,
+                                WAKE_ACCESS_CLIENT_SECRET, WAKE_WEBHOOK_KEY, and WAKE_HMAC_SECRET. The wake URL
+                                goes too when it is this tunnel's. Prints one line per object removed
+  uninstall [--yes]             remove the wake tunnel (when the config has one), the Worker, and the D1 database.
+                                One line per step, including when that object is already gone. Asks first;
+                                off a terminal, pass --yes. The config directory stays (owner token and peer
+                                tokens): remove that directory to delete them. cf runs from the Worker project
+                                when it has node_modules, otherwise from a directory with .cloudflare/cache
   init ... --tunnel             init, then tunnel create (also with --workers-dev)
 
 Status
@@ -111,7 +130,9 @@ Status
                                 When GET /owner/mcp reports enabled and the agent card is reachable, prints
                                 \`claude mcp add --transport http a2a-exposed <base URL>/mcp\`.
                                 A failed probe, an unreachable card, or a Worker that reports MCP off leaves that line out.
-                                Read-only; run it after an interruption and continue from "next step". Exit 1 = broken
+                                Read-only; run it after an interruption and continue from "next step". Exit 1 = broken.
+                                Right after tunnel create, for about 15 to 40 seconds, while the connector
+                                reports 0 connections, status prints a wait-about-30-seconds line and exits 0
   upstream verify [--json]      proxy mode: check the façade's whole path, layer by layer: façade peer auth
                                 (unauthenticated call -> 401), then the Worker calls the upstream with its stored
                                 secrets (never sent to the CLI) using a JSON-RPC method that doesn't exist (no task
@@ -135,8 +156,9 @@ Inbox (owner side)
 
 Pairing (OAuth 2.0 device flow, RFC 8628: agents connect without pasting tokens into chat)
   connect <base-or-card-url> [--alias A] [--name N] [--card-url URL] [--replace] [--no-wait] [--json]
-                          ask another inbox for a token: prints a code + link for your human (who confirms the
-                          code with that inbox's owner), waits for approval, stores the token as outbound peer A
+                          ask another inbox for a token: prints a code + link for your human (the code lasts
+                          10 minutes; they confirm the code with that inbox's owner), waits for approval, stores
+                          the token as outbound peer A
                           (never printed). --no-wait: print the code and exit; run the same command again to
                           check (same code). An expired code exits 1 (nothing new is requested silently).
                           An alias whose token still works is refused unless --replace (alias --force): the
@@ -149,9 +171,9 @@ Pairing (OAuth 2.0 device flow, RFC 8628: agents connect without pasting tokens
                           configured agent name, the worker name, or the public host's first label. The
                           other inbox labels the token from that name and adds -2, -3, … when it is taken
   pair set-password --web [--ttl MIN] [--json]
-                          one-time link (default 15 min, single use) where your human sets or changes the
-                          approval password on a web page. Send it to them privately; never open or fill it
-                          yourself. A new link invalidates the previous one
+                          one-time link (default 15 min, --ttl 1 to 60, single use) where your human sets or
+                          changes the approval password on a web page. Send it to them privately; never open
+                          or fill it yourself. A new link invalidates the previous one
   pair set-password       the same in a terminal, no echo (the human runs it; never via argv/stdin)
   pair set-oidc --issuer URL --client-id ID --subjects SUB[,SUB...] [--methods password,oidc] [--secret-stdin]
                           optional OpenID Connect approval on /device and the MCP consent page. The client
@@ -239,6 +261,7 @@ const SPEC = {
 	login: { "control-url": S, json: B },
 	pair: { json: B, web: B, ttl: S, issuer: S, "client-id": S, subjects: S, methods: S, "secret-stdin": B },
 	feedback: { kind: S, contact: S, steps: S, expected: S, actual: S, logs: S, agent: S, environment: S, connection: S, yes: B },
+	uninstall: { yes: B, dir: S, "worker-dir": S },
 };
 const STATES = ["completed", "input-required", "failed", "rejected", "working"];
 
@@ -274,6 +297,7 @@ export async function main(argv) {
 				throw e;
 			}
 		case "tunnel": return tun.tunnel(need(p[0], "tunnel create|status|rm"), o);
+		case "uninstall": return un.uninstall(o);
 		case "deploy": return dep.deploy(o);
 		case "status": return st.status(o);
 		case "upstream": {

package/lib/status.mjs

@@ -77,6 +77,17 @@ export function shadowedPeerTokens() {
 	return [...new Set(Object.values(C.loadPeers()).map((p) => p && p.token_env).filter(Boolean))].filter((k) => C.envOverridesFile(k));
 }
 
+/** How long after `tunnel create` uploads secrets `status` treats a missing Worker preview as propagation. */
+export const SECRET_PROPAGATION_MS = 60_000;
+
+/** True while the tunnel's Worker secrets were uploaded recently and may still be invisible to `wake preview`. */
+export function secretsPropagating(tunnel, now = Date.now()) {
+	const at = Number(tunnel && tunnel.secretsAt);
+	if (!Number.isFinite(at) || at <= 0) return false;
+	const age = now - at;
+	return age >= 0 && age < SECRET_PROPAGATION_MS;
+}
+
 /** The single most useful next step for a status snapshot (pure; unit-tested). `also`: optional extra hints, printed
  *  as separate lines (so the next step stays one short instruction). */
 export function nextStep(s) {
@@ -143,8 +154,12 @@ function nextStepCore(s) {
 		return fail(`the tunnel's connector token file (${t.tokenFile}) is missing or empty: run \`${CLI} tunnel create\` again (it downloads the token again; nothing new is created)`);
 	const agentSecret = s.wake.preset === "hermes" ? "WAKE_HMAC_SECRET" : "WAKE_WEBHOOK_KEY";
 	const needsAgentSecret = LOCAL_PRESETS.includes(s.wake.preset) && !s.wake.hasKey && !s.wake.hasHmacSecret;
-	if (t && !(s.wake.hasAccessServiceToken && t.workerUrlMatches))
+	const now = typeof s.now === "number" ? s.now : Date.now();
+	if (t && !(s.wake.hasAccessServiceToken && t.workerUrlMatches)) {
+		if (secretsPropagating(t, now) && (t.connections === 0 || t.connections == null))
+			return done(`Worker wake secrets are still propagating (about 15 to 40 seconds after tunnel create). Wait about 30 seconds and run \`${CLI} status\` again.`);
 		return fail(`the Worker does not have the tunnel's wake secrets: ${needsAgentSecret ? `export ${agentSecret} and ` : ""}run \`${CLI} tunnel create\` again (it re-uploads them; nothing new is created)`);
+	}
 	if (t && t.connections === 0)
 		return fail(`the tunnel has no running connector: on the agent's machine run \`cloudflared tunnel run --token-file ${t.tokenFile}\` (outbound port 7844 must be open), then \`${CLI} wake test\``);
 	if (s.wake.configured && needsAgentSecret)
@@ -223,7 +238,8 @@ export async function collect() {
 	if (host || C.get("A2A_TUNNEL_ID")) {
 		const url = T.wakeUrl(host || "?", C.get("A2A_TUNNEL_PATH") || "/");
 		s.tunnel = { hostname: host, wakeUrl: url, origin: C.get("A2A_TUNNEL_ORIGIN"), complete: T.tunnelComplete(), tokenFileOk: T.tokenFileOk(),
-			tokenFile: C.get("A2A_TUNNEL_TOKEN_FILE") || "<config dir>/tunnel-token", workerUrlMatches: s.wake?.urlFingerprint === fingerprint(url), connections: null };
+			tokenFile: C.get("A2A_TUNNEL_TOKEN_FILE") || "<config dir>/tunnel-token", workerUrlMatches: s.wake?.urlFingerprint === fingerprint(url),
+			secretsAt: Number(C.get("A2A_TUNNEL_SECRETS_AT")) || 0, connections: null };
 		if (haveCf && C.get("A2A_TUNNEL_ID")) {
 			try {
 				const t = T.cfCall(dir, ["tunnels", "get", C.get("A2A_TUNNEL_ID")], { allowNotFound: true });

package/lib/tunnel.mjs

@@ -6,6 +6,7 @@
 // A Cloudflare zone on the account is required on purpose (no quick tunnels, no unprotected hostnames). Any zone
 // on the account works: the inbox itself can stay on workers.dev or on another hostname.
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
 import { spawnSync } from "node:child_process";
@@ -32,7 +33,7 @@ export const SERVICE_TOKEN_DURATION = "8760h"; // 1 year (Cloudflare's default);
 export const TUNNEL_KEYS = [
 	"A2A_TUNNEL_HOSTNAME", "A2A_TUNNEL_ORIGIN", "A2A_TUNNEL_PATH", "A2A_TUNNEL_ZONE_ID", "A2A_TUNNEL_ID", "A2A_TUNNEL_DNS_ID",
 	"A2A_TUNNEL_ACCESS_APP_ID", "A2A_TUNNEL_ACCESS_TOKEN_ID", "A2A_TUNNEL_ACCESS_CLIENT_ID", "A2A_TUNNEL_ACCESS_CLIENT_SECRET",
-	"A2A_TUNNEL_TOKEN_FILE",
+	"A2A_TUNNEL_TOKEN_FILE", "A2A_TUNNEL_SECRETS_AT",
 ];
 
 // ------------------------------------------------------------------ pure helpers (unit-tested)
@@ -147,7 +148,8 @@ export function secretsPatch(map) {
 export function connectorInstructions(tokenFile, token = "") {
 	const t = token || `"$(cat ${tokenFile})"`;
 	return [
-		"Run the connector on the agent's machine (outbound TCP/UDP 7844 to Cloudflare must be allowed):",
+		"Install cloudflared on the agent's machine: https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/",
+		"Run the connector there (outbound TCP/UDP 7844 to Cloudflare must be allowed):",
 		`  cloudflared tunnel run --token-file ${tokenFile}        # cloudflared 2025.4+`,
 		`  cloudflared tunnel run --token ${t}`,
 		`  sudo cloudflared service install ${t}   # as a system service (starts on boot)`,
@@ -214,11 +216,28 @@ export function listZones(dir) {
 }
 
 // ------------------------------------------------------------------ commands
+/** A working directory for `cf`. A project with `node_modules` keeps its own cache. Otherwise `.cloudflare/cache`
+ *  in that directory (or a temp directory, when the project is gone) is where `cf` writes its account cache. */
+export function cfWorkDir(preferred) {
+	if (preferred && fs.existsSync(path.join(preferred, "node_modules"))) return preferred;
+	const base = preferred && fs.existsSync(preferred) ? preferred : fs.mkdtempSync(path.join(os.tmpdir(), "a2a-cf-"));
+	fs.mkdirSync(path.join(base, ".cloudflare", "cache"), { recursive: true });
+	return base;
+}
+
 function needDeployment(o) {
 	if (!C.get("A2A_D1_ID") || !C.get("A2A_WORKER_NAME")) die(`no saved deployment; run \`${CLI} init\` first`);
 	const dir = D.workerDir(o);
 	if (!fs.existsSync(dir)) die(`worker project not found at ${dir}; run \`${CLI} deploy\` once`);
-	return dir;
+	return cfWorkDir(dir);
+}
+
+/** `cf` cwd for `tunnel rm` / `uninstall`. A missing Worker project uses a temp directory with a writable cache. */
+function cfDirForRemove(o, { allowMissingProject = false } = {}) {
+	if (!C.get("A2A_D1_ID") || !C.get("A2A_WORKER_NAME")) die(`no saved deployment; run \`${CLI} init\` first`);
+	const dir = D.workerDir(o);
+	if (!fs.existsSync(dir) && !allowMissingProject) die(`worker project not found at ${dir}; run \`${CLI} deploy\` once`);
+	return cfWorkDir(dir);
 }
 
 /** Checks that need no Cloudflare calls (also used by `init --tunnel` before anything is deployed). */
@@ -293,7 +312,7 @@ export async function create(o) {
 		console.log(url);
 		console.error(`\ntunnel ready: wakes go to ${url} -> ${origin}${wpath} on the agent's machine`);
 		console.error(connectorInstructions(tokenFile, o["show-token"] ? token : ""));
-		console.error(`\nThen (Worker secrets apply within ~15 s): ${CLI} tunnel status   and   ${CLI} wake test`);
+		console.error(`\nThen (Worker secrets apply within about 15 to 40 seconds): ${CLI} tunnel status   and   ${CLI} wake test`);
 		if (!process.env.WAKE_WEBHOOK_KEY && !process.env.WAKE_HMAC_SECRET && preset !== "generic")
 			console.error(`note: no WAKE_WEBHOOK_KEY / WAKE_HMAC_SECRET in the environment; keep the ${preset} webhook's own auth too (export it and run \`wake set\`)`);
 	} catch (e) {
@@ -363,8 +382,10 @@ async function resume(dir, o) {
 	console.error(`Then: ${CLI} tunnel status   and   ${CLI} wake test`);
 }
 
-function putSecrets(dir, worker, map) {
-	return D.withSecretsFile(secretsPatch(map), (file) => cfCall(dir, ["workers", "secrets", "bulk", "--worker", worker], { file }));
+async function putSecrets(dir, worker, map) {
+	const r = await D.withSecretsFile(secretsPatch(map), (file) => cfCall(dir, ["workers", "secrets", "bulk", "--worker", worker], { file }));
+	if (Object.values(map).some((v) => v != null)) C.saveConfig({ A2A_TUNNEL_SECRETS_AT: String(Date.now()) });
+	return r;
 }
 
 export async function status(o) {
@@ -406,9 +427,10 @@ export async function status(o) {
 	if (!/^HTTP 40[13]/.test(info.probe.withoutToken)) console.error("WARNING: the bare request was not blocked by Access; check the Access application");
 }
 
-export async function remove(o, { quiet = false } = {}) {
-	const dir = needDeployment(o);
+export async function remove(o, { quiet = false, allowMissingProject = false } = {}) {
+	const dir = cfDirForRemove(o, { allowMissingProject });
 	const worker = D.workerName();
+	const label = `a2a-exposed wake ${worker}`;
 	const failures = [];
 	const attempt = async (what, key, fn) => {
 		if (key && !C.get(key)) return;
@@ -417,25 +439,27 @@ export async function remove(o, { quiet = false } = {}) {
 	};
 	const host = C.get("A2A_TUNNEL_HOSTNAME");
 	// 1. Worker secrets first, so no wake is sent to a half-removed hostname. WAKE_WEBHOOK_URL only if it is ours.
-	if (host) await attempt("Worker wake secrets (Access token, tunnel URL)", null, async () => {
-		const patch = { WAKE_ACCESS_CLIENT_ID: null, WAKE_ACCESS_CLIENT_SECRET: null };
+	if (host) {
+		const names = ["WAKE_ACCESS_CLIENT_ID", "WAKE_ACCESS_CLIENT_SECRET", "WAKE_WEBHOOK_KEY", "WAKE_HMAC_SECRET"];
 		let ours = false;
 		try { const p = await owner("GET", "/owner/wake/preview"); ours = p.fingerprints?.url === fingerprint(wakeUrl(host, C.get("A2A_TUNNEL_PATH") || "/")); }
 		catch { /* Worker unreachable: leave the URL */ }
-		if (ours) patch.WAKE_WEBHOOK_URL = null;
-		await putSecrets(dir, worker, patch);
-	});
+		if (ours) names.push("WAKE_WEBHOOK_URL");
+		await attempt(`Worker secrets for ${host} (${names.join(", ")})`, null, async () => {
+			await putSecrets(dir, worker, Object.fromEntries(names.map((k) => [k, null])));
+		});
+	}
 	// 2. DNS before Access, so the hostname never resolves without its Access app
-	await attempt("DNS record", "A2A_TUNNEL_DNS_ID", () => cfCall(dir, ["dns", "records", "delete", C.get("A2A_TUNNEL_DNS_ID"), "-z", C.get("A2A_TUNNEL_ZONE_ID"), "--force"], { allowNotFound: true }));
-	await attempt("tunnel", "A2A_TUNNEL_ID", () => {
+	await attempt(`DNS record ${host || C.get("A2A_TUNNEL_DNS_ID")}`, "A2A_TUNNEL_DNS_ID", () => cfCall(dir, ["dns", "records", "delete", C.get("A2A_TUNNEL_DNS_ID"), "-z", C.get("A2A_TUNNEL_ZONE_ID"), "--force"], { allowNotFound: true }));
+	await attempt(`tunnel "${label}"`, "A2A_TUNNEL_ID", () => {
 		const id = C.get("A2A_TUNNEL_ID");
 		// Already deleted (a previous rm stopped on the confirm prompt, or it was removed by hand): clear the saved id.
 		if (!cfCall(dir, ["tunnels", "get", id], { allowNotFound: true })) return;
 		cfCall(dir, ["tunnels", "connections", "cleanup", id, "--force"], { allowNotFound: true });
 		cfCall(dir, ["tunnels", "delete", id, "--force"], { allowNotFound: true });
 	});
-	await attempt("Access application (and its policy)", "A2A_TUNNEL_ACCESS_APP_ID", () => cfCall(dir, ["zero-trust", "access", "applications", "delete", C.get("A2A_TUNNEL_ACCESS_APP_ID"), "--force"], { allowNotFound: true }));
-	await attempt("Access service token", "A2A_TUNNEL_ACCESS_TOKEN_ID", () => {
+	await attempt(`Access application "${label}"`, "A2A_TUNNEL_ACCESS_APP_ID", () => cfCall(dir, ["zero-trust", "access", "applications", "delete", C.get("A2A_TUNNEL_ACCESS_APP_ID"), "--force"], { allowNotFound: true }));
+	await attempt(`Access service token "${label}"`, "A2A_TUNNEL_ACCESS_TOKEN_ID", () => {
 		cfCall(dir, ["zero-trust", "access", "service-tokens", "delete", C.get("A2A_TUNNEL_ACCESS_TOKEN_ID"), "--force"], { allowNotFound: true });
 		C.saveConfig({ A2A_TUNNEL_ACCESS_CLIENT_ID: null, A2A_TUNNEL_ACCESS_CLIENT_SECRET: null });
 	});

package/lib/uninstall.mjs

@@ -0,0 +1,48 @@
+// `uninstall`: remove the wake tunnel (when one is saved), the Worker, and the D1 database for this config.
+import readline from "node:readline/promises";
+import { CliError } from "./a2a.mjs";
+import * as C from "./config.mjs";
+import * as D from "./deploy.mjs";
+import * as T from "./tunnel.mjs";
+
+const step = (s) => console.error(`==> ${s}`);
+
+/** Ask before deleting. On a terminal, wait for y or yes unless `yes` is set. Off a terminal, `--yes` is required. */
+export async function confirmUninstall(yes, input = process.stdin, output = process.stderr) {
+	if (yes) return;
+	if (!input.isTTY) throw new CliError("uninstall removes the Worker, the D1 database, and the wake tunnel. Pass --yes.");
+	const rl = readline.createInterface({ input, output });
+	try {
+		const answer = (await rl.question("Remove the Worker, the D1 database, and the wake tunnel? [y/N] ")).trim().toLowerCase();
+		if (answer !== "y" && answer !== "yes") throw new CliError("uninstall cancelled");
+	} finally {
+		rl.close();
+	}
+}
+
+const kept = () => `config directory kept at ${C.CONFIG_DIR} (owner token and peer tokens). Remove that directory to delete them.`;
+
+/** One line per removal. A 404 counts as already gone. The config directory stays. */
+export async function uninstall(o) {
+	await confirmUninstall(Boolean(o.yes));
+	const tunnelish = T.TUNNEL_KEYS.some((k) => C.get(k));
+	if (tunnelish) await T.remove(o, { allowMissingProject: true });
+	else step("no tunnel to remove");
+
+	const name = C.get("A2A_WORKER_NAME");
+	const d1 = C.get("A2A_D1_ID");
+	const dir = name || d1 ? T.cfWorkDir(D.workerDir(o)) : "";
+	if (name) {
+		const r = T.cfCall(dir, ["workers", "delete", name, "--force"], { allowNotFound: true });
+		step(r === null ? `Worker ${name} is already gone` : `removed Worker ${name}`);
+	} else step("no Worker name saved");
+	if (d1) {
+		const r = T.cfCall(dir, ["d1", "delete", d1, "--force"], { allowNotFound: true });
+		step(r === null ? `D1 database ${d1} is already gone` : `removed D1 database ${d1}`);
+	} else step("no D1 database id saved");
+	C.saveConfig({
+		A2A_WORKER_NAME: null, A2A_D1_ID: null, A2A_D1_NAME: null, A2A_BASE_URL: null, A2A_HOSTNAME: null,
+		A2A_WORKER_DIR: null, A2A_WORKERS_DEV_SUBDOMAIN: null,
+	});
+	console.error(kept());
+}

package/package.json

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

package/worker/src/index.ts

@@ -6,7 +6,7 @@
 // context is the single self-host tenant and behaviour matches a Worker that read env.* directly.
 import * as A from "./a2a.ts";
 import * as F from "./facade.ts";
-import { renderWake, redact, cloudflareErrorHint, defaultDebounceSeconds, defaultMaxPerHour, type WakeConfig, type WakeEvent } from "./wake.ts";
+import { renderWake, redact, cloudflareErrorHint, wakeUrlIsTunnelHost, defaultDebounceSeconds, defaultMaxPerHour, type WakeConfig, type WakeEvent } from "./wake.ts";
 import { fetchCheckedWake } from "./wake-target.ts";
 import * as P from "./pairing.ts";
 import * as M from "./mcp.ts";
@@ -142,7 +142,9 @@ async function sendWake(ctx: TenantContext, ectx: ExecutionContext, payload: Jso
 			r = await doFetch(ctx, ectx, req.url, { method: "POST", headers: req.headers, body: req.body });
 		}
 		// explain Cloudflare edge errors (tunnel connector down, Access block) without echoing the body
-		const hint = r.ok ? "" : cloudflareErrorHint(r.status, (await r.text().catch(() => "")).slice(0, 4096));
+		const hint = r.ok ? "" : cloudflareErrorHint(r.status, (await r.text().catch(() => "")).slice(0, 4096), {
+			tunnel: !!(ctx.WAKE_ACCESS_CLIENT_ID && ctx.WAKE_ACCESS_CLIENT_SECRET) || wakeUrlIsTunnelHost(req.url),
+		});
 		log("wake_sent", { preset: preset(ctx), contextId: ev.contextId, taskId: ev.taskId, status: r.status, ...(hint ? { hint } : {}) });
 		if (r.status === 429 || r.status === 503) await requeueWake(ctx, ectx, payload, r.headers.get("retry-after"));
 		return { status: r.status, info: `HTTP ${r.status}${hint ? ` (${hint})` : ""}` };
@@ -440,7 +442,7 @@ async function fetchUpstreamCard(ctx: TenantContext, fresh = false): Promise<{ c
 			cardFailures.delete(url);
 			return { card, status: 200, url };
 		}
-		const hint = cloudflareErrorHint(r.status, text.slice(0, 4096));
+		const hint = cloudflareErrorHint(r.status, text.slice(0, 4096), { tunnel: true });
 		log("upstream_card_failed", { status: r.status, ...(hint ? { hint } : {}) });
 		return fail(r.status, `HTTP ${r.status}${hint ? ` (${hint})` : ""}`);
 	} catch (e) {
@@ -1385,6 +1387,16 @@ const pageRequest = (r: Json): P.PageRequest => ({ userCode: r.user_code, client
 	agentCardUrl: r.agent_card_url || "", ip: r.ip || "", country: r.country || "", createdMs: r.created_ms, expiresMs: r.expires_ms,
 	replacesLabel: r.replaces_label || undefined });
 
+/** The label approval will assign: the live token being replaced, otherwise the next free label. */
+async function withTokenLabel(ctx: TenantContext, r: Json): Promise<P.PageRequest> {
+	const base = pageRequest(r);
+	if (r.replaces_label && r.replaces_hash) {
+		const live = await ctx.DB.prepare("SELECT 1 FROM peers WHERE label = ? AND token_hash = ? AND revoked_at IS NULL").bind(r.replaces_label, r.replaces_hash).first();
+		if (live) return { ...base, tokenLabel: String(r.replaces_label) };
+	}
+	return { ...base, tokenLabel: await freeLabel(ctx, P.labelBase(r.client_name || "", r.client_id || "")) };
+}
+
 /** Optional page fields. Omitted when they would not change today's HTML. */
 function approvalPageBits(ctx: TenantContext): { oidc?: { label: string }; passwordEnabled?: boolean } {
 	const p = O.approvalPolicy(ctx.gates.approvalOidc);
@@ -1442,7 +1454,7 @@ async function devicePage(req: Request, ctx: TenantContext, url: URL, head = fal
 		}
 		const code = P.normUserCode(raw);
 		const r = code ? await pendingRequest(ctx, code) : null;
-		if (r && r.status === "pending" && Date.now() < r.expires_ms) model.request = pageRequest(r);
+		if (r && r.status === "pending" && Date.now() < r.expires_ms) model.request = await withTokenLabel(ctx, r);
 		else {
 			model.askCode = true;
 			model.codeValue = raw || "";
@@ -1549,14 +1561,14 @@ async function deviceOidcCallback(req: Request, ctx: TenantContext, url: URL, he
 		if (!seen.ok) {
 			if (seen.userCode) {
 				const pending = await pendingRequest(ctx, seen.userCode);
-				if (pending && pending.status === "pending" && Date.now() < pending.expires_ms) model.request = pageRequest(pending);
+				if (pending && pending.status === "pending" && Date.now() < pending.expires_ms) model.request = await withTokenLabel(ctx, pending);
 			}
 			model.notice = { kind: "error", text: seen.error };
 			return send(400);
 		}
 		const pending = seen.userCode ? await pendingRequest(ctx, seen.userCode) : null;
 		if (pending && pending.status === "pending" && Date.now() < pending.expires_ms) {
-			model.request = pageRequest(pending);
+			model.request = await withTokenLabel(ctx, pending);
 			return send(200);
 		}
 		model.notice = { kind: "error", text: "Nothing was approved." };
@@ -1567,7 +1579,7 @@ async function deviceOidcCallback(req: Request, ctx: TenantContext, url: URL, he
 		log("oidc_rejected", { kind: "device", reason: done.reason });
 		if (done.userCode) {
 			const pending = await pendingRequest(ctx, done.userCode);
-			if (pending && pending.status === "pending" && Date.now() < pending.expires_ms) model.request = pageRequest(pending);
+			if (pending && pending.status === "pending" && Date.now() < pending.expires_ms) model.request = await withTokenLabel(ctx, pending);
 		}
 		model.notice = { kind: "error", text: done.error };
 		return send(400);

package/worker/src/pairing.ts

@@ -173,7 +173,7 @@ export async function verifyPassword(password: string, rec: PasswordRecord): Pro
 // ------------------------------------------------------------------ /device page (no scripts, no external assets)
 export const esc = (s: unknown) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]!);
 
-export type PageRequest = { userCode: string; clientName: string; clientId: string; agentCardUrl: string; ip: string; country: string; createdMs: number; expiresMs: number; replacesLabel?: string };
+export type PageRequest = { userCode: string; clientName: string; clientId: string; agentCardUrl: string; ip: string; country: string; createdMs: number; expiresMs: number; replacesLabel?: string; tokenLabel?: string };
 export type PageModel = {
 	agentName: string;
 	mode: Mode;
@@ -197,13 +197,14 @@ export function devicePage(m: PageModel, nonce: string): string {
 		["Agent (as it calls itself)", r.clientName || r.clientId || "(no name given)"],
 		...(r.clientId && r.clientName && r.clientId !== r.clientName ? [["Alias (claimed)", r.clientId]] : []),
 		["Agent card (claimed)", r.agentCardUrl ? r.agentCardUrl + (cardIsPrivate(r.agentCardUrl) ? " (private network address, e.g. a Tailnet: not publicly reachable, so this inbox can't check it; informational only)" : "") : "(none given)"],
-		["Requested from", [r.ip || "unknown address", r.country].filter(Boolean).join(", ")],
+		["Requested from", `${[r.ip || "unknown address", r.country].filter(Boolean).join(", ")} (IP address of the machine that asked to connect)`],
 		["Expires", `${Math.max(0, Math.round((r.expiresMs - Date.now()) / 60000))} min`],
 		...(r.replacesLabel ? [["Replaces", `the active token "${r.replacesLabel}" (the requester proved it holds it); approving issues a new token under the same label and the old one stops working`]] : []),
 	] : [];
 	const notice = m.notice ? `<p class="n ${m.notice.kind}">${esc(m.notice.text)}</p>` : "";
+	const revoke = r?.tokenLabel ? `${m.cli} token revoke ${r.tokenLabel}` : `${m.cli} token revoke`;
 	const details = r ? `<table>${rows.map(([k, v]) => `<tr><th>${esc(k)}</th><td>${esc(v)}</td></tr>`).join("")}</table>
-<p class="w">Approve only if you expected this request and the code matches the one you were given. The name, alias and card URL are claimed by the requester. Approving gives it a token to send messages to this inbox; revoke it any time with <code>${esc(m.cli)} token revoke &lt;label&gt;</code>.</p>` : "";
+<p class="w">Approve only if you expected this request and the code matches the one you were given. The name, alias and card URL are claimed by the requester. Approving gives it a token to send messages to this inbox; revoke it any time with <code>${esc(revoke)}</code>.</p>` : "";
 	const noPassword = `<p class="n info">No approval password is set yet. Easiest: ask your agent to run <code>${esc(m.cli)} pair set-password --web</code> and send you the one-time link, then set the password on that page. Or run <code>${esc(m.cli)} pair set-password</code> yourself in a terminal on the owner's machine. Then reload this page. You can deny without a password.</p>`;
 	const denyOnly = `<form method="post" action="/device">
 <input type="hidden" name="csrf" value="${esc(m.csrf)}"><input type="hidden" name="user_code" value="${esc(r ? formatUserCode(r.userCode) : "")}">
@@ -294,11 +295,11 @@ export function setupPage(m: SetupModel, nonce: string): string {
 		? `<p>An approval password is already set (since ${esc(m.passwordSetAt)}). Saving here replaces it.</p>`
 		: `<p>Choose the password you will use to approve agents that ask to connect to this inbox.</p>`;
 	return pageShell(`Approval password for ${m.agentName}`, nonce, `${notice}${intro}
-<p class="w">Only you should know it: don't share it with your agent or anyone else. At least ${MIN_PASSWORD_LENGTH} characters; a passphrase of a few words works well. This one-time link expires in ${mins} min.</p>
+<p class="w">Only you should know it: don't share it with your agent or anyone else. Use ${MIN_PASSWORD_LENGTH} to 1024 characters. A passphrase of several unrelated words is stronger than one short word. This one-time link expires in ${mins} min.</p>
 <form method="post" action="/device/setup">
 <input type="hidden" name="csrf" value="${esc(m.csrf)}"><input type="hidden" name="t" value="${esc(m.token)}">
 <label for="pw1">New approval password</label><input id="pw1" name="password" type="password" autocomplete="new-password" required minlength="${MIN_PASSWORD_LENGTH}" maxlength="1024" autofocus>
-<label for="pw2">Repeat it</label><input id="pw2" name="password2" type="password" autocomplete="new-password" required minlength="${MIN_PASSWORD_LENGTH}" maxlength="1024">
+<label for="pw2">Repeat the password</label><input id="pw2" name="password2" type="password" autocomplete="new-password" required minlength="${MIN_PASSWORD_LENGTH}" maxlength="1024">
 <div class="b"><button type="submit">Set approval password</button></div>
 </form>`);
 }

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

package/worker/src/wake.ts

@@ -236,12 +236,20 @@ export function cloudflareErrorCode(body: string): string {
 	return m ? m[1] || m[2] || m[3] || m[4] : "";
 }
 
-/** Short explanation of a Cloudflare edge error page (e.g. "error code: 1033"), for wake test output. */
-export function cloudflareErrorHint(status: number, body: string): string {
+/** True when the wake URL's host is a Cloudflare Tunnel hostname (`*.cfargotunnel.com`). */
+export function wakeUrlIsTunnelHost(url: string): boolean {
+	try { return /\.cfargotunnel\.com$/i.test(new URL(url).hostname); } catch { return false; }
+}
+
+/** Short explanation of a Cloudflare edge error page (e.g. "error code: 1033"), for wake test output.
+ *  `tunnel` selects the 1016 wording: a tunnel hostname's DNS record, or a webhook host that failed to resolve. */
+export function cloudflareErrorHint(status: number, body: string, opts?: { tunnel?: boolean }): string {
 	const code = cloudflareErrorCode(body);
 	const known: Record<string, string> = {
 		"1033": "Cloudflare Tunnel has no running connector (start cloudflared on the agent's machine)",
-		"1016": "origin DNS error (the tunnel hostname has no matching DNS record)",
+		"1016": opts?.tunnel
+			? "origin DNS error (the tunnel hostname has no matching DNS record)"
+			: "origin DNS error (the webhook host failed to resolve)",
 		"1010": "blocked by a Cloudflare security rule",
 	};
 	if (code) return `Cloudflare error ${code}${known[code] ? ": " + known[code] : ""}`;

package/worker/test/pairing.test.ts

@@ -290,6 +290,9 @@ test("human approval: pending, slow_down, page approve with the password, single
 	assert.equal(g.status, 200);
 	assert.ok(!g.text.includes("<script>") && g.text.includes("Barry &lt;script&gt;"));
 	assert.ok(g.text.includes("https://barry.example.org/.well-known/agent-card.json") && g.text.includes("198.51.100.7"));
+	assert.match(g.text, /198\.51\.100\.7 \(IP address of the machine that asked to connect\)/);
+	assert.match(g.text, /token revoke Barry-script-alert-1-scr/);
+	assert.ok(!g.text.includes("&lt;label&gt;"));
 	assert.match(g.headers.get("content-security-policy")!, /^default-src 'none'; style-src 'nonce-[A-Za-z0-9_-]+'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'$/);
 	assert.equal(g.headers.get("cache-control"), "no-store");
 	assert.equal(g.headers.get("x-frame-options"), "DENY");
@@ -660,6 +663,9 @@ test("password setup link: one-time page sets the password (hashed on the Worker
 	assert.ok(!/<script|src=/i.test(get.text), "no scripts or external assets");
 	assert.match(get.text, /name="password" type="password" autocomplete="new-password" required minlength="12"/);
 	assert.match(get.text, /name="password2"/);
+	assert.match(get.text, /Repeat the password/);
+	assert.match(get.text, /Use 12 to 1024 characters/);
+	assert.match(get.text, /passphrase of several unrelated words/);
 	assert.match(get.text, /expires in 15 min/);
 	assert.equal(post.status, 200, post.text);
 	assert.match(post.text, /Approval password set \(\d{4}-\d\d-\d\dT[^)]+\)/);

package/worker/test/wake.test.ts

@@ -173,5 +173,8 @@ test("cloudflareErrorHint explains tunnel / Access failures", () => {
 	assert.match(cloudflareErrorHint(530, '<script>a={event:"feedback clicked",properties:{errorCode: 1033 }}</script>'), /1033/);
 	assert.match(cloudflareErrorHint(403, "Forbidden. You don't have access. cloudflareaccess.com"), /Cloudflare Access/);
 	assert.equal(cloudflareErrorHint(500, "boom"), "");
+	assert.match(cloudflareErrorHint(530, "error code: 1016"), /webhook host failed to resolve/);
+	assert.doesNotMatch(cloudflareErrorHint(530, "error code: 1016"), /tunnel hostname/);
+	assert.match(cloudflareErrorHint(530, "error code: 1016", { tunnel: true }), /tunnel hostname has no matching DNS record/);
 });