add GitHub App + OAuth delegated auth, scope-aware credential resolution, and 5 new API runners (v0.3.0)

CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+- GitHub App authentication (JWT generation, installation tokens, manifest flow)
+- OAuth delegated authentication (Authorization Code + PKCE, device code fallback)
+- Scope-aware credential resolution chain (8 sources, rate limit + scope fallback)
+- `ScopeRegistry` for caching credential-to-owner/repo authorization status
+- `CredentialFallback` Faraday middleware (transparent 403/429 retry with next credential)
+- `RateLimit` Faraday middleware with automatic credential exhaustion tracking
+- `ScopeProbe` Faraday middleware for passive scope learning from API responses
+- `Helpers::Cache` for two-tier API response caching (global Redis + local in-memory)
+- `Helpers::TokenCache` for token lifecycle management with per-installation keying
+- `App::Runners::Auth` (JWT generation, installation token exchange)
+- `App::Runners::Webhooks` (signature verification, event parsing, scope invalidation)
+- `App::Runners::Manifest` (GitHub App manifest flow)
+- `App::Runners::Installations` (list, get, suspend, unsuspend, delete)
+- `App::Runners::CredentialStore` (Vault persistence after manifest flow)
+- `OAuth::Runners::Auth` (authorize_url, exchange_code, refresh, device_code, revoke)
+- `Runners::Actions` (GitHub Actions workflow management)
+- `Runners::Checks` (check runs and check suites)
+- `Runners::Releases` (release and asset management)
+- `Runners::Deployments` (deployment and status management)
+- `Runners::RepositoryWebhooks` (programmatic webhook management)
+- `Helpers::CallbackServer` for standalone OAuth redirect handling
+- `Helpers::BrowserAuth` for browser-based OAuth with PKCE
+- `CLI::Auth` for `legion lex exec github auth login/status`
+- `CLI::App` for `legion lex exec github app setup`
+- `RateLimitError`, `AuthorizationError`, `ScopeDeniedError` error classes
+- `jwt` (~> 2.7) and `base64` (>= 0.1) runtime dependencies
+
+### Changed
+- `Helpers::Client` now uses scope-aware credential resolution (`owner:`, `repo:` context)
+- All existing runners forward `owner:` and `repo:` to `connection()` for scope-aware resolution
+- All existing runners now include `Helpers::Cache` for two-tier API response caching
+- `Client` class includes App and OAuth runner modules
+- Version bump to 0.3.0
+
+## [0.3.0] - 2026-03-30
+
+### Added
+- GitHub App authentication (JWT generation, installation tokens via `App::Runners::Auth`)
+- OAuth delegated user authentication (Authorization Code + PKCE, device code flow via `OAuth::Runners::Auth`)
+- GitHub App manifest flow for streamlined app registration (`App::Runners::Manifest`)
+- Webhook signature verification and event parsing (`App::Runners::Webhooks`)
+- 8-source credential resolution chain: Vault delegated → Settings delegated → Vault App → Settings App → Vault PAT → Settings PAT → GH CLI → ENV (`Helpers::Client`)
+- Rate limit fallback across credential sources with scope-aware skipping (`Helpers::ScopeRegistry`)
+- Token lifecycle management with expiry tracking and rate limit recording (`Helpers::TokenCache`)
+- Two-tier API response caching (global Redis + local in-memory) with configurable per-resource TTLs (`Helpers::Cache`)
+- `jwt` (~> 2.7) and `base64` (>= 0.1) runtime dependencies
+
 ## [0.2.5] - 2026-03-30
 
 ### Changed

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, and file contents.
+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.
 
 **GitHub**: https://github.com/LegionIO/lex-github
 **License**: MIT
-**Version**: 0.2.4
+**Version**: 0.3.0
 
 ## Architecture
 
@@ -29,40 +29,66 @@ Legion::Extensions::Github
 │   ├── Commits           # List, get, compare commits
 │   ├── Branches          # Create branches via Git Data API
 │   └── Contents          # Commit multiple files via Git Data API
+├── 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)
+├── OAuth/
+│   └── Runners/
+│       └── Auth          # PKCE + Authorization Code, device code, refresh, revoke
 ├── Helpers/
-│   └── Client            # Faraday connection builder (GitHub API v3)
+│   ├── 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)
 └── Client                # Standalone client class (includes all runners)
 ```
 
+### Credential Resolution Chain (8 sources, in priority order)
+
+1. `resolve_vault_delegated` — OAuth user token from Vault (`github/oauth/delegated/token`)
+2. `resolve_settings_delegated` — OAuth user token from `Legion::Settings[:github][:oauth][:access_token]`
+3. `resolve_vault_app` — GitHub App installation token (requires cached token from `TokenCache`)
+4. `resolve_settings_app` — App token from settings (requires cached token)
+5. `resolve_vault_pat` — PAT from Vault (`github/token`)
+6. `resolve_settings_pat` — PAT from `Legion::Settings[:github][:token]`
+7. `resolve_gh_cli` — Token from `gh auth token` CLI command (cached 300s)
+8. `resolve_env` — `GITHUB_TOKEN` environment variable
+
+Rate-limited credentials are skipped. Scope-denied credentials (for a given owner/repo) are skipped.
+
 ## Dependencies
 
 | Gem | Purpose |
 |-----|---------|
 | `faraday` | 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 |
 
 ## Key Files
 
 | File | Purpose |
 |------|---------|
-| `lib/legion/extensions/github.rb` | Extension entry point, requires all runners |
-| `lib/legion/extensions/github/client.rb` | Standalone client class |
-| `lib/legion/extensions/github/helpers/client.rb` | Faraday connection builder |
-| `lib/legion/extensions/github/runners/repositories.rb` | Repo CRUD, branches, tags |
-| `lib/legion/extensions/github/runners/issues.rb` | Issue CRUD |
-| `lib/legion/extensions/github/runners/pull_requests.rb` | PR CRUD, merge, files, reviews |
-| `lib/legion/extensions/github/runners/users.rb` | User lookup, followers/following |
-| `lib/legion/extensions/github/runners/organizations.rb` | Org info, repos, members |
-| `lib/legion/extensions/github/runners/gists.rb` | Gist CRUD |
-| `lib/legion/extensions/github/runners/search.rb` | Search repos/issues/users/code |
-| `lib/legion/extensions/github/runners/labels.rb` | Label CRUD, add/remove on issues |
-| `lib/legion/extensions/github/runners/comments.rb` | Issue/PR comment CRUD |
-| `lib/legion/extensions/github/runners/commits.rb` | List, get, compare commits |
-| `lib/legion/extensions/github/runners/branches.rb` | Create branches via Git Data API |
-| `lib/legion/extensions/github/runners/contents.rb` | Commit multiple files via Git Data API |
+| `lib/legion/extensions/github.rb` | Extension entry point, requires all modules |
+| `lib/legion/extensions/github/client.rb` | Standalone client class (includes all runners) |
+| `lib/legion/extensions/github/helpers/client.rb` | Credential resolution chain + Faraday builder |
+| `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/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/oauth/runners/auth.rb` | OAuth PKCE, device code, token refresh/revoke |
 
 ## Testing
 
-57 specs across 14 spec files.
+131 specs across 23 spec files (growing with each new runner).
 
 ```bash
 bundle install