fix(backend): Handle different GitHub token types in OAuth scope check

[brendan-kellam]

Summary

• Add token type detection for GitHub tokens based on their prefixes (ghp_, gho_, ghu_, ghs_, github_pat_)
• Update getOAuthScopesForAuthenticatedUser to return null for token types that don't support scope introspection
• Skip pre-flight scope validation for GitHub App tokens and fine-grained PATs, relying on runtime error handling instead
• Add improved error handling for 401/403 responses with helpful re-authorization messages

Token Type Support

Token Type	Prefix	Scope Check via x-oauth-scopes
Personal Access Token (classic)	ghp_	✅ Yes
OAuth App user token	gho_	✅ Yes
GitHub App user token	ghu_	❌ No (skip check)
GitHub App installation token	ghs_	❌ No (skip check)
Fine-grained PAT	github_pat_	❌ No (skip check)

Test plan

• Unit tests added for detectGitHubTokenType and supportsOAuthScopeIntrospection
• Test with OAuth app token (gho_) - should validate scopes via header

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Fixed account permission syncing failures when authenticating with GitHub App user tokens.
  • Improved error handling for insufficient repository access permissions with clearer re-authentication guidance.

• New Features

  • Enhanced error messages to guide users on re-authorizing with GitHub when required permissions are lacking.

[coderabbitai]

Walkthrough

The PR adds GitHub token-type detection and conditional scope introspection to address permission syncing failures with app user tokens. It introduces token classification utilities, modifies scope retrieval to support optional introspection, adds repository listing capabilities, and implements error handling for missing permissions with re-authorization guidance.

Changes

Cohort / File(s)	Summary
GitHub Token Infrastructure packages/backend/src/github.ts	Added GitHubTokenType union with token prefixes, detection logic via detectGitHubTokenType(), scope introspection support via supportsOAuthScopeIntrospection(), and SCOPE_INTROSPECTABLE_TOKEN_TYPES constant. Modified getOAuthScopesForAuthenticatedUser() to accept optional token and return null for non-introspectable tokens. Added getReposForAuthenticatedUser() for authenticated user repository listing.
Permission Syncer Error Handling packages/backend/src/ee/accountPermissionSyncer.ts	Integrated token-type aware scope introspection into GitHub authentication flow. Added scope validation with error messaging advising re-authorization. Wrapped repository listing in try/catch to handle 401/403 errors with user-facing re-authentication guidance.
Test Coverage packages/backend/src/github.test.ts	Added comprehensive test suites for detectGitHubTokenType() covering multiple token-type scenarios and supportsOAuthScopeIntrospection() with boolean expectations.
Changelog CHANGELOG.md	Documented fix for account-driven permission syncing failure when authenticating with GitHub App user token.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• chore(worker): Refactor permission syncing join table to be between Account <> Repo #600 — Modifies the same accountPermissionSyncer.ts permission-sync logic with related user-to-account data model refactoring.

Suggested labels

sourcebot-team

Suggested reviewers

• msukkari

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the primary change: handling different GitHub token types in OAuth scope checks, which aligns with the main objective of the PR to detect token types and conditionally perform scope introspection.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bkellam/fix-SOU-365

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[claude]

---

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

---

[claude]

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

[coderabbitai]

Actionable comments posted: 1

🤖 Fix all issues with AI agents

In `@CHANGELOG.md`:
- Line 13: Update the CHANGELOG entry line that reads "account driven permission
syncing" to use the hyphenated adjective "account-driven permission syncing";
locate the exact string in the CHANGELOG.md entry (the line beginning "- [EE]
Fixed issue where account driven permission syncing...") and replace "account
driven" with "account-driven".

🧹 Nitpick comments (1)

packages/backend/src/ee/accountPermissionSyncer.ts (1)

194-208: Consider extracting the HTTP error check into a shared utility.

The error status checking pattern here duplicates logic from isHttpError in github.ts (lines 80-85). Consider exporting that helper function and reusing it here for consistency.

♻️ Optional refactor

In packages/backend/src/github.ts, export the helper:

-const isHttpError = (error: unknown, status: number): boolean => {
+export const isHttpError = (error: unknown, status: number): boolean => {

Then in this file:

 import {
     createOctokitFromToken,
     getOAuthScopesForAuthenticatedUser as getGitHubOAuthScopesForAuthenticatedUser,
     getReposForAuthenticatedUser,
+    isHttpError,
 } from "../github.js";

                 } catch (error) {
-                    if (error && typeof error === 'object' && 'status' in error) {
-                        const status = (error as { status: number }).status;
-                        if (status === 401 || status === 403) {
-                            throw new Error(
-                                `GitHub API returned ${status} error. Your token may have expired or lacks the required permissions. ` +
-                                `Please re-authorize with GitHub to grant the necessary access.`
-                            );
-                        }
+                    if (isHttpError(error, 401) || isHttpError(error, 403)) {
+                        const status = (error as { status: number }).status;
+                        throw new Error(
+                            `GitHub API returned ${status} error. Your token may have expired or lacks the required permissions. ` +
+                            `Please re-authorize with GitHub to grant the necessary access.`
+                        );
                     }
                     throw error;
                 }