a2a-exposed 0.4.0 → 0.5.0

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.5.0",
 	"description": "Give any AI agent a public A2A (Agent2Agent) endpoint: Cloudflare Worker inbox + wake webhook or scheduled inbox checks",
 	"type": "module",
 	"bin": {

package/worker/cloudflare.config.ts

@@ -39,6 +39,7 @@ const plain: Record<string, string> = {
 	RATE_PER_MIN: v("A2A_RATE_PER_MIN"),
 	RETIRED_HOSTNAMES: v("A2A_RETIRED_HOSTNAMES"), // custom domains this agent moved away from (see movedResponse)
 	PAIRING_APPROVAL: v("PAIRING_APPROVAL") || "human", // device-flow pairing: human (approval password on /device) | agent | off
+	MCP: v("A2A_MCP"), // remote MCP server at /mcp (connector for Claude etc.): on unless "off"; never in proxy mode
 	PBKDF2_ITERATIONS: v("A2A_PBKDF2_ITERATIONS"), // approval password hashing; default 100000 (the Workers maximum), at least 50000
 	// proxy / expose mode: forward A2A to an agent that already speaks it, published through a Tunnel hostname behind
 	// Access (never a Tailnet / LAN URL: the Worker can't reach those, and they never appear in the public card)

package/worker/migrations/0006_mcp.sql

@@ -0,0 +1,43 @@
+-- Remote MCP server (/mcp): OAuth 2.1 clients (dynamic registration), one-time authorization codes, and the grants
+-- (owner-approved, inbox-scoped tokens) that `token list` shows and `token revoke` ends. Peer tokens stay in `peers`
+-- and are never accepted on /mcp; MCP tokens are never accepted on the A2A endpoint or /owner/*.
+CREATE TABLE IF NOT EXISTS oauth_clients (
+	client_id TEXT PRIMARY KEY,
+	client_name TEXT,
+	redirect_uris_json TEXT NOT NULL,
+	created_ms INTEGER NOT NULL,
+	ip TEXT
+);
+CREATE TABLE IF NOT EXISTS oauth_codes (
+	code_hash TEXT PRIMARY KEY,
+	client_id TEXT NOT NULL,
+	redirect_uri TEXT NOT NULL,
+	code_challenge TEXT NOT NULL,
+	scope TEXT NOT NULL,
+	resource TEXT NOT NULL,
+	created_ms INTEGER NOT NULL,
+	expires_ms INTEGER NOT NULL
+);
+CREATE TABLE IF NOT EXISTS mcp_grants (
+	label TEXT PRIMARY KEY,
+	client_id TEXT NOT NULL,
+	client_name TEXT,
+	redirect_host TEXT,
+	scope TEXT NOT NULL,
+	access_hash TEXT UNIQUE,
+	access_expires_ms INTEGER,
+	refresh_hash TEXT UNIQUE,
+	refresh_expires_ms INTEGER,
+	created_at TEXT NOT NULL,
+	last_used_at TEXT,
+	revoked_at TEXT
+);
+-- Peers this inbox sends to from the Worker (MCP `send` / `poll_outbound`), uploaded by `peers sync`. The token is
+-- AES-GCM ciphertext under a key derived from the Worker's OWNER_TOKEN secret, so a D1 export alone doesn't reveal it.
+CREATE TABLE IF NOT EXISTS outbound_peers (
+	alias TEXT PRIMARY KEY,
+	url TEXT NOT NULL,
+	token_enc TEXT,
+	created_at TEXT NOT NULL,
+	updated_at TEXT NOT NULL
+);

package/worker/migrations/0007_cimd.sql

@@ -0,0 +1,10 @@
+-- MCP authorization (2026-07-28): OAuth Client ID Metadata Documents. A client_id that is an https URL names a JSON
+-- document the Worker fetches (SSRF-guarded, 5 KB, 5 s) and validates; valid documents are cached here for their
+-- Cache-Control max-age (60 s - 24 h, default 1 h). Errors and invalid documents are never cached.
+CREATE TABLE IF NOT EXISTS oauth_client_metadata (
+	client_id TEXT PRIMARY KEY,
+	client_name TEXT,
+	redirect_uris_json TEXT NOT NULL,
+	fetched_ms INTEGER NOT NULL,
+	expires_ms INTEGER NOT NULL
+);

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?` };
+}