test(oauth): check OAuth scopes against a live server

Add `pnpm test:scopes`, which signs in through the extension's OAuth flow
against a throwaway deployment (test/scopes/compose.yaml) and runs a probe
for every Coder API method and CLI request the extension makes with the
granted token. It also checks that each requested scope is needed by a
named probe, and asserts the exact error of known gaps.

`scopeProbes.test.ts` runs on every PR and uses the TypeScript checker to
find every CoderApi method src/ references, failing when one has no probe.

The workflow runs the suite on relevant changes against a pinned
coder-preview image, and nightly against `latest`. `pnpm test` and the CI
unit job leave it out.

Author: EhabY

.github/workflows/oauth-scopes.yaml

@@ -0,0 +1,41 @@
+name: OAuth Scopes
+
+# Pushes and PRs use the image pinned in compose.yaml; nightly runs use latest
+# to catch server changes early.
+on:
+  push:
+    branches: [main]
+    # Code the probes run or import
+    paths: &paths
+      - src/**
+      - test/mocks/**
+      - test/scopes/**
+      - package.json
+      - pnpm-lock.yaml
+      - vitest.config.mts
+      - .github/workflows/oauth-scopes.yaml
+  pull_request:
+    paths: *paths
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  live-server:
+    name: Live Server Test (coder-preview)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/setup
+      - run: docker compose -f test/scopes/compose.yaml up -d --wait
+        env:
+          CODER_IMAGE: ${{ github.event_name == 'schedule' && 'ghcr.io/coder/coder-preview:latest' || '' }}
+      - run: pnpm test:scopes
+        env:
+          CODER_SCOPES_TEST_URL: http://localhost:7080

AGENTS.md

@@ -95,6 +95,7 @@ test/
 ├── unit/           # Extension unit tests (mirrors src/ structure)
 ├── webview/        # Webview unit tests (by package name)
 ├── integration/    # VS Code integration tests (uses Mocha, not Vitest)
+├── scopes/         # OAuth scopes against a live server (`pnpm test:scopes`)
 ├── utils/          # Test utilities that are also tested
 └── mocks/          # Shared test mocks
 ```

CONTRIBUTING.md

@@ -242,6 +242,22 @@ pnpm test:integration
 - Requires closing VS Code or running in a clean environment
 - Test files in `test/integration/` are compiled to `out/` before running
 
+### OAuth Scope Tests
+
+`test/scopes/` signs in through the extension's OAuth flow against a live
+server and runs the probes in `test/scopes/probes.ts` with the token. It needs
+Docker and a fresh deployment, since it creates users and workspaces, and
+`pnpm test` leaves it out:
+
+```bash
+docker compose -f test/scopes/compose.yaml up -d --wait
+CODER_SCOPES_TEST_URL=http://localhost:7080 pnpm test:scopes
+docker compose -f test/scopes/compose.yaml down -v  # before the next run
+```
+
+Pull requests run against the coder-preview image pinned in `compose.yaml`;
+the nightly run uses `latest`. Set `CODER_IMAGE` to test another image.
+
 ## Development
 
 > [!IMPORTANT]

package.json

@@ -34,9 +34,10 @@
 		"storybook:build": "storybook build --config-dir .storybook",
 		"storybook:ci": "storybook build --test --config-dir .storybook",
 		"sync:vscode-themes": "node .storybook/themes/sync.mjs",
-		"test": "cross-env CI=true ELECTRON_RUN_AS_NODE=1 electron node_modules/vitest/vitest.mjs",
+		"test": "cross-env CI=true ELECTRON_RUN_AS_NODE=1 electron node_modules/vitest/vitest.mjs --project !scopes",
 		"test:extension": "cross-env ELECTRON_RUN_AS_NODE=1 electron node_modules/vitest/vitest.mjs --project extension",
 		"test:integration": "pnpm build:test && node esbuild.mjs && vscode-test",
+		"test:scopes": "cross-env ELECTRON_RUN_AS_NODE=1 electron node_modules/vitest/vitest.mjs --project scopes",
 		"test:webview": "cross-env ELECTRON_RUN_AS_NODE=1 electron node_modules/vitest/vitest.mjs --project webview",
 		"typecheck": "concurrently -g -n extension,tests,packages,storybook \"tsc --noEmit\" \"tsc --noEmit -p test\" \"pnpm typecheck:packages\" \"tsc --noEmit -p .storybook\"",
 		"typecheck:packages": "pnpm -r --filter \"./packages/*\" --parallel typecheck",

pnpm-workspace.yaml

@@ -22,7 +22,8 @@ catalog:
   react-dom: ^19.3.0
   storybook: ^10.6.1
   storybook-addon-pseudo-states: ^10.6.1
-  # typescript stays on the 6.0 API for typescript-eslint; TypeScript 7 runs `tsc`.
+  # typescript stays on the 6.0 API for typescript-eslint and the compiler API in
+  # test/unit/oauth/scopeProbes.test.ts; TypeScript 7 runs `tsc`.
   # https://devblogs.microsoft.com/typescript/announcing-typescript-7-0/
   typescript: npm:@typescript/typescript6@^6.0.2
   vite: ^8.3.2

scripts/test-electron.sh

@@ -30,4 +30,4 @@ pnpm --dir "$RUNNER_DIR" add "electron@$ELECTRON_VERSION"
 
 echo "Running tests with Electron $ELECTRON_VERSION..."
 ELECTRON_RUN_AS_NODE=1 \
-  "$RUNNER_DIR/node_modules/.bin/electron" node_modules/vitest/vitest.mjs
+  "$RUNNER_DIR/node_modules/.bin/electron" node_modules/vitest/vitest.mjs --project "!scopes"

src/oauth/constants.ts

@@ -5,6 +5,7 @@ export const REFRESH_GRANT_TYPE = "refresh_token";
 /**
  * Scopes the extension and the CLI need. Stored sessions must have all of
  * them, so adding one signs out users of servers that enforce scopes.
+ * `scopeConsumers` in test/scopes/probes.ts names what needs each scope.
  */
 export const DEFAULT_OAUTH_SCOPES = [
 	"coder:workspaces.operate",

src/oauth/sessionManager.ts

@@ -4,10 +4,14 @@ import {
 	type AuthTokenRefreshTrigger,
 } from "../instrumentation/auth";
 
-import { DEFAULT_OAUTH_SCOPES, REFRESH_GRANT_TYPE } from "./constants";
+import { REFRESH_GRANT_TYPE } from "./constants";
 import { OAuthError, parseOAuthError } from "./errors";
 import { OAuthMetadataClient } from "./metadataClient";
-import { buildOAuthTokenData, toUrlSearchParams } from "./utils";
+import {
+	buildOAuthTokenData,
+	hasRequiredScopes,
+	toUrlSearchParams,
+} from "./utils";
 import { OAuth2TokenResponseSchema, parseOAuthResponse } from "./validation";
 
 import type { AxiosInstance } from "axios";
@@ -132,7 +136,7 @@ export class OAuthSessionManager implements vscode.Disposable {
 		StoredTokens | undefined
 	> {
 		const storedTokens = await this.getStoredTokens();
-		if (storedTokens && !this.hasRequiredScopes(storedTokens.scope)) {
+		if (storedTokens && !hasRequiredScopes(storedTokens.scope)) {
 			this.logger.warn("Stored tokens have insufficient scopes", {
 				scope: storedTokens.scope,
 			});
@@ -262,38 +266,6 @@ export class OAuthSessionManager implements vscode.Disposable {
 			});
 	}
 
-	/**
-	 * Check if granted scopes cover all required scopes.
-	 * Supports wildcard scopes like "workspace:*".
-	 */
-	private hasRequiredScopes(grantedScope: string): boolean {
-		const grantedScopes = new Set(grantedScope.split(" "));
-		if (grantedScopes.has("coder:all")) {
-			return true;
-		}
-		const requiredScopes = DEFAULT_OAUTH_SCOPES.split(" ");
-
-		for (const required of requiredScopes) {
-			if (grantedScopes.has(required)) {
-				continue;
-			}
-
-			// Check wildcard match (e.g., "workspace:*" grants "workspace:read")
-			const colonIndex = required.indexOf(":");
-			if (colonIndex !== -1) {
-				const prefix = required.substring(0, colonIndex);
-				const wildcard = `${prefix}:*`;
-				if (grantedScopes.has(wildcard)) {
-					continue;
-				}
-			}
-
-			return false;
-		}
-
-		return true;
-	}
-
 	/**
 	 * Run `fn` with a per-call CoderApi configured for the current
 	 * deployment. The client is disposed on exit so its config-change

src/oauth/utils.ts

@@ -1,5 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
 
+import { DEFAULT_OAUTH_SCOPES } from "./constants";
+
 import type { OAuth2TokenResponse } from "coder/site/src/api/typesGenerated";
 
 import type { OAuthTokenData } from "../core/secretsManager";
@@ -51,6 +53,38 @@ export function toUrlSearchParams(obj: object): URLSearchParams {
 	return new URLSearchParams(params);
 }
 
+/**
+ * Whether the granted scopes cover DEFAULT_OAUTH_SCOPES.
+ * Supports wildcard scopes like "workspace:*".
+ */
+export function hasRequiredScopes(grantedScope: string): boolean {
+	const grantedScopes = new Set(grantedScope.split(" "));
+	if (grantedScopes.has("coder:all")) {
+		return true;
+	}
+	const requiredScopes = DEFAULT_OAUTH_SCOPES.split(" ");
+
+	for (const required of requiredScopes) {
+		if (grantedScopes.has(required)) {
+			continue;
+		}
+
+		// Check wildcard match (e.g., "workspace:*" grants "workspace:read")
+		const colonIndex = required.indexOf(":");
+		if (colonIndex !== -1) {
+			const prefix = required.substring(0, colonIndex);
+			const wildcard = `${prefix}:*`;
+			if (grantedScopes.has(wildcard)) {
+				continue;
+			}
+		}
+
+		return false;
+	}
+
+	return true;
+}
+
 /**
  * Build OAuthTokenData from a token response.
  * Prefers the `expiry` timestamp over calculating from `expires_in`.

test/scopes/compose.yaml

@@ -0,0 +1,28 @@
+# A throwaway deployment for `pnpm test:scopes`; see CONTRIBUTING.md.
+services:
+  postgres:
+    image: postgres:17
+    environment:
+      POSTGRES_USER: coder
+      POSTGRES_PASSWORD: coder
+      POSTGRES_DB: coder
+    healthcheck:
+      test: pg_isready -U coder
+      interval: 2s
+      retries: 30
+
+  coder:
+    image: ${CODER_IMAGE:-ghcr.io/coder/coder-preview@sha256:22951b2840d24d0b2dcb75990f499cb844840ecd763731cc0361683c1ee457aa}
+    ports: ["127.0.0.1:7080:7080"]
+    environment:
+      CODER_PG_CONNECTION_URL: postgres://coder:coder@postgres:5432/coder?sslmode=disable
+      CODER_HTTP_ADDRESS: 0.0.0.0:7080
+      CODER_ACCESS_URL: http://localhost:7080
+      CODER_OAUTH2_PROVIDER_ENABLE: "true"
+    depends_on:
+      postgres:
+        condition: service_healthy
+    healthcheck:
+      test: curl -fs http://localhost:7080/healthz
+      interval: 2s
+      retries: 60