address review: require explicit dev signal for loopback A2A trust

The Builder review correctly pointed out that xForwardedFor:false only
returns the immediate socket peer, so on a self-hosted VPS/Docker/K8s
box running the app bound to 127.0.0.1 behind Nginx/Caddy every public
request appears loopback. The prior gate would then treat those
unrecognized runtimes as trusted local dev and accept anonymous
JSON-RPC and _process-task dispatches.

isTrustedLocalRuntime() now additionally requires a positive dev
signal (NODE_ENV=development or NODE_ENV=test) before honoring the
loopback bit. NODE_ENV alone unset is no longer a trust grant — bare
self-hosted deployments that forgot to set NODE_ENV=production still
fail closed. The A2A_ALLOW_UNSIGNED_INTERNAL=1 explicit opt-in remains
for operators who intentionally run unsigned internal dispatch.

Regression tests cover both the reverse-proxy relay case (NODE_ENV
unset, loopback true) and an unrecognized NODE_ENV value.

Author: sebastiondev

packages/core/src/a2a/auth-policy.spec.ts

@@ -161,11 +161,16 @@ describe("a2a auth-policy", () => {
       expect(isTrustedLocalRuntime({ loopback: true })).toBe(false);
     });
 
-    it("is true with no secret, loopback true, dev", () => {
+    it("is true with no secret, loopback true, NODE_ENV=development", () => {
       process.env.NODE_ENV = "development";
       expect(isTrustedLocalRuntime({ loopback: true })).toBe(true);
     });
 
+    it("is true with no secret, loopback true, NODE_ENV=test", () => {
+      process.env.NODE_ENV = "test";
+      expect(isTrustedLocalRuntime({ loopback: true })).toBe(true);
+    });
+
     it("is false with no secret, loopback false, no flag, dev (the VPS hole is now closed)", () => {
       process.env.NODE_ENV = "development";
       expect(isTrustedLocalRuntime({ loopback: false })).toBe(false);
@@ -180,6 +185,24 @@ describe("a2a auth-policy", () => {
       process.env.NETLIFY = "true";
       expect(isTrustedLocalRuntime({ loopback: true })).toBe(false);
     });
+
+    // Regression: a bare self-hosted VPS/Docker/K8s host where the operator
+    // runs the app bound to 127.0.0.1 behind Nginx/Caddy and forgets to set
+    // NODE_ENV. Every public request appears loopback-peered from the app's
+    // point of view. Without a positive dev signal we MUST fail closed so
+    // that anonymous JSON-RPC / _process-task is not silently reachable
+    // through the local reverse proxy.
+    it("is false when loopback is true but NODE_ENV is unset (reverse-proxy relay case)", () => {
+      // NODE_ENV was cleared in beforeEach — this simulates the bare
+      // Docker/VPS runtime that isn't in isA2AProductionRuntime()'s list.
+      expect(process.env.NODE_ENV).toBeUndefined();
+      expect(isTrustedLocalRuntime({ loopback: true })).toBe(false);
+    });
+
+    it("is false when loopback is true but NODE_ENV is an unrecognized value", () => {
+      process.env.NODE_ENV = "staging";
+      expect(isTrustedLocalRuntime({ loopback: true })).toBe(false);
+    });
   });
 
   describe("isLoopbackAddress", () => {

packages/core/src/a2a/auth-policy.ts

@@ -33,23 +33,43 @@ export function shouldAdvertiseJwtA2AAuth(): boolean {
 }
 
 /**
- * True only when unsigned internal self-dispatch is acceptable: no A2A_SECRET
- * is configured AND we can positively identify a local/dev runtime. Everything
- * else — production, or any UNRECOGNIZED deployed/networked host — must fail
- * closed and require A2A_SECRET. `loopback` should be whether the inbound
- * request arrived over the loopback interface (127.0.0.1/::1); callers that
- * cannot determine the peer address pass `false`.
+ * True when the process is a positively-identified developer/test runtime
+ * (NODE_ENV explicitly `development` or `test`). We deliberately do NOT treat
+ * an *unset* NODE_ENV as dev: a bare self-hosted Docker/VPS/K8s deployment
+ * that forgot to set NODE_ENV must fall through to the fail-closed path so
+ * that a local reverse proxy (Nginx/Caddy) forwarding public traffic to an
+ * app bound on 127.0.0.1 cannot silently satisfy the loopback gate.
+ */
+function isExplicitDevRuntime(): boolean {
+  const env = process.env.NODE_ENV;
+  return env === "development" || env === "test";
+}
+
+/**
+ * True only when unsigned internal self-dispatch is acceptable. This is the
+ * gate for anonymous A2A/JSON-RPC when no `A2A_SECRET` and no `apiKeyEnv` is
+ * configured. To pass:
+ *
+ *   - the runtime must NOT look like production/a recognized cloud host, AND
+ *   - EITHER the operator explicitly opted in with
+ *     `A2A_ALLOW_UNSIGNED_INTERNAL=1` (documented, deliberate),
+ *   - OR the request arrived over the loopback interface AND `NODE_ENV` is
+ *     explicitly `development` / `test` (positive dev signal, not just
+ *     "unrecognized runtime").
  *
- * NODE_ENV alone is deliberately NOT a trust grant: a self-hosted deployment
- * that doesn't set NODE_ENV=production and isn't recognized by
- * `isA2AProductionRuntime()` (a bare Docker/VPS/K8s pod) must still fail
- * closed unless the request actually came from loopback or the explicit
- * opt-in flag is set.
+ * The `NODE_ENV=development|test` requirement is what closes the
+ * reverse-proxy hole: on a self-hosted VPS/Docker box where the operator
+ * runs the app bound to 127.0.0.1 behind Nginx/Caddy WITHOUT setting
+ * NODE_ENV, every public request would otherwise appear as a loopback peer
+ * and satisfy an "is-local" check. Requiring an explicit dev signal makes
+ * the operator opt in either through NODE_ENV or through
+ * A2A_ALLOW_UNSIGNED_INTERNAL — an unset NODE_ENV alone is not a trust
+ * grant.
  */
 export function isTrustedLocalRuntime(opts: { loopback: boolean }): boolean {
   if (isA2AProductionRuntime()) return false;
   if (process.env.A2A_ALLOW_UNSIGNED_INTERNAL === "1") return true;
-  return opts.loopback === true;
+  return opts.loopback === true && isExplicitDevRuntime();
 }
 
 /** True if a socket peer address is a loopback/local address. */

packages/core/src/a2a/server.ts

@@ -43,8 +43,8 @@ function warnA2AUnauthOnce(): void {
   _warnedUnauthA2A = true;
   // eslint-disable-next-line no-console
   console.warn(
-    "[a2a] No A2A_SECRET or apiKeyEnv configured — A2A endpoint accepting an unauthenticated loopback request. " +
-      "Non-loopback callers are rejected; set A2A_SECRET (or A2A_ALLOW_UNSIGNED_INTERNAL=1 for trusted local dev) before deploying.",
+    "[a2a] No A2A_SECRET or apiKeyEnv configured — A2A endpoint accepting an unauthenticated loopback request from a NODE_ENV=development/test runtime. " +
+      "Non-loopback callers, unrecognized runtimes, and self-hosted deployments behind a local reverse proxy are rejected; set A2A_SECRET (or A2A_ALLOW_UNSIGNED_INTERNAL=1 for trusted local dev) before deploying.",
   );
 }