Distillation

Date: Sep 10, 2026

• 🔴 (11:14) User asserted the retry loop’s last attempt always returns "done" or "throw"; its final unreachable path is documented accordingly.
• 🔴 (11:14) User asserted throwOnError is always false because the CLI handles errors itself.
• 🔴 (11:14) User asserted certain endpoints are always on the control silo, including OAuth, user accounts, and regions.
• 🔴 (11:14) User asserted: “Never forward headers across an unvalidated origin.” The manual redirect flow validates a destination origin before rebuilding/attaching request headers.
• 🔴 (11:14) User asserted post-mutation response-cache housekeeping must never throw; a cache-invalidation failure must not convert an otherwise successful mutation into a failure.
• 🟡 (11:14) packages/cli/src/lib/sentry-client.ts recognizes final responses, retryable errors/401s, and terminal throws through action results including { action: "throw", error }; retryable errors continue until the final retry attempt, then propagate.
• 🟡 (11:14) packages/cli/src/lib/sentry-client.ts auto-invalidates cache entries only after successful non-GET mutations; it skips GET requests and non-OK responses.
• 🟡 (11:14) fetchWithRetry() snapshots request bodies with await new Response(body).arrayBuffer() so it can reconstruct a fresh (input, init) request per retry because fetch consumes request bodies.
• 🟡 (11:14) fetchWithRetry() obtains the current token via refreshToken() without forcing refresh for fast, Vary-correct cache lookups, then caches responses and carries updated headers returned by retry handling.
• 🟡 (11:14) OAuth-related source search found refreshToken usage in packages/cli/src/lib/sentry-client.ts at lines 27, 183, 188, and 678; OAuth token endpoints in packages/cli/src/lib/oauth.ts include POST /oauth/device/code/ and POST /oauth/token/ for device-code and refresh-token grants.
• 🟡 (11:14) packages/cli/src/lib/oauth.ts contains a guard that refuses to POST a refresh token to a host that does not match the active token host, throwing HostScopeError.
• 🟡 (11:15) packages/cli/src/lib/oauth.ts implements RFC 8628 Device Authorization Grant. getSentryUrl() lazily resolves getConfiguredSentryUrl() ?? DEFAULT_SENTRY_URL, allowing SENTRY_URL set after module import—such as through self-hosted URL argument parsing—to affect device flow and token refresh.
• 🟡 (11:15) OAuth client-ID precedence in packages/cli/src/lib/oauth.ts is SENTRY_CLIENT_ID environment variable → SENTRY_CLIENT_ID_BUILD build-time define → committed DEFAULT_OAUTH_CLIENT_ID; the default public client ID is 1d673b81d60ef84c951359c36296972ca6fd41bd8f45acd2d3a783a3b3c28e41.
• 🟡 (11:15) OAUTH_SCOPES in packages/cli/src/lib/oauth.ts are, in order: 1. project:read, 2. project:write, 3. project:admin, 4. org:read, 5. event:read, 6. event:write, 7. member:read, 8. team:read, 9. team:write, 10. alerts:read, 11. alerts:write.
• 🟡 (11:15) resolveOAuthScopeString(selection) prioritizes explicit scopes, then the derived :read-only subset, then the complete default scope list. Explicit scope normalization trims and lowercases entries, validates against SENTRY_SCOPES, collapses duplicates while preserving first-seen order, throws ValidationError for an unknown scope, and throws ValidationError("No scopes provided to --scope", "scope") when normalization yields no scopes.
• 🟡 (11:15) fetchWithConnectionError(url, init) in packages/cli/src/lib/oauth.ts copies request headers, calls applyCustomHeaders(merged, url) for URL-scoped self-hosted proxy/IAP/mTLS headers, uses getCustomTlsOptions(), and calls warnIfSaasWithEnvCa(url) when custom TLS is configured.
• 🟡 (11:15) OAuth connection error handling maps TLS certificate failures to ApiError with buildTlsErrorDetail(error), status 0, and message TLS certificate error connecting to ${getSentryUrl()}; ECONNREFUSED, "fetch failed", or "network" errors become status-0 ApiError advising users to check network connectivity and SENTRY_URL.
• 🟡 (11:15) packages/cli/src/lib/token-host.ts defines host equivalence as exact normalized origin match (scheme, host, and explicit port) or strict SaaS equivalence: a token scoped to https://sentry.io permits *.sentry.io only when both origins use HTTPS and default port. Non-SaaS hosts require exact matches; sentry.acme.com does not trust sentry.acme.evil.com.
• 🟡 (11:15) getActiveTokenHost() mirrors authentication precedence: usable stored OAuth host wins over an environment token unless a raw environment token exists and SENTRY_FORCE_ENV_TOKEN is nonblank; otherwise it returns getEnvTokenHost() for the active environment token.
• 🟡 (11:15) loginTrustAnchor in packages/cli/src/lib/token-host.ts is process-local and is registered only through explicit applyLoginUrl sources (--url or boot-time environment snapshot), not the .sentryclirc shim. It permits custom headers during tokenless OAuth bootstrap against an IAP-protected self-hosted instance.
• 🟡 (11:15) isLoginTrustAnchorFor(host) compares the candidate to loginTrustAnchor using host-scoping equivalence rather than checking only whether an anchor exists, preventing a stale auth login --url <other-host> anchor from authorizing a different host in library/test mode. resetLoginTrustAnchorForTesting() clears the anchor.
• 🟡 (11:15) isOriginTrustedFor() trusts a request if it matches its anchor through isHostTrusted() or if its normalized origin is in dynamically trusted regional origins via isTrustedRegionOrigin(). isRequestOriginTrusted() returns true when no token is active; otherwise it evaluates against getActiveTokenHost().
• 🟡 (11:15) isRequestOriginTrustedForCustomHeaders() trusts custom headers by active-token host scope when a token exists; without a token, it trusts only an explicit matching login trust anchor; with neither, it fails closed.