a2a-exposed 0.8.26 → 0.8.28

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, createLink } from "./link-finish.mjs";
 
 const VERSION = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
@@ -22,10 +23,12 @@ Usage: npx -y a2a-exposed@latest <command> [options]
        --version, -v                 print the version
        --help, -h                    print this help
 
+Setup options: --skip-install skips dependency installation when dependencies already exist.
+
 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
-(https://a2a.exposed/pricing). When to use it, and the sentence to say:
+(https://a2a.exposed/pricing). When to use it:
 https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md#hosted-inbox)
   init [--hostname <host> | --workers-dev [--workers-dev-subdomain NAME]]
        [--agent-name N] [--agent-description D] [--agent-skills JSON]
@@ -41,14 +44,18 @@ https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md
                                 --workers-dev  move an existing custom-domain deployment to workers.dev (and
                                                --hostname H moves it back); the old URL answers 301/410
                                 --workers-dev-subdomain  create the account's workers.dev subdomain if missing
+                                               Uses system script on macOS/Linux, including under automation.
                                 --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
                                                on the /device page; agent: the agent runs \`pair approve\` after
                                                the human says yes; off: no pairing endpoints, \`token issue\` only)
+                                init reports readiness when password approval is enabled; when missing, use
+                                               \`pair set-password --web\` for the human-owned setup page.
                                 --pbkdf2-iterations  approval-password hashing cost, 50000-100000 (default 100000,
                                                the Workers maximum; lower only if /device hits error 1102)
                                 --workers-logs on|off  persisted Cloudflare Workers Logs (query strings redacted)
@@ -156,6 +163,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".
@@ -260,7 +277,7 @@ Owner
   the MCP consent page when the issuer, client id, client secret, and allowlist are all set.
 
 Feedback
-  feedback "message" [--kind bug|idea|other] [--contact x]
+  feedback "message" [--json] [--kind bug|idea|other] [--contact x]
             [--steps S] [--expected S] [--actual S] [--logs S] [--agent A]
             [--environment local|cloud VM|CI|cloud agent sandbox|other]
             [--connection webhook|proxy|polling] [--yes]
@@ -272,9 +289,9 @@ Feedback
                                 confidential information: secrets, tokens, owner or pairing
                                 tokens, private URLs or hostnames, message contents, or
                                 personal data. Prints that warning and asks before sending,
-                                unless --yes is set. Off a terminal, --yes is required.
+                                unless --yes is set. Off a terminal, posting requires --yes.
                                 Posts when this A2A endpoint names a feedback URL.
-                                Otherwise prints a link to the bug
+                                Otherwise prints Not filed and a link to the bug
                                 report form and does not open a browser. The CLI adds its
                                 version, the A2A endpoint Worker version when the A2A endpoint reports it,
                                 the OS, the Node version, the connection (webhook, proxy, or
@@ -282,7 +299,7 @@ Feedback
                                 that detection. Remove tokens from the message and from --logs.
 
 Presets: grok-bot | claude-code | openclaw-wake | openclaw-agent | hermes | openbot | generic
-         Which clients are tested end to end is in the client table:
+         Clients and how to load them:
          https://github.com/telegraphic-dev/a2a-exposed/blob/main/docs/getting-started.md#clients
 Config: ${C.CONFIG_FILE}  (override dir with --config-dir DIR or A2A_CONFIG_DIR; env vars override file values)
 Update notice: at most a daily background check of the npm registry; off with A2A_NO_UPDATE_CHECK=1 (or DO_NOT_TRACK=1)`;
@@ -328,6 +345,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, hostname: S, origin: S, path: S, preset: 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 },
@@ -341,10 +359,11 @@ const SPEC = {
 	export: { sql: B },
 	upstream: { json: B },
 	connect: { alias: S, name: S, json: B, "no-wait": B, replace: B, force: B, "card-url": S },
+	// Internal hosted-service integration commands. Keep out of public help until the production flow is available.
 	signup: { "control-url": S, json: B },
 	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 },
+	feedback: { kind: S, contact: S, steps: S, expected: S, actual: S, logs: S, agent: S, environment: S, connection: S, yes: B, json: B },
 	uninstall: { yes: B, "dry-run": B, dir: S, "worker-dir": S },
 };
 const STATES = ["completed", "input-required", "failed", "rejected", "working"];
@@ -388,7 +407,7 @@ export async function main(argv) {
 		if (e && e.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
 			const flag = (String(e.message).match(/'([^']+)'/) || [])[1] || "that flag";
 			if (flag === "-y") throw new CliError("unknown flag -y. To skip a prompt, pass --yes.");
-			throw new CliError(`unknown flag ${flag}. Run \`${CLI} ${name} --help\` for this command's flags.`);
+			throw new CliError(`unknown flag ${flag}. Run \`${CLI} --help\` and see the ${name} section.`);
 		}
 		if (e && String(e.code || "").startsWith("ERR_PARSE_ARGS")) throw new CliError(String(e.message));
 		throw e;
@@ -449,6 +468,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" || !["finish", "create"].includes(p[1])) throw new CliError("usage: hosted link create --agent NAME --hostname HOST --origin URL --path PATH --preset ID (--secret-file FILE | --secret-env VAR | --secret-from hermes); or hosted link finish --agent NAME (--secret-file FILE | --secret-env VAR | --secret-from hermes)");
+			return (p[1] === "create" ? createLink : finishLink)({ ...o, "control-url": o["control-url"] || C.get("CONTROL_URL") });
+		}
 		case "signup":
 		case "login": {
 			const result = await account.deviceLogin({ controlUrl: o["control-url"] || C.get("CONTROL_URL"), intent: name });
@@ -469,21 +492,22 @@ export async function main(argv) {
 		case "outbound": return cmd.outbound(need(p[0], "outbound <taskId>"));
 		case "feedback": {
 			const message = p.join(" ").trim();
-			need(message, `feedback "message" [--kind bug|idea|other] [--steps S] [--expected S] [--actual S] [--logs S] [--agent A] [--environment E] [--connection webhook|proxy|polling]`);
+			need(message, `feedback "message" [--json] [--kind bug|idea|other] [--steps S] [--expected S] [--actual S] [--logs S] [--agent A] [--environment E] [--connection webhook|proxy|polling]`);
 			const kind = o.kind || "other";
 			if (!fb.KINDS.includes(kind)) throw new CliError("--kind must be bug, idea, or other");
 			if (o.connection && !fb.CONNECTIONS.includes(o.connection)) throw new CliError("--connection must be webhook, proxy, or polling");
 			if (kind === "bug" && !String(o.steps || "").trim()) throw new CliError("a bug report needs reproduction steps (--steps)");
 			const repo = await fb.feedbackPublicRepo({ baseUrl: C.get("A2A_BASE_URL"), ownerToken: C.get("A2A_OWNER_TOKEN") });
-			await fb.confirmPublicIssue(Boolean(o.yes), undefined, undefined, repo);
 			const result = await fb.runFeedback({
+				beforePost: () => fb.confirmPublicIssue(Boolean(o.yes), undefined, undefined, repo),
 				message, kind, contact: o.contact || "", version: VERSION,
 				steps: o.steps || "", expected: o.expected || "", actual: o.actual || "", logs: o.logs || "",
 				agent: o.agent || "", environment: o.environment || "",
 				connection: o.connection || "",
 				baseUrl: C.get("A2A_BASE_URL"), ownerToken: C.get("A2A_OWNER_TOKEN"),
 			});
-			console.log(result.url);
+			if (!result.filed) console.error("Not filed: this A2A endpoint has no feedback inbox. Open this link to file it on GitHub:");
+			console.log(o.json ? JSON.stringify(result.filed ? { filed: true, issue: result.url } : result) : result.url);
 			return;
 		}
 		default: throw new CliError(`unknown command ${name} (see --help)`);

package/lib/script.mjs

@@ -0,0 +1,56 @@
+// Node's "pipe" stdin is a socket on macOS. BSD script refuses its ioctl
+// error, so relay stdin through a real shell pipe before allocating the PTY.
+import { spawn } from "node:child_process";
+
+export function spawnScript(args, options = {}) {
+	if (process.platform !== "darwin") return forwardShutdown(spawn("script", args, { ...options, detached: true, stdio: ["pipe", "pipe", "pipe"] }));
+	// All command arguments remain positional, never interpolated into shell code.
+	// fd 3 reports script completion so cat cannot keep the wrapper alive waiting
+	// for input. The terminal job cannot write that channel or inherit it.
+	const relay = '/bin/cat | { "$@" 3>&-; result=$?; printf "%s\\n" "$result" >&3; exit "$result"; }';
+	const child = spawn("/bin/sh", ["-c", relay, "a2a-script", "/usr/bin/script", ...args], {
+		...options, detached: true, stdio: ["pipe", "pipe", "pipe", "pipe"],
+	});
+	child.stdio[3].once("data", () => child.stdin.end());
+	child.stdio[3].resume();
+	child.stdin.on("error", () => {}); // script can exit just before an answer.
+	return forwardShutdown(child);
+}
+
+export function stopScript(child, signal = "SIGTERM") {
+	if (!child.pid) return false;
+	try {
+		// Stop the relay and script together. Closing the PTY master also hangs
+		// up the terminal job rather than leaving it waiting for an answer.
+		process.kill(-child.pid, signal);
+		return true;
+	} catch (error) {
+		if (error.code === "ESRCH") return false;
+		throw error;
+	}
+}
+
+// Detached PTYs do not receive the CLI's terminal signals. Forward shutdown
+// before allowing the parent's usual signal behavior, and release all hooks
+// on spawn failure or completion so repeated commands do not retain children.
+function forwardShutdown(child) {
+	const handlers = new Map();
+	const cleanup = () => {
+		for (const [signal, handler] of handlers) process.removeListener(signal, handler);
+		process.removeListener("exit", onExit);
+	};
+	const onExit = () => stopScript(child);
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+		const handler = () => {
+			stopScript(child, signal);
+			cleanup();
+			if (process.listenerCount(signal) === 0) process.kill(process.pid, signal);
+		};
+		handlers.set(signal, handler);
+		process.on(signal, handler);
+	}
+	process.on("exit", onExit);
+	child.once("error", cleanup);
+	child.once("close", cleanup);
+	return child;
+}