feat: Add GitHub App authentication support

.github/workflows/run-tests.yml

@@ -12,7 +12,7 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-    timeout-minutes: 5
+    timeout-minutes: 8
     strategy:
       fail-fast: false
       matrix:
@@ -45,6 +45,17 @@ jobs:
           tools: composer:v2
           coverage: none
 
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache composer dependencies
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-php-${{ matrix.php }}-laravel-${{ matrix.laravel }}-composer-${{ hashFiles('**/composer.json') }}
+          restore-keys: ${{ runner.os }}-php-${{ matrix.php }}-laravel-${{ matrix.laravel }}-composer-
+
       - name: Install dependencies
         run: |
           composer remove --dev --no-update larastan/larastan phpstan/phpstan-deprecation-rules phpstan/phpstan-phpunit phpstan/extension-installer

config/github-client.php

@@ -65,6 +65,29 @@
         ],
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | GitHub App Configuration
+    |--------------------------------------------------------------------------
+    |
+    | Configuration for GitHub App authentication. GitHub Apps provide
+    | enhanced security and granular permissions compared to OAuth apps.
+    */
+    'github_app' => [
+        // App ID from your GitHub App settings
+        'app_id' => env('GITHUB_APP_ID'),
+
+        // Installation ID (optional, can be set per request)
+        'installation_id' => env('GITHUB_APP_INSTALLATION_ID'),
+
+        // Private key for signing JWT tokens
+        // Can be the key contents directly or a path to the key file
+        'private_key' => env('GITHUB_APP_PRIVATE_KEY'),
+
+        // Path to private key file (alternative to direct key)
+        'private_key_path' => env('GITHUB_APP_PRIVATE_KEY_PATH'),
+    ],
+
     /*
     |--------------------------------------------------------------------------
     | Rate Limiting

src/Auth/GitHubAppAuthentication.php

@@ -16,6 +16,8 @@ class GitHubAppAuthentication implements AuthenticationStrategy
 
     private ?DateTimeImmutable $installationTokenExpiry = null;
 
+    private ?object $connector = null;
+
     public function __construct(
         private readonly string $appId,
         private readonly string $privateKey,
@@ -107,18 +109,65 @@ private function hasValidInstallationToken(): bool
 
     /**
      * Refresh the installation token.
+     *
+     * Note: This method requires the connector to be set via setConnector()
+     * before calling refresh(). The connector is typically injected when
+     * used with GithubConnector.
      */
     private function refreshInstallationToken(): void
     {
         if (! $this->installationId) {
             throw AuthenticationException::githubAppAuthFailed('Installation ID required for installation token');
         }
 
-        // This would typically make an API call to GitHub to get an installation token
-        // For now, we'll throw an exception indicating this needs to be implemented
-        throw AuthenticationException::githubAppAuthFailed(
-            'Installation token refresh not yet implemented. Use GitHub client to fetch installation tokens.',
+        // Import the required classes
+        $createTokenRequest = new \JordanPartridge\GithubClient\Requests\Installations\CreateAccessToken(
+            (int) $this->installationId,
         );
+
+        // Make the API call to get the installation token
+        // This will use JWT authentication (app-level) to get the installation token
+        try {
+            $response = $this->makeApiRequest($createTokenRequest);
+
+            if (! $response->successful()) {
+                throw AuthenticationException::githubAppAuthFailed(
+                    'Failed to refresh installation token: ' . ($response->json('message') ?? 'Unknown error'),
+                );
+            }
+
+            $data = $response->json();
+            $this->installationToken = $data['token'];
+            $this->installationTokenExpiry = new DateTimeImmutable($data['expires_at']);
+        } catch (\Exception $e) {
+            throw AuthenticationException::githubAppAuthFailed(
+                'Failed to refresh installation token: ' . $e->getMessage(),
+            );
+        }
+    }
+
+    /**
+     * Make an API request (to be implemented by connector integration).
+     *
+     * @throws AuthenticationException
+     */
+    private function makeApiRequest(object $request): mixed
+    {
+        if (! isset($this->connector)) {
+            throw AuthenticationException::githubAppAuthFailed(
+                'Connector not set. Cannot refresh installation token without connector.',
+            );
+        }
+
+        return $this->connector->send($request);
+    }
+
+    /**
+     * Set the connector for making API requests.
+     */
+    public function setConnector(object $connector): void
+    {
+        $this->connector = $connector;
     }
 
     /**

src/Auth/TokenResolver.php

@@ -22,27 +22,27 @@ class TokenResolver
      */
     public static function resolve(): ?string
     {
-        // 1. Check GitHub CLI first (if available)
-        if ($token = self::getGitHubCliToken()) {
-            self::$lastSource = 'GitHub CLI';
-
-            return $token;
-        }
-
-        // 2. Check environment variables
+        // 1. Check environment variables first (fast, no external process)
         if ($token = self::getEnvironmentToken()) {
             self::$lastSource = env('GITHUB_TOKEN') ? 'GITHUB_TOKEN' : 'GH_TOKEN';
 
             return $token;
         }
 
-        // 3. Check Laravel config
+        // 2. Check Laravel config
         if ($token = self::getConfigToken()) {
             self::$lastSource = 'config';
 
             return $token;
         }
 
+        // 3. Check GitHub CLI last (slower, spawns external process)
+        if ($token = self::getGitHubCliToken()) {
+            self::$lastSource = 'GitHub CLI';
+
+            return $token;
+        }
+
         // 4. Return null - authentication is optional for public repos
         self::$lastSource = null;
 
@@ -55,22 +55,22 @@ public static function resolve(): ?string
     private static function getGitHubCliToken(): ?string
     {
         try {
-            // Check if gh CLI is available
-            $result = Process::run('which gh');
+            // Check if gh CLI is available (with timeout to prevent hanging in CI)
+            $result = Process::timeout(2)->run('which gh');
             if (! $result->successful()) {
                 return null;
             }
 
-            // Get token from gh CLI
-            $result = Process::run('gh auth token');
+            // Get token from gh CLI (with timeout to prevent hanging if not authenticated)
+            $result = Process::timeout(3)->run('gh auth token');
             if ($result->successful()) {
                 $token = trim($result->output());
                 if (! empty($token)) {
                     return $token;
                 }
             }
         } catch (\Exception) {
-            // gh CLI not available or not authenticated
+            // gh CLI not available, not authenticated, or timed out
         }
 
         return null;
@@ -124,10 +124,7 @@ public static function hasAuthentication(): bool
      */
     public static function getAuthenticationStatus(): string
     {
-        if ($token = self::getGitHubCliToken()) {
-            return 'Authenticated via GitHub CLI';
-        }
-
+        // Check in same order as resolve() for consistency
         if ($token = self::getEnvironmentToken()) {
             $source = env('GITHUB_TOKEN') ? 'GITHUB_TOKEN' : 'GH_TOKEN';
 
@@ -138,6 +135,10 @@ public static function getAuthenticationStatus(): string
             return 'Authenticated via config file';
         }
 
+        if ($token = self::getGitHubCliToken()) {
+            return 'Authenticated via GitHub CLI';
+        }
+
         return 'No authentication (public access only)';
     }
 

src/Connectors/GithubConnector.php

@@ -2,6 +2,8 @@
 
 namespace JordanPartridge\GithubClient\Connectors;
 
+use JordanPartridge\GithubClient\Auth\AuthenticationStrategy;
+use JordanPartridge\GithubClient\Auth\GitHubAppAuthentication;
 use JordanPartridge\GithubClient\Auth\TokenResolver;
 use JordanPartridge\GithubClient\Exceptions\ApiException;
 use JordanPartridge\GithubClient\Exceptions\AuthenticationException;
@@ -30,15 +32,25 @@ class GithubConnector extends Connector
 
     protected ?string $token;
     protected ?string $tokenSource;
+    protected ?AuthenticationStrategy $authStrategy = null;
 
     /**
      * Create a new GitHub connector.
      *
-     * @param  string|null  $token  Optional GitHub token. If null, will attempt to resolve from multiple sources.
+     * @param  string|AuthenticationStrategy|null  $token  Token, auth strategy, or null to auto-resolve
      */
-    public function __construct(?string $token = null)
+    public function __construct(string|AuthenticationStrategy|null $token = null)
     {
-        if ($token !== null) {
+        if ($token instanceof AuthenticationStrategy) {
+            $this->authStrategy = $token;
+            $this->token = null;
+            $this->tokenSource = $token->getType();
+
+            // Inject connector into auth strategy if it's a GitHub App
+            if ($token instanceof GitHubAppAuthentication) {
+                $token->setConnector($this);
+            }
+        } elseif ($token !== null) {
             $this->token = $token;
             $this->tokenSource = 'explicit';
         } else {
@@ -73,7 +85,24 @@ protected function defaultHeaders(): array
      */
     protected function defaultAuth(): ?Authenticator
     {
-        if (! $this->token || $this->token === '') {
+        // Use auth strategy if set
+        if ($this->authStrategy) {
+            // Check if token needs refresh
+            if ($this->authStrategy->needsRefresh()) {
+                $this->authStrategy->refresh();
+            }
+
+            // Get the authorization header value
+            $authHeader = $this->authStrategy->getAuthorizationHeader();
+
+            // Extract token from "Bearer <token>" format
+            $token = str_replace('Bearer ', '', $authHeader);
+
+            return new TokenAuthenticator($token);
+        }
+
+        // Fall back to simple token authentication
+        if (! $this->token) {
             return null;
         }
 
@@ -85,7 +114,7 @@ protected function defaultAuth(): ?Authenticator
      */
     public function isAuthenticated(): bool
     {
-        return ! empty($this->token);
+        return $this->authStrategy !== null || ! empty($this->token);
     }
 
     /**
@@ -145,7 +174,7 @@ public function getRequestException(Response $response, ?\Throwable $senderExcep
             429 => $this->handleRateLimitError($response, $message),
             500, 502, 503, 504 => new NetworkException(
                 operation: 'GitHub API request',
-                reason: "Server error ({$status}): {$message}",
+                message: "Server error ({$status}): {$message}",
                 previous: $senderException,
             ),
             default => new ApiException(

src/Data/Installations/InstallationData.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace JordanPartridge\GithubClient\Data\Installations;
+
+use Carbon\Carbon;
+
+class InstallationData
+{
+    public function __construct(
+        public int $id,
+        public string $account_login,
+        public string $account_type,
+        public ?string $target_type = null,
+        public ?array $permissions = null,
+        public ?array $events = null,
+        public ?Carbon $created_at = null,
+        public ?Carbon $updated_at = null,
+        public ?string $app_slug = null,
+    ) {}
+
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            id: $data['id'],
+            account_login: $data['account']['login'] ?? '',
+            account_type: $data['account']['type'] ?? '',
+            target_type: $data['target_type'] ?? null,
+            permissions: $data['permissions'] ?? null,
+            events: $data['events'] ?? null,
+            created_at: isset($data['created_at']) ? Carbon::parse($data['created_at']) : null,
+            updated_at: isset($data['updated_at']) ? Carbon::parse($data['updated_at']) : null,
+            app_slug: $data['app_slug'] ?? null,
+        );
+    }
+
+    public function toArray(): array
+    {
+        return array_filter([
+            'id' => $this->id,
+            'account_login' => $this->account_login,
+            'account_type' => $this->account_type,
+            'target_type' => $this->target_type,
+            'permissions' => $this->permissions,
+            'events' => $this->events,
+            'created_at' => $this->created_at?->toISOString(),
+            'updated_at' => $this->updated_at?->toISOString(),
+            'app_slug' => $this->app_slug,
+        ], fn ($value) => $value !== null);
+    }
+}