a2a-exposed 0.8.25 → 0.8.27

package/lib/deploy.mjs

@@ -439,15 +439,46 @@ async function deployAndLearn(dir, secrets, o) {
 }
 
 /**
- * whoami before npm install. A previous install has node_modules/.bin/cf.
+ * whoami and accounts list run before npm install. A previous install has node_modules/.bin/cf.
  * A fresh init does not: `npx cf auth login` does not put `cf` on PATH, so this check uses `npx --yes cf`.
+ * cwd stays outside the Worker project. Inside it, cf loads cloudflare.config.ts, and that import fails
+ * with "Cannot find package 'cf'" until npm install. These commands do not need the project.
  */
+function cfAccountCwd() {
+	return os.tmpdir();
+}
+
+function firstStreamLine(text) {
+	return String(text || "").split(/\r?\n/).map((s) => s.trim()).find(Boolean) || "";
+}
+
 function cfSpawn(dir, args, { allowFail = false } = {}) {
 	const local = path.join(dir, "node_modules", ".bin", "cf");
 	const full = cfArgs(args);
-	return fs.existsSync(local)
-		? run(local, full, { cwd: dir, capture: true, allowFail })
-		: run("npx", ["--yes", "cf", ...full], { cwd: dir, capture: true, allowFail });
+	const cwd = cfAccountCwd();
+	const r = fs.existsSync(local)
+		? run(local, full, { cwd, capture: true, captureStderr: true, allowFail: true })
+		: run("npx", ["--yes", "cf", ...full], { cwd, capture: true, captureStderr: true, allowFail: true });
+	if (r.status !== 0 && !allowFail) die(cfCommandFailure(args, r));
+	return r;
+}
+
+function cfCommandFailure(args, r) {
+	const line = firstStreamLine(r && (r.stderr || r.stdout));
+	const code = r && r.status != null ? r.status : "unknown";
+	const shown = args.slice(0, 2).join(" ");
+	const prof = cfProfile();
+	const profileArg = prof ? ` --profile ${prof}` : "";
+	return `cf ${shown} failed (exit ${code})${line ? `: ${line}` : ""}\nCheck: npx --yes cf ${shown}${profileArg}   (run it outside the project directory)`;
+}
+
+function accountsListFailure(r) {
+	const line = firstStreamLine(r && r.stderr) || firstStreamLine(r && r.stdout);
+	const code = r && r.status != null ? r.status : "unknown";
+	const prof = cfProfile();
+	const forProfile = prof ? ` for profile "${prof}"` : "";
+	const check = `npx --yes cf accounts list${prof ? ` --profile ${prof}` : ""}`;
+	return `could not list Cloudflare accounts${forProfile}${line ? `: ${line}` : ""}\ncf accounts list failed (exit ${code}).\nCheck: ${check}   (run it outside the project directory)\nOr pass --account-id <id>.`;
 }
 
 function cfLoginJson(dir) {
@@ -460,13 +491,18 @@ function normalizeAccounts(raw) {
 	return list.filter((a) => a && typeof a.id === "string" && a.id).map((a) => ({ id: a.id, name: typeof a.name === "string" && a.name ? a.name : a.id }));
 }
 
-/** `cf accounts list` (GET /accounts). whoami intersects memberships and can return [] for a logged-in profile. */
-function accountsFromList(dir) {
+/** `cf accounts list` (GET /accounts). whoami intersects memberships and can return [] for a logged-in profile.
+ *  A non-zero exit is a failed cf call. It is not an empty account list. When an account id is already
+ *  set, a failed list is not fatal: init keeps that id. */
+function accountsFromList(dir, { required = true } = {}) {
 	const all = [];
 	const seen = new Set();
 	for (let page = 1; page <= 20; page++) {
 		const r = cfSpawn(dir, ["accounts", "list", "--page", String(page), "--per-page", "50"], { allowFail: true });
-		if (!r || r.status !== 0) return page === 1 ? [] : all;
+		if (!r || r.status !== 0) {
+			if (!required) return page === 1 ? [] : all;
+			die(accountsListFailure(r));
+		}
 		let data;
 		try { data = JSON.parse(r.stdout); } catch { return page === 1 ? [] : all; }
 		if (data && typeof data === "object" && !Array.isArray(data) && Array.isArray(data.result)) data = data.result;
@@ -489,7 +525,7 @@ function requireCfLogin(dir) {
 		? `cf profile "${prof}" is not logged in: run \`npx cf auth create ${prof} --no-browser\`, open the printed URL, enter the code, then re-run init`
 		: "not logged in to Cloudflare: run `npx cf auth login --no-browser`, open the printed URL, enter the code, then re-run init") + `\n${LOGIN_403_HELP}`);
 	let accts = normalizeAccounts(who.accounts);
-	if (!accts.length && prof) accts = accountsFromList(dir);
+	if (!accts.length && prof) accts = accountsFromList(dir, { required: !C.get("CLOUDFLARE_ACCOUNT_ID") });
 	if (!C.get("CLOUDFLARE_ACCOUNT_ID")) {
 		if (!accts.length && process.env.CLOUDFLARE_API_TOKEN)
 			die("the API token can't list accounts: add the permission User -> Memberships -> Read (or pass --account-id <id> / export CLOUDFLARE_ACCOUNT_ID; the id is in the dashboard URL)");

package/lib/layers.mjs

@@ -0,0 +1,205 @@
+// Eight read-only checks for `status`. Pure: the caller supplies DNS and HTTP results.
+// Each layer is PASS, FAIL, or SKIP. A failure names the missing or mismatched object and a fix.
+// Nothing here prints a token, a client secret, or a webhook key.
+import { CLI, isPrivateHost } from "./a2a.mjs";
+import { isIP } from "node:net";
+
+export const LAYER_NAMES = [
+	"Worker DNS",
+	"Worker",
+	"Owner API",
+	"Wake DNS",
+	"Access",
+	"Connector",
+	"Local webhook",
+	"Pairing",
+];
+
+const TLS_RE = /CERT_HAS_EXPIRED|UNABLE_TO_VERIFY_LEAF_SIGNATURE|ERR_TLS_CERT_ALTNAME_INVALID|DEPTH_ZERO_SELF_SIGNED_CERT|UNABLE_TO_GET_ISSUER_CERT|CERT_UNTRUSTED/;
+
+/** Shown when public DNS has the Worker hostname and this machine's resolver does not. */
+export function publicDnsMismatch(host) {
+	return `public DNS resolves ${host}; this machine's resolver does not (local cache or resolver). The Worker is reachable through Cloudflare.`;
+}
+
+/** Shown when public DNS has no A record for the Worker hostname. */
+export function noPublicDns(host) {
+	return `no public DNS record for ${host} yet: check the Worker custom domain in Cloudflare (Workers → Settings → Domains)`;
+}
+
+export const MACOS_RESOLVER_FIX = "sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder";
+
+/** An address from DNS-over-HTTPS that is safe to connect to (not loopback, LAN, or link-local). */
+export function usablePin(ip) {
+	return typeof ip === "string" && isIP(ip) !== 0 && !isPrivateHost(ip);
+}
+
+function layer(name, result, detail, fix = "") {
+	return { name, result, detail, fix: result === "FAIL" ? fix : "" };
+}
+
+/** One status row: `PASS|FAIL|SKIP  detail` and, on failure, `Fix: …`. */
+export function layerValue(l) {
+	if (!l || l.result !== "FAIL" || !l.fix) return `${l.result}  ${l.detail}`;
+	const gap = /[.]$/.test(l.detail) ? " " : ". ";
+	return `${l.result}  ${l.detail}${gap}Fix: ${l.fix}`;
+}
+
+function workerDnsLayer(f) {
+	if (!f.host) return layer("Worker DNS", "SKIP", "no base URL saved");
+	const d = f.workerDns || { kind: "skip" };
+	if (d.kind === "ip") return layer("Worker DNS", "PASS", `${f.host} is an address (no DNS name to resolve)`);
+	if (d.kind === "system") return layer("Worker DNS", "PASS", `system resolver resolved ${f.host}${d.ip ? ` to ${d.ip}` : ""}`);
+	if (d.kind === "public-only") {
+		const mac = f.platform === "darwin" ? ` ${MACOS_RESOLVER_FIX}` : "";
+		const fix = f.platform === "darwin" ? MACOS_RESOLVER_FIX : "flush this machine's DNS cache";
+		return layer("Worker DNS", "FAIL", `${publicDnsMismatch(f.host)}${mac}`, fix);
+	}
+	if (d.kind === "no-record") return layer("Worker DNS", "FAIL", noPublicDns(f.host));
+	if (d.kind === "fail") return layer("Worker DNS", "FAIL", `DNS lookup failed (${d.error || "unknown"}). Likely mismatched: resolver for ${f.host}`, "flush this machine's DNS cache, or check the hostname");
+	return layer("Worker DNS", "SKIP", "not checked");
+}
+
+function workerLayer(f) {
+	if (!f.baseUrl) return layer("Worker", "SKIP", "not checked (no base URL)");
+	const https = /^https:/i.test(f.baseUrl);
+	const card = f.card || { ok: false, error: "not checked" };
+	if (https && card.error && TLS_RE.test(card.error))
+		return layer("Worker", "FAIL", `Likely mismatched: TLS certificate for ${f.host}. ${card.error}`, `check the certificate for ${f.host} in Cloudflare (SSL/TLS)`);
+	if (!card.ok)
+		return layer("Worker", "FAIL", `Likely missing: deployed Worker. Agent card: ${card.error || "unreachable"}`, `${CLI} deploy`);
+	if (card.urlProblem)
+		return layer("Worker", "FAIL", `Likely mismatched: agent card URL. ${card.urlProblem}`, `${CLI} deploy`);
+	const tls = https ? "TLS ok" : "TLS skipped (not https)";
+	const named = card.name ? ` ("${card.name}")` : "";
+	const cardBit = `${tls}; agent card HTTP ${card.httpStatus || 200}${named}`;
+	const h = f.health;
+	if (!h || h.ok !== true) {
+		const problem = !h || h.httpStatus == null
+			? `/health unreachable${h && h.error ? ` (${h.error})` : ""}`
+			: h.httpStatus < 200 || h.httpStatus >= 300
+				? `/health HTTP ${h.httpStatus}`
+				: `/health HTTP ${h.httpStatus} did not report ok`;
+		return layer("Worker", "FAIL", `Likely missing: Worker /health. ${cardBit}; ${problem}`, `${CLI} deploy`);
+	}
+	return layer("Worker", "PASS", `${cardBit}; /health HTTP ${h.httpStatus || 200}`);
+}
+
+function ownerLayer(f) {
+	if (!f.deployed || !f.baseUrl) return layer("Owner API", "SKIP", "not checked (nothing deployed)");
+	if (!f.hasOwnerToken) return layer("Owner API", "FAIL", "Likely missing: owner token", `${CLI} init`);
+	if (f.ownerApi && f.ownerApi.ok) return layer("Owner API", "PASS", "owner token accepted");
+	const err = (f.ownerApi && f.ownerApi.error) || "not checked";
+	if (err === "not checked") return layer("Owner API", "SKIP", "not checked");
+	if (/HTTP 401/.test(err)) return layer("Owner API", "FAIL", "Likely mismatched: owner token", `${CLI} init --rotate-owner-token`);
+	return layer("Owner API", "FAIL", `Likely missing: deployed Worker. ${err}`, `${CLI} deploy`);
+}
+
+function wakeDnsLayer(f) {
+	if (!f.wakeHost) return layer("Wake DNS", "SKIP", "no wake hostname");
+	const d = f.wakeDns || { kind: "skip" };
+	if (d.kind === "pass") return layer("Wake DNS", "PASS", `public DNS resolves ${f.wakeHost}${d.ip ? ` to ${d.ip}` : ""}`);
+	if (d.kind === "no-record") return layer("Wake DNS", "FAIL", `no public DNS record for ${f.wakeHost} yet. Likely missing: tunnel DNS record for ${f.wakeHost}`, `${CLI} tunnel status`);
+	if (d.kind === "fail") return layer("Wake DNS", "FAIL", `wake DNS check failed (${d.error || "unknown"}). Likely missing: tunnel DNS record for ${f.wakeHost}`, `${CLI} tunnel status`);
+	return layer("Wake DNS", "SKIP", "not checked");
+}
+
+function accessProtected(bare) {
+	if (!bare || bare.error || bare.status == null) return false;
+	if (bare.status === 401 || bare.status === 403) return true;
+	return bare.status >= 300 && bare.status < 400 && /cloudflareaccess\.com/i.test(bare.location || "");
+}
+
+function accessLayer(f) {
+	if (!f.wakeHost) return layer("Access", "SKIP", "no wake hostname");
+	const dns = f.wakeDns || {};
+	if (dns.kind === "no-record" || dns.kind === "fail") return layer("Access", "SKIP", "not checked (wake DNS failed)");
+	const bare = f.bare;
+	if (!bare) return layer("Access", "SKIP", "not checked");
+	if (bare.error) return layer("Access", "FAIL", `wake endpoint not reachable (${bare.error}). Likely missing: DNS record or Access application for ${f.wakeHost}`, `${CLI} tunnel status`);
+	if (!accessProtected(bare))
+		return layer("Access", "FAIL", `bare request was not blocked (HTTP ${bare.status}). Likely missing: Access application for ${f.wakeHost}`, `${CLI} tunnel status`);
+	if (f.serviceToken !== "configured")
+		return layer("Access", "FAIL", `protected (HTTP ${bare.status}); Access service token not configured. Likely missing: Access service token`, `${CLI} tunnel create`);
+	return layer("Access", "PASS", `protected (HTTP ${bare.status}); Access service token configured`);
+}
+
+function connectorLayer(f) {
+	const t = f.tunnel;
+	if (!t) return layer("Connector", "SKIP", "no tunnel configured");
+	const file = t.tokenFile || "tunnel-token";
+	if (!t.complete) return layer("Connector", "FAIL", "Likely mismatched: unfinished tunnel", `${CLI} tunnel rm, then ${CLI} tunnel create`);
+	if (!t.tokenFileOk) return layer("Connector", "FAIL", `Likely missing: connector token file (${file})`, `${CLI} tunnel create`);
+	if (t.grace) return layer("Connector", "SKIP", `waiting for the connector to connect. Start \`cloudflared tunnel run --token-file ${file}\``);
+	if (t.down1033 || t.connections === 0)
+		return layer("Connector", "FAIL", `Likely missing: cloudflared connector${t.down1033 ? " (Cloudflare error 1033)" : ""}`, `cloudflared tunnel run --token-file ${file}`);
+	if (typeof t.connections === "number" && t.connections > 0) return layer("Connector", "PASS", `connected (${t.connections})`);
+	return layer("Connector", "SKIP", "connector state unknown");
+}
+
+function webhookLayer(f) {
+	if (!f.wakeHost) return layer("Local webhook", "SKIP", "no wake hostname");
+	const dns = f.wakeDns || {};
+	if (dns.kind === "no-record" || dns.kind === "fail") return layer("Local webhook", "SKIP", "not checked (wake DNS failed)");
+	if (f.tunnel && f.tunnel.grace) return layer("Local webhook", "SKIP", "not checked (connector still connecting)");
+	if (!f.localServiceToken) {
+		const where = f.serviceToken === "configured" ? "the Worker has an Access service token; this machine does not" : "no Access service token in the local config";
+		return layer("Local webhook", "SKIP", `not probed (${where})`);
+	}
+	const p = f.authed;
+	if (!p) return layer("Local webhook", "SKIP", "not checked");
+	if (p.cf === "1033") return layer("Local webhook", "SKIP", "not reached (Cloudflare error 1033)");
+	const origin = f.tunnel && f.tunnel.origin ? ` at ${f.tunnel.origin}` : "";
+	if (p.error) return layer("Local webhook", "FAIL", `wake endpoint not reachable (${p.error}). Likely missing: local webhook${origin}`, "start the agent's webhook");
+	const refusal = serviceTokenRefusal(p);
+	if (refusal) return layer("Local webhook", "FAIL", `Likely mismatched: Access service token or Access policy. The service-token request was refused (${refusal})`, `${CLI} tunnel status`);
+	if (p.status === 502 || p.status === 504 || p.status === 530)
+		return layer("Local webhook", "FAIL", `wake endpoint HTTP ${p.status}. Likely missing: local webhook${origin}`, "start the agent's webhook");
+	return layer("Local webhook", "PASS", `wake endpoint HTTP ${p.status}`);
+}
+
+/** Login host, Access path, Access error page, or an Access challenge. "Forbidden" alone is not a marker. */
+const ACCESS_MARK = /cloudflareaccess\.com|\/cdn-cgi\/access\/|cloudflare[- ]access/i;
+
+/** True when this response shows Cloudflare Access, from its headers or its body. */
+function accessMarked(p) {
+	const headers = Array.isArray(p.accessHeaders) ? p.accessHeaders : [];
+	if (headers.some((n) => String(n).toLowerCase().startsWith("cf-access-"))) return true;
+	return ACCESS_MARK.test(String(p.location || ""))
+		|| ACCESS_MARK.test(String(p.wwwAuthenticate || ""))
+		|| ACCESS_MARK.test(String(p.body || ""));
+}
+
+/** Access rejected the service token: a login redirect, or a 401/403 that carries Access markers.
+ *  A 401/403 without those markers is not an Access refusal. The location URL is not repeated. */
+function serviceTokenRefusal(p) {
+	if (!p || p.error || p.status == null) return "";
+	const loc = String(p.location || "");
+	const login = /cloudflareaccess\.com|\/cdn-cgi\/access\//i.test(loc);
+	if (p.status >= 300 && p.status < 400 && login) return `HTTP ${p.status} redirect to the Cloudflare Access login`;
+	if ((p.status === 401 || p.status === 403) && accessMarked(p)) return `HTTP ${p.status} from Cloudflare Access`;
+	return "";
+}
+
+function pairingLayer(f) {
+	if (!f.deployed || !f.baseUrl) return layer("Pairing", "SKIP", "not checked (nothing deployed)");
+	const p = f.pairing;
+	if (!p) return layer("Pairing", "SKIP", "not checked (owner API did not report pairing)");
+	if (p.mode === "off") return layer("Pairing", "PASS", "off (token issue only)");
+	if (p.mode === "agent") return layer("Pairing", "PASS", "agent approval");
+	if (p.mode === "human" && p.passwordSet) return layer("Pairing", "PASS", "approval password set");
+	if (p.mode === "human" && p.oidcIssuer) return layer("Pairing", "PASS", `OpenID Connect (${p.oidcIssuer})`);
+	if (p.mode === "human") return layer("Pairing", "FAIL", "Likely missing: approval password", `${CLI} pair set-password --web`);
+	return layer("Pairing", "SKIP", "not checked");
+}
+
+/** The eight layers, in order. `f` is the snapshot gathered by `status` (no secrets). */
+export function buildLayers(f) {
+	const layers = [
+		workerDnsLayer(f), workerLayer(f), ownerLayer(f), wakeDnsLayer(f),
+		accessLayer(f), connectorLayer(f), webhookLayer(f), pairingLayer(f),
+	];
+	if (layers.length !== LAYER_NAMES.length || layers.some((l, i) => l.name !== LAYER_NAMES[i] || !["PASS", "FAIL", "SKIP"].includes(l.result)))
+		throw new Error("status layers drifted");
+	return layers;
+}

package/lib/link-finish.mjs

@@ -0,0 +1,97 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import os from "node:os";
+import { CliError } from "./a2a.mjs";
+import { controlOrigin } from "./account.mjs";
+import { readSigningSecret, validateSecretSource, writeTokenFile, startConnector, connectorCommand } from "./local-link.mjs";
+
+const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const ERRORS = new Set(["access_denied", "expired_token", "link_not_ready", "invalid_grant", "already_delivered", "connector_not_connected", "not_found", "cloudflare_unavailable"]);
+
+// Deliberately never echo server text, bodies, fetch errors, or child output.
+function failure(status, body) {
+	const code = ERRORS.has(body?.error) ? body.error : `HTTP ${status}`;
+	return new CliError(`link finish failed (${code}); check the link on the website and run finish again for fresh approval`);
+}
+
+export async function finishLink(o, {
+	fetchImpl = fetch, sleep = sleepDefault, now = Date.now,
+	write = (line) => console.error(line), saveToken = writeTokenFile,
+	readSecret = readSigningSecret, runConnector = startConnector,
+} = {}) {
+	validateSecretSource(o);
+	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)");
+	const origin = controlOrigin(o["control-url"]);
+	if (!origin) throw new CliError("--control-url must be an https origin with no path");
+	const request = async (endpoint, body, grant, timeout = 15000) => {
+		let response;
+		try {
+			response = await fetchImpl(`${origin}/api/link-finish/${endpoint}`, {
+				method: body === undefined ? "GET" : "POST", redirect: "error",
+				headers: { accept: "application/json", ...(body === undefined ? {} : { "content-type": "application/json" }), ...(grant ? { authorization: `Grant ${grant}` } : {}) },
+				...(body === undefined ? {} : { body: JSON.stringify(body) }), signal: AbortSignal.timeout(timeout),
+			});
+			const text = await response.text();
+			if (text.length > 128 * 1024) throw new Error();
+			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 finish request failed; check the connection and run finish again for fresh approval"); }
+	};
+	const verifier = crypto.randomBytes(32).toString("base64url");
+	const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");
+	const started = await request("requests", { agent, challenge });
+	if (started.response.status !== 201) throw failure(started.response.status, started.body);
+	const setup = started.body;
+	let approval;
+	try { approval = new URL(setup.approve_url); } catch { throw new CliError("invalid approval response"); }
+	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");
+	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;
+	for (let poll = 0; poll < 120 && now() < deadline; poll++) {
+		await sleep(Math.min(interval * 1000, deadline - now()));
+		if (now() >= deadline) break;
+		const token = await request("token", { request_id: setup.request_id, verifier });
+		if (token.response.status === 428 && token.body.error === "authorization_pending") continue;
+		if (token.response.status === 429 && token.body.error === "slow_down") { interval += 5; continue; }
+		if (!token.response.ok) throw failure(token.response.status, token.body);
+		authorized = token.body; break;
+	}
+	if (!authorized) throw failure(410, { error: "expired_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" || !link.preset || typeof link.hostname !== "string" || typeof link.origin !== "string")
+		throw new CliError("invalid approved link response");
+	// Resolve and validate the source before spending the one-time connector delivery.
+	const secret = readSecret(o, link);
+	const connector = await request("connector", {}, grant);
+	if (!connector.response.ok) throw failure(connector.response.status, connector.body);
+	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");
+	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 };
+	}
+	await runConnector(tokenFile);
+	let connected = false;
+	const connectDeadline = now() + 60000;
+	for (let poll = 0; poll < 20 && now() < connectDeadline; poll++) {
+		const status = await request("status", undefined, grant, Math.min(15000, connectDeadline - now()));
+		if (now() >= connectDeadline) break;
+		if (!status.response.ok) throw failure(status.response.status, status.body);
+		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");
+	const tested = await request("wake-test", { signing_secret: secret, preset: link.preset }, grant);
+	if (!tested.response.ok) throw failure(tested.response.status, tested.body);
+	if (tested.body.result !== "ok" || tested.body.saved !== true) {
+		const result = ["dns-missing", "access-401", "access-403", "origin-4xx/5xx", "timeout"].includes(tested.body.result) ? tested.body.result : "unknown";
+		throw new CliError(`wake test did not save settings (${result}); fix the receiver and run finish again for fresh approval`);
+	}
+	write("Connector connected. Wake test passed and settings saved.");
+	return { saved: true, connectorStarted: true };
+}

package/lib/local-link.mjs

@@ -0,0 +1,101 @@
+// Shared local setup operations. No shell, token arguments, or child output.
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+import { spawn } from "node:child_process";
+import { CliError } from "./a2a.mjs";
+
+export function writeTokenFile(file, token) {
+	const dir = path.dirname(file);
+	let tmp, fd;
+	try {
+		fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+		tmp = path.join(dir, `.a2a-token-${crypto.randomBytes(16).toString("hex")}`);
+		fd = fs.openSync(tmp, "wx", 0o600);
+		fs.fchmodSync(fd, 0o600);
+		fs.writeFileSync(fd, token + "\n");
+		fs.fsyncSync(fd);
+		fs.closeSync(fd); fd = undefined;
+		fs.renameSync(tmp, file);
+	} catch {
+		throw new CliError("could not save the connector token; fix the destination permissions and retry setup; hosted finish needs fresh approval");
+	} finally {
+		if (fd !== undefined) fs.closeSync(fd);
+		if (tmp && fs.existsSync(tmp)) fs.unlinkSync(tmp);
+	}
+}
+
+function readPrivate(file) {
+	let fd;
+	try {
+		fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+		const stat = fs.fstatSync(fd);
+		if (!stat.isFile() || (stat.mode & 0o777) !== 0o600 || stat.size > 1024 * 1024)
+			throw new Error();
+		return fs.readFileSync(fd, "utf8");
+	} catch {
+		throw new CliError("secret source must be a readable regular file with mode 600 (no symlinks, maximum 1 MiB)");
+	} finally {
+		if (fd !== undefined) fs.closeSync(fd);
+	}
+}
+
+function usableSecret(value) {
+	if (typeof value !== "string" || !value.trim() || value === "INSECURE_NO_AUTH" || Buffer.byteLength(value) > 65536)
+		throw new CliError("the selected source has no usable signing secret");
+	return value;
+}
+
+export function validateSecretSource(o) {
+	if (["secret-file", "secret-env", "secret-from"].filter((key) => o[key] !== undefined).length !== 1)
+		throw new CliError("choose exactly one of --secret-file, --secret-env, or --secret-from hermes");
+	if (o["secret-from"] !== undefined && o["secret-from"] !== "hermes")
+		throw new CliError("the only secret adapter is hermes");
+	if ((o["hermes-home"] || o.route) && o["secret-from"] !== "hermes")
+		throw new CliError("--hermes-home and --route require --secret-from hermes");
+	if (o["secret-env"] !== undefined && !/^[A-Za-z_][A-Za-z0-9_]*$/.test(o["secret-env"]))
+		throw new CliError("--secret-env must name an environment variable");
+}
+
+export function readSigningSecret(o, link, env = process.env) {
+	validateSecretSource(o);
+	if (o["secret-file"] !== undefined) return usableSecret(readPrivate(o["secret-file"]).replace(/\r?\n$/, ""));
+	if (o["secret-env"] !== undefined) return usableSecret(env[o["secret-env"]]);
+	if (link.preset !== "hermes") throw new CliError("the Hermes adapter requires the hermes preset");
+	const match = /^\/webhooks\/([A-Za-z0-9_-]+)$/.exec(link.path);
+	if (!match || (o.route && o.route !== match[1]))
+		throw new CliError("Hermes route does not match the approved link path; select the exact route and Hermes home");
+	const home = o["hermes-home"] || env.HERMES_HOME || path.join(os.homedir(), ".hermes");
+	// Static YAML routes override dynamic subscriptions. Without a YAML dependency,
+	// fail closed on any routes key; never guess which secret the gateway uses.
+	try {
+		const config = fs.readFileSync(path.join(home, "config.yaml"), "utf8");
+		if (/\broutes\b/.test(config)) throw new CliError("Hermes static routes may override this subscription; use --secret-file or --secret-env for the exact route secret");
+	} catch (error) {
+		if (error instanceof CliError) throw error;
+		if (error.code !== "ENOENT") throw new CliError("could not check Hermes static route configuration");
+	}
+	let subscriptions;
+	try { subscriptions = JSON.parse(readPrivate(path.join(home, "webhook_subscriptions.json")).replace(/^\uFEFF/, "")); }
+	catch (error) {
+		if (error instanceof CliError) throw error;
+		throw new CliError("could not parse the Hermes subscriptions file");
+	}
+	const route = Object.hasOwn(subscriptions || {}, match[1]) ? subscriptions[match[1]] : null;
+	if (!route || route.enabled === false) throw new CliError("the selected Hermes subscription is missing or disabled");
+	return usableSecret(route.secret);
+}
+
+export const connectorArgs = (file) => ["tunnel", "run", "--token-file", file];
+export const connectorCommand = (file) => "cloudflared " + connectorArgs(file).map((s) => "'" + s.replaceAll("'", "'\\''") + "'").join(" ");
+
+export async function startConnector(file, spawnImpl = spawn) {
+	let child;
+	try {
+		child = spawnImpl("cloudflared", connectorArgs(file), { detached: true, stdio: "ignore", env: Object.fromEntries(Object.entries(process.env).filter(([key]) => ["PATH", "HOME", "TMPDIR", "TEMP", "TMP", "SystemRoot", "WINDIR"].includes(key))) });
+		await new Promise((resolve, reject) => { child.once("error", reject); child.once("spawn", resolve); });
+		child.unref();
+		return child;
+	} catch { throw new CliError("could not start cloudflared; install cloudflared and run finish again"); }
+}

package/lib/main.mjs

@@ -12,6 +12,7 @@ import * as account from "./account.mjs";
 import * as upd from "./update.mjs";
 import * as fb from "./feedback.mjs";
 import * as un from "./uninstall.mjs";
+import { finishLink } from "./link-finish.mjs";
 
 const VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
@@ -22,6 +23,15 @@ Usage: npx -y a2a-exposed@latest <command> [options]
        --version, -v                 print the version
        --help, -h                    print this help
 
+  hosted link finish --agent NAME --control-url https://control.example
+       (--secret-file FILE | --secret-env VAR | --secret-from hermes)
+       [--hermes-home DIR] [--route NAME] [--token-file FILE] [--no-run]
+                                Human approves the printed URL/code. Saves the connector token privately,
+                                starts cloudflared, waits up to 60 seconds, then tests and saves the wake.
+                                --control-url defaults to saved CONTROL_URL. No secrets in arguments/output.
+                                --no-run saves the token and prints the connector command; wake is not saved.
+                                Recovery: rerun with fresh approval; the ready link is reused.
+
 Setup (needs Node 22.18+, e.g. \`mise exec node@22 -- npx -y a2a-exposed@latest ...\`, and a Cloudflare login:
 npx cf auth login --no-browser; on a VPS where it fails with HTTP 403 before showing a code, export
 CLOUDFLARE_API_TOKEN instead: setup skill, Troubleshooting. a2a.exposed hosts the A2A endpoint and is open to everyone
@@ -44,6 +54,7 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
                                 --cf-profile   cf auth profile for a separate Cloudflare login
                                                (npx cf auth create NAME --no-browser); saved, used by every cf call.
                                                When whoami lists no accounts, init reads cf accounts list
+                                               outside the Worker directory. A failed list prints cf's error unless --account-id is set
                                 --d1-name      D1 database to create or reuse (default: worker name)
                                 --pairing-approval  who approves device-flow pairing requests (default human:
                                                the owner token via \`pair approve\`, or the approval password
@@ -156,6 +167,16 @@ Status
                                 \`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.
+                                Prints eight layers in order, each PASS, FAIL, or SKIP, and still checks the
+                                later layers after one fails: Worker DNS (system lookup, then DNS-over-HTTPS
+                                when that lookup fails), Worker (TLS, the agent card, and /health), Owner API,
+                                Wake DNS, Access (protected or not, and whether a service token is configured;
+                                the token is never printed), Connector, Local webhook (HTTP status of the wake
+                                endpoint), and Pairing. A 401 or 403 fails the local webhook layer only when the
+                                response shows Cloudflare Access. The webhook's own auth refusal reports the HTTP
+                                status and passes, as does a 401 or 403 with no Access marker. A failure names the
+                                missing or mismatched object and a fix. --json includes layers (eight objects).
+                                Exit 1 if any layer fails.
                                 For about a minute after tunnel create, while the connector reports 0 connections,
                                 status prints "waiting for the connector to connect" and exits 0. After that,
                                 0 connections is broken. A tunnel status of inactive is "never connected".
@@ -328,6 +349,7 @@ const deployOpts = {
 	"workers-dev": B, "workers-dev-subdomain": S, "upstream-token-stdin": B, "no-upstream-token": B, "event-secret-stdin": B,
 };
 const SPEC = {
+	hosted: { agent: S, "control-url": S, "secret-file": S, "secret-env": S, "secret-from": S, "hermes-home": S, route: S, "token-file": S, "no-run": B },
 	init: { ...deployOpts, ...tunnelOpts, tunnel: B }, deploy: deployOpts, wake: deployOpts, tunnel: tunnelOpts,
 	inbox: { context: S, from: S, all: B, json: B },
 	reply: { text: S, stdin: B, state: { type: "string", default: "completed" }, artifact: B, "artifact-name": { type: "string", default: "response" }, force: B },
@@ -449,6 +471,10 @@ export async function main(argv) {
 			if (sub === "forward") return address.forward(o);
 			throw new CliError(`unknown peer action ${sub} (announce|forward)`);
 		}
+		case "hosted": {
+			if (p.length !== 2 || p[0] !== "link" || p[1] !== "finish") throw new CliError("usage: hosted link finish --agent NAME (--secret-file FILE | --secret-env VAR | --secret-from hermes)");
+			return finishLink({ ...o, "control-url": o["control-url"] || C.get("CONTROL_URL") });
+		}
 		case "signup":
 		case "login": {
 			const result = await account.deviceLogin({ controlUrl: o["control-url"] || C.get("CONTROL_URL"), intent: name });