fix(api): centralize 403 Forbidden enrichment with actionable hints (CLI-1JG) (#892)

## Summary

- Centralize 403 Forbidden error enrichment in `throwApiError()` /
`throwRawApiError()` so **all 60+ API endpoints** get actionable error
messages instead of the raw `"You do not have permission to perform this
action."`
- For env-var tokens: extract specific missing scope names from the API
response and link to `https://sentry.io/settings/auth-tokens/`
- For OAuth tokens: suggest re-authentication with `sentry auth login`
- Add `enriched403` flag to `ApiError` to prevent double-enrichment
where command-layer code already has specialized 403 handling (issue
list, dashboard, project delete)

Fixes CLI-1JG — a user hit `sentry org view` with an auto-detected org
and got a completely unhelpful 403 error.

## Before
```
Error: Failed to get organization: 403 Forbidden
  You do not have permission to perform this action.
```

## After (env-var token)
```
Error: Failed to get organization: 403 Forbidden
  You do not have permission to perform this action.

  Your SENTRY_AUTH_TOKEN token may lack the required scope for this operation.
  Check token scopes at: https://sentry.io/settings/auth-tokens/
```

## After (OAuth token)
```
Error: Failed to get organization: 403 Forbidden
  You do not have permission to perform this action.

  You may not have access to this resource.
  Re-authenticate with: sentry auth login
```

Author: BYK

src/commands/dashboard/resolve.ts

@@ -636,6 +636,13 @@ export function enrichDashboardError(
   }
 
   if (error.status === 403) {
+    // Centralized 403 enrichment (infrastructure.ts) already added
+    // scope/token hints. Re-throw the enriched ApiError directly —
+    // passing the multi-line enriched detail into build403Error would
+    // nest it as a single messy bullet in a ResolutionError.
+    if (error.enriched403) {
+      throw error;
+    }
     build403Error(ctx, org, error.detail);
   }
 

src/commands/issue/list.ts

@@ -1101,11 +1101,17 @@ function enrichIssueListError(
       );
     }
     if (error.status === 403) {
+      // Centralized 403 enrichment (infrastructure.ts) already added
+      // scope/token hints. Only append the project-membership hint.
+      const detail = error.enriched403
+        ? appendProjectMembershipHint(error.detail)
+        : build403Detail(error.detail);
       throw new ApiError(
         error.message,
         error.status,
-        build403Detail(error.detail),
-        error.endpoint
+        detail,
+        error.endpoint,
+        true
       );
     }
   }
@@ -1170,6 +1176,17 @@ function build403Detail(originalDetail: unknown): string {
   return lines.join("\n  ");
 }
 
+/**
+ * Append a project membership verification hint to an already-enriched
+ * 403 detail string. Used when centralized enrichment (infrastructure.ts)
+ * has already added scope/token hints and we only need the issue-list-specific
+ * suggestion.
+ */
+function appendProjectMembershipHint(detail: string | undefined): string {
+  const base = detail ?? "You do not have permission to perform this action.";
+  return `${base}\n  Verify project membership: sentry project list <org>/`;
+}
+
 /**
  * Handle auto-detect, explicit, and project-search modes.
  *
@@ -1327,13 +1344,16 @@ async function handleResolvedTargets(
       if (first.status === 400) {
         detail = build400Detail(first.detail, flags);
       } else if (first.status === 403) {
-        detail = build403Detail(first.detail);
+        detail = first.enriched403
+          ? appendProjectMembershipHint(first.detail)
+          : build403Detail(first.detail);
       }
       throw new ApiError(
         `${prefix}: ${first.message}`,
         first.status,
         detail,
-        first.endpoint
+        first.endpoint,
+        first.enriched403 || first.status === 403
       );
     }
 

src/lib/api/infrastructure.ts

@@ -11,6 +11,8 @@ import { parseSentryLinkHeader } from "@sentry/api";
 import * as Sentry from "@sentry/node-core/light";
 import type { z } from "zod";
 
+import { extractRequiredScopes } from "../api-scope.js";
+import { getActiveEnvVarName, isEnvTokenActive } from "../db/auth.js";
 import { getEnv } from "../env.js";
 import { ApiError, AuthError, stringifyUnknown } from "../errors.js";
 import { resolveOrgRegion } from "../region.js";
@@ -20,6 +22,47 @@ import {
   getSdkConfig,
 } from "../sentry-client.js";
 
+/**
+ * Enrich a 403 Forbidden error detail with actionable guidance.
+ *
+ * For env-var tokens (SENTRY_AUTH_TOKEN / SENTRY_TOKEN): extracts the specific
+ * missing scope from the API response when available, otherwise suggests
+ * checking token scopes. Includes a link to the token settings page.
+ *
+ * For OAuth tokens: suggests the user may lack access and should re-authenticate.
+ *
+ * @param rawDetail - The original detail string from the API 403 response
+ * @returns Enriched detail string with actionable suggestions
+ */
+function enrich403Detail(rawDetail: string | undefined): string {
+  const lines: string[] = [];
+  if (rawDetail) {
+    lines.push(rawDetail, "");
+  }
+
+  if (isEnvTokenActive()) {
+    const scopes = extractRequiredScopes(rawDetail);
+    if (scopes.length > 0) {
+      lines.push(
+        `Your ${getActiveEnvVarName()} token is missing the required scope(s) '${scopes.join("', '")}'.`
+      );
+    } else {
+      lines.push(
+        `Your ${getActiveEnvVarName()} token may lack the required scope for this operation.`
+      );
+    }
+    lines.push(
+      "Check token scopes at: https://sentry.io/settings/auth-tokens/"
+    );
+  } else {
+    lines.push(
+      "You may not have access to this resource.",
+      "Re-authenticate with: sentry auth login"
+    );
+  }
+  return lines.join("\n  ");
+}
+
 /**
  * Parse Sentry's RFC 5988 Link response header to extract pagination cursors.
  *
@@ -67,15 +110,26 @@ export function throwApiError(
   }
 
   const status = response.status;
-  const detail =
+  const rawDetail =
     error && typeof error === "object" && "detail" in error
-      ? stringifyUnknown((error as { detail: unknown }).detail)
-      : stringifyUnknown(error);
-
+      ? (error as { detail: unknown }).detail
+      : undefined;
+  const hasUsableDetail = rawDetail !== null && rawDetail !== undefined;
+  // When the API returns `{ detail: null }` or `{ detail: undefined }`,
+  // fall back to stringifying the whole error object for non-403 errors
+  // (useful for debugging). For 403s, pass undefined to enrich403Detail
+  // so the enrichment stands alone without a noisy `{}` prefix.
+  const detail = hasUsableDetail
+    ? stringifyUnknown(rawDetail)
+    : stringifyUnknown(error);
+
+  const is403 = status === 403;
   throw new ApiError(
     `${context}: ${status} ${response.statusText ?? "Unknown"}`,
     status,
-    detail
+    is403 ? enrich403Detail(hasUsableDetail ? detail : undefined) : detail,
+    undefined,
+    is403
   );
 }
 
@@ -303,38 +357,7 @@ export async function apiRequestToRegion<T>(
   });
 
   if (!response.ok) {
-    let detail: string | undefined;
-    try {
-      const text = await response.text();
-      try {
-        const parsed = JSON.parse(text) as { detail?: string };
-        detail = parsed.detail ?? JSON.stringify(parsed);
-      } catch {
-        detail = text;
-      }
-    } catch {
-      detail = response.statusText;
-    }
-    // Attach a small allowlisted subset of response headers to the Sentry
-    // event as context. This lets us distinguish Sentry-app 4xx/5xx (which
-    // ship a `{"detail": "..."}` JSON body and `content-type: application/json`)
-    // from CDN / WAF / edge 4xx (Cloudflare / proxy) that return empty or HTML
-    // bodies — a gap that previously made empty-`detail` events like CLI-1AZ
-    // impossible to triage without user-side repro.
-    Sentry.setContext("api_response_headers", {
-      "content-type": response.headers.get("content-type"),
-      "content-length": response.headers.get("content-length"),
-      server: response.headers.get("server"),
-      "cf-ray": response.headers.get("cf-ray"),
-      "x-sentry-error": response.headers.get("x-sentry-error"),
-      "www-authenticate": response.headers.get("www-authenticate"),
-    });
-    throw new ApiError(
-      `API request failed: ${response.status} ${response.statusText}`,
-      response.status,
-      detail,
-      endpoint
-    );
+    await throwRawApiError(response, endpoint);
   }
 
   // 204 No Content / 205 Reset Content have no body by spec — calling
@@ -377,6 +400,61 @@ export async function apiRequestToRegion<T>(
   return { data: data as T, headers: response.headers };
 }
 
+/**
+ * Extract error detail from a failed HTTP response, attach diagnostic
+ * headers to the Sentry scope, and throw an enriched {@link ApiError}.
+ *
+ * Extracted from `apiRequestToRegion` to keep the main function's
+ * cognitive complexity under the lint threshold.
+ */
+async function throwRawApiError(
+  response: Response,
+  endpoint: string
+): Promise<never> {
+  let detail: string | undefined;
+  try {
+    const text = await response.text();
+    try {
+      const parsed = JSON.parse(text) as { detail?: string };
+      // Prefer the explicit `detail` field; fall back to the full JSON
+      // for non-403 errors (useful for debugging). For 403s, pass
+      // undefined so enrich403Detail stands alone without a noisy
+      // `{"detail":null}` prefix.
+      if (typeof parsed.detail === "string") {
+        detail = parsed.detail;
+      } else if (response.status !== 403) {
+        detail = JSON.stringify(parsed);
+      }
+    } catch {
+      detail = text || undefined;
+    }
+  } catch {
+    detail = response.statusText;
+  }
+  // Attach a small allowlisted subset of response headers to the Sentry
+  // event as context. This lets us distinguish Sentry-app 4xx/5xx (which
+  // ship a `{"detail": "..."}` JSON body and `content-type: application/json`)
+  // from CDN / WAF / edge 4xx (Cloudflare / proxy) that return empty or HTML
+  // bodies — a gap that previously made empty-`detail` events like CLI-1AZ
+  // impossible to triage without user-side repro.
+  Sentry.setContext("api_response_headers", {
+    "content-type": response.headers.get("content-type"),
+    "content-length": response.headers.get("content-length"),
+    server: response.headers.get("server"),
+    "cf-ray": response.headers.get("cf-ray"),
+    "x-sentry-error": response.headers.get("x-sentry-error"),
+    "www-authenticate": response.headers.get("www-authenticate"),
+  });
+  const is403 = response.status === 403;
+  throw new ApiError(
+    `API request failed: ${response.status} ${response.statusText}`,
+    response.status,
+    is403 ? enrich403Detail(detail) : detail,
+    endpoint,
+    is403
+  );
+}
+
 /**
  * Make an authenticated request to the default Sentry API.
  *

src/lib/api/organizations.ts

@@ -16,8 +16,6 @@ import {
   UserRegionsResponseSchema,
 } from "../../types/index.js";
 
-import { extractRequiredScopes } from "../api-scope.js";
-import { getActiveEnvVarName, isEnvTokenActive } from "../db/auth.js";
 import { ApiError, withAuthGuard } from "../errors.js";
 import {
   getApiBaseUrl,
@@ -62,67 +60,18 @@ export async function listOrganizationsInRegion(
     ...config,
   });
 
-  try {
-    const data = unwrapResult(result, "Failed to list organizations");
-    if (!Array.isArray(data)) {
-      throw new ApiError(
-        "Failed to list organizations: unexpected response format",
-        0,
-        `Expected an array from ${regionUrl}/api/0/organizations/ but received ${typeof data}. ` +
-          "This may indicate an incompatible self-hosted Sentry version or a proxy interfering with the response."
-      );
-    }
-    return data as unknown as SentryOrganization[];
-  } catch (error) {
-    // Enrich 403 errors with contextual guidance (CLI-89, 24 users).
-    // Only mention token scopes when using a custom env-var token —
-    // the regular `sentry auth login` OAuth flow always grants org:read.
-    if (error instanceof ApiError && error.status === 403) {
-      throw enrichListOrgsForbidden(error);
-    }
-    throw error;
-  }
-}
-
-/**
- * Enrich a 403 from the list-organizations endpoint with actionable
- * hints. Prefers scope(s) named explicitly in the API response over
- * the hardcoded `'org:read'` fallback (getsentry/cli#785 item #9).
- */
-function enrichListOrgsForbidden(error: ApiError): ApiError {
-  const lines: string[] = [];
-  if (error.detail) {
-    lines.push(error.detail, "");
-  }
-  if (isEnvTokenActive()) {
-    lines.push(buildEnvTokenScopeHint(error.detail));
-    lines.push(
-      "Check token scopes at: https://sentry.io/settings/auth-tokens/"
+  // 403 enrichment (CLI-89, 24 users) is now handled centrally by
+  // throwApiError() in infrastructure.ts — no per-endpoint catch needed.
+  const data = unwrapResult(result, "Failed to list organizations");
+  if (!Array.isArray(data)) {
+    throw new ApiError(
+      "Failed to list organizations: unexpected response format",
+      0,
+      `Expected an array from ${regionUrl}/api/0/organizations/ but received ${typeof data}. ` +
+        "This may indicate an incompatible self-hosted Sentry version or a proxy interfering with the response."
     );
-  } else {
-    lines.push(
-      "You may not have access to this organization.",
-      "Re-authenticate with: sentry auth login"
-    );
-  }
-  return new ApiError(
-    error.message,
-    error.status,
-    lines.join("\n  "),
-    error.endpoint
-  );
-}
-
-/**
- * Build a single-line hint mentioning the scope(s) the env-var token
- * is missing, preferring the API-provided list when available.
- */
-function buildEnvTokenScopeHint(detail: unknown): string {
-  const scopes = extractRequiredScopes(detail);
-  if (scopes.length > 0) {
-    return `Your ${getActiveEnvVarName()} token is missing the required scope(s) '${scopes.join("', '")}'.`;
   }
-  return `Your ${getActiveEnvVarName()} token may lack the required scope 'org:read'.`;
+  return data as unknown as SentryOrganization[];
 }
 
 /**

src/lib/errors.ts

@@ -177,17 +177,27 @@ export class ApiError extends CliError {
   readonly detail?: string;
   readonly endpoint?: string;
 
+  /**
+   * Set by centralized 403 enrichment in `infrastructure.ts`.
+   * Command-layer code can check this to avoid double-enriching
+   * the error detail with scope/token hints.
+   */
+  readonly enriched403: boolean;
+
+  // biome-ignore lint/nursery/useMaxParams: established 4-param shape; enriched403 is a defaulted extension
   constructor(
     message: string,
     status: number,
     detail?: string,
-    endpoint?: string
+    endpoint?: string,
+    enriched403 = false
   ) {
     super(message, EXIT.API);
     this.name = "ApiError";
     this.status = status;
     this.detail = detail;
     this.endpoint = endpoint;
+    this.enriched403 = enriched403;
   }
 
   override format(): string {