feat(auth): add --scope/-s and --read-only flags to login and refresh

Add explicit OAuth scope selection following `gh` CLI conventions:

- `auth login --scope/-s`: variadic, comma-separated scope flag
- `auth login --read-only`: sugar for the read-only subset
- `auth refresh --scope/-s` and `--read-only`: re-run device flow with
  new scopes (like `gh auth refresh -s`), bypassing the 'already
  authenticated' gate
- 403 enrichment: when specific missing scopes are detected, suggest
  the exact `sentry auth refresh --scope X` command
- Interactive 403 recovery middleware: in TTYs, prompt to re-authenticate
  with missing scopes (merged with default set) and retry the command

Scopes are validated against the canonical SENTRY_SCOPES set from
getsentry/sentry. The plumbing passes a resolved scope string (not a
boolean) through performDeviceFlow, avoiding positional-boolean creep.

Refs #1031.

Author: BYK

.lore.md

@@ -20,6 +20,8 @@ Authenticate with Sentry
 - `--timeout <value> - Timeout for OAuth flow in seconds (default: 900) - (default: "900")`
 - `--force - Re-authenticate without prompting`
 - `--url <value> - Sentry instance URL to authenticate against (e.g. https://sentry.example.com). Required for self-hosted; defaults to SaaS (https://sentry.io).`
+- `--read-only - Request only read-only OAuth scopes (project:read, org:read, event:read, member:read, team:read). Useful for handing tokens to AI agents or CI jobs that should not be able to mutate Sentry state.`
+- `-s, --scope <value>... - Request specific OAuth scopes (repeatable, comma-separated). E.g. --scope project:read --scope org:read. Overrides the default scope set.`
 
 **Examples:**
 
@@ -49,6 +51,8 @@ Refresh your authentication token
 
 **Flags:**
 - `--force - Force refresh even if token is still valid`
+- `--read-only - Re-authenticate with read-only OAuth scopes (project:read, org:read, event:read, member:read, team:read)`
+- `-s, --scope <value>... - Re-authenticate with specific OAuth scopes (repeatable, comma-separated). E.g. --scope project:read --scope org:read`
 
 **Examples:**
 

plugins/sentry-cli/skills/sentry-cli/references/auth.md

@@ -357,6 +357,93 @@ export async function runCli(cliArgs: string[]): Promise<void> {
     }
   };
 
+  /**
+   * Check whether a caught error is a recoverable 403 missing-scope error.
+   *
+   * Returns the extracted scope names when all conditions are met:
+   * - Interactive TTY (stdin)
+   * - Error is an `ApiError` with status 403
+   * - Token is an OAuth token (not env-var — those can't be re-scoped via CLI)
+   * - The 403 detail mentions specific missing scopes
+   *
+   * Returns `null` when recovery is not possible, signaling the caller to
+   * re-throw.
+   */
+  async function extractRecoverableScopes(
+    err: unknown
+  ): Promise<string[] | null> {
+    if (!isatty(0)) {
+      return null;
+    }
+    const { ApiError } = await import("./lib/errors.js");
+    if (!(err instanceof ApiError) || err.status !== 403) {
+      return null;
+    }
+    const { isEnvTokenActive } = await import("./lib/db/auth.js");
+    if (isEnvTokenActive()) {
+      return null;
+    }
+    const { extractRequiredScopes } = await import("./lib/api-scope.js");
+    const scopes = extractRequiredScopes(err.detail);
+    return scopes.length > 0 ? scopes : null;
+  }
+
+  /**
+   * Scope recovery middleware.
+   *
+   * Catches 403 Forbidden errors for OAuth tokens (not env-var tokens) in
+   * interactive TTYs. When specific missing scopes are detected in the API
+   * response, offers to re-authenticate with those scopes and retries the
+   * command — mirroring `gh auth refresh -s <scope>`.
+   *
+   * Env-var tokens are excluded: the user must regenerate those manually
+   * via the Sentry web UI (the 403 enrichment already directs them there).
+   */
+  const scopeRecoveryMiddleware: ErrorMiddleware = async (next, argv) => {
+    try {
+      await next(argv);
+    } catch (err) {
+      const scopes = await extractRecoverableScopes(err);
+      if (!scopes) {
+        throw err;
+      }
+
+      const scopeList = scopes.map((s) => `'${s}'`).join(", ");
+      const { logger: logModule } = await import("./lib/logger.js");
+      const confirmed = await logModule
+        .withTag("auth")
+        .prompt(
+          `Missing scope(s): ${scopeList}. Re-authenticate with default scopes?`,
+          { type: "confirm", initial: true }
+        );
+
+      // Symbol(clack:cancel) is truthy — strict equality check
+      if (confirmed !== true) {
+        throw err;
+      }
+
+      process.stderr.write("\n");
+      // Merge missing scopes with the default set so the new token retains
+      // all previously-held scopes plus the ones the API requested.
+      const { OAUTH_SCOPES, resolveOAuthScopeString } = await import(
+        "./lib/oauth.js"
+      );
+      const merged = [...new Set([...OAUTH_SCOPES, ...scopes])];
+      const scope = resolveOAuthScopeString({ scopes: merged });
+      const loginSuccess = await runInteractiveLogin({ scope });
+
+      if (loginSuccess) {
+        process.stderr.write("\nRetrying command...\n\n");
+        await next(argv);
+        return;
+      }
+
+      // Login failed or was cancelled — re-throw so the user sees the
+      // original 403 message with the scope hint.
+      throw err;
+    }
+  };
+
   /**
    * Auto-authentication middleware.
    *
@@ -409,6 +496,7 @@ export async function runCli(cliArgs: string[]): Promise<void> {
   const errorMiddlewares: ErrorMiddleware[] = [
     seerTrialMiddleware,
     rcImportMiddleware,
+    scopeRecoveryMiddleware,
     autoAuthMiddleware,
   ];
 

src/cli.ts

@@ -36,6 +36,7 @@ import {
   toLoginUser,
 } from "../../lib/interactive-login.js";
 import { logger } from "../../lib/logger.js";
+import { resolveOAuthScopeString } from "../../lib/oauth.js";
 import { clearResponseCache } from "../../lib/response-cache.js";
 import {
   isSaaSTrustOrigin,
@@ -77,8 +78,61 @@ type LoginFlags = {
   readonly timeout: number;
   readonly force: boolean;
   readonly url?: string;
+  readonly "read-only": boolean;
+  readonly scope?: readonly string[];
 };
 
+/**
+ * Resolve the OAuth scope string from the login flags, enforcing mutual
+ * exclusivity between `--token`, `--read-only`, and `--scope`.
+ *
+ * OAuth scope is fixed when a token is issued, so `--read-only` / `--scope`
+ * cannot narrow an existing `--token`. `--read-only` and `--scope` are also
+ * mutually exclusive — `--read-only` is a shorthand for a specific subset.
+ *
+ * @returns The resolved scope string for the device flow, or `undefined` to
+ *   use the device flow's full default scope set.
+ * @throws {ValidationError} on any conflicting flag combination or invalid
+ *   scope value.
+ */
+function resolveLoginScope(flags: LoginFlags): string | undefined {
+  const hasScope = flags.scope !== undefined && flags.scope.length > 0;
+  const readOnly = flags["read-only"];
+
+  if (flags.token && (readOnly || hasScope)) {
+    const conflicting = readOnly ? "--read-only" : "--scope";
+    throw new ValidationError(
+      [
+        `${conflicting} cannot be used with --token — OAuth scope is fixed when the token is issued, so the CLI cannot narrow an existing token's permissions.`,
+        "",
+        "To restrict OAuth scopes, drop --token and use the device flow:",
+        "  sentry auth login --read-only",
+        "  sentry auth login --scope project:read --scope org:read",
+        "",
+        "Or create a scoped User Auth Token in Sentry (Account → Auth Tokens) and pass it without --read-only/--scope.",
+      ].join("\n"),
+      readOnly ? "read-only" : "scope"
+    );
+  }
+
+  if (readOnly && hasScope) {
+    throw new ValidationError(
+      "--read-only and --scope cannot be used together. Use --read-only for the read-only subset, or --scope to list exact scopes.",
+      "scope"
+    );
+  }
+
+  if (hasScope) {
+    // Flatten comma-separated values so `-s a,b` and `-s a -s b` both work.
+    const scopes = (flags.scope ?? []).flatMap((value) => value.split(","));
+    return resolveOAuthScopeString({ scopes });
+  }
+  if (readOnly) {
+    return resolveOAuthScopeString({ readOnly: true });
+  }
+  return;
+}
+
 /**
  * Normalize and validate the `--url` flag value. Accepts bare hostnames
  * and full URLs; returns the normalized origin.
@@ -356,10 +410,32 @@ export const loginCommand = buildCommand({
           "Required for self-hosted; defaults to SaaS (https://sentry.io).",
         optional: true,
       },
+      "read-only": {
+        kind: "boolean",
+        brief:
+          "Request only read-only OAuth scopes (project:read, org:read, event:read, member:read, team:read). " +
+          "Useful for handing tokens to AI agents or CI jobs that should not be able to mutate Sentry state.",
+        default: false,
+      },
+      scope: {
+        kind: "parsed",
+        parse: String,
+        brief:
+          "Request specific OAuth scopes (repeatable, comma-separated). " +
+          "E.g. --scope project:read --scope org:read. Overrides the default scope set.",
+        variadic: true,
+        optional: true,
+      },
     },
+    aliases: { s: "scope" },
   },
   output: { human: formatLoginResult },
   async *func(this: SentryContext, flags: LoginFlags) {
+    // Resolve OAuth scopes up front so conflicting flag combinations
+    // (--token + --read-only/--scope, --read-only + --scope) and invalid
+    // scope values fail fast before any network or DB work.
+    const oauthScope = resolveLoginScope(flags);
+
     // Apply --url first so the device flow / token refresh target the
     // requested instance. Default URL persistence is deferred until login
     // succeeds — see persistLoginUrlAsDefault calls below.
@@ -435,6 +511,7 @@ export const loginCommand = buildCommand({
     // OAuth device flow (host scope recorded via completeOAuthFlow → setAuthToken)
     const result = await runInteractiveLogin({
       timeout: flags.timeout * 1000,
+      scope: oauthScope,
     });
 
     if (result) {

src/commands/auth/login.ts

@@ -1,7 +1,13 @@
 /**
  * sentry auth refresh
  *
- * Manually refresh the authentication token.
+ * Manually refresh the authentication token, or re-authenticate with
+ * different scopes via the OAuth device flow (like `gh auth refresh -s`).
+ *
+ * When `--scope` or `--read-only` is passed, the command runs a new device
+ * flow with the requested scopes instead of refreshing the existing token.
+ * This bypasses the "already authenticated" gate in `auth login`, making
+ * scope changes frictionless.
  */
 
 import type { SentryContext } from "../../context.js";
@@ -12,14 +18,18 @@ import {
   getAuthConfig,
   refreshToken,
 } from "../../lib/db/auth.js";
-import { AuthError } from "../../lib/errors.js";
+import { AuthError, ValidationError } from "../../lib/errors.js";
 import { success } from "../../lib/formatters/colors.js";
 import { formatDuration } from "../../lib/formatters/human.js";
 import { CommandOutput } from "../../lib/formatters/output.js";
+import { runInteractiveLogin } from "../../lib/interactive-login.js";
+import { resolveOAuthScopeString } from "../../lib/oauth.js";
 
 type RefreshFlags = {
   readonly json: boolean;
   readonly force: boolean;
+  readonly "read-only": boolean;
+  readonly scope?: readonly string[];
   readonly fields?: string[];
 };
 
@@ -31,10 +41,37 @@ type RefreshOutput = {
   expiresAt?: string;
 };
 
+/** Whether the user asked for a scope change (--scope or --read-only). */
+function hasScopeRequest(flags: RefreshFlags): boolean {
+  return (
+    flags["read-only"] || (flags.scope !== undefined && flags.scope.length > 0)
+  );
+}
+
+/**
+ * Resolve the OAuth scope string from the refresh flags.
+ *
+ * @throws {ValidationError} when `--read-only` and `--scope` are both set,
+ *   or when `--scope` contains an invalid value.
+ */
+function resolveRefreshScope(flags: RefreshFlags): string {
+  if (flags["read-only"] && flags.scope?.length) {
+    throw new ValidationError(
+      "--read-only and --scope cannot be used together. Use --read-only for the read-only subset, or --scope to list exact scopes.",
+      "scope"
+    );
+  }
+  if (flags.scope?.length) {
+    const scopes = [...flags.scope].flatMap((v) => v.split(","));
+    return resolveOAuthScopeString({ scopes });
+  }
+  return resolveOAuthScopeString({ readOnly: true });
+}
+
 /** Format refresh result for terminal output */
 function formatRefreshResult(data: RefreshOutput): string {
   return data.refreshed
-    ? `${success("✓")} Token refreshed successfully. Expires in ${formatDuration(data.expiresIn ?? 0)}.`
+    ? `${success("✓")} ${data.message}. Expires in ${formatDuration(data.expiresIn ?? 0)}.`
     : `Token still valid (expires in ${formatDuration(data.expiresIn ?? 0)}).\nUse --force to refresh anyway.`;
 }
 
@@ -49,13 +86,24 @@ Token refresh normally happens automatically when making API requests.
 Use this command to force an immediate refresh or to verify the refresh
 mechanism is working correctly.
 
+When --scope or --read-only is passed, re-authenticates via the OAuth
+device flow with the requested scopes instead of refreshing the existing
+token. This is the preferred way to add or change scopes on an existing
+session (similar to \`gh auth refresh -s <scope>\`).
+
 Examples:
   $ sentry auth refresh
   Token refreshed successfully. Expires in 59 minutes.
 
   $ sentry auth refresh --force
   Token refreshed successfully. Expires in 60 minutes.
 
+  $ sentry auth refresh --scope event:read --scope org:read
+  Re-authenticating with scopes: event:read, org:read...
+
+  $ sentry auth refresh --read-only
+  Re-authenticating with read-only scopes...
+
   $ sentry auth refresh --json
   {"success":true,"refreshed":true,"expiresIn":3600,"expiresAt":"..."}
     `.trim(),
@@ -68,10 +116,26 @@ Examples:
         brief: "Force refresh even if token is still valid",
         default: false,
       },
+      "read-only": {
+        kind: "boolean",
+        brief:
+          "Re-authenticate with read-only OAuth scopes (project:read, org:read, event:read, member:read, team:read)",
+        default: false,
+      },
+      scope: {
+        kind: "parsed",
+        parse: String,
+        brief:
+          "Re-authenticate with specific OAuth scopes (repeatable, comma-separated). " +
+          "E.g. --scope project:read --scope org:read",
+        variadic: true,
+        optional: true,
+      },
     },
+    aliases: { s: "scope" },
   },
   async *func(this: SentryContext, flags: RefreshFlags) {
-    // Env var tokens can't be refreshed — only block if env is the effective source
+    // Env var tokens can't be refreshed or re-scoped via the CLI.
     const currentAuth = getAuthConfig();
     if (currentAuth?.source.startsWith(ENV_SOURCE_PREFIX)) {
       const envVar = getActiveEnvVarName();
@@ -83,7 +147,29 @@ Examples:
       );
     }
 
-    // Pre-check for refresh token availability (better error message)
+    // --scope / --read-only: re-run the device flow with new scopes.
+    if (hasScopeRequest(flags)) {
+      const scope = resolveRefreshScope(flags);
+
+      const result = await runInteractiveLogin({ scope });
+      if (!result) {
+        process.exitCode = 1;
+        return;
+      }
+
+      const payload: RefreshOutput = {
+        success: true,
+        refreshed: true,
+        message: "Re-authenticated with updated scopes",
+        expiresIn: result.expiresIn,
+        expiresAt: result.expiresIn
+          ? new Date(Date.now() + result.expiresIn * 1000).toISOString()
+          : undefined,
+      };
+      return yield new CommandOutput(payload);
+    }
+
+    // Standard token refresh path (no scope change).
     const auth = await getAuthConfig();
     if (!auth?.refreshToken && auth?.token) {
       throw new AuthError(