If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ruby-oauth/oauth2 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2w ago
• 5 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ruby-oauth/oauth2 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ruby-oauth/oauth2.

What it runs against: a local clone of ruby-oauth/oauth2 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ruby-oauth/oauth2 | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 43 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ruby-oauth/oauth2. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ruby-oauth/oauth2.git
#   cd oauth2
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ruby-oauth/oauth2 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ruby-oauth/oauth2(\\.git)?\\b" \\
  && ok "origin remote is ruby-oauth/oauth2" \\
  || miss "origin remote is not ruby-oauth/oauth2 (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/oauth2.rb" \\
  && ok "lib/oauth2.rb" \\
  || miss "missing critical file: lib/oauth2.rb"
test -f "lib/oauth2/client.rb" \\
  && ok "lib/oauth2/client.rb" \\
  || miss "missing critical file: lib/oauth2/client.rb"
test -f "lib/oauth2/access_token.rb" \\
  && ok "lib/oauth2/access_token.rb" \\
  || miss "missing critical file: lib/oauth2/access_token.rb"
test -f "lib/oauth2/strategy/base.rb" \\
  && ok "lib/oauth2/strategy/base.rb" \\
  || miss "missing critical file: lib/oauth2/strategy/base.rb"
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 43 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~13d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ruby-oauth/oauth2"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ruby-oauth2 is a Ruby wrapper gem implementing OAuth 2.0 and OAuth 2.1 authorization frameworks, plus OpenID Connect (OIDC) support, enabling Ruby applications to build OAuth 2.0 clients (not servers) that authenticate and authorize users via third-party providers. It abstracts the complexity of OAuth flows, token management, and OIDC identity verification into a clean Ruby API. Monolithic gem structure (lib/oauth2/ contains core implementation) with modular concerns: lib/oauth2/client.rb for client logic, lib/oauth2/token.rb for token lifecycle, lib/oauth2/access_token.rb for bearer tokens. Heavy use of GitHub Actions workflows (.github/workflows/) for multi-Ruby testing, dependency management (unlocked/locked/heads variants), and security scanning (CodeQL, license-eye).

Ruby developers building web applications that need to integrate OAuth 2.0 login with third-party providers (Google, GitHub, Facebook, etc.), or applications requiring OpenID Connect identity verification. Maintainers of Ruby web frameworks and libraries that depend on OAuth 2.0 functionality.

Highly mature and production-ready: the repo has extensive test coverage (CI badges for coverage via CodeCov, Coveralls, QLTY), runs against Ruby 2.7 through 3.x plus JRuby with dedicated workflows (.github/workflows/), and maintains backward compatibility across OAuth 2.0/2.1/OIDC specs. Active maintenance with support for modern OAuth specs and security best practices.

Low risk for core functionality but moderate dependency surface: the gem wraps HTTP libraries and requires Ruby 2.7+ (constraining for legacy apps). Single maintainer model evident from OpenCollective funding plea in README suggests sustainability questions, though test coverage and CI rigor mitigate execution risk. Monitor deprecation warnings in dependencies (see .github/workflows/dep-heads.yml for dependency headtrack testing).

Active maintenance with recent security and compatibility updates: .github/workflows/ shows parallel CI for ancient/legacy/supported/unsupported/heads Ruby versions, dependency-review workflow for supply chain safety, and automated dependabot updates. The .git-hooks/commit-msg template suggests recent governance standardization. Work on OAuth 2.1 spec compliance and OIDC edge cases is ongoing.

git clone https://github.com/ruby-oauth/oauth2.git
cd oauth2
bundle install
# optional: copy .env.local.example to .env.local for local config
bundle exec rake test

Daily commands:

bundle exec rake test          # Run full test suite
bundle exec rake spec          # Run RSpec (if configured)
bundle exec rspec spec/        # Alternative RSpec invoke
# For development: use IRB with bundled gem
bundle console

• lib/oauth2.rb — Main entry point that loads all OAuth2 modules and establishes the public API surface.
• lib/oauth2/client.rb — Core Client class that manages OAuth 2.0 token flows, authorization, and HTTP requests; all authentication workflows depend on this.
• lib/oauth2/access_token.rb — Encapsulates access tokens and provides authenticated request methods; essential for making authorized API calls post-authentication.
• lib/oauth2/strategy/base.rb — Abstract base for OAuth 2.0 grant type strategies; understanding this enables adding new grant types or modifying authorization flows.
• Gemfile — Declares runtime and development dependencies; required to understand external integrations and test requirements.
• README.md — Documents library purpose, usage patterns, and design philosophy; essential onboarding for understanding when and how to use oauth2.
• OIDC.md — Explains OpenID Connect extensions and differences from base OAuth 2.0; critical for OIDC-specific implementations.

Add Support for a New OAuth 2.0 Grant Type

1. Create a new strategy class inheriting from Strategy::Base in lib/oauth2/strategy/ (lib/oauth2/strategy/custom_grant.rb)
2. Implement required methods: authorize_url (if applicable) and get_token with provider-specific logic (lib/oauth2/strategy/custom_grant.rb)
3. Register the strategy in the Client class by adding a method that instantiates and returns your strategy (lib/oauth2/client.rb)
4. Add comprehensive RSpec tests under spec/oauth2/strategy/custom_grant_spec.rb (spec/oauth2/strategy/custom_grant_spec.rb)
5. Document the new grant in OIDC.md or README.md with usage examples (OIDC.md)

Add a New HTTP Middleware or Custom Faraday Adapter

1. Create middleware class in lib/oauth2/middleware/ that implements Faraday middleware interface (call method) (lib/oauth2/middleware/custom_middleware.rb)
2. Update Connection class to conditionally register your middleware based on configuration options (lib/oauth2/connection.rb)
3. Add option flag to Client initialization to enable/configure the middleware (lib/oauth2/client.rb)
4. Write integration tests verifying middleware is called and modifies requests/responses as expected (spec/oauth2/connection_spec.rb)

Handle a New OAuth Provider Error Response Format

1. Examine Response class to understand current error parsing logic (lib/oauth2/response.rb)
2. Add a new error class in lib/oauth2/error.rb for the provider-specific error or extend existing Error class (lib/oauth2/error.rb)
3. Update Response#parse_error or add provider-specific error parsing in Request class (lib/oauth2/request.rb)
4. Create test case in spec/oauth2/response_spec.rb demonstrating correct error extraction and raising (spec/oauth2/response_spec.rb)
5. Document the provider-specific behavior in README.md under a 'Provider-Specific Handling' section (README.md)

• Faraday HTTP client — Provides flexible HTTP adapter abstraction, middleware support, and automatic redirects; allows users to swap adapters (Net::HTTP, Excon, Typhoeus) without library changes.
• Ruby as implementation language — Seamless integration with Rails/Rack ecosystem; duck typing enables easy strategy extension; metaprogramming simplifies DSL-like client configuration.
• RSpec for testing — Industry standard in Ruby; supports mocking, stubbing, and BDD-style specs; integrates with coverage tools and CI workflows.
• Appraisal for multi-version testing — Tests library against multiple Faraday/Ruby versions simultaneously; catches version-specific incompatibilities early.

• Strategy pattern over conditional branching for grant types

  • Why: Enables new grant types without modifying Client class (Open/Closed Principle); users can inject custom strategies.
  • Consequence: Slight performance overhead from polymorphism; more files to maintain; steeper learning curve for new contributors.

• Faraday middleware instead of custom HTTP layer

  • Why: Reuses proven middleware ecosystem; reduces code duplication; lets users layer their own concerns (logging, retry, caching).
  • Consequence: Dependency on Faraday version stability; middleware ordering bugs can be subtle; users must understand Faraday pipeline.

• Mutable AccessToken state (expires_at, refresh_token storage)

  • Why: Simplifies token refresh workflow; no need to re-instantiate for every request.
  • Consequence: Thread-safety concerns if token shared across threads; refresh race conditions possible; testing requires careful fixture setup.

• Minimal error recovery (no automatic retry)

  • Why: Keeps library small; retries are application-specific (exponential backoff, jitter vary by use case).
  • Consequence: Applications must implement retry logic; transient network errors not handled transparently; developers may not realize retry is needed.

• Does not implement OpenID Connect Discovery; users must manually configure endpoints.
• Does not validate JWT signatures; relies on provider to sign and application to verify.
• Does not handle PKCE (Proof Key for Code Exchange) automatically; optional for advanced security flows.
• Does not support device flow or push authorization request (PAR); only standard OAuth 2.0 and OIDC flows.
• Does not provide built-in session management or user persistence; application responsible for storing tokens.
• Does not handle token revocation retry or invalidation callbacks.
• Not suitable for embedded systems or resource-constrained environments (requires full HTTP stack).

Faraday adapter selection: Gem does not vendor HTTP adapter; must bundle (e.g., faraday-httpclient) explicitly to avoid 'adapter not found' runtime errors. Token refresh race conditions: AccessToken#refresh! is not thread-safe; applications must serialize token refresh in multi-threaded contexts. Provider-specific quirks: Some OAuth providers deviate from spec (e.g., return_type, scope handling); see examples/ for provider-specific workarounds. OIDC id_token validation: Must install and configure jwt gem; missing jti/aud claims can silently fail validation. Ruby version constraints: Ancient/unsupported workflows test old versions; main gem targets 2.7+.

• Authorization Code Flow — The most secure OAuth 2.0 grant type supported by this gem; requires understanding redirect flow, authorization server interaction, and backend token exchange for proper client implementation
• Client Credentials Flow — Machine-to-machine OAuth flow implemented in lib/oauth2/strategy/; used when the client itself is the resource owner (service accounts, not user delegation)
• PKCE (Proof Key for Public Clients) — OAuth 2.1 spec addition (security enhancement for native/SPA clients) supported by this gem; requires understanding code_challenge, code_verifier, and S256 hashing to prevent authorization code interception
• OpenID Connect (OIDC) — Identity layer built on OAuth 2.0; this gem includes OIDC support (id_token validation, claims extraction, user info endpoint); critical for authentication vs. authorization distinction
• Bearer Token (RFC 6750) — Standard token credential format used by AccessToken in this gem; explains why tokens are passed in Authorization header with 'Bearer' prefix in signed requests
• Token Refresh & Expiration — AccessToken lifecycle in lib/oauth2/access_token.rb includes automatic refresh via refresh_token; understanding token expiry, refresh_token rotation, and edge cases (race conditions, offline scenarios) is essential for production use
• Scope & Permission Delegation — OAuth scopes define what permissions a client requests; this gem manages scope negotiation in authorization request and validation in token response; provider-specific scope names require careful documentation

• oauth-xx/oauth — Predecessor OAuth 1.0a gem; many users upgrade from oauth to oauth2 for modern OAuth 2.0 support
• intridea/omniauth — High-level authentication abstraction layer that uses ruby-oauth2 under the hood for provider integrations; commonly used alongside this gem
• rails/rails — No Rails dependency but most users integrate oauth2 into Rails apps; often paired with devise or custom Rack middleware
• lsegal/yard — Documentation generator; oauth2 gem generates YARD docs from source; understanding YARD syntax aids contributors
• ruby-jwt/ruby-jwt — Companion gem for OIDC id_token validation; required for secure OpenID Connect implementations with this gem

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add OpenID Connect (OIDC) integration tests for ID token validation

The repo description mentions OpenID Connect (OIDC) support, but the file structure shows extensive test workflows (.github/workflows/) without explicit OIDC test coverage. This is critical for security since ID token validation is complex (JWT signature verification, nonce validation, issuer validation). New contributors can add comprehensive specs validating OIDC-specific flows.

• [ ] Review spec/ directory structure for existing OIDC tests
• [ ] Create spec/oauth2/access_token_oidc_spec.rb for ID token claim validation (iss, aud, exp, nonce)
• [ ] Add spec/oauth2/client_oidc_spec.rb for OpenID Connect request/response handling (scope=openid, userinfo endpoint)
• [ ] Add integration tests in spec/integration/ for complete OIDC flows with real-world providers
• [ ] Ensure tests cover JWT signature verification using public key from jwks_uri

Add Windows-specific CI workflow refinement and test matrix validation

The repo has .github/workflows/windows.yml but the workflow definitions are not visible in the provided structure. OAuth2 libraries often have edge cases on Windows (SSL certificate handling, line endings in request signing). A new contributor can audit and enhance the Windows CI to catch platform-specific bugs earlier.

• [ ] Inspect .github/workflows/windows.yml for current test matrix (Ruby versions, dependency versions)
• [ ] Add explicit Windows-specific tests for SSL/TLS certificate validation in spec/oauth2/connection_spec.rb
• [ ] Test request signing with different line endings (\r\n vs \n) which affects HMAC signatures
• [ ] Add Windows-specific timeout handling tests for HTTP connections
• [ ] Document any Windows-only gotchas in CONTRIBUTING.md with references to specific test files

Implement JRuby compatibility test suite and fix jruby-specific failures

The repo includes .github/workflows/jruby.yml and .jrubyrc file, indicating JRuby support is intended but may have gaps. OAuth2 libraries often fail on JRuby due to threading, OpenSSL bindings, or Fiber differences. A contributor can create dedicated JRuby compatibility tests.

• [ ] Review existing .github/workflows/jruby.yml to identify which tests are skipped on JRuby
• [ ] Create spec/jruby/ directory with JRuby-specific tests for threading behavior in connection pooling
• [ ] Add tests for OpenSSL certificate validation differences between CRuby and JRuby in spec/oauth2/connection_spec.rb
• [ ] Test concurrent token refresh scenarios (potential deadlock issues on JRuby)
• [ ] Document JRuby limitations in README.md with workarounds, if any

• Add RFC 9207 (OAuth 2.0 Authorization Server Issuer Identification) support to lib/oauth2/client.rb by validating issuer claim in OIDC flow responses; currently missing iss parameter checks
• Write integration tests in spec/oauth2/access_token_spec.rb for edge cases in token refresh with 'expires_in' null/missing, covering real-world provider inconsistencies
• Create lib/oauth2/openid_connect/claims.rb to parse and validate OpenID Connect ID token claims (sub, aud, iss, iat, exp) with proper error messages; currently validation is minimal

The oauth2 Ruby gem demonstrates a reasonable security posture with documented security policies and CI/CD automation. However, there are opportunities for improvement: the security support policy lacks specificity on version numbers and timelines, security reporting relies on external infrastructure, and development dependencies require continuous monitoring. The project would benefit from more explicit version support guarantees, direct security contact channels, and strengthened dependency management practices. No critical vulnerabilities were identified in the visible file structure, but runtime analysis of the actual gem code and dependencies would be necessary for comprehensive assessment.

• Medium · Overly Permissive Security Policy Version Support — SECURITY.md. The SECURITY.md file indicates only 'latest' version is supported, with no specific version number provided. This creates ambiguity about which versions receive security patches and may leave users on older versions vulnerable without clear communication. Fix: Specify explicit version numbers (e.g., '2.x.x and above') and define a clear support timeline. Maintain a detailed version support matrix showing when versions enter and exit support.
• Medium · External Dependency for Security Reporting — SECURITY.md. Security vulnerabilities are reported through a third-party service (Tidelift) rather than direct project channels. This introduces a dependency on external infrastructure for critical security communications. Fix: Maintain a direct security contact email address (e.g., security@project.org) as primary contact. Use Tidelift as a secondary channel but provide direct alternatives.
• Low · Example Environment Configuration Exposed — .env.local.example. The presence of '.env.local.example' file suggests environment-based configuration. If example files contain sensitive patterns or defaults, they could guide attackers on what to look for. Fix: Ensure .env.local.example contains only non-sensitive, safe default values. Document security-critical environment variables separately. Add clear warnings in the file about never committing actual credentials.
• Low · Multiple CI/CD Workflows Require Review — .github/workflows/. The extensive .github/workflows directory contains many workflow files. Some workflows (ancient.yml, unsupported.yml, legacy.yml) testing old Ruby versions may use outdated dependencies with known vulnerabilities. Fix: Regularly audit and update all CI/CD workflows. Remove or archive workflows for unsupported Ruby versions. Use dependabot to keep actions and dependencies current across all workflows.
• Low · Development Dependencies in Repository — Gemfile, Gemfile.lock, Appraisals. The presence of Appraisals, Gemfile.lock, and multiple gemfile references suggests development dependencies are tracked. Outdated lock files could include vulnerable transitive dependencies. Fix: Implement automated dependency scanning using tools like bundler-audit (already present). Run security audits in CI/CD pipeline. Keep Gemfile.lock updated regularly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.