fix(scopes): Allow project:distribution scope to be granted to integration tokens (#102967)

## Summary

Fixes two related issues with the `project:distribution` scope for
Custom Integration tokens:

1. **Creation Error**: Users couldn't add the `project:distribution`
permission when creating Custom Integration tokens, getting the error:
*"Requested permission of project:distribution exceeds requester's
permission. Please contact an administrator to make the requested
change."*
<img width="1266" height="241" alt="Screenshot 2025-11-07 at 18 01 11"
src="https://github.com/user-attachments/assets/a7fdee78-182b-4f0c-a9da-be0b6d89d520"
/>

2. **Client Secret Masked**: Even if users bypassed the creation error,
the client secret was immediately masked as `****` instead of being
visible.
<img width="604" height="223" alt="Screenshot 2025-11-07 at 18 20 03"
src="https://github.com/user-attachments/assets/66f50d31-06bd-4454-9f7e-c280a9f6ab9e"
/>

## Root Cause

The `project:distribution` scope is a specialized token-only scope that
is intentionally not included in any user role (including owner). This
design allows distribution tokens to be used in apps that are
distributed without risking accidentally leaking a token with broader
permissions.

However, two pieces of validation logic were checking if the user
personally had these scopes:

1. **`SentryAppParser.validate_scopes()`** - Blocked creation if the
user didn't have the requested scopes
2. **`SentryApp.show_auth_info()`** - Hid the client secret if the user
didn't have all the integration's scopes

## Changes

- Added `SENTRY_TOKEN_ONLY_SCOPES` constant in `server.py` to define
scopes that can be granted to integration tokens even if the user
doesn't have them
- Updated `SentryAppParser.validate_scopes()` to skip permission checks
for token-only scopes
- Updated `SentryApp.show_auth_info()` to exclude token-only scopes when
determining if the client secret should be visible
- Added `project:distribution` to `SENTRY_SCOPE_SETS` for documentation
- Added test coverage for token-only scope validation and visibility

Author: runningcode

src/sentry/conf/server.py

@@ -1789,6 +1789,15 @@ def custom_parameter_sort(parameter: dict) -> tuple[str, int]:
     "email": {"email"},
 }
 
+# Specialized scopes that can be granted to integration tokens even if the
+# user doesn't have them in their role. These are token-only scopes not intended
+# for user roles.
+SENTRY_TOKEN_ONLY_SCOPES = frozenset(
+    [
+        "project:distribution",  # App distribution/preprod artifacts
+    ]
+)
+
 SENTRY_SCOPE_SETS = (
     (
         ("org:admin", "Read, write, and admin access to organization details."),
@@ -1818,6 +1827,7 @@ def custom_parameter_sort(parameter: dict) -> tuple[str, int]:
         ("project:read", "Read access to projects."),
     ),
     (("project:releases", "Read, write, and admin access to project releases."),),
+    (("project:distribution", "Access to app distribution and preprod artifacts."),),
     (
         ("event:admin", "Read, write, and admin access to events."),
         ("event:write", "Read and write access to events."),

src/sentry/sentry_apps/api/parsers/sentry_app.py

@@ -176,12 +176,20 @@ def validate_scopes(self, value):
         if not value:
             return value
 
+        from sentry.conf.server import SENTRY_TOKEN_ONLY_SCOPES
+
         validation_errors = []
         for scope in value:
             # if the existing instance already has this scope, skip the check
             if self.instance and self.instance.has_scope(scope):
                 continue
 
+            # Token-only scopes can be granted even if the user doesn't have them.
+            # These are specialized scopes (like project:distribution) that are not
+            # included in any user role but can be granted to integration tokens.
+            if scope in SENTRY_TOKEN_ONLY_SCOPES:
+                continue
+
             assert (
                 self.access is not None
             ), "Access is required to validate scopes in SentryAppParser"

src/sentry/sentry_apps/models/sentry_app.py

@@ -200,8 +200,12 @@ def build_signature(self, body):
         ).hexdigest()
 
     def show_auth_info(self, access):
+        from sentry.conf.server import SENTRY_TOKEN_ONLY_SCOPES
+
         encoded_scopes = set({"%s" % scope for scope in list(access.scopes)})
-        return set(self.scope_list).issubset(encoded_scopes)
+        # Exclude token-only scopes from the check since users don't have them in their roles
+        integration_scopes = set(self.scope_list) - SENTRY_TOKEN_ONLY_SCOPES
+        return integration_scopes.issubset(encoded_scopes)
 
     def outboxes_for_update(self) -> list[ControlOutbox]:
         return [

tests/sentry/sentry_apps/api/endpoints/test_sentry_apps.py

@@ -793,6 +793,21 @@ def test_create_integration_exceeding_scopes(self) -> None:
             ]
         }
 
+    def test_create_integration_with_token_only_scopes(self) -> None:
+        """Test that token-only scopes (like project:distribution) can be granted
+        even if the user doesn't have them in their role."""
+        self.create_project(organization=self.organization)
+
+        # Token-only scopes like project:distribution are not in any user role,
+        # but should still be grantable to integration tokens
+        data = self.get_data(
+            events=(),
+            scopes=("project:read", "project:distribution"),
+            isInternal=True,
+        )
+        response = self.get_success_response(**data, status_code=201)
+        assert response.data["scopes"] == ["project:distribution", "project:read"]
+
     def test_create_internal_integration_with_non_globally_unique_name(self) -> None:
         # Internal integration names should only need to be unique within an organization.
         self.create_project(organization=self.organization)