coder · BobbyHo · Sep 9, 2026 · Aug 14, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/coderd/oauth2provider/authorize.go b/coderd/oauth2provider/authorize.go
@@ -40,9 +40,9 @@ var (
 	errNoGrantableScope = xerrors.New("none of the scopes registered for this app are supported by this deployment; change the app's registered scopes to supported ones")
 	// The scope expands to permissions the allowlist does not cover.
 	errScopeNotAllowed = xerrors.New("scope requests permissions beyond this app's allowed scopes")
-	// A comparison that failed outright. The underlying error names RBAC
+	// The coverage check itself failed. The underlying error names RBAC
 	// internals, so it is logged rather than rendered.
-	errCoverageUndecidable = xerrors.New("scope coverage against this app's allowed scopes could not be determined")
+	errCoverageUndecidable = xerrors.New("scope coverage could not be determined")
 )
 
 // canonicalScopes rewrites each name to its api_key_scope enum spelling and
@@ -56,6 +56,18 @@ func canonicalScopes(names []string) []string {
 	return slice.Unique(canonical)
 }
 
+// firstUnknownScope returns the first name clients may not request, and whether
+// there was one. The catalog is a curation, not a validity check: RBAC also
+// expands internal-only names such as debug_info:read.
+func firstUnknownScope(names []string) (string, bool) {
+	for _, name := range names {
+		if !rbac.IsExternalScope(rbac.ScopeName(name)) {
+			return name, true
+		}
+	}
+	return "", false
+}
+
 // noScopeAllowlist reports whether an app has no scope allowlist. NULL and ""
 // are the same state: admin-created apps store NULL, DCR-registered apps store
 // a possibly empty req.Scope. Whitespace-only is a configured allowlist that
@@ -92,30 +104,33 @@ func grantableScopes(appScope string) []string {
 	return filtered
 }
 
-// firstScopeOutsideAllowlist returns the first scope in granted that the
-// allowlist does not confer, or "" when it confers all of them. It compares
-// what the scopes grant, not their names: `coder:workspaces.access` covers
+const (
+	phaseAuthorize = "authorize"
+	phaseRedeem    = "redeem"
+	phaseRefresh   = "refresh"
+)
+
+// firstScopeBeyondCeiling returns the first requested scope the ceiling does not
+// confer, or "" when it confers all of them. It compares what the scopes grant,
+// not their names: a ceiling of `coder:workspaces.access` covers
 // `workspace:read`. Pass both slices through canonicalScopes first, since RBAC
 // expands `coder:all` but not the bare `all` alias. A comparison it cannot
 // decide refuses.
-func firstScopeOutsideAllowlist(ctx context.Context, logger slog.Logger, phase string, appID uuid.UUID, allowlist, granted []string) (string, error) {
-	allowedNames := make([]rbac.ScopeName, 0, len(allowlist))
-	for _, a := range allowlist {
-		allowedNames = append(allowedNames, rbac.ScopeName(a))
-	}
-	requestedNames := make([]rbac.ScopeName, 0, len(granted))
-	for _, g := range granted {
-		requestedNames = append(requestedNames, rbac.ScopeName(g))
-	}
-	// One pass over the allowlist rather than one per granted scope.
-	outside, err := rbac.FirstScopeNotCovered(allowedNames, requestedNames)
+func firstScopeBeyondCeiling(ctx context.Context, logger slog.Logger, phase string, appID uuid.UUID, ceiling, requested []string) (string, error) {
+	ceilingNames := slice.StringEnums[rbac.ScopeName](ceiling)
+	requestedNames := slice.StringEnums[rbac.ScopeName](requested)
+	// One pass over the ceiling rather than one per requested scope.
+	outside, err := rbac.FirstScopeNotCovered(ceilingNames, requestedNames)
 	if err != nil {
 		logger.Warn(ctx, "oauth2 scope coverage could not be determined",
 			slog.Error(err),
 			slog.F("phase", phase),
 			slog.F("app_id", appID.String()),
-			slog.F("allowlist", strings.Join(allowlist, " ")),
+			slog.F("ceiling", strings.Join(ceiling, " ")),
 			slog.F("scope", string(outside)))
+		// outside is a name from the ceiling, so it can be a stored value.
+		// Both handlers answer with a fixed string; rendering err.Error()
+		// here would echo it to the client.
 		return "", xerrors.Errorf("'%s': %w", outside, errCoverageUndecidable)
 	}
 	return string(outside), nil
@@ -139,13 +154,8 @@ func negotiateScope(ctx context.Context, logger slog.Logger, app database.OAuth2
 	// of the two aliases, so checking after the rewrite accepts the same names.
 	granted := canonicalScopes(requested)
 
-	// The catalog is a curation, not a validity check: RBAC also expands
-	// internal-only names such as debug_info:read, but clients may not request
-	// them.
-	for _, s := range granted {
-		if !rbac.IsExternalScope(rbac.ScopeName(s)) {
-			return "", xerrors.Errorf("%q: %w", s, errUnknownScope)
-		}
+	if unknown, ok := firstUnknownScope(granted); ok {
+		return "", xerrors.Errorf("'%s': %w", unknown, errUnknownScope)
 	}
 
 	if noScopeAllowlist(app.Scope) {
@@ -169,7 +179,7 @@ func negotiateScope(ctx context.Context, logger slog.Logger, app database.OAuth2
 		return strings.Join(allowlist, " "), nil // RFC 6749 §3.3 default
 	}
 
-	outside, err := firstScopeOutsideAllowlist(ctx, logger, "authorize", app.ID, allowlist, granted)
+	outside, err := firstScopeBeyondCeiling(ctx, logger, phaseAuthorize, app.ID, allowlist, granted)
 	if err != nil {
 		return "", err
 	}
@@ -207,6 +217,15 @@ func consentScopes(granted string) (names []string, unrestricted bool) {
 // short enough for a Location header to survive the proxies in front of it.
 const maxErrorDescription = 2048
 
+// capErrorDescription bounds a description, whose length is otherwise the
+// client's to choose.
+func capErrorDescription(description string) string {
+	if len(description) > maxErrorDescription {
+		return description[:maxErrorDescription] + " (truncated)"
+	}
+	return description
+}
+
 // responseTypeCode is the only response type this server supports. response_type
 // is read as text rather than through the SDK enum so every unsupported value
 // takes one path, instead of splitting on whether a Go constant happens to
@@ -533,11 +552,8 @@ func (a authorizeResponse) codeURL(code string) *url.URL {
 }
 
 func redirectAuthorizeError(rw http.ResponseWriter, r *http.Request, logger slog.Logger, response authorizeResponse, code codersdk.OAuth2ErrorCode, description string) {
-	// Descriptions echo values the client sent, so their length is the client's
-	// to choose. Cap here, ahead of both the log field and the Location header.
-	if len(description) > maxErrorDescription {
-		description = description[:maxErrorDescription] + " (truncated)"
-	}
+	// Capped ahead of both the log field and the Location header.
+	description = capErrorDescription(description)
 
 	app := httpmw.OAuth2ProviderApp(r)
 	logger.Info(r.Context(), "oauth2 authorization rejected",

diff --git a/coderd/oauth2provider/authorize_internal_test.go b/coderd/oauth2provider/authorize_internal_test.go
@@ -265,6 +265,9 @@ var (
 	ReasonCoverageUndecidable = errCoverageUndecidable.Error()
 )
 
+// MaxErrorDescription is the description bound, for the same tests.
+const MaxErrorDescription = maxErrorDescription
+
 // TestGrantableScopesNotSizedByInput pins the shape of the result, not just its
 // contents. app.Scope is unvalidated registration metadata read on every
 // authorization and redemption, so collecting duplicates and dropping them
@@ -383,6 +386,27 @@ func TestHashOAuth2State(t *testing.T) {
 	})
 }
 
+func TestCapErrorDescription(t *testing.T) {
+	t.Parallel()
+
+	t.Run("ShortDescriptionUnchanged", func(t *testing.T) {
+		t.Parallel()
+		assert.Equal(t, "unknown or unsupported scope", capErrorDescription("unknown or unsupported scope"))
+	})
+
+	t.Run("BoundIsInclusive", func(t *testing.T) {
+		t.Parallel()
+		atBound := strings.Repeat("x", maxErrorDescription)
+		assert.Equal(t, atBound, capErrorDescription(atBound))
+	})
+
+	t.Run("LongerDescriptionTruncated", func(t *testing.T) {
+		t.Parallel()
+		got := capErrorDescription(strings.Repeat("x", maxErrorDescription+1))
+		assert.Equal(t, strings.Repeat("x", maxErrorDescription)+" (truncated)", got)
+	})
+}
+
 func TestSanitizeErrorDescription(t *testing.T) {
 	t.Parallel()
 
@@ -397,13 +421,13 @@ func TestSanitizeErrorDescription(t *testing.T) {
 			want:        "Only response_type=code is supported",
 		},
 		{
-			// What negotiateScope's %q produces for a well-behaved scope name.
+			// §5.2 excludes the double quote.
 			name:        "QuotedScopeBecomesApostrophes",
 			description: `"openid": unknown or unsupported scope`,
 			want:        "'openid': unknown or unsupported scope",
 		},
 		{
-			// %q escapes a quote inside the value; the backslash goes with it.
+			// §5.2 excludes the backslash too.
 			name:        "EscapedQuoteLosesItsBackslash",
 			description: `"\"><img>": unknown or unsupported scope`,
 			want:        "''><img>': unknown or unsupported scope",