fix(gateway): spurious manual scope-upgrade approval for local clients

allenz-srp · allenz-srp · commit be03ab5cd778 · 2026-06-24T18:32:16.000+08:00
A local, same-host operator client (e.g. an in-pod agent CLI) was interrupted
with a manual scope-upgrade approval prompt mid-session, even though its initial
pairing had been silently auto-approved on the same trusted local connection.

It reproduces whenever such a client's first gateway call uses a read-scoped
method and a later call needs an admin scope: e.g. an agent that calls cron.list
(-&gt; operator.read) before cron.add (-&gt; operator.admin) is baselined at
operator.read, so the cron.add trips a operator.read -&gt; operator.admin upgrade
that was forced onto the manual-approval path, stalling the agent on /approve.

shouldAllowSilentLocalPairing() already treats a local scope-upgrade as
silent-eligible (like initial pairing and role-upgrades), but the pairing
call-site hard-forced silent:false for every scope-upgrade regardless of
locality. Extract the decision into resolveDevicePairingSilent() and honor
allowSilentLocalPairing for scope-upgrades too.

Boundaries: only LOCAL scope upgrades become silent (allowSilentLocalPairing is
false for remote clients, so remote escalations stay on the explicit-approval
path); the trusted-CIDR and bootstrap node paths never silence a scope-upgrade.
Net effect: a local scope-upgrade now behaves like a local role-upgrade already
does.
diff --git a/src/gateway/server/ws-connection/handshake-auth-helpers.test.ts b/src/gateway/server/ws-connection/handshake-auth-helpers.test.ts
@@ -9,6 +9,7 @@ import type { AuthRateLimiter } from "../../auth-rate-limit.js";
 import {
   BROWSER_ORIGIN_RATE_LIMIT_KEY_PREFIX,
   BROWSER_ORIGIN_LOOPBACK_RATE_LIMIT_IP,
+  resolveDevicePairingSilent,
   resolveHandshakeBrowserSecurityContext,
   resolvePairingLocality,
   resolveUnauthorizedHandshakeContext,
@@ -621,3 +622,72 @@ describe("handshake auth helpers", () => {
     ).toBe("cli_container_local");
   });
 });
+
+describe("resolveDevicePairingSilent", () => {
+  const base = {
+    allowSilentLocalPairing: false,
+    allowSilentTrustedCidrsNodePairing: false,
+    allowSilentBootstrapPairing: false,
+  };
+
+  it("auto-approves a local scope-upgrade silently (read -> admin for an in-pod CLI)", () => {
+    expect(
+      resolveDevicePairingSilent({
+        ...base,
+        reason: "scope-upgrade",
+        allowSilentLocalPairing: true,
+      }),
+    ).toBe(true);
+  });
+
+  it("keeps a remote scope-upgrade on the explicit-approval path", () => {
+    // allowSilentLocalPairing is false for remote clients (shouldAllowSilentLocalPairing).
+    expect(
+      resolveDevicePairingSilent({
+        ...base,
+        reason: "scope-upgrade",
+      }),
+    ).toBe(false);
+  });
+
+  it("does not let the trusted-CIDR or bootstrap node paths silence a scope-upgrade", () => {
+    expect(
+      resolveDevicePairingSilent({
+        reason: "scope-upgrade",
+        allowSilentLocalPairing: false,
+        allowSilentTrustedCidrsNodePairing: true,
+        allowSilentBootstrapPairing: true,
+      }),
+    ).toBe(false);
+  });
+
+  it.each(["not-paired", "role-upgrade", "metadata-upgrade"] as const)(
+    "auto-approves %s silently when any silent condition holds",
+    (reason) => {
+      expect(
+        resolveDevicePairingSilent({ ...base, reason, allowSilentLocalPairing: true }),
+      ).toBe(true);
+      expect(
+        resolveDevicePairingSilent({
+          ...base,
+          reason,
+          allowSilentTrustedCidrsNodePairing: true,
+        }),
+      ).toBe(true);
+      expect(
+        resolveDevicePairingSilent({ ...base, reason, allowSilentBootstrapPairing: true }),
+      ).toBe(true);
+    },
+  );
+
+  it("requires approval when no silent condition holds", () => {
+    for (const reason of [
+      "not-paired",
+      "role-upgrade",
+      "scope-upgrade",
+      "metadata-upgrade",
+    ] as const) {
+      expect(resolveDevicePairingSilent({ ...base, reason })).toBe(false);
+    }
+  });
+});
diff --git a/src/gateway/server/ws-connection/handshake-auth-helpers.ts b/src/gateway/server/ws-connection/handshake-auth-helpers.ts
@@ -117,6 +117,40 @@ export function shouldAllowSilentLocalPairing(params: {
   return false;
 }
 
+/**
+ * Decide whether a device-pairing request may be auto-approved silently.
+ *
+ * A scope-upgrade (e.g. operator.read -> operator.admin, which happens when a
+ * CLI device's first gateway call was a read method and a later call needs an
+ * admin scope) is auto-approvable under the SAME local-trust condition that
+ * already governs initial pairing and role-upgrades — i.e. only when the client
+ * is local (`allowSilentLocalPairing`, which is false for remote clients). It is
+ * never silently granted via the trusted-CIDR node path or the bootstrap path,
+ * both of which target initial node onboarding rather than scope escalation.
+ *
+ * This keeps remote scope escalations on the explicit-approval path while
+ * removing the spurious manual-approval prompt for same-host/in-pod CLI clients
+ * whose initial pairing was already silently auto-approved.
+ * `shouldAllowSilentLocalPairing` already returns true for a local scope-upgrade;
+ * this is the call-site that honors it (it previously hard-forced `false` for
+ * every scope-upgrade regardless of locality).
+ */
+export function resolveDevicePairingSilent(params: {
+  reason: "not-paired" | "role-upgrade" | "scope-upgrade" | "metadata-upgrade";
+  allowSilentLocalPairing: boolean;
+  allowSilentTrustedCidrsNodePairing: boolean;
+  allowSilentBootstrapPairing: boolean;
+}): boolean {
+  if (params.reason === "scope-upgrade") {
+    return params.allowSilentLocalPairing;
+  }
+  return (
+    params.allowSilentLocalPairing ||
+    params.allowSilentTrustedCidrsNodePairing ||
+    params.allowSilentBootstrapPairing
+  );
+}
+
 function isCliContainerLocalEquivalent(params: {
   connectParams: ConnectParams;
   requestHost?: string;
diff --git a/src/gateway/server/ws-connection/message-handler.ts b/src/gateway/server/ws-connection/message-handler.ts
@@ -163,6 +163,7 @@ import {
   shouldSkipControlUiPairing,
 } from "./connect-policy.js";
 import {
+  resolveDevicePairingSilent,
   resolveDeviceSignaturePayloadVersion,
   resolveHandshakeBrowserSecurityContext,
   resolvePairingLocality,
@@ -1419,12 +1420,12 @@ export function attachGatewayWsMessageHandler(params: GatewayWsMessageHandlerPar
                     scopes: bootstrapPairingScopes ?? [],
                   }
                 : {}),
-              silent:
-                reason === "scope-upgrade"
-                  ? false
-                  : allowSilentLocalPairing ||
-                    allowSilentTrustedCidrsNodePairing ||
-                    allowSetupCodeMobileBootstrapPairing,
+              silent: resolveDevicePairingSilent({
+                reason,
+                allowSilentLocalPairing,
+                allowSilentTrustedCidrsNodePairing,
+                allowSilentBootstrapPairing: allowSetupCodeMobileBootstrapPairing,
+              }),
             });
             const context = buildRequestContext();
             let approved: Awaited<ReturnType<typeof approveDevicePairing>> | undefined;
