fix(auth): prefer stored OAuth over env token by default (#646)

When SENTRY_AUTH_TOKEN is set by build tooling (e.g. the Sentry wizard)
but lacks the scopes needed for interactive CLI commands, the CLI now
prefers stored OAuth credentials by default.

OAuth-preferred default: when the user is logged in via OAuth, env
tokens are automatically skipped. This prevents wizard-generated build
tokens from silently overriding interactive credentials. Set
SENTRY_FORCE_ENV_TOKEN=1 to restore the old env-token-first priority.

Key changes:
- getEnvToken() returns undefined when stored OAuth credentials exist,
  cascading through all consumers (isEnvTokenActive, refreshToken, etc.)
- SENTRY_FORCE_ENV_TOKEN env var to force env token priority
- sentry auth login no longer blocks when an env token is present
- sentry auth status shows env token info (active vs bypassed)
- Enhanced 401/403 error messages when env token is the only auth source

Author: BYK

src/commands/auth/login.ts

@@ -9,6 +9,7 @@ import { buildCommand, numberParser } from "../../lib/command.js";
 import {
   clearAuth,
   getActiveEnvVarName,
+  hasStoredAuthCredentials,
   isAuthenticated,
   isEnvTokenActive,
   setAuthToken,
@@ -71,11 +72,15 @@ type LoginFlags = {
 async function handleExistingAuth(force: boolean): Promise<boolean> {
   if (isEnvTokenActive()) {
     const envVar = getActiveEnvVarName();
-    log.info(
-      `Authentication is provided via ${envVar} environment variable. ` +
-        `Unset ${envVar} to use OAuth-based login instead.`
+    log.warn(
+      `${envVar} is set in your environment (likely from build tooling).\n` +
+        "  OAuth credentials will be stored separately and used for CLI commands."
     );
-    return false;
+    // If no stored OAuth token exists, proceed directly to login
+    if (!hasStoredAuthCredentials()) {
+      return true;
+    }
+    // Fall through to the re-auth confirmation logic below
   }
 
   if (!force) {

src/commands/auth/status.ts

@@ -11,8 +11,11 @@ import {
   type AuthConfig,
   type AuthSource,
   ENV_SOURCE_PREFIX,
+  getActiveEnvVarName,
   getAuthConfig,
+  getRawEnvToken,
   isAuthenticated,
+  isEnvTokenActive,
 } from "../../lib/db/auth.js";
 import {
   getDefaultOrganization,
@@ -77,6 +80,13 @@ export type AuthStatusData = {
     /** Error message if verification failed */
     error?: string;
   };
+  /** Environment variable token info (present when SENTRY_AUTH_TOKEN or SENTRY_TOKEN is set) */
+  envToken?: {
+    /** Name of the env var (e.g., "SENTRY_AUTH_TOKEN") */
+    envVar: string;
+    /** Whether the env token is the effective auth source (vs bypassed for OAuth) */
+    active: boolean;
+  };
 };
 
 /**
@@ -186,6 +196,13 @@ export const statusCommand = buildCommand({
         : undefined;
     }
 
+    // Check for env token regardless of whether it's the active source
+    // (it may be set but bypassed because stored OAuth takes priority)
+    const rawEnv = getRawEnvToken();
+    const envTokenData: AuthStatusData["envToken"] = rawEnv
+      ? { envVar: getActiveEnvVarName(), active: isEnvTokenActive() }
+      : undefined;
+
     const data: AuthStatusData = {
       authenticated: true,
       source: auth?.source ?? "oauth",
@@ -194,6 +211,7 @@ export const statusCommand = buildCommand({
       token: collectTokenInfo(auth, flags["show-token"]),
       defaults: collectDefaults(),
       verification: await verifyCredentials(),
+      envToken: envTokenData,
     };
 
     yield new CommandOutput(data);

src/lib/api/infrastructure.ts

@@ -10,6 +10,7 @@
 import * as Sentry from "@sentry/node-core/light";
 import type { z } from "zod";
 
+import { getRawEnvToken } from "../db/auth.js";
 import { getEnv } from "../env.js";
 import { ApiError, AuthError, stringifyUnknown } from "../errors.js";
 import { resolveOrgRegion } from "../region.js";
@@ -57,6 +58,29 @@ export function throwApiError(
     error && typeof error === "object" && "detail" in error
       ? stringifyUnknown((error as { detail: unknown }).detail)
       : stringifyUnknown(error);
+
+  // When an env token is set and we get 401, the HTTP-layer fallback to
+  // stored OAuth already failed (no stored credentials). Convert to AuthError
+  // so the auto-login middleware in cli.ts can trigger interactive login.
+  if (status === 401 && getRawEnvToken()) {
+    throw new AuthError(
+      "not_authenticated",
+      `${context}: ${status} ${response.statusText ?? "Unknown"}.\n` +
+        "  SENTRY_AUTH_TOKEN is set but lacks permissions for this endpoint.\n" +
+        "  Run 'sentry auth login' to authenticate with OAuth."
+    );
+  }
+
+  // For 403 with env token, keep as ApiError but add guidance
+  if (status === 403 && getRawEnvToken()) {
+    throw new ApiError(
+      `${context}: ${status} ${response.statusText ?? "Unknown"}`,
+      status,
+      `${detail}\n\n  SENTRY_AUTH_TOKEN may lack permissions for this endpoint.\n` +
+        "  Run 'sentry auth login' to authenticate with OAuth."
+    );
+  }
+
   throw new ApiError(
     `${context}: ${status} ${response.statusText ?? "Unknown"}`,
     status,

src/lib/db/auth.ts

@@ -36,21 +36,64 @@ export type AuthConfig = {
   source: AuthSource;
 };
 
+/**
+ * Read the raw token string from environment variables, ignoring all filters.
+ *
+ * Unlike {@link getEnvToken}, this always returns the env token if set, even
+ * when stored OAuth credentials would normally take priority. Used by the HTTP
+ * layer to check "was an env token provided?" independent of whether it's being
+ * used, and by the per-endpoint permission cache.
+ */
+export function getRawEnvToken(): string | undefined {
+  const authToken = getEnv().SENTRY_AUTH_TOKEN?.trim();
+  if (authToken) {
+    return authToken;
+  }
+  const sentryToken = getEnv().SENTRY_TOKEN?.trim();
+  if (sentryToken) {
+    return sentryToken;
+  }
+  return;
+}
+
 /**
  * Read token from environment variables.
  * `SENTRY_AUTH_TOKEN` takes priority over `SENTRY_TOKEN` (matches legacy sentry-cli).
  * Empty or whitespace-only values are treated as unset.
+ *
+ * **Default behavior**: When the user is logged in (stored OAuth credentials
+ * exist in the database), env tokens are skipped so OAuth takes priority. This
+ * prevents wizard-generated build tokens from silently overriding interactive
+ * CLI credentials. Set `SENTRY_FORCE_ENV_TOKEN=1` to override this and force
+ * the env token to take priority (e.g., for CI pipelines that intentionally
+ * use an env token alongside stored credentials).
  */
 function getEnvToken(): { token: string; source: AuthSource } | undefined {
+  const raw = getRawEnvToken();
+  if (!raw) {
+    return;
+  }
+
+  // When OAuth credentials are stored and env token is not forced, prefer OAuth.
+  // This is the core fix for #646: wizard-generated tokens no longer silently
+  // override the user's interactive login.
+  const forceEnv = getEnv().SENTRY_FORCE_ENV_TOKEN?.trim();
+  if (!forceEnv) {
+    try {
+      if (hasStoredAuthCredentials()) {
+        return;
+      }
+    } catch {
+      // DB unavailable (e.g., read-only filesystem, test environment).
+      // Fall through to use the env token rather than breaking auth entirely.
+    }
+  }
+
   const authToken = getEnv().SENTRY_AUTH_TOKEN?.trim();
   if (authToken) {
     return { token: authToken, source: "env:SENTRY_AUTH_TOKEN" };
   }
-  const sentryToken = getEnv().SENTRY_TOKEN?.trim();
-  if (sentryToken) {
-    return { token: sentryToken, source: "env:SENTRY_TOKEN" };
-  }
-  return;
+  return { token: raw, source: "env:SENTRY_TOKEN" };
 }
 
 /**
@@ -179,6 +222,35 @@ export function isAuthenticated(): boolean {
   return !!token;
 }
 
+/**
+ * Check if usable OAuth credentials are stored in the database.
+ *
+ * Returns true when the `auth` table has either:
+ * - A non-expired token, or
+ * - An expired token with a refresh token (will be refreshed on next use)
+ *
+ * This is the gate for the "OAuth-preferred" default: when this returns true,
+ * {@link getEnvToken} skips the env token so OAuth takes priority. Also used
+ * by the login command to decide whether to prompt for re-authentication.
+ */
+export function hasStoredAuthCredentials(): boolean {
+  return withDbSpan("hasStoredAuthCredentials", () => {
+    const db = getDatabase();
+    const row = db.query("SELECT * FROM auth WHERE id = 1").get() as
+      | AuthRow
+      | undefined;
+    if (!row?.token) {
+      return false;
+    }
+    // Non-expired token
+    if (!row.expires_at || Date.now() <= row.expires_at) {
+      return true;
+    }
+    // Expired but has refresh token — will be refreshed on next use
+    return !!row.refresh_token;
+  });
+}
+
 export type RefreshTokenOptions = {
   /** Bypass threshold check and always refresh */
   force?: boolean;
@@ -229,7 +301,7 @@ async function performTokenRefresh(
 export async function refreshToken(
   options: RefreshTokenOptions = {}
 ): Promise<RefreshTokenResult> {
-  // Env var tokens are assumed valid — no refresh, no expiry check
+  // Env var tokens are assumed valid — no refresh, no expiry check.
   const envToken = getEnvToken();
   if (envToken) {
     return { token: envToken.token, refreshed: false };

src/lib/db/schema.ts

@@ -675,18 +675,8 @@ function getSchemaVersion(db: Database): number {
   return row?.version ?? 0;
 }
 
-/**
- * Run migrations for schema changes between versions.
- *
- * Note: Auto-repair handles missing tables/columns as a safety net, but explicit
- * migrations are still needed for:
- * - Data transformations (e.g., splitting a column)
- * - Column renames (requires data copy in SQLite)
- * - Complex constraints
- */
-export function runMigrations(db: Database): void {
-  const currentVersion = getSchemaVersion(db);
-
+/** Migrations 1–6: early schema additions and repairs */
+function runEarlyMigrations(db: Database, currentVersion: number): void {
   // Migration 1 -> 2: Add org_regions, user_info, and instance_info tables
   if (currentVersion < 2) {
     db.exec(`
@@ -733,7 +723,10 @@ export function runMigrations(db: Database): void {
     db.exec("DROP TABLE pagination_cursors");
     db.exec(EXPECTED_TABLES.pagination_cursors as string);
   }
+}
 
+/** Migrations 7–13: column additions and new tables */
+function runLateMigrations(db: Database, currentVersion: number): void {
   // Migration 6 -> 7: Add project_id column to project_cache for numeric project filtering
   if (currentVersion < 7) {
     addColumnIfMissing(db, "project_cache", "project_id", "TEXT");
@@ -769,6 +762,22 @@ export function runMigrations(db: Database): void {
     }
     db.exec(EXPECTED_TABLES.pagination_cursors as string);
   }
+}
+
+/**
+ * Run migrations for schema changes between versions.
+ *
+ * Note: Auto-repair handles missing tables/columns as a safety net, but explicit
+ * migrations are still needed for:
+ * - Data transformations (e.g., splitting a column)
+ * - Column renames (requires data copy in SQLite)
+ * - Complex constraints
+ */
+export function runMigrations(db: Database): void {
+  const currentVersion = getSchemaVersion(db);
+
+  runEarlyMigrations(db, currentVersion);
+  runLateMigrations(db, currentVersion);
 
   if (currentVersion < CURRENT_SCHEMA_VERSION) {
     db.query("UPDATE schema_version SET version = ?").run(

src/lib/formatters/human.ts

@@ -1826,6 +1826,10 @@ export function formatAuthStatus(data: AuthStatusData): string {
     lines.push(mdKvTable(authRows));
   }
 
+  if (data.envToken) {
+    lines.push(formatEnvTokenSection(data.envToken));
+  }
+
   if (data.defaults) {
     lines.push(formatDefaultsSection(data.defaults));
   }
@@ -1837,6 +1841,24 @@ export function formatAuthStatus(data: AuthStatusData): string {
   return renderMarkdown(lines.join("\n"));
 }
 
+/**
+ * Format the env token status section.
+ * Shows whether the env token is active or bypassed, and how many endpoints
+ * have been marked insufficient.
+ */
+function formatEnvTokenSection(
+  envToken: NonNullable<AuthStatusData["envToken"]>
+): string {
+  const status = envToken.active
+    ? "active"
+    : "set but not used (using OAuth credentials)";
+  const rows: [string, string][] = [
+    ["Env var", safeCodeSpan(envToken.envVar)],
+    ["Status", status],
+  ];
+  return `\n${mdKvTable(rows, "Environment Token")}`;
+}
+
 // Project Creation Formatting
 
 /** Input for the project-created success formatter */