lex-github 0.3.2 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ea69decf68b91f650186b1719a7e29646ce4f7308bd2d90eebeadcd6048718d
-  data.tar.gz: 3bdf52e0d20f137e7efb2f7c7330905de6b924d184edb4007c616435d679f44a
+  metadata.gz: 61ef9dc50273e5c0700962c3864a8d3ae24276621ed29215d35551f52fb4573d
+  data.tar.gz: b5a4de4b921f743c86320e2c95c99c2773ebcf56b02df788cf2a62323929ae87
 SHA512:
-  metadata.gz: 2cc5f719ed57a84ebc740a0009a0836fecfcfaa162794e64806e9770dc653e2368ac37d44ef3655d29bd132ed1957148be691dd4544fadb05e969250949144ce
-  data.tar.gz: 9bccdb81c9b7f52348c623b19473db41bc36f3d5539680789eceb7d50997136abafe3d42dcccb3010dacb57db8fb7c53998b1ea0374adfedab54e0414b7364af
+  metadata.gz: c06065ce5d893b0a4008c7195155669985c3e44cb4b4eb8817c74e2faa99912fdbadb0a8b74fb49be445e95696293e750f0f945ab05576b08cc5d02ebaa645a9
+  data.tar.gz: f3d6915a975c4b35c669b3cf0aaf0d9e443a6333136e019df460638574a7f58362904560cc6c366093a4c797ee2518d2c62f742fd9e2a339a5c194bd06c4b11d

data/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-04-06
+
+### Added
+- `resolve_broker_app` to `CREDENTIAL_RESOLVERS` for Broker integration (Phase 8 Wave 3)
+- Stable `installation_id` fingerprint for consistent credential caching across GitHub App installations
+
+## [0.3.3] - 2026-03-31
+
+### Fixed
+- CLI runner output: `status` and `login` commands now print JSON results to stdout
+- CLI runner errors print to stderr via `warn`
+
 ## [0.3.2] - 2026-03-31
 
 ### Added

data/CLAUDE.md

@@ -6,11 +6,11 @@
 
 ## Purpose
 
-Legion Extension that connects LegionIO to GitHub. Provides runners for interacting with the GitHub REST API covering repositories, issues, pull requests, users, organizations, gists, search, labels, comments, commits, branches, file contents, GitHub App authentication, OAuth delegated auth, and webhook handling.
+Legion Extension that connects LegionIO to GitHub. Provides runners for interacting with the GitHub REST API covering repositories, issues, pull requests, users, organizations, gists, search, labels, comments, commits, branches, file contents, Actions workflows, checks, releases, deployments, repository webhooks, GitHub App authentication, OAuth delegated auth, and credential storage.
 
 **GitHub**: https://github.com/LegionIO/lex-github
 **License**: MIT
-**Version**: 0.3.0
+**Version**: 0.3.3
 
 ## Architecture
 
@@ -28,21 +28,45 @@ Legion::Extensions::Github
 │   ├── Comments          # CRUD issue/PR comments
 │   ├── Commits           # List, get, compare commits
 │   ├── Branches          # Create branches via Git Data API
-│   └── Contents          # Commit multiple files via Git Data API
+│   ├── Contents          # Commit multiple files via Git Data API
+│   ├── Actions           # Workflows, runs, jobs, artifacts, logs
+│   ├── Checks            # Check runs, check suites, annotations
+│   ├── Releases          # CRUD releases, release assets
+│   ├── Deployments       # CRUD deployments and deployment statuses
+│   ├── RepositoryWebhooks # CRUD repo webhooks, ping, test, deliveries
+│   └── Auth              # Composite runner: delegates to App, CredentialStore, OAuth auth modules
 ├── App/
-│   └── Runners/
-│       ├── Auth          # JWT generation, installation token exchange, list/get installations
-│       ├── Webhooks      # HMAC signature verification, event parsing
-│       ├── Manifest      # GitHub App manifest flow (generate, exchange code, manifest URL)
-│       └── Installations # Full installation management (list repos, suspend, delete)
+│   ├── Runners/
+│   │   ├── Auth          # JWT generation, installation token exchange, list/get installations
+│   │   ├── Webhooks      # HMAC signature verification, event parsing
+│   │   ├── Manifest      # GitHub App manifest flow (generate, exchange code, manifest URL)
+│   │   ├── Installations # Full installation management (list repos, suspend, delete)
+│   │   └── CredentialStore # Store app credentials and OAuth tokens in Vault
+│   ├── Actors/
+│   │   ├── TokenRefresh  # Periodic App installation token refresh
+│   │   └── WebhookPoller # Polls GitHub webhook deliveries
+│   └── Transport/        # AMQP transport (exchanges/queues/messages)
 ├── OAuth/
-│   └── Runners/
-│       └── Auth          # PKCE + Authorization Code, device code, refresh, revoke
+│   ├── Runners/
+│   │   └── Auth          # PKCE + Authorization Code, device code, refresh, revoke
+│   ├── Actors/
+│   │   └── TokenRefresh  # Periodic OAuth delegated token refresh
+│   └── Transport/        # AMQP transport (exchanges/queues)
+├── Middleware/
+│   ├── RateLimit         # Tracks rate-limit headers, skips exhausted credentials
+│   ├── ScopeProbe        # Detects scope-denied 403s for specific owner/repo
+│   └── CredentialFallback # Triggers fallback to next credential source on auth failure
 ├── Helpers/
 │   ├── Client            # 8-source scope-aware credential resolution chain + Faraday builder
 │   ├── Cache             # Two-tier read-through/write-through API response caching
 │   ├── TokenCache        # Token lifecycle management (store, fetch, expiry, rate limits)
-│   └── ScopeRegistry     # Credential-to-scope authorization cache (org/repo level)
+│   ├── ScopeRegistry     # Credential-to-scope authorization cache (org/repo level)
+│   ├── BrowserAuth       # Delegated OAuth orchestrator (PKCE, headless detection, browser launch)
+│   └── CallbackServer    # Ephemeral TCP server for OAuth redirect callback
+├── CLI/
+│   ├── Auth              # `legion lex exec github auth login/status`
+│   ├── App               # `legion lex exec github app setup/complete_setup`
+│   └── Runner            # CLI dispatch registration
 └── Client                # Standalone client class (includes all runners)
 ```
 
@@ -63,12 +87,16 @@ Rate-limited credentials are skipped. Scope-denied credentials (for a given owne
 
 | Gem | Purpose |
 |-----|---------|
-| `faraday` | HTTP client for GitHub REST API |
-| `jwt` (~> 2.7) | RS256 JWT generation for GitHub App authentication |
+| `faraday` (>= 2.0) | HTTP client for GitHub REST API |
+| `jwt` (>= 2.7) | RS256 JWT generation for GitHub App authentication |
 | `base64` (>= 0.1) | PKCE code challenge computation |
-| `legion-cache` | Two-tier caching (global Redis + local in-memory) |
-| `legion-crypt` | Vault secret resolution for credentials |
-| `legion-settings` | Settings-based credential resolution |
+| `legion-cache` (>= 1.3.11) | Two-tier caching (global Redis + local in-memory) |
+| `legion-crypt` (>= 1.4.9) | Vault secret resolution for credentials |
+| `legion-data` (>= 1.4.17) | Data persistence |
+| `legion-json` (>= 1.2.1) | JSON serialization |
+| `legion-logging` (>= 1.3.2) | Logging |
+| `legion-settings` (>= 1.3.14) | Settings-based credential resolution |
+| `legion-transport` (>= 1.3.9) | AMQP transport for actors |
 
 ## Key Files
 
@@ -80,15 +108,20 @@ Rate-limited credentials are skipped. Scope-denied credentials (for a given owne
 | `lib/legion/extensions/github/helpers/cache.rb` | Two-tier API response caching |
 | `lib/legion/extensions/github/helpers/token_cache.rb` | Token lifecycle + rate limit tracking |
 | `lib/legion/extensions/github/helpers/scope_registry.rb` | Credential-to-scope authorization cache |
+| `lib/legion/extensions/github/helpers/browser_auth.rb` | OAuth PKCE browser launch + headless detection |
+| `lib/legion/extensions/github/helpers/callback_server.rb` | Ephemeral TCP server for OAuth redirect |
 | `lib/legion/extensions/github/app/runners/auth.rb` | JWT generation, installation tokens |
 | `lib/legion/extensions/github/app/runners/webhooks.rb` | Webhook signature verification, event parsing |
 | `lib/legion/extensions/github/app/runners/manifest.rb` | GitHub App manifest registration flow |
 | `lib/legion/extensions/github/app/runners/installations.rb` | Installation management |
+| `lib/legion/extensions/github/app/runners/credential_store.rb` | Store app/OAuth credentials in Vault |
 | `lib/legion/extensions/github/oauth/runners/auth.rb` | OAuth PKCE, device code, token refresh/revoke |
+| `lib/legion/extensions/github/runners/auth.rb` | Composite auth runner (delegates to app + oauth + credential_store) |
+| `lib/lex/github.rb` | Redirect shim for `require 'lex/github'` |
 
 ## Testing
 
-131 specs across 23 spec files (growing with each new runner).
+234 specs across 38 spec files.
 
 ```bash
 bundle install

data/lib/legion/extensions/github/cli/auth.rb

@@ -15,9 +15,9 @@ module Legion
             csec = client_secret || settings_client_secret
             sc = scopes || settings_scopes
 
-            unless cid && csec
+            unless cid
               return { error:       'missing_config',
-                       description: 'Set github.oauth.client_id or github.app.client_id and github.app.client_secret in settings or pass as arguments' }
+                       description: 'Set github.oauth.client_id or github.app.client_id in settings' }
             end
 
             browser = Helpers::BrowserAuth.new(client_id: cid, client_secret: csec, scopes: sc)

data/lib/legion/extensions/github/cli/runner.rb

@@ -1,90 +1,101 @@
 # frozen_string_literal: true
 
-require 'legion/extensions/github/cli/auth'
-require 'legion/extensions/github/cli/app'
-require 'legion/extensions/github/app/runners/credential_store'
+require 'json'
+require 'net/http'
+require 'uri'
+require 'rbconfig'
 
 module Legion
   module Extensions
     module Github
       module CLI
-        class AuthRunner
-          include Legion::Logging::Helper if defined?(Legion::Logging::Helper)
-          include Github::CLI::Auth
-          include Github::App::Runners::CredentialStore
-
-          def credential_fingerprint(auth_type:, identifier:)
-            "#{auth_type}:#{identifier}"
-          end
+        DAEMON_URL = ENV.fetch('LEGION_API_URL', 'http://127.0.0.1:4567')
 
-          def vault_get(path)
-            return nil unless defined?(Legion::Crypt)
+        module DaemonApi
+          private
 
-            ::Legion::Crypt.get(path)
-          rescue StandardError => e
-            log.warn("[lex-github] vault_get failed: #{e.message}")
-            nil
+          def api_post(path, body = {})
+            uri = URI("#{DAEMON_URL}#{path}")
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.open_timeout = 5
+            http.read_timeout = 30
+            request = Net::HTTP::Post.new(uri.path, 'Content-Type' => 'application/json')
+            request.body = ::JSON.generate(body)
+            parse_response(http.request(request))
+          rescue Errno::ECONNREFUSED, Errno::ECONNRESET => _e
+            { error: 'daemon_unavailable', description: "Legion daemon not running at #{DAEMON_URL}. Start it with: legionio start" }
           end
 
-          def cache_connected?
-            defined?(Legion::Cache) && ::Legion::Cache.connected?
-          rescue StandardError => e
-            log.debug("[lex-github] cache_connected? check failed: #{e.message}")
-            false
+          def api_get(path)
+            uri = URI("#{DAEMON_URL}#{path}")
+            parse_response(Net::HTTP.get_response(uri))
+          rescue Errno::ECONNREFUSED, Errno::ECONNRESET => _e
+            { error: 'daemon_unavailable', description: "Legion daemon not running at #{DAEMON_URL}. Start it with: legionio start" }
           end
 
-          def local_cache_connected?
-            defined?(Legion::Cache::Local) && ::Legion::Cache::Local.connected?
-          rescue StandardError => e
-            log.debug("[lex-github] local_cache_connected? check failed: #{e.message}")
-            false
+          def parse_response(response)
+            ::JSON.parse(response.body, symbolize_names: true)
+          rescue ::JSON::ParserError => _e
+            { error: "http_#{response.code}", description: response.body&.strip }
           end
 
-          def cache_get(key)
-            ::Legion::Cache.get(key)
-          rescue StandardError => e
-            log.debug("[lex-github] cache_get failed: #{e.message}")
-            nil
+          def print_json(result)
+            if result.is_a?(Hash) && result[:error]
+              warn "Error: #{result[:error]}"
+              warn "  #{result[:description]}" if result[:description]
+            else
+              puts ::JSON.pretty_generate(result)
+            end
           end
 
-          def local_cache_get(key)
-            ::Legion::Cache::Local.get(key)
-          rescue StandardError => e
-            log.debug("[lex-github] local_cache_get failed: #{e.message}")
-            nil
+          def open_browser(url)
+            cmd = case RbConfig::CONFIG['host_os']
+                  when /darwin/      then 'open'
+                  when /linux/       then 'xdg-open'
+                  when /mswin|mingw/ then 'start'
+                  end
+            system(cmd, url) if cmd
           end
+        end
 
-          def cache_set(key, value, ttl: 300)
-            ::Legion::Cache.set(key, value, ttl)
-          rescue StandardError => e
-            log.debug("[lex-github] cache_set failed: #{e.message}")
-            nil
+        class AuthRunner
+          include DaemonApi
+
+          def status
+            print_json(api_post('/api/extensions/github/runners/auth/status'))
           end
 
-          def local_cache_set(key, value, ttl: 300)
-            ::Legion::Cache::Local.set(key, value, ttl)
-          rescue StandardError => e
-            log.debug("[lex-github] local_cache_set failed: #{e.message}")
-            nil
+          def login
+            print_json(api_post('/api/extensions/github/runners/auth/login'))
           end
         end
 
         class AppRunner
-          include Legion::Logging::Helper if defined?(Legion::Logging::Helper)
-          include Github::CLI::App
-          include Github::App::Runners::CredentialStore
+          include DaemonApi
 
-          def credential_fingerprint(auth_type:, identifier:)
-            "#{auth_type}:#{identifier}"
-          end
+          def setup
+            result = api_post('/api/extensions/github/cli/app/setup')
 
-          def vault_get(path)
-            return nil unless defined?(Legion::Crypt)
+            if result[:error]
+              print_json(result)
+              return
+            end
+
+            url = result.dig(:data, :manifest_url)
+            if url
+              warn 'Opening browser to create GitHub App...'
+              open_browser(url)
+              warn 'Waiting for callback...'
+              poll = api_post('/api/extensions/github/cli/app/await_callback',
+                              { timeout: 300 })
+              print_json(poll)
+            else
+              print_json(result)
+            end
+          end
 
-            ::Legion::Crypt.get(path)
-          rescue StandardError => e
-            log.warn("[lex-github] vault_get failed: #{e.message}")
-            nil
+          def complete_setup
+            print_json(api_post('/api/extensions/github/cli/app/complete_setup'))
           end
         end
       end

data/lib/legion/extensions/github/helpers/browser_auth.rb

@@ -14,7 +14,7 @@ module Legion
 
           attr_reader :client_id, :client_secret, :scopes
 
-          def initialize(client_id:, client_secret:, scopes: DEFAULT_SCOPES, auth: nil, **)
+          def initialize(client_id:, client_secret: nil, scopes: DEFAULT_SCOPES, auth: nil, **)
             @client_id = client_id
             @client_secret = client_secret
             @scopes = scopes

data/lib/legion/extensions/github/helpers/client.rb

@@ -15,6 +15,7 @@ module Legion
 
           CREDENTIAL_RESOLVERS = %i[
             resolve_vault_delegated resolve_settings_delegated
+            resolve_broker_app
             resolve_vault_app resolve_settings_app
             resolve_vault_pat resolve_settings_pat
             resolve_gh_cli resolve_env
@@ -139,6 +140,23 @@ module Legion
             nil
           end
 
+          def resolve_broker_app
+            return nil unless defined?(Legion::Identity::Broker)
+
+            token = Legion::Identity::Broker.token_for(:github)
+            return nil unless token
+
+            lease = Legion::Identity::Broker.lease_for(:github)
+            installation_id = lease&.metadata&.dig(:installation_id) || 'unknown'
+            fp = credential_fingerprint(auth_type:  :app_installation,
+                                        identifier: "broker_app_#{installation_id}")
+            { token: token, auth_type: :app_installation,
+              metadata: { source: :broker, credential_type: :installation_token,
+                          credential_fingerprint: fp } }
+          rescue StandardError => _e
+            nil
+          end
+
           def resolve_vault_app
             return nil unless defined?(Legion::Crypt)
 

data/lib/legion/extensions/github/oauth/runners/auth.rb

@@ -33,21 +33,19 @@ module Legion
               { result: "https://github.com/login/oauth/authorize?#{params}" }
             end
 
-            def exchange_code(client_id:, client_secret:, code:, redirect_uri:, code_verifier:, **)
-              response = oauth_connection.post('/login/oauth/access_token', {
-                                                 client_id: client_id, client_secret: client_secret,
-                                                code: code, redirect_uri: redirect_uri,
-                                                code_verifier: code_verifier
-                                               })
+            def exchange_code(client_id:, code:, redirect_uri:, code_verifier:, client_secret: nil, **)
+              body = { client_id: client_id, code: code,
+                       redirect_uri: redirect_uri, code_verifier: code_verifier }
+              body[:client_secret] = client_secret if client_secret
+              response = oauth_connection.post('/login/oauth/access_token', body)
               { result: response.body }
             end
 
-            def refresh_token(client_id:, client_secret:, refresh_token:, **)
-              response = oauth_connection.post('/login/oauth/access_token', {
-                                                 client_id: client_id, client_secret: client_secret,
-                                                refresh_token: refresh_token,
-                                                grant_type: 'refresh_token'
-                                               })
+            def refresh_token(client_id:, refresh_token:, client_secret: nil, **)
+              body = { client_id: client_id, refresh_token: refresh_token,
+                       grant_type: 'refresh_token' }
+              body[:client_secret] = client_secret if client_secret
+              response = oauth_connection.post('/login/oauth/access_token', body)
               { result: response.body }
             end
 

data/lib/legion/extensions/github/runners/auth.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/github/helpers/client'
+require 'legion/extensions/github/helpers/browser_auth'
+require 'legion/extensions/github/app/runners/auth'
+require 'legion/extensions/github/app/runners/credential_store'
+require 'legion/extensions/github/oauth/runners/auth'
+
+module Legion
+  module Extensions
+    module Github
+      module Runners
+        module Auth
+          include Legion::Extensions::Github::Helpers::Client
+          include Legion::Extensions::Github::App::Runners::Auth
+          include Legion::Extensions::Github::App::Runners::CredentialStore
+          include Legion::Extensions::Github::OAuth::Runners::Auth
+
+          def self.remote_invocable?
+            false
+          end
+
+          def status(**)
+            cred = resolve_credential
+            unless cred
+              log.warn('[lex-github] auth status: no credential found across all sources')
+              return { result: { authenticated: false } }
+            end
+
+            log.info("[lex-github] auth status: credential found via #{cred[:auth_type]}")
+
+            user_info = {}
+            scopes = nil
+            begin
+              response = connection(token: cred[:token]).get('/user')
+              user_info = response.body || {}
+              headers = response.respond_to?(:headers) ? response.headers : {}
+              scopes_header = headers['X-OAuth-Scopes'] || headers['x-oauth-scopes']
+              scopes = scopes_header&.split(',')&.map(&:strip)
+              log.info("[lex-github] auth status: authenticated as #{user_info['login']} (#{cred[:auth_type]})")
+            rescue StandardError => e
+              log.warn("[lex-github] auth status: credential found but /user request failed: #{e.message}")
+            end
+
+            { result: { authenticated: true, auth_type: cred[:auth_type],
+                        user: user_info['login'], scopes: scopes } }
+          end
+
+          def login(client_id: nil, scopes: nil, **)
+            cid = client_id || settings_client_id
+            unless cid
+              log.error('[lex-github] auth login: no client_id configured — set github.app.client_id in settings')
+              return { error: 'missing_config', description: 'Set github.app.client_id in settings' }
+            end
+
+            log.info("[lex-github] auth login: starting OAuth flow with client_id=#{cid[0..7]}...")
+
+            sc = scopes || settings_scopes
+            browser = Helpers::BrowserAuth.new(client_id: cid, scopes: sc)
+            result = browser.authenticate
+
+            if result[:error]
+              log.error("[lex-github] auth login failed: #{result[:error]} — #{result[:description]}")
+              return { result: nil, error: result[:error], description: result[:description] }
+            end
+
+            if result[:result]&.dig('access_token')
+              user = begin
+                current_user(token: result[:result]['access_token'])
+              rescue StandardError => e
+                log.warn("[lex-github] auth login: token obtained but /user lookup failed: #{e.message}")
+                'default'
+              end
+
+              log.info("[lex-github] auth login: authenticated as #{user}")
+
+              if respond_to?(:store_oauth_token, true)
+                store_oauth_token(
+                  user:          user,
+                  access_token:  result[:result]['access_token'],
+                  refresh_token: result[:result]['refresh_token'],
+                  expires_in:    result[:result]['expires_in']
+                )
+                log.info("[lex-github] auth login: token stored for user=#{user}")
+              else
+                log.warn('[lex-github] auth login: store_oauth_token not available — token not persisted')
+              end
+            else
+              log.warn('[lex-github] auth login: OAuth completed but no access_token in response')
+            end
+
+            result
+          end
+
+          def installations(**)
+            log.info('[lex-github] listing app installations')
+            list_installations(**)
+          end
+
+          private
+
+          def current_user(token:)
+            connection(token: token).get('/user').body['login']
+          end
+
+          def settings_client_id
+            defined?(Legion::Settings) &&
+              (Legion::Settings.dig(:github, :oauth, :client_id) ||
+               Legion::Settings.dig(:github, :app, :client_id))
+          rescue StandardError => _e
+            nil
+          end
+
+          def settings_scopes
+            defined?(Legion::Settings) && Legion::Settings.dig(:github, :oauth, :scopes)
+          rescue StandardError => _e
+            nil
+          end
+
+          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
+                                                      Legion::Extensions::Helpers.const_defined?(:Lex, false)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/github/version.rb

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Github
-      VERSION = '0.3.2'
+      VERSION = '0.3.4'
     end
   end
 end

data/lib/legion/extensions/github.rb

@@ -35,6 +35,7 @@ require 'legion/extensions/github/runners/actions'
 require 'legion/extensions/github/runners/checks'
 require 'legion/extensions/github/runners/releases'
 require 'legion/extensions/github/runners/deployments'
+require 'legion/extensions/github/runners/auth'
 require 'legion/extensions/github/runners/repository_webhooks'
 require 'legion/extensions/github/client'
 require 'legion/extensions/github/cli/runner'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-github
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.3.4
 platform: ruby
 authors:
 - Esity
@@ -203,6 +203,7 @@ files:
 - lib/legion/extensions/github/oauth/transport/exchanges/oauth.rb
 - lib/legion/extensions/github/oauth/transport/queues/auth.rb
 - lib/legion/extensions/github/runners/actions.rb
+- lib/legion/extensions/github/runners/auth.rb
 - lib/legion/extensions/github/runners/branches.rb
 - lib/legion/extensions/github/runners/checks.rb
 - lib/legion/extensions/github/runners/comments.rb