a2a-exposed 0.8.26 → 0.8.28

package/lib/config.mjs

@@ -54,6 +54,14 @@ export function get(key, dflt = "") {
 	return f !== undefined && f !== "" ? f : dflt;
 }
 
+/** Resolve a control credential with the origin from the same source.
+ * A partial environment override must never borrow saved credentials.
+ */
+export function controlSession(env = process.env, saved = fileConfig()) {
+	const source = env.CONTROL_URL || env.CONTROL_TOKEN ? env : saved;
+	return { origin: source.CONTROL_URL || "", token: source.CONTROL_TOKEN || "" };
+}
+
 function ensureDir() {
 	fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
 }

package/lib/deploy.mjs

@@ -124,6 +124,21 @@ function run(cmd, args, { cwd, env, capture = false, captureStderr = false, allo
 	return r;
 }
 
+/** Keep dependency installer output in a private local log. */
+export function installDependencies(dir, { configDir = C.CONFIG_DIR, env = process.env } = {}) {
+	fs.mkdirSync(configDir, { recursive: true, mode: 0o700 });
+	const log = path.join(configDir, "npm-install.log");
+	const fd = fs.openSync(log, "w", 0o600);
+	fs.fchmodSync(fd, 0o600);
+	let result;
+	try {
+		result = spawnSync("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir, env, stdio: ["ignore", fd, fd] });
+	} finally {
+		fs.closeSync(fd);
+	}
+	if (result.error || result.status !== 0) die(`npm install failed; inspect the private log: ${log}`);
+}
+
 export function cfBin(dir) {
 	const local = path.join(dir, "node_modules", ".bin", "cf");
 	return fs.existsSync(local) ? local : "cf";
@@ -439,15 +454,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 +506,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 +540,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)");
@@ -525,7 +576,7 @@ export async function init(o) {
 	step(`worker project -> ${dir}`);
 	syncTemplate(dir);
 	requireCfLogin(dir);
-	if (!o["skip-install"]) run("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir });
+	if (!o["skip-install"]) installDependencies(dir);
 	const env = cfEnv();
 
 	const dbName = C.get("A2A_D1_NAME") || C.get("A2A_WORKER_NAME");
@@ -552,6 +603,7 @@ export async function init(o) {
 	const base = deployedBase();
 	if (base) await verifyDeployedCard(base);
 	console.log(base);
+	await reportApprovalReadiness(base, ownerToken);
 	reportSwitch(switched);
 	proxyNote(secrets);
 	if (rotated) console.error(`owner token replaced. Update A2A_OWNER_TOKEN wherever this A2A endpoint is called, then run \`${CLI} peers sync\` so uploaded peers stay readable.`);
@@ -559,6 +611,21 @@ export async function init(o) {
 	printStar();
 }
 
+/** Read the deployed inbox, using its saved owner token rather than an environment override. */
+async function reportApprovalReadiness(base, ownerToken) {
+	try {
+		if (!base) throw new Error();
+		const { status, data } = await httpJson(`${base}/owner/pairing`, { headers: { authorization: `Bearer ${ownerToken}` }, timeout: 3000 });
+		if (status !== 200 || typeof data?.passwordSet !== "boolean" || !["human", "agent", "off"].includes(data.mode)) throw new Error();
+		if (data.mode === "off" || (Array.isArray(data.approvalMethods) && !data.approvalMethods.includes("password"))) return;
+		console.error(data.passwordSet ? "Approval password: set."
+			: `Approval password: not set. To approve pairing on /device with a password, run: ${CLI} pair set-password --web`);
+		if (!data.passwordSet) console.error("Send the one-time setup link privately to your human. They set the password themselves; never open the page or ask for the password.");
+	} catch {
+		console.error(`Approval password: could not check. Run: ${CLI} pair list --json`);
+	}
+}
+
 /** Proxy / expose mode reminder after a deploy (the upstream credentials are secrets: only their names are shown). */
 function proxyNote(secrets = {}) {
 	const up = C.get("A2A_UPSTREAM_URL");
@@ -649,7 +716,7 @@ export async function deploy(o) {
 	guardTunnelUrl();
 	step(`worker project -> ${dir}${cfProfile() ? ` (cf profile ${cfProfile()})` : ""}`);
 	syncTemplate(dir);
-	if (!o["skip-install"]) run("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir });
+	if (!o["skip-install"]) installDependencies(dir);
 	const env = cfEnv();
 	applyMigrations(dir, env);
 	const secrets = { ...deploySecretsFromEnv(), ...upstreamSecrets, ...await eventSecretFromStdin(o) };

package/lib/feedback.mjs

@@ -32,7 +32,7 @@ const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 /** The repository that will receive the issue. The prefilled form is ISSUE_REPO. A hosted post uses the name that URL returns. */
 export function publicIssueWarning(repo = ISSUE_REPO) {
 	const name = typeof repo === "string" && REPO_RE.test(repo) && repo.length <= 100 && !repo.includes("..") ? repo : ISSUE_REPO;
-	return `This report is filed as a public GitHub issue on ${name}. Do not include confidential information: secrets, tokens, owner or pairing tokens, private URLs or hostnames, message contents, or personal data.`;
+	return `Posting this report creates a public GitHub issue on ${name}. Do not include confidential information: secrets, tokens, owner or pairing tokens, private URLs or hostnames, message contents, or personal data.`;
 }
 
 export const PUBLIC_ISSUE_WARNING = publicIssueWarning(ISSUE_REPO);
@@ -316,6 +316,7 @@ export async function runFeedback(input) {
 		}),
 	});
 	if (!endpoint) return fallback();
+	await input.beforePost?.();
 	let response;
 	try {
 		response = await call(endpoint, {

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,178 @@
+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 * as C from "./config.mjs";
+import { readSigningSecret, validateSecretSource, writeTokenFile, startConnector, connectorCommand } from "./local-link.mjs";
+
+const sleepDefault = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const ERRORS = {
+	unauthorized: "Run a2a-exposed login, then run finish again.",
+	invalid_request: "Check the agent name, hostname and link options before running the command again.",
+	link_exists: "The link request was refused; review the approval page before changing or removing an existing link.",
+	apex_hostname: "The domain itself cannot be a secure link. Choose a hostname below it, such as wake.example.com, then run create again.",
+	outside_zone: "The hostname is not on a domain in your Cloudflare account. Choose a hostname on your domain, then run create again.",
+	existing_dns: "The hostname already has a DNS record. Choose another hostname, then run create again.",
+	existing_tunnel: "The hostname is already routed through another tunnel. Choose another hostname, then run create again.",
+	provision_failed: "Check the approval page for the failing provisioning phase and cleanup state before running the command again.",
+	preset: "Select a valid wake preset with --preset <id>, then run finish again.",
+	signing_secret: "Check the local signing-secret source and receiver configuration before running the command again.",
+	unreadable: "Reconnect Cloudflare on the website, then run finish again.",
+	unavailable: "The service is temporarily unavailable; retry later with fresh approval.",
+};
+const APPROVAL_ERRORS = new Set(["access_denied", "expired_token", "link_not_ready", "invalid_grant", "already_delivered", "connector_not_connected", "not_found", "cloudflare_unavailable"]);
+
+// Only these public validation templates may cross the server-text boundary.
+// Never echo arbitrary bodies, fetch errors, child output, or credential-bearing fields.
+const VALIDATION_MESSAGES = new Set([
+	"Choose a wake preset.", "Choose a wake preset and try again.",
+	"Use a hostname on the selected domain.",
+	"Use a full hostname such as wake.example.com.",
+	"Remove the scheme (https://), port and path. Use a full hostname such as wake.example.com.",
+	"Enter the local origin URL, such as http://127.0.0.1:8644.",
+	"Use an http or https origin with no path or credentials.",
+	"Use a path beginning with /, with no query or fragment.",
+]);
+function validationDetail(body, hostname) {
+	if (typeof body?.message !== "string") return "";
+	if (VALIDATION_MESSAGES.has(body.message)) return body.message.replace(/ and try again\.$/, ".");
+	const apex = `Use a hostname under ${hostname}, such as wake.${hostname}. The domain itself is not a secure link.`;
+	return hostname && body.message === apex ? apex : "";
+}
+
+function failure(status, body, { command, hostname }) {
+	const code = Object.hasOwn(ERRORS, body?.error) || APPROVAL_ERRORS.has(body?.error) ? body.error : `HTTP ${status}`;
+	const detail = ["invalid_request", "apex_hostname"].includes(code) ? validationDetail(body, hostname) : "";
+	const message = detail || (Object.hasOwn(ERRORS, code) ? ERRORS[code].replace(/run finish/g, `run ${command}`) : "check the link on the website and rerun the command for fresh approval");
+	return new CliError(`link ${command} failed${hostname ? ` for ${hostname}` : ""} (${code}); ${message}`);
+}
+
+export function savedLinkSession(origin, session = C.controlSession()) {
+	if (controlOrigin(session.origin) !== origin || !session.token)
+		throw new CliError("sign in to this service first: run login --control-url <service-origin>, then rerun link setup; environment sessions require both CONTROL_URL and CONTROL_TOKEN");
+	return session.token;
+}
+
+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}`);
+	}
+	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");
+	let origin;
+	try { origin = new URL(o.origin); } catch { throw new CliError("--origin must be an http or https origin"); }
+	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");
+	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");
+	return { hostname, origin: origin.origin, path: o.path, preset: o.preset };
+}
+
+export function createLink(o, deps) {
+	const create = createPlan(o);
+	// 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");
+	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");
+	return setupLink(o, deps);
+}
+
+async function setupLink(o, {
+	fetchImpl = fetch, sleep = sleepDefault, now = Date.now,
+	write = (line) => console.error(line), saveToken = writeTokenFile,
+	readSecret = readSigningSecret, runConnector = startConnector,
+	sessionToken = savedLinkSession,
+} = {}, create) {
+	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");
+	const origin = controlOrigin(o["control-url"]);
+	if (!origin) throw new CliError("--control-url must be an https origin with no path");
+	const session = sessionToken(origin);
+	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" }), ...(endpoint === "requests" ? { authorization: `Bearer ${session}` } : 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 ${context.command} request failed; check the connection and run ${context.command} 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, ...(create ? { create } : {}) });
+	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"); }
+	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, context);
+		authorized = token.body; break;
+	}
+	if (!authorized) throw failure(410, { error: "expired_token" }, context);
+	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");
+	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");
+	// 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);
+	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, context);
+		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 }, grant);
+	if (!tested.response.ok) throw failure(tested.response.status, tested.body, context);
+	if (tested.body.result !== "ok" || tested.body.saved !== true) {
+		const result = (["dns-missing", "access-401", "access-403", "timeout"].includes(tested.body.result) || /^origin-\d{3}$/.test(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 };
+}