fix(auth): propagate scope-mismatch reason instead of collapsing to device_token_mismatch

Bartok9 · Bartok9 · commit 238f0c0d8e7b · 2026-05-08T04:36:06.000-04:00
When verifyDeviceToken returns { ok: false, reason: 'scope-mismatch' }, resolveConnectAuthDecision was discarding that reason and always emitting 'device_token_mismatch'. This caused the gateway to tell the user their token value was wrong (rotate/reissue) when the real problem was that the connected client requested scopes beyond what the stored device token allows (e.g. operator.admin / operator.pairing which bootstrap tokens do not include). Changes: - auth-context.ts: propagate scope-mismatch reason as scope_mismatch (also widens VerifyDeviceTokenResult to include optional reason) - connect-error-details.ts: add AUTH_DEVICE_TOKEN_SCOPE_MISMATCH code and map scope_mismatch in resolveAuthConnectErrorDetailCode - auth-messages.ts: human-readable message directing users to re-pair or approve a scope upgrade - auth-context.test.ts: regression test for scope-mismatch propagation Fixes #79292
diff --git a/src/gateway/protocol/connect-error-details.ts b/src/gateway/protocol/connect-error-details.ts
@@ -11,6 +11,7 @@ export const ConnectErrorDetailCodes = {
   AUTH_PASSWORD_NOT_CONFIGURED: "AUTH_PASSWORD_NOT_CONFIGURED", // pragma: allowlist secret
   AUTH_BOOTSTRAP_TOKEN_INVALID: "AUTH_BOOTSTRAP_TOKEN_INVALID",
   AUTH_DEVICE_TOKEN_MISMATCH: "AUTH_DEVICE_TOKEN_MISMATCH",
+  AUTH_DEVICE_TOKEN_SCOPE_MISMATCH: "AUTH_DEVICE_TOKEN_SCOPE_MISMATCH",
   AUTH_RATE_LIMITED: "AUTH_RATE_LIMITED",
   AUTH_TAILSCALE_IDENTITY_MISSING: "AUTH_TAILSCALE_IDENTITY_MISSING",
   AUTH_TAILSCALE_PROXY_MISSING: "AUTH_TAILSCALE_PROXY_MISSING",
@@ -158,6 +159,8 @@ export function resolveAuthConnectErrorDetailCode(
       return ConnectErrorDetailCodes.AUTH_RATE_LIMITED;
     case "device_token_mismatch":
       return ConnectErrorDetailCodes.AUTH_DEVICE_TOKEN_MISMATCH;
+    case "scope_mismatch":
+      return ConnectErrorDetailCodes.AUTH_DEVICE_TOKEN_SCOPE_MISMATCH;
     case undefined:
       return ConnectErrorDetailCodes.AUTH_REQUIRED;
     default:
diff --git a/src/gateway/server/ws-connection/auth-context.test.ts b/src/gateway/server/ws-connection/auth-context.test.ts
@@ -126,6 +126,27 @@ describe("resolveConnectAuthDecision", () => {
     expect(decision.authResult.reason).toBe("device_token_mismatch");
   });
 
+  it("reports scope-mismatch from verifyDeviceToken as scope_mismatch (not device_token_mismatch)", async () => {
+    const verifyDeviceToken = vi.fn<VerifyDeviceTokenFn>(async () => ({
+      ok: false,
+      reason: "scope-mismatch",
+    }));
+    const decision = await resolveConnectAuthDecision({
+      state: createBaseState({
+        deviceTokenCandidateSource: "explicit-device-token",
+      }),
+      hasDeviceIdentity: true,
+      deviceId: "dev-1",
+      publicKey: "pub-1",
+      role: "operator",
+      scopes: ["operator.read", "operator.admin"],
+      verifyBootstrapToken: async () => ({ ok: false, reason: "bootstrap_token_invalid" }),
+      verifyDeviceToken,
+    });
+    expect(decision.authOk).toBe(false);
+    expect(decision.authResult.reason).toBe("scope_mismatch");
+  });
+
   it("accepts valid device tokens and marks auth method as device-token", async () => {
     const rateLimiter = createRateLimiter();
     const verifyDeviceToken = vi.fn<VerifyDeviceTokenFn>(async () => ({ ok: true }));
diff --git a/src/gateway/server/ws-connection/auth-context.ts b/src/gateway/server/ws-connection/auth-context.ts
@@ -32,7 +32,7 @@ export type ConnectAuthState = {
   deviceTokenCandidateSource?: DeviceTokenCandidateSource;
 };
 
-type VerifyDeviceTokenResult = { ok: boolean };
+type VerifyDeviceTokenResult = { ok: boolean; reason?: string };
 type VerifyBootstrapTokenResult = { ok: boolean; reason?: string };
 
 export type ConnectAuthDecision = {
@@ -214,10 +214,12 @@ export async function resolveConnectAuthDecision(params: {
         params.rateLimiter?.reset(params.clientIp, AUTH_RATE_LIMIT_SCOPE_SHARED_SECRET);
       }
     } else {
+      const isScopeMismatch = tokenCheck.reason === "scope-mismatch";
       authResult = {
         ok: false,
-        reason:
-          params.state.deviceTokenCandidateSource === "explicit-device-token"
+        reason: isScopeMismatch
+          ? "scope_mismatch"
+          : params.state.deviceTokenCandidateSource === "explicit-device-token"
             ? "device_token_mismatch"
             : (authResult.reason ?? "device_token_mismatch"),
       };
diff --git a/src/gateway/server/ws-connection/auth-messages.ts b/src/gateway/server/ws-connection/auth-messages.ts
@@ -55,6 +55,8 @@ export function formatGatewayAuthFailureMessage(params: {
       return "unauthorized: too many failed authentication attempts (retry later)";
     case "device_token_mismatch":
       return "unauthorized: device token mismatch (rotate/reissue device token)";
+    case "scope_mismatch":
+      return "unauthorized: device token scope mismatch (re-pair or approve scope upgrade in Control UI)";
     default:
       break;
   }

Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,8 @@ export function formatGatewayAuthFailureMessage(params: {`
`55`	`55`	`return "unauthorized: too many failed authentication attempts (retry later)";`
`56`	`56`	`case "device_token_mismatch":`
`57`	`57`	`return "unauthorized: device token mismatch (rotate/reissue device token)";`
	`58`	`+ case "scope_mismatch":`
	`59`	`+ return "unauthorized: device token scope mismatch (re-pair or approve scope upgrade in Control UI)";`
`58`	`60`	`default:`
`59`	`61`	`break;`
`60`	`62`	`}`