a2a-exposed 0.4.0 → 0.4.1

package/lib/a2a.mjs

@@ -185,3 +185,70 @@ export async function rpc(url, version, token, method03, method1, params, peer =
 		die(`peer returned ${data && typeof data === "object" && data.error ? `JSON-RPC error ${describeHttp(status, data).replace(/^HTTP \d+: /, "")} (HTTP ${status})` : describeHttp(status, data)}`);
 	return data.result;
 }
+
+// ---------------------------------------------------------------- proxy mode: what the upstream card asks for
+// Same rules as the Worker's facade.ts (schemeKind / upstreamAuth); keep the two in step.
+
+/** "bearer" (HTTP bearer; OAuth 2.0 / OpenID Connect also send `Authorization: Bearer`), "basic", "http", "apiKey",
+ *  "mtls" or "unknown", for an A2A 1.0 ({ httpAuthSecurityScheme: ... }) or 0.3 / OpenAPI ({ type: "http", ... }) scheme. */
+export function schemeKind(s) {
+	if (!s || typeof s !== "object") return "unknown";
+	const http = (scheme) => { const v = String(scheme || "").toLowerCase(); return v === "bearer" ? "bearer" : v === "basic" ? "basic" : "http"; };
+	if (s.httpAuthSecurityScheme) return http(s.httpAuthSecurityScheme.scheme);
+	if (s.oauth2SecurityScheme || s.openIdConnectSecurityScheme) return "bearer";
+	if (s.apiKeySecurityScheme) return "apiKey";
+	if (s.mtlsSecurityScheme || s.mutualTlsSecurityScheme) return "mtls";
+	switch (String(s.type || "").toLowerCase()) {
+		case "http": return http(s.scheme);
+		case "oauth2": case "openidconnect": return "bearer";
+		case "apikey": return "apiKey";
+		case "mutualtls": return "mtls";
+	}
+	return "unknown";
+}
+
+/** { bearer: true | false | null, schemes: ["name: kind"], unsupported: [...] } for an upstream card. bearer: true when
+ *  the card asks for a bearer token (UPSTREAM_TOKEN), false when it declares no bearer / HTTP auth (no schemes,
+ *  anonymous allowed, or only schemes the façade can't present), null without a card. Requirements come from 1.0
+ *  `securityRequirements` or 0.3 `security`; without requirements every declared scheme counts. */
+export function upstreamAuth(card) {
+	if (!card || typeof card !== "object" || Array.isArray(card)) return { bearer: null, schemes: [], unsupported: [] };
+	const defs = card.securitySchemes && typeof card.securitySchemes === "object" && !Array.isArray(card.securitySchemes) ? card.securitySchemes : {};
+	const kinds = {};
+	for (const [n, s] of Object.entries(defs)) kinds[n] = schemeKind(s);
+	const schemes = Object.entries(kinds).map(([n, k]) => `${n}: ${k}`);
+	const raw = Array.isArray(card.securityRequirements) ? card.securityRequirements : Array.isArray(card.security) ? card.security : [];
+	const alts = raw.filter((r) => r && typeof r === "object" && !Array.isArray(r))
+		.map((r) => Object.keys(r.schemes && typeof r.schemes === "object" && !Array.isArray(r.schemes) ? r.schemes : r));
+	const kindOf = (n) => kinds[n] || "unknown";
+	if (!alts.length) {
+		const all = Object.keys(kinds);
+		const bearer = all.some((n) => kinds[n] === "bearer");
+		return { bearer, schemes, unsupported: bearer ? [] : all.filter((n) => kinds[n] !== "unknown").map((n) => `${n}: ${kinds[n]}`) };
+	}
+	if (alts.some((a) => a.length === 0)) return { bearer: false, schemes, unsupported: [] };
+	const bearer = alts.some((a) => a.some((n) => kindOf(n) === "bearer"));
+	return { bearer, schemes, unsupported: bearer ? [] : [...new Set(alts.flat())].map((n) => `${n}: ${kindOf(n)}`) };
+}
+
+/** Fetch the upstream's card from this machine (setup check), with the Access service token from the environment
+ *  when exported; only ever to the upstream origin (the caller checked it). Never sends UPSTREAM_TOKEN. Returns
+ *  { card } or { card: null, error }. Redirects are not followed (an Access login redirect is reported as such). */
+export async function fetchUpstreamCard(cardUrl, env = process.env) {
+	const headers = { accept: "application/json", "user-agent": "a2a-exposed-cli" };
+	if (env.UPSTREAM_ACCESS_CLIENT_ID && env.UPSTREAM_ACCESS_CLIENT_SECRET) {
+		headers["cf-access-client-id"] = env.UPSTREAM_ACCESS_CLIENT_ID;
+		headers["cf-access-client-secret"] = env.UPSTREAM_ACCESS_CLIENT_SECRET;
+	}
+	let r;
+	try { r = await fetch(cardUrl, { headers, redirect: "manual", signal: AbortSignal.timeout(15000) }); }
+	catch (e) { return { card: null, error: `request failed: ${e?.cause?.code || e?.cause?.message || e?.message || e}` }; }
+	const text = (await r.text().catch(() => "")).slice(0, 262144);
+	const loc = r.headers.get("location") || "";
+	if (r.status >= 300 && r.status < 400)
+		return { card: null, error: /cloudflareaccess\.com|\/cdn-cgi\/access\//i.test(loc) ? `HTTP ${r.status}: redirected to the Cloudflare Access login (export UPSTREAM_ACCESS_CLIENT_ID / UPSTREAM_ACCESS_CLIENT_SECRET so this check can pass Access)` : `HTTP ${r.status} redirect` };
+	let data = null;
+	try { data = JSON.parse(text); } catch { /* not JSON */ }
+	if (r.status === 200 && data && typeof data === "object" && !Array.isArray(data)) return { card: data };
+	return { card: null, error: describeHttp(r.status, data ?? text) };
+}

package/lib/config.mjs

@@ -1,14 +1,12 @@
-// Config storage: ~/.config/a2a-exposed/config.env (chmod 600) + peers.json. Before the rename the directory was
-// ~/.config/a2a-over-webhook: when only that one exists it is used as is (nothing is moved or copied).
+// Config storage: ~/.config/a2a-exposed/config.env (chmod 600) + peers.json.
 // Environment variables always override values from config.env.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-/** <base>/a2a-exposed, or the pre-rename <base>/a2a-over-webhook when only that exists (an existing deployment). */
-export function defaultConfigDir(base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config"), exists = fs.existsSync) {
-	const dir = path.join(base, "a2a-exposed"), legacy = path.join(base, "a2a-over-webhook");
-	return !exists(dir) && exists(legacy) ? legacy : dir;
+/** <base>/a2a-exposed (base: $XDG_CONFIG_HOME or ~/.config). */
+export function defaultConfigDir(base = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config")) {
+	return path.join(base, "a2a-exposed");
 }
 
 export const CONFIG_DIR = process.env.A2A_CONFIG_DIR || defaultConfigDir();

package/lib/deploy.mjs

@@ -5,8 +5,9 @@ import path from "node:path";
 import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import * as C from "./config.mjs";
-import { cardUrlProblem, cfErrorCode, die, fingerprint, httpJson, randomToken, upstreamCardUrlProblem, upstreamUrlProblem } from "./a2a.mjs";
-import { owner } from "./commands.mjs";
+import { cardUrlProblem, cfErrorCode, die, fetchUpstreamCard, fingerprint, httpJson, randomToken, upstreamAuth, upstreamCardUrlProblem, upstreamUrlProblem } from "./a2a.mjs";
+import { owner, ownerTry } from "./commands.mjs";
+import { readHidden } from "./pair.mjs";
 import * as WD from "./workersdev.mjs";
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -43,10 +44,8 @@ export const PAIRING_MODES = ["human", "agent", "off"];
 export const DEPLOY_FLAGS = Object.keys(FLAG_KEYS);
 
 const step = (s) => console.error(`==> ${s}`);
-// Worker (and default D1) name for new deployments. A deployment made before the rename that has no saved
-// A2A_WORKER_NAME (a hand-written config.env) keeps the old default, so `deploy` never creates a second Worker.
-export const LEGACY_WORKER_NAME = "a2a-over-webhook";
-export const workerName = () => C.get("A2A_WORKER_NAME") || (C.get("A2A_D1_ID") ? LEGACY_WORKER_NAME : "a2a-exposed");
+// Worker (and default D1) name: A2A_WORKER_NAME (saved by init), else a2a-exposed.
+export const workerName = () => C.get("A2A_WORKER_NAME") || "a2a-exposed";
 /** No custom hostname: the Worker is served on <worker>.<account subdomain>.workers.dev (and only there). */
 const workersDevMode = () => !C.get("A2A_HOSTNAME");
 export const publicBase = () =>
@@ -63,6 +62,9 @@ export const NODE_HELP = `How to get Node 22 (any one; no root needed):
   or the official installer / binaries: https://nodejs.org/en/download
 Then check: node --version   (v22.18.0 or newer)`;
 
+/** What to do when the Cloudflare login itself is blocked (printed with "not logged in"; the setup skill says the same). */
+export const LOGIN_403_HELP = `If \`cf auth login\` (or \`wrangler login\`) fails with "OAuth error: HTTP 403 Forbidden" or a "Just a moment..." page BEFORE any code is shown, that is Cloudflare's bot mitigation for datacenter / VPS IPs, not a wrong account: don't retry. Use an API token instead: export CLOUDFLARE_API_TOKEN (and CLOUDFLARE_ACCOUNT_ID) in the environment, never argv (setup skill, Troubleshooting: API token).`;
+
 /** Dies unless `version` (default: this Node) is 22.18+; the message says how to get it. */
 export function checkNode(version = process.versions.node) {
 	const [maj, min] = String(version).replace(/^v/, "").split(".").map(Number);
@@ -199,7 +201,11 @@ function applyFlags(o) {
 	if (upd.WAKE_PRESET && !PRESETS.includes(upd.WAKE_PRESET)) die(`unknown preset ${upd.WAKE_PRESET} (${PRESETS.join(" | ")})`);
 	for (const [flag, key] of [["upstream", "A2A_UPSTREAM_URL"], ["upstream-card-url", "A2A_UPSTREAM_CARD_URL"]]) {
 		if (upd[key] === undefined) continue;
-		if (["", "none", "off"].includes(String(upd[key]).trim().toLowerCase())) { upd[key] = null; continue; }
+		if (["", "none", "off"].includes(String(upd[key]).trim().toLowerCase())) {
+			upd[key] = null;
+			if (key === "A2A_UPSTREAM_URL") upd.A2A_UPSTREAM_NO_TOKEN = null; // the opt-out belonged to that upstream
+			continue;
+		}
 		const why = upstreamUrlProblem(String(upd[key]).trim());
 		if (why) die(`--${flag} ${why}`);
 		upd[key] = new URL(String(upd[key]).trim()).href;
@@ -346,7 +352,9 @@ function deployedBase() {
 
 export async function init(o) {
 	checkNode();
+	const prevUpstream = C.fileConfig().A2A_UPSTREAM_URL || "";
 	const switched = applyFlags(o);
+	const upstreamSecrets = await upstreamTokenCheck(o, { upstreamChanged: (C.get("A2A_UPSTREAM_URL") || "") !== prevUpstream });
 	const dir = workerDir(o);
 	C.saveConfig({ A2A_WORKER_DIR: dir, A2A_WORKER_NAME: workerName() });
 	if (workersDevMode()) {
@@ -361,11 +369,15 @@ export async function init(o) {
 	const prof = cfProfile();
 	step(`checking Cloudflare login (cf auth whoami${prof ? ` --profile ${prof}` : ""})`);
 	const who = cfJson(dir, ["auth", "whoami"]);
-	if (!who.authenticated) die(prof
+	if (!who.authenticated) die((process.env.CLOUDFLARE_API_TOKEN
+		? "CLOUDFLARE_API_TOKEN is set but cf does not accept it (expired, revoked, or IP-restricted: an IP filter must allow both this host's IPv4 /32 and IPv6 /128). Check the token (setup skill, Troubleshooting: API token), then re-run init"
+		: prof
 		? `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 `cf auth login --no-browser`, open the printed URL, enter the code, then re-run init");
+		: "not logged in to Cloudflare: run `cf auth login --no-browser`, open the printed URL, enter the code, then re-run init") + `\n${LOGIN_403_HELP}`);
 	const accts = who.accounts || [];
 	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)");
 		if (accts.length !== 1) die(`${accts.length} accounts available; pass --account-id <id>:\n` + accts.map((a) => `  ${a.id}  ${a.name}`).join("\n"));
 		C.saveConfig({ CLOUDFLARE_ACCOUNT_ID: accts[0].id });
 	} else if (accts.length && !accts.some((a) => a.id === C.get("CLOUDFLARE_ACCOUNT_ID"))) {
@@ -391,30 +403,102 @@ export async function init(o) {
 	if (!ownerToken || o["rotate-owner-token"]) ownerToken = randomToken(32);
 	C.saveConfig({ A2A_OWNER_TOKEN: ownerToken, A2A_BASE_URL: publicBase() || undefined });
 
-	const secrets = { OWNER_TOKEN: ownerToken, ...deploySecretsFromEnv() };
+	const secrets = { OWNER_TOKEN: ownerToken, ...deploySecretsFromEnv(), ...upstreamSecrets };
 	step(`deploying (secrets uploaded: ${Object.keys(secrets).join(", ")})`);
 	await deployAndLearn(dir, secrets, o);
 	const base = deployedBase();
 	if (base) await verifyDeployedCard(base);
 	console.log(base);
 	reportSwitch(switched);
-	proxyNote();
+	proxyNote(secrets);
 	console.error(`config saved to ${C.CONFIG_FILE} (chmod 600). Next: a2a-exposed status (shows the next setup step)`);
 }
 
-/** Proxy / expose mode reminder after a deploy (the upstream credentials are secrets: only their presence is shown). */
-function proxyNote() {
+/** 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");
 	if (!up) return;
-	const sent = UPSTREAM_SECRETS.filter((k) => process.env[k]);
+	const sent = UPSTREAM_SECRETS.filter((k) => k in secrets);
 	console.error(`proxy mode: authenticated A2A calls are forwarded to ${up}; the public card is the upstream's, rewritten to this deployment's URL.` +
-		` Upstream secrets uploaded now: ${sent.join(", ") || "none (existing ones kept)"}. Check the upstream and the card with: a2a-exposed status`);
+		` Upstream secrets uploaded now: ${sent.join(", ") || "none (existing ones kept)"}. Check the whole path (Access, the agent's bearer check) with: a2a-exposed status`);
+}
+
+/** stdin and stderr are a terminal (a human at the keyboard), and not CI: only then may setup prompt. */
+const interactive = () => !!(process.stdin.isTTY && process.stderr.isTTY && !process.env.CI);
+
+/** Proxy mode setup check: the façade must hold the bearer token the upstream agent checks (UPSTREAM_TOKEN) in addition
+ *  to the Cloudflare Access service token, which only gets the Worker through the tunnel. Returns extra secrets to
+ *  upload ({ UPSTREAM_TOKEN } when read from stdin or a hidden prompt), or dies with what to do. Never reads argv.
+ *  Order: --upstream-token-stdin / exported UPSTREAM_TOKEN (uploaded) > --no-upstream-token (saved opt-out) > the
+ *  Worker already holds one for this upstream, or the card it fetched declares no bearer > the upstream card fetched from
+ *  here (with the exported Access token): no bearer declared -> fine; bearer or unknown -> hidden prompt on a terminal,
+ *  else exit 1. */
+export async function upstreamTokenCheck(o, { upstreamChanged = false } = {}) {
+	const up = C.get("A2A_UPSTREAM_URL");
+	if (!up) return {};
+	if (o["upstream-token-stdin"] && o["no-upstream-token"]) die("--upstream-token-stdin and --no-upstream-token are mutually exclusive");
+	if (o["upstream-token-stdin"]) {
+		const t = (process.stdin.isTTY ? await readHidden("UPSTREAM_TOKEN, the bearer the upstream agent expects (not shown): ") : fs.readFileSync(0, "utf8")).trim();
+		if (!t) die("--upstream-token-stdin: no token on stdin");
+		C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: null });
+		return { UPSTREAM_TOKEN: t };
+	}
+	if (process.env.UPSTREAM_TOKEN) { C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: null }); return {}; } // uploaded with the other exported secrets
+	if (o["no-upstream-token"]) {
+		C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: "1" });
+		console.error("note: --no-upstream-token: deploying without an upstream bearer token (saved; `status` warns if the upstream card asks for one)");
+		return {};
+	}
+	if (C.get("A2A_UPSTREAM_NO_TOKEN") === "1") return {};
+	// an existing façade for this upstream: the Worker's secrets persist across deploys, and it reads the card through Access
+	if (!upstreamChanged && C.get("A2A_BASE_URL") && C.get("A2A_OWNER_TOKEN")) {
+		try {
+			const r = await ownerTry("GET", "/owner/facade");
+			if (r.status === 200 && r.data && r.data.mode === "proxy") {
+				if (r.data.hasUpstreamToken) return {};
+				if (r.data.upstreamAuth && r.data.upstreamAuth.bearer === false) return {};
+			}
+		} catch { /* not deployed yet / unreachable: check the card from here */ }
+	}
+	const cardUrl = C.get("A2A_UPSTREAM_CARD_URL") || new URL("/.well-known/agent-card.json", up).href;
+	step(`checking which credential the upstream's agent card asks for (${cardUrl})`);
+	const { card, error } = await fetchUpstreamCard(cardUrl);
+	const auth = upstreamAuth(card);
+	if (auth.unsupported.length)
+		console.error(`warning: the upstream card requires ${auth.unsupported.join(", ")}; the façade only presents \`Authorization: Bearer <UPSTREAM_TOKEN>\` (plus the Access service token), so the agent may refuse it`);
+	if (auth.bearer === false) {
+		console.error(`upstream card: no bearer auth declared${auth.schemes.length ? ` (schemes: ${auth.schemes.join(", ")})` : ""}, so no UPSTREAM_TOKEN is needed`);
+		return {};
+	}
+	const why = auth.bearer
+		? `the upstream's agent card asks for a bearer token (${auth.schemes.join(", ")})`
+		: `the upstream's agent card could not be read from here (${error}), so whether the agent needs a bearer token is unknown`;
+	const access = "Cloudflare Access (UPSTREAM_ACCESS_CLIENT_ID / _SECRET) only lets the Worker through the tunnel; the agent checks its own token too";
+	if (interactive()) {
+		console.error(`${why}. ${access}.`);
+		const t = (await readHidden("UPSTREAM_TOKEN, the bearer the upstream agent expects (not shown; empty = the agent needs none): ")).trim();
+		if (t) { C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: null }); return { UPSTREAM_TOKEN: t }; }
+		if (auth.bearer) die("no UPSTREAM_TOKEN given, but the upstream card asks for one: peers' calls would fail with HTTP 502. Re-run and enter it, or pass --no-upstream-token if the agent really accepts calls without it");
+		C.saveConfig({ A2A_UPSTREAM_NO_TOKEN: "1" });
+		console.error("note: deploying without an upstream bearer token (saved; check the whole path with `a2a-exposed status`)");
+		return {};
+	}
+	die(`${why}, and no UPSTREAM_TOKEN is set. ${access}, so without it every peer call fails with HTTP 502.\n` +
+		"  Provide it (never as an argument): `read -rs UPSTREAM_TOKEN && export UPSTREAM_TOKEN`, then re-run; or pipe it: <command that prints the token> | a2a-exposed " +
+		`${C.get("A2A_D1_ID") ? "deploy" : "init ..."} --upstream-token-stdin\n` +
+		"  The agent needs no bearer token? Re-run with --no-upstream-token (saved for later deploys).");
 }
 
 export async function deploy(o) {
 	checkNode();
 	if (!C.get("A2A_D1_ID")) die("no saved deployment; run `a2a-exposed init` first");
+	// init saves A2A_WORKER_NAME before it creates the D1 database, so a saved D1 without a name is a hand-edited config:
+	// refuse rather than guess, so a redeploy never creates a second Worker next to the one this config deployed.
+	if (!C.get("A2A_WORKER_NAME") && o["worker-name"] === undefined)
+		die(`${C.CONFIG_FILE} has a saved deployment (A2A_D1_ID) but no A2A_WORKER_NAME; rerun with --worker-name <the Worker it deployed> (saved for next time)`);
+	const prevUpstream = C.fileConfig().A2A_UPSTREAM_URL || "";
 	const switched = applyFlags(o);
+	const upstreamSecrets = await upstreamTokenCheck(o, { upstreamChanged: (C.get("A2A_UPSTREAM_URL") || "") !== prevUpstream });
 	const dir = workerDir(o);
 	if (workersDevMode() && !WD.LABEL_RE.test(workerName())) die("on workers.dev the worker name must be a DNS label (lowercase letters, digits, hyphens)");
 	guardTunnelUrl();
@@ -423,14 +507,14 @@ export async function deploy(o) {
 	if (!o["skip-install"]) run("npm", ["install", "--no-audit", "--no-fund", "--loglevel=error"], { cwd: dir });
 	const env = cfEnv();
 	applyMigrations(dir, env);
-	const secrets = deploySecretsFromEnv();
+	const secrets = { ...deploySecretsFromEnv(), ...upstreamSecrets };
 	if (Object.keys(secrets).length && C.get("A2A_OWNER_TOKEN")) secrets.OWNER_TOKEN = C.get("A2A_OWNER_TOKEN");
 	step(Object.keys(secrets).length ? `deploying (secrets uploaded: ${Object.keys(secrets).join(", ")})` : "deploying (existing secrets kept)");
 	await deployAndLearn(dir, secrets, o);
 	const base = deployedBase();
 	if (base) await verifyDeployedCard(base);
 	if (switched) { console.log(base); reportSwitch(switched); }
-	proxyNote();
+	proxyNote(secrets);
 }
 
 /** Fingerprints of the wake secrets in the local environment (what `wake set` would upload). */

package/lib/main.mjs

@@ -16,13 +16,14 @@ const HELP = `a2a-exposed ${VERSION} - public A2A endpoint for any AI agent (Clo
 Usage: a2a-exposed <command> [options]        (or: npx a2a-exposed <command>)
 
 Setup (needs Node 22.18+, e.g. \`mise exec node@22 -- npx a2a-exposed ...\`, and a Cloudflare login:
-npx cf auth login --no-browser)
+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)
   init [--hostname <host> | --workers-dev [--workers-dev-subdomain NAME]]
        [--agent-name N] [--agent-description D] [--agent-skills JSON]
        [--provider-organization O --provider-url U] [--preset P] [--worker-name W] [--d1-name D]
        [--account-id ID] [--cf-profile NAME] [--cli-command CMD] [--debounce S] [--max-per-hour N]
        [--pairing-approval human|agent|off] [--pbkdf2-iterations N] [--workers-logs on|off] [--cron]
-       [--upstream URL [--upstream-card-url URL]] [--worker-dir DIR]
+       [--upstream URL [--upstream-card-url URL] [--upstream-token-stdin | --no-upstream-token]] [--worker-dir DIR]
                                 deploy the Worker + D1 to your account; wake secrets are read from
                                 env WAKE_WEBHOOK_URL / WAKE_WEBHOOK_KEY / WAKE_HMAC_SECRET (never argv)
                                 no --hostname: serve on https://<worker>.<account subdomain>.workers.dev
@@ -48,6 +49,12 @@ npx cf auth login --no-browser)
                                 --upstream-card-url  the upstream's card (default <upstream origin>/.well-known/
                                                agent-card.json); must be on the --upstream origin (it is
                                                fetched with the upstream credentials)
+                                               Setup reads that card: unless it declares no bearer auth, the
+                                               façade needs UPSTREAM_TOKEN besides the Access token (Access only
+                                               gets the Worker through the tunnel). Without it: a hidden prompt
+                                               on a terminal, else exit 1 with what to do
+                                --upstream-token-stdin  read UPSTREAM_TOKEN from stdin (hidden prompt on a terminal)
+                                --no-upstream-token  the upstream needs no bearer token: skip that check (saved)
                                 --cli-command  command shown in wake hints (default "npx a2a-exposed";
                                                e.g. "node /path/to/repo/cli/bin/a2a-exposed.mjs")
                                 --worker-dir   where the Worker project (template copy) lives (default
@@ -79,9 +86,16 @@ anywhere on the account: the inbox itself can be on workers.dev or a custom host
 
 Status
   status [--json]               deployment, base URL, agent card check (fetched by the CLI: no curl needed), wake
-                                mode (webhook / tunnel / none = polling), tunnel state, proxy-mode upstream and
-                                card-leak check (--upstream), and the next step to run.
+                                mode (webhook / tunnel / none = polling), tunnel state, proxy mode (--upstream):
+                                upstream card, Access credential and upstream bearer configured (separately), the
+                                live upstream check, the last failed peer call, card-leak check; warnings for peer
+                                token variables shadowing saved tokens; and the next step to run.
                                 Read-only; run it after an interruption and continue from "next step". Exit 1 = broken
+  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
+                                is created): Cloudflare Access, the agent's bearer check, the A2A app. Exit 1 unless
+                                the app answered. \`status\` runs the same check
   url                           print the public base URL (exit 1 if none is configured)
   config                        print config (secrets masked) and its location
 
@@ -126,7 +140,7 @@ Outbound (agents you call)
   peers add <alias> <url> [--token-env VAR | --token-stdin]
   peers list | peers rm <alias>
                           a token variable set in the environment overrides config.env; when a peer token
-                          differs between the two, connect/send/poll/peers warn on stderr (values never shown)
+                          differs between the two, connect/send/poll/peers/status warn (values never shown)
   send --to <alias|url> [--text T | stdin] [--context C] [--task T] [--push] [--proto 0.3|1.0]
   poll --to <alias|url> <taskId> [--proto 0.3|1.0]
   outbound <taskId>       stored state of a task you sent (incl. pushed updates)
@@ -139,7 +153,7 @@ const S = { type: "string" }, B = { type: "boolean" };
 const tunnelOpts = { "tunnel-hostname": S, "tunnel-zone": S, "tunnel-origin": S, "tunnel-path": S, "show-token": B, "zero-trust-org": S, dir: S, "worker-dir": S };
 const deployOpts = {
 	...Object.fromEntries(dep.DEPLOY_FLAGS.map((f) => [f, S])), dir: S, "worker-dir": S, cron: B, "skip-install": B, "rotate-owner-token": B,
-	"workers-dev": B, "workers-dev-subdomain": S,
+	"workers-dev": B, "workers-dev-subdomain": S, "upstream-token-stdin": B, "no-upstream-token": B,
 };
 const SPEC = {
 	init: { ...deployOpts, ...tunnelOpts, tunnel: B }, deploy: deployOpts, wake: deployOpts, tunnel: tunnelOpts,
@@ -151,6 +165,7 @@ const SPEC = {
 	send: { to: S, text: S, context: S, task: S, push: B, proto: S },
 	poll: { to: S, proto: S },
 	status: { json: B },
+	upstream: { json: B },
 	connect: { alias: S, name: S, json: B, "no-wait": B, replace: B, force: B, "card-url": S },
 	pair: { json: B, web: B, ttl: S },
 };
@@ -188,6 +203,11 @@ export async function main(argv) {
 		case "tunnel": return tun.tunnel(need(p[0], "tunnel create|status|rm"), o);
 		case "deploy": return dep.deploy(o);
 		case "status": return st.status(o);
+		case "upstream": {
+			const sub = need(p[0], "upstream verify [--json]");
+			if (sub === "verify" || sub === "check") return st.upstreamVerify(o);
+			throw new CliError(`unknown upstream action ${sub} (verify)`);
+		}
 		case "wake": return dep.wake(p[0], o);
 		case "url": {
 			const u = cmd.baseUrl();

package/lib/pair.mjs

@@ -181,7 +181,7 @@ export function cardUrlToSend(flag, own, quiet = false) {
 	if (flag) {
 		let u;
 		try { u = new URL(flag); } catch { die(`--card-url must be a URL (your agent card, e.g. https://agent.example.com/.well-known/agent-card.json)`); }
-		if (u.protocol !== "https:" || u.username || u.password) { note(`note: --card-url ${u.origin} is not a plain https URL, so it is left out of the pairing request (inboxes accept only https cards)`); return ""; }
+		if (u.protocol !== "https:" || u.username || u.password) { note(`note: --card-url ${u.origin} is not a plain https URL, so it is left out of the pairing request (inboxes accept only public https cards). Peers can't call an agent there: to be reachable, expose it through a public façade (setup skill: "Already have A2A on a Tailnet or LAN") and pass the façade's card`); return ""; }
 		if (u.href.length > 300) { note("note: --card-url is longer than 300 characters, so it is left out of the pairing request"); return ""; }
 		if (isPrivateHost(u.hostname)) note(`note: ${u.hostname} is on a private network: the peer's owner sees the card as informational ("not publicly reachable"). Expose your agent through a public façade for others to reach it (setup skill: "Already have A2A on a Tailnet or LAN").`);
 		return u.href;
@@ -278,7 +278,9 @@ A different agent at the same URL? Pass another --alias.`);
 		const r = await postForm(ep.device, params, replace && oldToken ? oldToken : null);
 		if (r.status !== 200 || !r.data.device_code || !r.data.user_code) {
 			const why = r.data.error_description || r.data.error || `HTTP ${r.status}`;
-			die(r.status === 429 ? `${peerName} is not accepting more pairing requests right now: ${why}` : r.status === 404 ? `${peerName} has device-flow pairing disabled (${why}); ask its owner for a token` : `pairing request to ${peerName} failed: ${why}`);
+			const privateCard = !!card && (() => { try { return isPrivateHost(new URL(card).hostname); } catch { return false; } })();
+			die(r.status === 429 ? `${peerName} is not accepting more pairing requests right now: ${why}` : r.status === 404 ? `${peerName} has device-flow pairing disabled (${why}); ask its owner for a token`
+				: `pairing request to ${peerName} failed: ${why}${privateCard && r.status === 400 ? `. The card URL sent (${new URL(card).host}) is not publicly reachable, and inboxes may accept only public https cards: retry with --card-url set to a public card, or expose your agent through a public façade first (setup skill: "Already have A2A on a Tailnet or LAN")` : ""}`);
 		}
 		st = { base, alias, device: ep.device, token: ep.token, deviceCode: r.data.device_code, userCode: r.data.user_code,
 			verificationUri: r.data.verification_uri || "", verificationUriComplete: r.data.verification_uri_complete || r.data.verification_uri || "",

package/lib/status.mjs

@@ -3,8 +3,8 @@
 // itself, so agents need no curl (some agent sandboxes flag *.dev URLs in shell commands).
 import fs from "node:fs";
 import * as C from "./config.mjs";
-import { cardUrlProblem, cfErrorCode, describeHttp, fingerprint, httpJson } from "./a2a.mjs";
-import { baseUrl, owner } from "./commands.mjs";
+import { cardUrlProblem, cfErrorCode, describeHttp, die, fingerprint, httpJson } from "./a2a.mjs";
+import { baseUrl, owner, ownerTry } from "./commands.mjs";
 import * as D from "./deploy.mjs";
 import * as T from "./tunnel.mjs";
 
@@ -35,9 +35,58 @@ export function wakeLine(s) {
 	return `webhook (preset ${w.preset}${s.tunnel ? ", through the tunnel" : ""}); auth: ${auth.join(" + ") || "none"}; URL fingerprint ${w.urlFingerprint || "-"}`;
 }
 
+// ---------------------------------------------------------------- proxy mode: upstream diagnosis
+/** What to do for each reason code of the Worker's upstream check (`POST /owner/facade/verify`, Worker log
+ *  `upstream_error`). `d` is the check's detail line (HTTP status, Cloudflare error; never a secret). */
+export const UPSTREAM_FIX = {
+	access_credentials_missing: (d) => `Cloudflare Access refused the Worker (${d}). Export UPSTREAM_ACCESS_CLIENT_ID / UPSTREAM_ACCESS_CLIENT_SECRET (the service token the upstream's Access app admits) and run \`${CLI} deploy\``,
+	access_rejected: (d) => `Cloudflare Access refused the Worker's service token (${d}): the Access app on the upstream hostname needs a Service Auth policy for that token, and UPSTREAM_ACCESS_CLIENT_ID / _SECRET must be its current pair (export them and run \`${CLI} deploy\`)`,
+	upstream_auth_missing: (d) => `Access let the Worker through, but the agent refused the call (${d}). Export UPSTREAM_TOKEN (the bearer the agent expects; its card advertises it) and run \`${CLI} deploy\` (or pipe it: \`<print token> | ${CLI} deploy --upstream-token-stdin\`)`,
+	upstream_auth_rejected: (d) => `Access let the Worker through, but the agent refused its UPSTREAM_TOKEN (${d}): wrong or rotated. Export the current one and run \`${CLI} deploy\``,
+	tunnel_down: (d) => `Cloudflare can't reach the upstream tunnel (${d}): start the connector on the agent's machine (\`cloudflared tunnel run ...\`)`,
+	upstream_unavailable: (d) => `the tunnel answers but the agent's A2A server behind it does not (${d}): start the agent, and check the tunnel ingress \`service:\` URL`,
+	network: (d) => `the Worker could not connect to the upstream (${d}): check the tunnel hostname (DNS record, certificate)`,
+	unexpected_response: (d) => `the upstream answered without JSON-RPC (${d}): --upstream must be the agent's JSON-RPC endpoint (not its web UI or card URL); fix it with \`${CLI} deploy --upstream <URL>\``,
+	misconfigured: (d) => `the upstream URL is unusable (${d}): fix it with \`${CLI} deploy --upstream <tunnel URL>\``,
+};
+
+/** The upstream check as layer-by-layer rows: façade peer auth (public), Cloudflare Access, the agent's bearer check, the
+ *  A2A app. `v`: the Worker's verify answer; `fa`: the public peer-auth probe ({ status }) or null. Pure; unit-tested. */
+export function verifyLayers(v, fa = null) {
+	const rows = [];
+	if (fa) rows.push(["façade peer auth", fa.status === 401 ? "enforced (an unauthenticated call gets 401 from the façade)"
+		: fa.error ? `not checked (${fa.error})` : `UNEXPECTED: an unauthenticated call got HTTP ${fa.status} (expected 401)`]);
+	if (!v) return rows;
+	const r = v.reason, sent = v.sent || {};
+	const notReached = "not reached";
+	const access = r === "access_credentials_missing" ? "FAILED: refused by Cloudflare Access; the Worker has no Access service token"
+		: r === "access_rejected" ? "FAILED: Cloudflare Access refused the Worker's service token (policy or wrong token)"
+		: ["upstream_auth_missing", "upstream_auth_rejected", "reachable", "upstream_unavailable"].includes(r) ? (sent.accessServiceToken ? "passed" : "no service token sent (the upstream hostname is not behind Access?)")
+		: r === "tunnel_down" || r === "network" ? notReached : "?";
+	const bearer = r === "upstream_auth_missing" ? "FAILED: the agent wants a credential; the Worker has no UPSTREAM_TOKEN"
+		: r === "upstream_auth_rejected" ? "FAILED: the agent refused the Worker's UPSTREAM_TOKEN"
+		: r === "reachable" ? (sent.bearer ? "accepted" : "none sent (the agent accepted the call without one)")
+		: notReached;
+	const app = r === "reachable" ? `reachable (${v.detail}${v.rpcErrorCode === -32601 ? ": method not found, as expected" : ""}; no task created)`
+		: ["tunnel_down", "upstream_unavailable", "network", "unexpected_response", "misconfigured"].includes(r) ? `FAILED: ${v.detail}` : notReached;
+	rows.push(["Access", access], ["upstream bearer", bearer], ["A2A app", app]);
+	return rows;
+}
+
+/** Peer token variables set in the environment that shadow a different token saved in config.env (names only). */
+export function shadowedPeerTokens() {
+	return [...new Set(Object.values(C.loadPeers()).map((p) => p && p.token_env).filter(Boolean))].filter((k) => C.envOverridesFile(k));
+}
+
 /** 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) {
+	const n = nextStepCore(s);
+	const sh = (s.peerTokenShadowed || []).map((k) => `${k} is set in the environment and overrides the different peer token saved in ${s.configFile} (e.g. a stale value from before \`connect\` stored a new one): send/poll use the environment value. Unset ${k} where it is set to use the saved token`);
+	return sh.length ? { ...n, also: [...n.also, ...sh] } : n;
+}
+
+function nextStepCore(s) {
 	const fail = (text) => ({ ok: false, text, also: [] });
 	const done = (text, also = []) => ({ ok: true, text, also });
 	if (!s.deployed) return fail(`nothing is deployed from ${s.configFile}: run \`${CLI} init ...\` (setup skill, section 2). Another bot's deployment? Set A2A_CONFIG_DIR.`);
@@ -62,12 +111,28 @@ export function nextStep(s) {
 			return fail(`${s.configFile} has A2A_UPSTREAM_URL, but the Worker is not in proxy mode (an older template or an interrupted deploy): run \`${CLI} deploy\``);
 		if (fc.upstreamProblem) return fail(`the upstream URL is unusable: ${fc.upstreamProblem}. Fix it with \`${CLI} deploy --upstream <tunnel URL>\``);
 		if (fc.upstreamCardProblem) return fail(`the upstream card URL is refused: ${fc.upstreamCardProblem}. Fix it with \`${CLI} deploy --upstream-card-url <URL on the upstream's origin>\` (or \`--upstream-card-url none\` for the default)`);
+		// the live check (owner-authenticated, run by the Worker with its stored secrets) is the precise diagnosis
+		const v = s.upstreamVerify;
+		if (v && v.reason && v.reason !== "reachable" && UPSTREAM_FIX[v.reason]) return fail(UPSTREAM_FIX[v.reason](v.detail || v.reason));
+		// an Access-only configuration must not look complete when the agent's card asks for a bearer
+		const wantsBearer = fc.upstreamAuth && fc.upstreamAuth.bearer === true;
+		if (wantsBearer && !fc.hasUpstreamToken && !(v && v.ok) && !s.upstreamNoToken)
+			return fail(`the upstream's card asks for a bearer token (${(fc.upstreamAuth.schemes || []).join(", ")}) and the Worker has no UPSTREAM_TOKEN: Cloudflare Access only lets the Worker through the tunnel, so peers' calls would fail with HTTP 502. Export UPSTREAM_TOKEN and run \`${CLI} deploy\``);
 		if (fc.upstreamCard !== "ok")
 			return fail(`the Worker can't fetch the upstream's agent card (${fc.upstreamCard}): is the tunnel connector running on the agent's machine, and does the Access app admit the service token you exported as UPSTREAM_ACCESS_CLIENT_ID / UPSTREAM_ACCESS_CLIENT_SECRET (re-run \`${CLI} deploy\` with them exported)?`);
 		if (fc.publicCardLeaks && fc.publicCardLeaks.length)
 			return fail(`the public card still names a private URL (${fc.publicCardLeaks[0]}): report this as a bug; meanwhile override the field with --agent-description / --agent-skills and run \`${CLI} deploy\``);
 		const also = [];
 		if (!fc.hasUpstreamAccessServiceToken) also.push("no Access service token for the upstream: unless the upstream hostname is protected another way, put it behind Cloudflare Access and export UPSTREAM_ACCESS_CLIENT_ID / UPSTREAM_ACCESS_CLIENT_SECRET, then deploy");
+		if (wantsBearer && !fc.hasUpstreamToken)
+			also.push(`the upstream's card asks for a bearer token but the Worker has none${s.upstreamNoToken ? " (--no-upstream-token)" : ""}${v && v.ok ? "; the agent accepts calls without it today" : ""}: if peers get HTTP 502, export UPSTREAM_TOKEN and run \`${CLI} deploy\``);
+		if (fc.upstreamAuth && fc.upstreamAuth.unsupported && fc.upstreamAuth.unsupported.length)
+			also.push(`the upstream's card requires ${fc.upstreamAuth.unsupported.join(", ")}; the façade only presents a bearer token (UPSTREAM_TOKEN) and the Access service token`);
+		if (s.localUpstreamToken && fc.fingerprints && fc.fingerprints.upstreamToken !== s.localUpstreamToken)
+			also.push(`the UPSTREAM_TOKEN exported here (fingerprint ${s.localUpstreamToken}) differs from the Worker's (${fc.fingerprints.upstreamToken || "none"}): run \`${CLI} deploy\` to upload it`);
+		if (!v && s.upstreamVerifyError) also.push(`the live upstream check was not run (${s.upstreamVerifyError || "unavailable"})${/HTTP 404/.test(s.upstreamVerifyError || "") ? `: run \`${CLI} deploy\` for a Worker with \`upstream verify\`` : ""}`);
+		if (fc.lastFailure && fc.lastFailure.reason && v && v.ok)
+			also.push(`last failed peer call: ${fc.lastFailure.reason}${fc.lastFailure.status ? ` (HTTP ${fc.lastFailure.status})` : ""} at ${fc.lastFailure.at}; the live check passes now`);
 		if (s.pairing && s.pairing.mode === "human" && !s.pairing.passwordSet)
 			also.push(`peers can't connect yet: run \`${CLI} pair set-password --web\` and send your human the one-time link (or they run \`${CLI} pair set-password\` in a terminal); never set it yourself`);
 		if (s.pairing && s.pairing.pending) also.push(`${s.pairing.pending} pending pairing request(s): \`${CLI} pair list\`, then tell your human (never approve on your own)`);
@@ -117,7 +182,9 @@ export async function collect() {
 		baseUrl: baseUrl(), urlKind: C.get("A2A_HOSTNAME") ? "custom domain" : "workers.dev", cron: C.get("A2A_ENABLE_CRON") === "1",
 		hasOwnerToken: !!C.get("A2A_OWNER_TOKEN"), baseUrlSaved: (C.fileConfig().A2A_BASE_URL || "").replace(/\/$/, ""), baseUrlEnv: "",
 		card: { ok: false, error: "not checked" }, ownerApi: { ok: false, error: "not checked" }, wake: null, tunnel: null, zones: null, pairing: null,
-		upstream: C.get("A2A_UPSTREAM_URL") || null, facade: null,
+		upstream: C.get("A2A_UPSTREAM_URL") || null, facade: null, upstreamVerify: null, upstreamVerifyError: "", facadePeerAuth: null,
+		upstreamNoToken: C.get("A2A_UPSTREAM_NO_TOKEN") === "1", localUpstreamToken: fingerprint(process.env.UPSTREAM_TOKEN),
+		peerTokenShadowed: shadowedPeerTokens(),
 	};
 	const envBase = (process.env.A2A_BASE_URL || "").replace(/\/$/, "");
 	if (envBase && envBase !== s.baseUrlSaved) s.baseUrlEnv = envBase;
@@ -140,6 +207,7 @@ export async function collect() {
 			if (s.upstream) {
 				try { s.facade = await owner("GET", "/owner/facade"); }
 				catch (e) { s.facade = { mode: "unknown", error: e.message }; }
+				if (s.facade && s.facade.mode === "proxy") Object.assign(s, await upstreamCheck(s.baseUrl));
 			}
 		}
 	}
@@ -163,6 +231,42 @@ export async function collect() {
 	return s;
 }
 
+const VERIFY_METHOD = "a2a-exposed/verify-unknown-method";
+
+/** The two upstream probes, neither creating anything: (1) public: an unauthenticated JSON-RPC call to the façade, which
+ *  must answer 401 before looking at the method; (2) owner-authenticated: the Worker sends a JSON-RPC call with an
+ *  unknown method to the upstream with its stored secrets and classifies the answer (POST /owner/facade/verify). */
+export async function upstreamCheck(base) {
+	const out = { facadePeerAuth: null, upstreamVerify: null, upstreamVerifyError: "" };
+	try {
+		const r = await httpJson(base + "/", { method: "POST", body: { jsonrpc: "2.0", id: "a2a-exposed-verify", method: VERIFY_METHOD, params: {} }, headers: { "a2a-version": "1.0" }, timeout: 15000 });
+		out.facadePeerAuth = { status: r.status };
+	} catch (e) { out.facadePeerAuth = { status: null, error: e.message }; }
+	try {
+		const r = await ownerTry("POST", "/owner/facade/verify", {});
+		if (r.status === 200 && r.data && typeof r.data === "object" && r.data.reason) out.upstreamVerify = r.data;
+		else out.upstreamVerifyError = describeHttp(r.status, r.data);
+	} catch (e) { out.upstreamVerifyError = e.message; }
+	return out;
+}
+
+/** `upstream verify`: the façade's whole path, layer by layer; exit 1 unless the upstream app answered. */
+export async function upstreamVerify(o) {
+	if (!C.get("A2A_UPSTREAM_URL")) die(`not a façade: ${C.CONFIG_FILE} has no A2A_UPSTREAM_URL (proxy mode: \`${CLI} deploy --upstream <tunnel URL>\`). For an inbox, check wakes with \`${CLI} wake test\``);
+	const base = baseUrl();
+	if (!base || !C.get("A2A_OWNER_TOKEN")) die(`A2A_BASE_URL / A2A_OWNER_TOKEN missing (run \`${CLI} init\` or edit ${C.CONFIG_FILE})`);
+	const r = await upstreamCheck(base);
+	const v = r.upstreamVerify;
+	if (o.json) console.log(JSON.stringify({ ...r, ok: !!(v && v.ok) }, null, 2));
+	else {
+		const rows = [["upstream", C.get("A2A_UPSTREAM_URL")], ...verifyLayers(v, r.facadePeerAuth)];
+		if (!v) rows.push(["check", `FAILED: ${r.upstreamVerifyError}${/HTTP 404/.test(r.upstreamVerifyError) ? ` (this Worker predates \`upstream verify\`: run \`${CLI} deploy\`)` : ""}`]);
+		else rows.push(["result", v.ok ? "OK: the façade reaches the agent with its stored credentials" : `${v.reason}: ${UPSTREAM_FIX[v.reason] ? UPSTREAM_FIX[v.reason](v.detail || v.reason) : v.detail}`]);
+		for (const [k, val] of rows) console.log(`${(k + ":").padEnd(18)} ${val}`);
+	}
+	if (!(v && v.ok) || (r.facadePeerAuth && r.facadePeerAuth.status !== null && r.facadePeerAuth.status !== 401)) process.exitCode = 1;
+}
+
 export async function status(o) {
 	const s = await collect();
 	const next = nextStep(s);
@@ -179,7 +283,18 @@ export async function status(o) {
 			rows.push(["owner API", s.ownerApi.ok ? "OK" : `FAILED: ${s.ownerApi.error}`]);
 			if (s.upstream) {
 				const f = s.facade || {};
-				rows.push(["upstream", `${s.upstream} (proxy mode)${f.mode === "proxy" ? `; card ${f.upstreamCard}${f.upstreamVersions && f.upstreamVersions.length ? ` (A2A ${f.upstreamVersions.join(", ")})` : ""}; credential ${f.hasUpstreamToken ? "set" : "none"}; Access service token ${f.hasUpstreamAccessServiceToken ? "set" : "NONE"}; public card ${f.publicCardLeaks && f.publicCardLeaks.length ? "LEAKS a private URL" : "clean"}` : f.error ? `; ${f.error}` : "; the Worker is not in proxy mode"}`]);
+				rows.push(["upstream", `${s.upstream} (proxy mode)${f.mode === "proxy" ? `; card ${f.upstreamCard}${f.upstreamVersions && f.upstreamVersions.length ? ` (A2A ${f.upstreamVersions.join(", ")})` : ""}; public card ${f.publicCardLeaks && f.publicCardLeaks.length ? "LEAKS a private URL" : "clean"}` : f.error ? `; ${f.error}` : "; the Worker is not in proxy mode"}`]);
+				if (f.mode === "proxy") {
+					const ua = f.upstreamAuth || {};
+					rows.push(["upstream Access", f.hasUpstreamAccessServiceToken ? `credential configured (UPSTREAM_ACCESS_CLIENT_ID fingerprint ${f.fingerprints?.upstreamAccessClientId || "?"})` : "NONE (UPSTREAM_ACCESS_CLIENT_ID / _SECRET not on the Worker)"]);
+					rows.push(["upstream bearer", f.hasUpstreamToken ? `bearer configured (UPSTREAM_TOKEN fingerprint ${f.fingerprints?.upstreamToken || "?"})`
+						: ua.bearer === true ? `NONE, but the upstream card asks for one (${(ua.schemes || []).join(", ")})${s.upstreamNoToken ? "; --no-upstream-token" : ""}`
+						: ua.bearer === false ? "none (the upstream card declares no bearer auth)" : `none${s.upstreamNoToken ? " (--no-upstream-token)" : ""}`]);
+					const v = s.upstreamVerify;
+					rows.push(["upstream check", !v ? `not run (${s.upstreamVerifyError || "?"})` : v.ok ? `OK: ${verifyLayers(v).map(([k, x]) => `${k} ${x.replace(/ \(.*$/, "")}`).join("; ")}` : `FAILED (${v.reason}): ${v.detail}`]);
+					if (s.facadePeerAuth) rows.push(["peer auth", verifyLayers(null, s.facadePeerAuth)[0][1]]);
+					if (f.lastFailure && f.lastFailure.reason) rows.push(["last failure", `${f.lastFailure.reason}${f.lastFailure.status ? ` (HTTP ${f.lastFailure.status})` : ""} on ${f.lastFailure.method || "?"} from peer ${f.lastFailure.peer || "?"} at ${f.lastFailure.at}`]);
+				}
 			}
 			rows.push(["wake", wakeLine(s)]);
 			const t = s.tunnel;
@@ -192,7 +307,8 @@ export async function status(o) {
 		}
 		rows.push(["next step", next.text]);
 		for (const a of next.also || []) rows.push(["also", a]);
-		for (const [k, v] of rows) console.log(`${(k + ":").padEnd(12)} ${v}`);
+		const w = Math.max(12, ...rows.map(([k]) => k.length + 2));
+		for (const [k, v] of rows) console.log(`${(k + ":").padEnd(w)} ${v}`);
 	}
 	if (!next.ok) process.exitCode = 1;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "a2a-exposed",
-	"version": "0.4.0",
+	"version": "0.4.1",
 	"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/facade.ts

@@ -252,3 +252,121 @@ export function wantsPush(op: string, p: Json): boolean {
 	if (op !== "send" || !p || typeof p !== "object" || !p.configuration || typeof p.configuration !== "object") return false;
 	return Object.entries(p.configuration).some(([k, v]) => /push/i.test(k) && v !== undefined && v !== null);
 }
+
+// ------------------------------------------------------------------ upstream auth + failure diagnosis (proxy mode)
+
+/** How an upstream security scheme authenticates: "bearer" (HTTP bearer; OAuth 2.0 and OpenID Connect also send
+ *  `Authorization: Bearer`), "basic" / "http" (other HTTP schemes), "apiKey", "mtls", or "unknown". Accepts the A2A 1.0
+ *  shape ({ httpAuthSecurityScheme: { scheme } }, { oauth2SecurityScheme }, ...) and the 0.3 / OpenAPI shape
+ *  ({ type: "http", scheme: "bearer" }, { type: "oauth2" }, ...). */
+export function schemeKind(s: Json): string {
+	if (!s || typeof s !== "object") return "unknown";
+	const http = (scheme: unknown) => { const v = String(scheme || "").toLowerCase(); return v === "bearer" ? "bearer" : v === "basic" ? "basic" : "http"; };
+	if (s.httpAuthSecurityScheme) return http(s.httpAuthSecurityScheme.scheme);
+	if (s.oauth2SecurityScheme || s.openIdConnectSecurityScheme) return "bearer";
+	if (s.apiKeySecurityScheme) return "apiKey";
+	if (s.mtlsSecurityScheme || s.mutualTlsSecurityScheme) return "mtls";
+	switch (String(s.type || "").toLowerCase()) {
+		case "http": return http(s.scheme);
+		case "oauth2": case "openidconnect": return "bearer";
+		case "apikey": return "apiKey";
+		case "mutualtls": return "mtls";
+	}
+	return "unknown";
+}
+
+export type UpstreamAuth = {
+	/** true: the card asks for a bearer token (UPSTREAM_TOKEN); false: it declares no bearer / HTTP auth (no schemes, or
+	 *  anonymous access allowed, or only schemes the façade can't present); null: no card to tell. */
+	bearer: boolean | null;
+	/** Declared schemes as "name: kind" (names and kinds only, never values). */
+	schemes: string[];
+	/** Required schemes the façade can't present (it only sends `Authorization: Bearer <UPSTREAM_TOKEN>`). */
+	unsupported: string[];
+};
+
+/** What the upstream card says about authenticating to it. Security requirements are read from A2A 1.0
+ *  `securityRequirements` ([{ schemes: { name: { list: [] } } }]) or 0.3 `security` ([{ name: [] }]); without
+ *  requirements every declared scheme counts. An empty requirement ({}) means anonymous access is allowed. */
+export function upstreamAuth(card: Json): UpstreamAuth {
+	if (!card || typeof card !== "object" || Array.isArray(card)) return { bearer: null, schemes: [], unsupported: [] };
+	const defs: Record<string, Json> = card.securitySchemes && typeof card.securitySchemes === "object" && !Array.isArray(card.securitySchemes) ? card.securitySchemes : {};
+	const kinds: Record<string, string> = {};
+	for (const [n, s] of Object.entries(defs)) kinds[n] = schemeKind(s);
+	const schemes = Object.entries(kinds).map(([n, k]) => `${n}: ${k}`);
+	const raw = Array.isArray(card.securityRequirements) ? card.securityRequirements : Array.isArray(card.security) ? card.security : [];
+	const alts: string[][] = raw.filter((r: Json) => r && typeof r === "object" && !Array.isArray(r))
+		.map((r: Json) => Object.keys(r.schemes && typeof r.schemes === "object" && !Array.isArray(r.schemes) ? r.schemes : r));
+	const kindOf = (n: string) => kinds[n] || "unknown";
+	if (!alts.length) {
+		const all = Object.keys(kinds);
+		return { bearer: all.some((n) => kinds[n] === "bearer"), schemes, unsupported: all.some((n) => kinds[n] === "bearer") ? [] : all.filter((n) => kinds[n] !== "unknown").map((n) => `${n}: ${kinds[n]}`) };
+	}
+	if (alts.some((a) => a.length === 0)) return { bearer: false, schemes, unsupported: [] }; // anonymous allowed
+	const bearer = alts.some((a) => a.some((n) => kindOf(n) === "bearer"));
+	const unsupported = bearer ? [] : [...new Set(alts.flat())].map((n) => `${n}: ${kindOf(n)}`);
+	return { bearer, schemes, unsupported };
+}
+
+/** Why a call to the upstream did not produce a JSON-RPC answer, as a stable reason code (Worker logs, the owner
+ *  diagnostics, `status`). Never shown to peers: their 502 stays generic. */
+export type UpstreamReason =
+	| "reachable" // a JSON-RPC response came back (any result or error): Access, the tunnel and the bearer all passed
+	| "access_credentials_missing" // Cloudflare Access refused the request and the façade has no Access service token
+	| "access_rejected" // Cloudflare Access refused the façade's service token (wrong token, or not admitted by the app's policy)
+	| "upstream_auth_missing" // the agent answered 401/403 and the façade has no UPSTREAM_TOKEN
+	| "upstream_auth_rejected" // the agent answered 401/403 to the façade's UPSTREAM_TOKEN
+	| "tunnel_down" // Cloudflare could not reach the tunnel / origin (error 1033, 1016, 530, ...)
+	| "upstream_unavailable" // a 5xx without JSON-RPC (cloudflared up, the agent's server not answering)
+	| "network" // the fetch itself failed (DNS, TLS, timeout)
+	| "unexpected_response" // anything else that is not JSON-RPC (a 404 page, HTML, a redirect elsewhere)
+	| "misconfigured"; // UPSTREAM_URL unusable
+
+export type UpstreamVerdict = { reason: UpstreamReason; status: number | null; cloudflareError?: string; rpcErrorCode?: number; detail: string };
+
+/** Classify one upstream HTTP answer (or a fetch failure: status null + error). Pure; `bearerSent` says whether the
+ *  façade sent UPSTREAM_TOKEN, `accessSent` whether it sent an Access service token (false turns an Access refusal into
+ *  access_credentials_missing). Access is recognised by its login redirect (<team>.cloudflareaccess.com,
+ *  /cdn-cgi/access/), its CF-Access-* response headers, or its error page. */
+export function classifyUpstream(i: { status: number | null; headers?: Headers | Record<string, string>; body?: string; error?: string; bearerSent: boolean; accessSent?: boolean }): UpstreamVerdict {
+	if (i.status === null) return { reason: "network", status: null, detail: `request failed: ${String(i.error || "unknown error").slice(0, 200)}` };
+	const status = i.status;
+	const body = String(i.body || "");
+	const get = (k: string): string => {
+		const h: any = i.headers;
+		if (!h) return "";
+		if (typeof h.get === "function") return h.get(k) || "";
+		for (const [n, v] of Object.entries(h)) if (n.toLowerCase() === k) return String(v);
+		return "";
+	};
+	const names: string[] = [];
+	const h: any = i.headers;
+	if (h && typeof h.forEach === "function" && typeof h.get === "function") h.forEach((_v: string, k: string) => names.push(k.toLowerCase()));
+	else if (h) names.push(...Object.keys(h).map((k) => k.toLowerCase()));
+	let rpc: Json = null;
+	try { rpc = JSON.parse(body); } catch { /* not JSON */ }
+	if (rpc && typeof rpc === "object" && !Array.isArray(rpc) && rpc.jsonrpc === "2.0" && status !== 401 && status !== 403) {
+		const code = rpc.error && typeof rpc.error === "object" && typeof rpc.error.code === "number" ? rpc.error.code : undefined;
+		return { reason: "reachable", status, ...(code !== undefined ? { rpcErrorCode: code } : {}),
+			detail: code !== undefined ? `JSON-RPC error ${code} (HTTP ${status})` : `JSON-RPC result (HTTP ${status})` };
+	}
+	const location = get("location");
+	const accessPage = /cloudflareaccess\.com|\/cdn-cgi\/access\//i.test(location) || /cloudflareaccess\.com|\/cdn-cgi\/access\/|Cloudflare Access/i.test(body.slice(0, 8192));
+	const accessHeader = names.some((n) => n.startsWith("cf-access-"));
+	if ((status >= 300 && status < 400 && /cloudflareaccess\.com|\/cdn-cgi\/access\//i.test(location)) || ((status === 401 || status === 403) && (accessPage || accessHeader)))
+		return { reason: i.accessSent === false ? "access_credentials_missing" : "access_rejected", status,
+			detail: `${status >= 300 && status < 400 ? `HTTP ${status} redirect to the Cloudflare Access login` : `HTTP ${status} from Cloudflare Access`}: ${i.accessSent === false
+				? "the façade has no Access service token (UPSTREAM_ACCESS_CLIENT_ID / _SECRET)" : "Access refused the façade's service token (wrong token, or the app's policy doesn't admit it)"}` };
+	if (status === 401 || status === 403)
+		return i.bearerSent
+			? { reason: "upstream_auth_rejected", status, detail: `HTTP ${status} from the agent: it refused the façade's UPSTREAM_TOKEN` }
+			: { reason: "upstream_auth_missing", status, detail: `HTTP ${status} from the agent: it wants a credential and the façade has no UPSTREAM_TOKEN` };
+	const m = /error code:?\s*(\d{4})|\bError\s+(\d{4})\b|errorCode:?\s*(\d{4})|cf-error-code[^>]*>\s*(\d{4})/i.exec(body.slice(0, 8192));
+	const cf = m ? m[1] || m[2] || m[3] || m[4] : "";
+	if (cf === "1033" || cf === "1016" || status === 530)
+		return { reason: "tunnel_down", status, ...(cf ? { cloudflareError: cf } : {}), detail: `HTTP ${status}${cf ? `, Cloudflare error ${cf}` : ""}: Cloudflare can't reach the tunnel (is cloudflared running?)` };
+	if (status >= 500)
+		return { reason: "upstream_unavailable", status, ...(cf ? { cloudflareError: cf } : {}), detail: `HTTP ${status}${cf ? `, Cloudflare error ${cf}` : ""} without a JSON-RPC answer: the agent's server behind the tunnel is not answering` };
+	return { reason: "unexpected_response", status, ...(cf ? { cloudflareError: cf } : {}),
+		detail: `HTTP ${status} without a JSON-RPC answer${status >= 300 && status < 400 && location ? " (a redirect)" : ""}: is UPSTREAM_URL the agent's JSON-RPC endpoint?` };
+}

package/worker/src/index.ts

@@ -602,6 +602,63 @@ async function handleRpc(req: Request, env: Env, ectx: ExecutionContext): Promis
 }
 
 // ------------------------------------------------------------------ proxy mode: forward JSON-RPC to the private upstream
+/** What a peer sees when the upstream hop fails: generic on purpose (no secret names, no upstream host, no hint which
+ *  lock refused). The operator's diagnosis is the reason code in the Worker log, `status` and `upstream verify`. */
+const PUBLIC_UPSTREAM_ERROR: Record<string, string> = {
+	access_credentials_missing: "This agent is unavailable: its façade is misconfigured; tell its operator",
+	access_rejected: "This agent is unavailable: its façade is misconfigured; tell its operator",
+	upstream_auth_missing: "This agent is unavailable: its façade is misconfigured; tell its operator",
+	upstream_auth_rejected: "This agent is unavailable: its façade is misconfigured; tell its operator",
+	tunnel_down: "This agent is not reachable right now; try again later",
+	upstream_unavailable: "This agent is not reachable right now; try again later",
+	network: "This agent is not reachable right now; try again later",
+	unexpected_response: "This agent gave an invalid answer; try again later or tell its operator",
+};
+
+/** Last failed upstream hop of a peer call (settings row `upstream_last_failure`): reason code, HTTP status, when, which
+ *  method and peer. Shown to the owner by `GET /owner/facade` (and so `status`); never to peers. Best effort. */
+const hasAccess = (env: Env) => !!(env.UPSTREAM_ACCESS_CLIENT_ID && env.UPSTREAM_ACCESS_CLIENT_SECRET);
+
+async function recordUpstreamFailure(env: Env, v: F.UpstreamVerdict, c: { method: string; label: string }) {
+	const rec = { at: A.nowIso(), reason: v.reason, status: v.status, ...(v.cloudflareError ? { cloudflareError: v.cloudflareError } : {}), method: c.method, peer: c.label };
+	try {
+		await env.DB.prepare("INSERT INTO settings (key, value) VALUES ('upstream_last_failure', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+			.bind(JSON.stringify(rec)).run();
+	} catch (e) { log("upstream_failure_not_recorded", { error: String(e).slice(0, 200) }); }
+}
+
+async function lastUpstreamFailure(env: Env): Promise<Json | null> {
+	try {
+		const r: Json = await env.DB.prepare("SELECT value FROM settings WHERE key = 'upstream_last_failure'").first();
+		return r ? JSON.parse(r.value) : null;
+	} catch { return null; }
+}
+
+/** Owner-only upstream check (`POST /owner/facade/verify`): one JSON-RPC call with a method no A2A server implements,
+ *  sent from the Worker with the stored upstream credentials over the same path as peer traffic (Access, tunnel, the
+ *  agent's bearer check), then classified. An unknown method can't create or touch a task, and the secrets never leave
+ *  the Worker: the answer carries reason codes and HTTP status only. */
+const VERIFY_METHOD = "a2a-exposed/verify-unknown-method";
+async function verifyUpstream(env: Env): Promise<Json> {
+	const sent = { bearer: !!env.UPSTREAM_TOKEN, accessServiceToken: hasAccess(env) };
+	const [ep, why] = F.upstreamEndpoint(env.UPSTREAM_URL);
+	if (!ep) return { ok: false, reason: "misconfigured", status: null, detail: why, sent, method: VERIFY_METHOD };
+	const up = await fetchUpstreamCard(env);
+	const versions = F.upstreamJsonRpcVersions(up.card);
+	const v1 = !versions.length || versions.includes("1.0");
+	const headers = upstreamHeaders(env, ep, { "content-type": "application/json", accept: "application/json", "a2a-version": v1 ? "1.0" : "0.3" });
+	const rid = `a2a-exposed-verify-${A.newId()}`;
+	let verdict: F.UpstreamVerdict;
+	try {
+		const r = await fetch(ep, { method: "POST", headers, body: JSON.stringify({ jsonrpc: "2.0", id: rid, method: VERIFY_METHOD, params: {} }), redirect: "manual", signal: AbortSignal.timeout(20000) });
+		verdict = F.classifyUpstream({ status: r.status, headers: r.headers, body: (await r.text()).slice(0, 8192), bearerSent: sent.bearer, accessSent: sent.accessServiceToken });
+	} catch (e) {
+		verdict = F.classifyUpstream({ status: null, error: String(e), bearerSent: sent.bearer, accessSent: sent.accessServiceToken });
+	}
+	log("upstream_verify", { reason: verdict.reason, status: verdict.status, ...(verdict.rpcErrorCode !== undefined ? { code: verdict.rpcErrorCode } : {}) });
+	return { ok: verdict.reason === "reachable", ...verdict, sent, method: VERIFY_METHOD, upstreamWantsBearer: F.upstreamAuth(up.card).bearer };
+}
+
 // Methods only the façade forwards (the inbox has one push config per task and no delete).
 const PROXY_V1: Record<string, string> = { ListTaskPushNotificationConfig: "pushlist", DeleteTaskPushNotificationConfig: "pushdel" };
 const PROXY_V03: Record<string, string> = { "tasks/pushNotificationConfig/list": "pushlist", "tasks/pushNotificationConfig/delete": "pushdel" };
@@ -659,8 +716,10 @@ async function proxyRpc(req: Request, env: Env, c: { raw: string; rid: Json; met
 	try {
 		r = await fetch(ep, { method: "POST", headers, body: c.raw, redirect: "manual", signal: AbortSignal.timeout(90000) });
 	} catch (e) {
-		log("upstream_failed", { peer: c.label, method: c.method, error: String(e).slice(0, 200) });
-		return err(-32603, "This agent is not reachable right now (upstream unavailable); try again later", 502);
+		const v = F.classifyUpstream({ status: null, error: String(e), bearerSent: !!env.UPSTREAM_TOKEN, accessSent: hasAccess(env) });
+		log("upstream_error", { reason: v.reason, peer: c.label, method: c.method, detail: v.detail });
+		await recordUpstreamFailure(env, v, c);
+		return err(-32603, PUBLIC_UPSTREAM_ERROR[v.reason] || PUBLIC_UPSTREAM_ERROR.network, 502);
 	}
 	const text = await r.text();
 	if (text.length > 8 * 1048576) { log("upstream_too_large", { peer: c.label, method: c.method, bytes: text.length }); return err(-32603, "Upstream response too large", 502); }
@@ -668,11 +727,12 @@ async function proxyRpc(req: Request, env: Env, c: { raw: string; rid: Json; met
 	try { body = JSON.parse(text); } catch { /* not JSON */ }
 	const isRpc = body && typeof body === "object" && !Array.isArray(body) && body.jsonrpc === "2.0";
 	if (r.status === 401 || r.status === 403 || !isRpc) {
-		const hint = cloudflareErrorHint(r.status, text.slice(0, 4096));
-		log("upstream_error", { peer: c.label, method: c.method, status: r.status, ...(hint ? { hint } : {}) });
-		return err(-32603, r.status === 401 || r.status === 403
-			? "This agent's façade was refused by its upstream (credential or Access policy); tell its operator"
-			: `This agent's upstream answered HTTP ${r.status} without a JSON-RPC response; try again later`, 502);
+		// the operator gets the precise reason (Worker log line + `status` / `upstream verify`); the peer a generic 502
+		// that names no secret, header or upstream detail
+		const v = F.classifyUpstream({ status: r.status, headers: r.headers, body: text.slice(0, 8192), bearerSent: !!env.UPSTREAM_TOKEN, accessSent: hasAccess(env) });
+		log("upstream_error", { reason: v.reason, peer: c.label, method: c.method, status: r.status, ...(v.cloudflareError ? { cloudflareError: v.cloudflareError } : {}) });
+		await recordUpstreamFailure(env, v, c);
+		return err(-32603, PUBLIC_UPSTREAM_ERROR[v.reason] || PUBLIC_UPSTREAM_ERROR.unexpected_response, 502);
 	}
 	if (c.op === "send" && body.result) {
 		const { taskId, contextId } = F.idsFromResult(body.result);
@@ -893,10 +953,17 @@ async function handleOwner(req: Request, env: Env, ectx: ExecutionContext, path:
 		const [, cardWhy] = ep ? F.upstreamCardUrl(ep, env.UPSTREAM_CARD_URL) : ["", ""];
 		return json({ mode: "proxy", upstreamValid: !!ep, ...(why ? { upstreamProblem: why } : {}), ...(cardWhy ? { upstreamCardProblem: cardWhy } : {}), upstreamCardUrl: up.url || null,
 			upstreamCard: up.status === 200 ? "ok" : up.error || "unavailable", upstreamVersions: F.upstreamJsonRpcVersions(up.card),
+			// what the upstream card asks for (scheme names and kinds only), from the copy the Worker fetched through Access
+			upstreamAuth: F.upstreamAuth(up.status === 200 ? up.card : null),
 			hasUpstreamToken: !!env.UPSTREAM_TOKEN, hasUpstreamAccessServiceToken: !!(env.UPSTREAM_ACCESS_CLIENT_ID && env.UPSTREAM_ACCESS_CLIENT_SECRET),
 			fingerprints: { upstreamToken: await A.fingerprint(env.UPSTREAM_TOKEN), upstreamAccessClientId: await A.fingerprint(env.UPSTREAM_ACCESS_CLIENT_ID) },
+			lastFailure: await lastUpstreamFailure(env),
 			publicCardLeaks: F.cardLeaks(card, env.PUBLIC_URL, upstreamOrigins(env, up.card)) });
 	}
+	if (seg[0] === "facade" && seg[1] === "verify" && !seg[2] && m === "POST") {
+		if (!proxyMode(env)) return json({ mode: "inbox", ok: false, reason: "not_proxy_mode", detail: "this Worker is an inbox (no UPSTREAM_URL): nothing to verify" }, 409);
+		return json({ mode: "proxy", ...(await verifyUpstream(env)) });
+	}
 	if (seg[0] === "wake" && seg[1] === "preview" && m === "GET") {
 		// rendered wake request for a sample event, partially masked, plus short sha256 fingerprints of the
 		// uploaded secrets so the owner can compare them with local values without revealing them

package/worker/test/facade.test.ts

@@ -360,7 +360,8 @@ test("proxy mode: upstream failures are the façade's errors, never a 401 to the
 	const send = () => s.rpc(a, "SendMessage", { message: { role: "ROLE_USER", parts: [{ text: "x" }] } });
 	let r = await send();
 	assert.equal(r.status, 502);
-	assert.match(r.data.error.message, /refused by its upstream/);
+	assert.match(r.data.error.message, /façade is misconfigured; tell its operator/);
+	assert.doesNotMatch(r.text, /UPSTREAM|Access|token|bearer|agent-upstream|401/i, "the public 502 names no secret, lock or upstream detail");
 	mode = "html";
 	r = await send();
 	assert.equal(r.status, 502);
@@ -419,3 +420,163 @@ test("proxy mode: the landing page shows the rewritten card (upstream name and s
 	assert.equal(j.data.name, "Jean");
 	assert.ok(!JSON.stringify(j.data).includes("ts.net"));
 });
+
+// ------------------------------------------------------------------ upstream auth, failure reasons, owner verify
+
+test("upstreamAuth: bearer wanted or not, from A2A 1.0 and 0.3 card shapes", () => {
+	assert.deepEqual(F.upstreamAuth(null), { bearer: null, schemes: [], unsupported: [] });
+	assert.equal(F.upstreamAuth({ name: "x" }).bearer, false, "no schemes: no auth declared");
+	// 1.0 (ProtoJSON oneof wrappers + securityRequirements)
+	const v1 = { securitySchemes: { bearer: { httpAuthSecurityScheme: { scheme: "Bearer" } } }, securityRequirements: [{ schemes: { bearer: { list: [] } } }] };
+	assert.deepEqual(F.upstreamAuth(v1), { bearer: true, schemes: ["bearer: bearer"], unsupported: [] });
+	assert.equal(F.upstreamAuth({ securitySchemes: { o: { oauth2SecurityScheme: { flows: {} } } }, securityRequirements: [{ schemes: { o: { list: ["a2a"] } } }] }).bearer, true, "OAuth 2.0 sends a bearer");
+	assert.equal(F.upstreamAuth({ securitySchemes: { o: { openIdConnectSecurityScheme: { openIdConnectUrl: "https://id.example.com" } } } }).bearer, true);
+	// 0.3 (OpenAPI style + security)
+	const v03 = { securitySchemes: { bearerAuth: { type: "http", scheme: "bearer" } }, security: [{ bearerAuth: [] }] };
+	assert.deepEqual(F.upstreamAuth(v03), { bearer: true, schemes: ["bearerAuth: bearer"], unsupported: [] });
+	assert.equal(F.upstreamAuth({ securitySchemes: { bearerAuth: { type: "http", scheme: "bearer" } } }).bearer, true, "declared without requirements still counts");
+	// anonymous allowed as an alternative
+	assert.equal(F.upstreamAuth({ ...v03, security: [{ bearerAuth: [] }, {}] }).bearer, false);
+	// only schemes the façade can't present
+	const key = F.upstreamAuth({ securitySchemes: { k: { apiKeySecurityScheme: { location: "header", name: "x-api-key" } } }, securityRequirements: [{ schemes: { k: { list: [] } } }] });
+	assert.deepEqual(key, { bearer: false, schemes: ["k: apiKey"], unsupported: ["k: apiKey"] });
+	assert.deepEqual(F.upstreamAuth({ securitySchemes: { b: { type: "http", scheme: "basic" } }, security: [{ b: [] }] }).unsupported, ["b: basic"]);
+	assert.equal(F.upstreamAuth(tailnetCard()).bearer, false, "the test card wants an API key header");
+});
+
+test("classifyUpstream: Access, the agent's bearer check, tunnel, network and a reachable app are told apart", () => {
+	const c = (status: number | null, body = "", headers: Record<string, string> = {}, bearerSent = false, error = "") => F.classifyUpstream({ status, body, headers, bearerSent, error });
+	const rpc = JSON.stringify({ jsonrpc: "2.0", id: 1, error: { code: -32601, message: "Method not found" } });
+	assert.deepEqual(c(200, rpc), { reason: "reachable", status: 200, rpcErrorCode: -32601, detail: "JSON-RPC error -32601 (HTTP 200)" });
+	assert.equal(c(404, rpc).reason, "reachable", "any JSON-RPC answer means the app was reached");
+	assert.equal(c(200, JSON.stringify({ jsonrpc: "2.0", id: 1, result: {} })).reason, "reachable");
+	assert.equal(c(302, "", { Location: "https://team.cloudflareaccess.com/cdn-cgi/access/login/up.example.com?kid=x" }).reason, "access_rejected");
+	assert.equal(c(403, "<html>Forbidden. You don't have permission ... Cloudflare Access</html>").reason, "access_rejected");
+	assert.equal(c(401, "", { "cf-access-domain": "up.example.com" }, true).reason, "access_rejected");
+	assert.equal(F.classifyUpstream({ status: 302, headers: { location: "https://team.cloudflareaccess.com/cdn-cgi/access/login/x" }, bearerSent: true, accessSent: false }).reason, "access_credentials_missing");
+	assert.equal(F.classifyUpstream({ status: 403, body: "Forbidden (Cloudflare Access)", bearerSent: true, accessSent: true }).reason, "access_rejected", "a configured token Access refuses: policy / wrong token");
+	assert.equal(c(401, "unauthorized", {}, false).reason, "upstream_auth_missing");
+	// Hermes, verbatim from Jean's probe: Access headers only -> 401 + JSON-RPC -32050; Access + Hermes bearer -> 200 + -32601
+	const hermes401 = JSON.stringify({ jsonrpc: "2.0", id: "probe", error: { code: -32050, message: "unauthorized" } });
+	assert.equal(c(401, hermes401, { "content-type": "application/json" }, false).reason, "upstream_auth_missing");
+	assert.equal(c(401, hermes401, { "content-type": "application/json" }, true).reason, "upstream_auth_rejected");
+	const hermes200 = JSON.stringify({ jsonrpc: "2.0", id: "probe", error: { code: -32601, message: "Method not found" } });
+	assert.deepEqual(c(200, hermes200, { "content-type": "application/json" }, true), { reason: "reachable", status: 200, rpcErrorCode: -32601, detail: "JSON-RPC error -32601 (HTTP 200)" });
+	assert.equal(c(403, JSON.stringify({ error: "bad token" }), {}, true).reason, "upstream_auth_rejected");
+	assert.equal(c(401, JSON.stringify({ jsonrpc: "2.0", id: 1, error: { code: -32000, message: "unauthorized" } }), {}, true).reason, "upstream_auth_rejected", "a JSON-RPC body on 401 is still an auth failure");
+	assert.deepEqual(c(530, "error code: 1033"), { reason: "tunnel_down", status: 530, cloudflareError: "1033", detail: "HTTP 530, Cloudflare error 1033: Cloudflare can't reach the tunnel (is cloudflared running?)" });
+	assert.equal(c(502, "<html>Bad gateway</html>").reason, "upstream_unavailable");
+	assert.equal(c(null, "", {}, false, "TypeError: fetch failed").reason, "network");
+	assert.equal(c(404, "<html>Not found</html>").reason, "unexpected_response");
+	assert.equal(c(301, "", { location: "https://elsewhere.example.com/" }).reason, "unexpected_response");
+	const h = new Headers({ location: "https://team.cloudflareaccess.com/cdn-cgi/access/login/x" });
+	assert.equal(F.classifyUpstream({ status: 302, headers: h, body: "", bearerSent: false }).reason, "access_rejected", "Headers objects work too");
+});
+
+/** Jean's façade: Access admits the Worker's service token, but the agent (Hermes) also checks its own bearer. */
+function bearerCheckingUpstream(want = "hermes-bearer") {
+	const seen: any[] = [];
+	const card = { ...tailnetCard(), securitySchemes: { bearer: { type: "http", scheme: "bearer" } }, securityRequirements: undefined, security: [{ bearer: [] }] }; // 0.3-style auth, as Hermes advertises
+	const fn = async (url: string, init: any): Promise<Response> => {
+		const h = init.headers || {};
+		if (h["cf-access-client-id"] !== "cid.access" || h["cf-access-client-secret"] !== "csecret")
+			return new Response(null, { status: 302, headers: { location: "https://team.cloudflareaccess.com/cdn-cgi/access/login/agent-upstream.example.net" } });
+		if (url.endsWith(".json")) return Response.json(card); // the card itself is public behind Access
+		const rq = JSON.parse(init.body);
+		seen.push(rq);
+		if (h.authorization !== `Bearer ${want}`) return Response.json({ jsonrpc: "2.0", id: rq.id, error: { code: -32050, message: "unauthorized" } }, { status: 401 }); // Hermes, as Jean probed it
+		if (rq.method !== "SendMessage" && rq.method !== "GetTask") return Response.json({ jsonrpc: "2.0", id: rq.id, error: { code: -32601, message: "Method not found" } });
+		return Response.json({ jsonrpc: "2.0", id: rq.id, result: { task: { id: "t-1", contextId: "c-1", status: { state: "TASK_STATE_SUBMITTED" } } } });
+	};
+	return { fn, seen };
+}
+
+test("proxy mode: missing UPSTREAM_TOKEN (Jean's case): peers get a generic 502, the owner gets the precise reason", async (t) => {
+	const up = bearerCheckingUpstream();
+	const s = setup({ UPSTREAM_URL: UPSTREAM, UPSTREAM_CARD_URL: "https://agent-upstream.example.net/card-jean.json", UPSTREAM_ACCESS_CLIENT_ID: "cid.access", UPSTREAM_ACCESS_CLIENT_SECRET: "csecret" }, up.fn);
+	t.after(s.restore);
+	const a = await s.issue("alice");
+	const r = await s.rpc(a, "SendMessage", { message: { role: "ROLE_USER", parts: [{ text: "hi" }] } });
+	assert.equal(r.status, 502);
+	assert.equal(r.data.error.code, -32603);
+	assert.doesNotMatch(r.text, /UPSTREAM|Access|bearer|token|agent-upstream|401/i);
+	const diag = (await s.call("GET", "/owner/facade", { token: "owner-secret" })).data;
+	assert.equal(diag.upstreamCard, "ok", "the card passes (Access only), the calls don't");
+	assert.deepEqual(diag.upstreamAuth, { bearer: true, schemes: ["bearer: bearer"], unsupported: [] });
+	assert.equal(diag.hasUpstreamToken, false);
+	assert.equal(diag.hasUpstreamAccessServiceToken, true);
+	assert.equal(diag.lastFailure.reason, "upstream_auth_missing");
+	assert.equal(diag.lastFailure.status, 401);
+	assert.equal(diag.lastFailure.method, "SendMessage");
+	assert.equal(diag.lastFailure.peer, "alice");
+	assert.match(diag.lastFailure.at, /^\d{4}-/);
+
+	const v = await s.call("POST", "/owner/facade/verify", { token: "owner-secret" });
+	assert.equal(v.status, 200);
+	assert.equal(v.data.ok, false);
+	assert.equal(v.data.reason, "upstream_auth_missing");
+	assert.equal(v.data.status, 401);
+	assert.deepEqual(v.data.sent, { bearer: false, accessServiceToken: true });
+	assert.equal(v.data.upstreamWantsBearer, true);
+	assert.equal(up.seen.at(-1).method, "a2a-exposed/verify-unknown-method");
+});
+
+test("owner verify: classifies Access, bearer, tunnel and network failures; a reachable app answers -32601; never creates a task", async (t) => {
+	const up = bearerCheckingUpstream();
+	const env = { UPSTREAM_URL: UPSTREAM, UPSTREAM_CARD_URL: "https://agent-upstream.example.net/card-v.json", UPSTREAM_ACCESS_CLIENT_ID: "cid.access", UPSTREAM_ACCESS_CLIENT_SECRET: "csecret", UPSTREAM_TOKEN: "hermes-bearer" };
+	const s = setup(env, up.fn);
+	t.after(s.restore);
+	const verify = async (st = s) => (await st.call("POST", "/owner/facade/verify", { token: "owner-secret" })).data;
+	let v = await verify();
+	assert.equal(v.ok, true, JSON.stringify(v));
+	assert.equal(v.reason, "reachable");
+	assert.equal(v.rpcErrorCode, -32601);
+	assert.deepEqual(v.sent, { bearer: true, accessServiceToken: true });
+	assert.ok(!JSON.stringify(v).includes("hermes-bearer") && !JSON.stringify(v).includes("csecret"), "no secret values in the answer");
+	const probe = s.calls.filter((c) => c.url === UPSTREAM).at(-1);
+	assert.equal(probe.headers.authorization, "Bearer hermes-bearer");
+	assert.equal(probe.headers["cf-access-client-id"], "cid.access");
+	assert.equal(JSON.parse(probe.body).method, "a2a-exposed/verify-unknown-method");
+	assert.equal((s.DB.db.prepare("SELECT COUNT(*) AS n FROM facade_owners").get() as any).n, 0, "nothing recorded");
+	assert.equal((s.DB.db.prepare("SELECT COUNT(*) AS n FROM tasks").get() as any).n, 0, "no task");
+
+	const wrong = setup({ ...env, UPSTREAM_TOKEN: "stale" }, up.fn);
+	t.after(wrong.restore);
+	assert.equal((await verify(wrong)).reason, "upstream_auth_rejected");
+	const wrongAccess = setup({ ...env, UPSTREAM_ACCESS_CLIENT_SECRET: "wrong" }, up.fn);
+	t.after(wrongAccess.restore);
+	v = await verify(wrongAccess);
+	assert.equal(v.reason, "access_rejected");
+	assert.equal(v.status, 302);
+	const { UPSTREAM_ACCESS_CLIENT_ID: _i, UPSTREAM_ACCESS_CLIENT_SECRET: _s, ...noAccessEnv } = env;
+	const noAccess = setup(noAccessEnv, up.fn);
+	t.after(noAccess.restore);
+	assert.equal((await verify(noAccess)).reason, "access_credentials_missing");
+	const down = setup(env, async () => new Response("error code: 1033", { status: 530 }));
+	t.after(down.restore);
+	assert.equal((await verify(down)).reason, "tunnel_down");
+	const net = setup(env, async () => { throw new TypeError("fetch failed"); });
+	t.after(net.restore);
+	assert.equal((await verify(net)).reason, "network");
+	const bad = setup({ UPSTREAM_URL: "https://jean.tail1234.ts.net/a2a" });
+	t.after(bad.restore);
+	v = await verify(bad);
+	assert.equal(v.reason, "misconfigured");
+	assert.equal(bad.calls.length, 0);
+});
+
+test("owner verify is owner-only and proxy-only (no public or peer-reachable probe)", async (t) => {
+	const up = bearerCheckingUpstream();
+	const s = setup({ UPSTREAM_URL: UPSTREAM, UPSTREAM_CARD_URL: "https://agent-upstream.example.net/card-o.json", UPSTREAM_ACCESS_CLIENT_ID: "cid.access", UPSTREAM_ACCESS_CLIENT_SECRET: "csecret", UPSTREAM_TOKEN: "hermes-bearer" }, up.fn);
+	t.after(s.restore);
+	const peer = await s.issue("mallory");
+	const n0 = s.calls.filter((c) => c.url === UPSTREAM).length;
+	assert.equal((await s.call("POST", "/owner/facade/verify")).status, 401);
+	assert.equal((await s.call("POST", "/owner/facade/verify", { token: peer })).status, 401, "a peer token is not the owner token");
+	assert.equal(s.calls.filter((c) => c.url === UPSTREAM).length, n0, "unauthenticated calls never reach the upstream");
+	const inbox = setup();
+	t.after(inbox.restore);
+	const r = await inbox.call("POST", "/owner/facade/verify", { token: "owner-secret" });
+	assert.equal(r.status, 409);
+	assert.equal(r.data.reason, "not_proxy_mode");
+});