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

Add `pnpm test:scopes`, which signs in and refreshes the token through the
extension's OAuth flow against a throwaway deployment
(test/scopes/compose.yaml). It checks that login and refresh both grant
exactly the requested scopes, then runs a probe for every Coder API method
the extension calls and for the requests `coder ssh` and `coder start`
make, using the refreshed token.

`scopeProbes.test.ts` runs in `pnpm test` and uses the TypeScript checker
to find every CoderApi method src/ references, failing when one has no
probe or listed reason.

The workflow runs the suite on relevant PRs against a pinned coder-preview
image, and nightly against `latest`. A failed nightly run comments on an
open tracking issue, or opens one. Release images ignore requested scopes,
and GHCR deletes preview images after a few weeks, so
`pnpm sync:coder-preview` pins the newest one.

Author: EhabY

.github/workflows/oauth-scopes.yaml

@@ -0,0 +1,57 @@
+name: OAuth Scopes
+
+# PRs use the image pinned in compose.yaml; nightly runs use latest to catch
+# server changes early.
+on:
+  pull_request:
+    # Code the probes run or import
+    paths:
+      - src/**
+      - test/mocks/**
+      - test/scopes/**
+      - package.json
+      - pnpm-lock.yaml
+      - vitest.config.mts
+      - .github/workflows/oauth-scopes.yaml
+  schedule:
+    # Off the hour, when GitHub delays or drops fewer scheduled runs
+    - cron: "17 6 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  live-server:
+    name: Live Server Test (coder-preview)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      issues: write
+    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
+      # A failed scheduled run notifies only one person, so track it in an issue.
+      - name: Report nightly failure
+        if: failure() && github.event_name == 'schedule'
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          title="Nightly OAuth scope test failed"
+          issue=$(gh issue list --state open --search "\"$title\" in:title" --json number --jq '.[0].number')
+          if [ -n "$issue" ]; then
+            gh issue comment "$issue" --body "Failed again: $RUN_URL"
+          else
+            gh issue create --title "$title" --body "The scope test failed against \`coder-preview:latest\`: $RUN_URL"
+          fi

AGENTS.md

@@ -42,6 +42,8 @@ Before changing anything under `packages/` or `test/webview/`, read
 - Unit tests: `pnpm test`, or `pnpm test:extension` / `pnpm test:webview`
   with an optional file path
 - Integration tests: `pnpm test:integration`
+- OAuth scope tests: `pnpm test:scopes`, against a live server
+  ([docs/TESTING.md](docs/TESTING.md#oauth-scope-tests))
 - Storybook: `pnpm storybook`; theme snapshots: `pnpm sync:vscode-themes`
 
 Integration tests and the theme sync launch VS Code; on headless machines

CONTRIBUTING.md

@@ -8,8 +8,8 @@ guides cover the rest; they serve humans and coding agents alike, and
   naming, and test placement.
 - [Architecture](docs/ARCHITECTURE.md): how opening a workspace works, SSH
   config management, Windows permissions and connection logging.
-- [Testing](docs/TESTING.md): unit, webview and integration tests, and
-  testing the open flow by hand.
+- [Testing](docs/TESTING.md): unit, webview, integration and OAuth scope
+  tests, and testing the open flow by hand.
 - [Tooling](docs/TOOLING.md): linting, formatting, TypeScript, Node.js and
   dependency upgrades.
 - [Webviews](packages/AGENTS.md): React, `@repo/ui`, Storybook and the

docs/TESTING.md

@@ -50,6 +50,7 @@ test/
 ├── unit/           # Extension unit tests (mirrors src/)
 ├── webview/        # Webview unit tests (mirrors packages/<pkg>/src/, jsdom)
 ├── integration/    # Integration tests (real VS Code, Mocha)
+├── scopes/         # OAuth scopes against a live server
 ├── utils/          # Test utilities that are also tested
 └── mocks/          # Shared test mocks
 ```
@@ -72,6 +73,30 @@ command with `xvfb-run -a`.
   run in that copy with its own user data directory, so an open VS Code
   doesn't interfere.
 
+## OAuth scope tests
+
+`test/scopes/` signs in and refreshes the token through the extension's OAuth
+flow against a live server, then probes each server call the extension makes.
+When `pnpm test` reports an unprobed method, add a probe to
+`test/scopes/probes.ts` and run the suite. 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` and reports failures in a "Nightly OAuth scope
+test failed" issue. Set `CODER_IMAGE` to test another image. Release images
+ignore requested scopes, so only preview images can catch a missing one.
+
+GHCR deletes preview images after a few weeks. If the pinned image is gone,
+or to test a newer server, run `pnpm sync:coder-preview` to pin the newest
+one, then run the suite.
+
 ## Testing the open flow by hand
 
 There are a few ways you can test the "Open in VS Code" flow:

package.json

@@ -40,10 +40,12 @@
 		"storybook": "storybook dev -p 6006 --config-dir .storybook",
 		"storybook:build": "storybook build --config-dir .storybook",
 		"storybook:ci": "storybook build --test --config-dir .storybook",
+		"sync:coder-preview": "node scripts/sync-coder-preview.mjs",
 		"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 scripts/esbuild.mjs && vscode-test --config test/integration/.vscode-test.mjs",
+		"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/sync-coder-preview.mjs

@@ -0,0 +1,33 @@
+// Pins test/scopes/compose.yaml to the newest coder-preview image. GHCR deletes
+// preview images after a few weeks, so rerun this when the pinned one is gone.
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
+
+const IMAGE = "ghcr.io/coder/coder-preview";
+const COMPOSE = new URL("../test/scopes/compose.yaml", import.meta.url);
+
+const docker = (...args) =>
+	execFileSync("docker", args, { encoding: "utf8" }).trim();
+
+docker("pull", "--quiet", `${IMAGE}:latest`);
+const [repoDigest, version] = docker(
+	"image",
+	"inspect",
+	`${IMAGE}:latest`,
+	"--format",
+	'{{index .RepoDigests 0}} {{index .Config.Labels "org.opencontainers.image.version"}}',
+).split(" ");
+// The tag only makes the pin readable; the digest is what Docker pulls.
+const tag = version.replace("+", "-");
+const pinned = `${IMAGE}:${tag}@${repoDigest.split("@")[1]}`;
+
+const compose = readFileSync(COMPOSE, "utf8");
+const updated = compose.replace(
+	/(\$\{CODER_IMAGE:-)[^}]+(\})/,
+	`$1${pinned}$2`,
+);
+if (updated === compose && !compose.includes(pinned)) {
+	throw new Error("No CODER_IMAGE default found in test/scopes/compose.yaml");
+}
+writeFileSync(COMPOSE, updated);
+console.log(`Pinned ${pinned}`);

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/websocket/oneWayWebSocket.ts

@@ -161,7 +161,7 @@ export class OneWayWebSocket<
 	}
 }
 
-function rawDataToString(data: RawData): string {
+export function rawDataToString(data: RawData): string {
 	if (Buffer.isBuffer(data)) {
 		return data.toString("utf8");
 	} else if (data instanceof ArrayBuffer) {

test/scopes/compose.yaml

@@ -0,0 +1,29 @@
+# A throwaway deployment for `pnpm test:scopes`; see docs/TESTING.md. Update
+# the coder image with `pnpm sync:coder-preview`.
+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:2.38.0-devel-2d96e88ebe@sha256:e6f38cf2da013f68bced6006a8e9197611d41dd1ef2d036867e458df3c0893af}
+    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