fix(auth): surface distinct scope-mismatch reason for device token failures

hclsys · hclsys · commit 1a7612f0be29 · 2026-05-08T14:56:26.000+08:00
When verifyDeviceToken returns reason="scope-mismatch" (the device token's approved scopes do not cover the requested connection scopes), the auth pipeline previously collapsed this into the generic device_token_mismatch error, causing clients to rotate/reissue a perfectly valid token. Surface a distinct device_token_scope_mismatch reason and error message ("re-pair this device to request the current scope set") so clients can take the right corrective action. Adds AUTH_DEVICE_TOKEN_SCOPE_MISMATCH error detail code for protocol-level classification. Fixes #79292.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
+- Gateway/auth: surface a distinct `device_token_scope_mismatch` reason and error message when a device token's approved scopes do not cover the requested connection scopes, instead of collapsing all `verifyDeviceToken` failures into the generic `device_token_mismatch` error. Fixes #79292.
 - Google/Gemini: normalize retired `google/gemini-3-pro-preview` and `google-gemini-cli/gemini-3-pro-preview` selections to `google/gemini-3.1-pro-preview` before they are written to model config.
 - Control UI: read the Quick Settings exec policy badge from `tools.exec.security` instead of the non-schema `agents.defaults.exec.security` path, so configured `full`/`deny` values render accurately. Fixes #78311. Thanks @FriedBack.
 - Control UI/usage: add transcript-backed historical lineage rollups for rotated logical sessions, with current-instance vs historical-lineage scope controls and long-range presets so usage history stays visible after restarts and updates. Fixes #50701. Thanks @dev-gideon-llc and @BunsDev.
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 "device_token_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
@@ -108,6 +108,27 @@ describe("resolveConnectAuthDecision", () => {
     expect(verifyDeviceToken).toHaveBeenCalledOnce();
   });
 
+  it("reports scope-mismatch from verifyDeviceToken as device_token_scope_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", "operator.pairing"],
+      verifyBootstrapToken: async () => ({ ok: false, reason: "bootstrap_token_invalid" }),
+      verifyDeviceToken,
+    });
+    expect(decision.authOk).toBe(false);
+    expect(decision.authResult.reason).toBe("device_token_scope_mismatch");
+  });
+
   it("reports explicit device-token mismatches as device_token_mismatch", async () => {
     const verifyDeviceToken = vi.fn<VerifyDeviceTokenFn>(async () => ({ ok: false }));
     const decision = await resolveConnectAuthDecision({
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
+          ? "device_token_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 "device_token_scope_mismatch":
+      return "unauthorized: device token scope mismatch (re-pair this device to request the current scope set)";
     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 "device_token_scope_mismatch":`
	`59`	`+ return "unauthorized: device token scope mismatch (re-pair this device to request the current scope set)";`
`58`	`60`	`default:`
`59`	`61`	`break;`
`60`	`62`	`}`