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/doorkeeper-gem/doorkeeper 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 5d ago
• 19 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 50% 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 doorkeeper-gem/doorkeeper repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/doorkeeper-gem/doorkeeper.

What it runs against: a local clone of doorkeeper-gem/doorkeeper — 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 doorkeeper-gem/doorkeeper | 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 ≤ 35 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of doorkeeper-gem/doorkeeper. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/doorkeeper-gem/doorkeeper.git
#   cd doorkeeper
#
# 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 doorkeeper-gem/doorkeeper and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "doorkeeper-gem/doorkeeper(\\.git)?\\b" \\
  && ok "origin remote is doorkeeper-gem/doorkeeper" \\
  || miss "origin remote is not doorkeeper-gem/doorkeeper (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/doorkeeper.rb" \\
  && ok "lib/doorkeeper.rb" \\
  || miss "missing critical file: lib/doorkeeper.rb"
test -f "lib/doorkeeper/config.rb" \\
  && ok "lib/doorkeeper/config.rb" \\
  || miss "missing critical file: lib/doorkeeper/config.rb"
test -f "lib/doorkeeper/engine.rb" \\
  && ok "lib/doorkeeper/engine.rb" \\
  || miss "missing critical file: lib/doorkeeper/engine.rb"
test -f "app/controllers/doorkeeper/authorizations_controller.rb" \\
  && ok "app/controllers/doorkeeper/authorizations_controller.rb" \\
  || miss "missing critical file: app/controllers/doorkeeper/authorizations_controller.rb"
test -f "app/controllers/doorkeeper/tokens_controller.rb" \\
  && ok "app/controllers/doorkeeper/tokens_controller.rb" \\
  || miss "missing critical file: app/controllers/doorkeeper/tokens_controller.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 35 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~5d)"
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/doorkeeper-gem/doorkeeper"
  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).

Doorkeeper is a Ruby on Rails/Grape engine that adds OAuth 2.0 provider functionality to applications, implementing the full RFC 6749 authorization framework. It enables applications to issue access tokens, handle authorization flows (code, implicit, password, client credentials), manage token revocation/introspection, and support PKCE for native app security—turning your Rails app into an OAuth server that third-party clients can authenticate against. Rails engine architecture: app/controllers/doorkeeper/ contains the OAuth endpoints (authorizations, tokens, token_info), app/models/ (not shown but implied) holds the domain models, app/views/doorkeeper/ provides the authorization grant UI templates and application management interfaces, and lib/doorkeeper/ likely contains the core OAuth logic and configuration. The gem mounts itself as a Rails mountable engine in host applications.

Ruby on Rails and Grape developers who need to expose their application as an OAuth 2.0 provider so external applications can request access to user data via standardized token-based authentication, without implementing the OAuth spec from scratch.

Highly mature and production-ready. The gem has strong CI coverage (GitHub Actions workflows for CI, RuboCop linting, changelog automation), uses Coveralls for code coverage tracking, passes GuardRails security checks, and has Dependabot enabled for dependency management. Regular releases and active maintenance visible through the RELEASING.md and CHANGELOG.md files indicate sustained project health.

Low risk overall. The gem is well-established with comprehensive test coverage and active security monitoring. Main considerations: single organization maintainers (doorkeeper-gem) mean bus-factor risk, and as a security-critical component (OAuth provider), any vulnerabilities in dependencies or implementation could affect all downstream applications. Review SECURITY.md for vulnerability disclosure policy and keep dependencies current via Dependabot.

Active maintenance with Dependabot monitoring dependencies, recent focus on CI/CD via GitHub Actions (ci.yml, rubocop.yml workflows), changelog automation, and code quality via CodeClimate integration. The presence of UPGRADE.md suggests recent breaking changes being documented for users upgrading between versions.

git clone https://github.com/doorkeeper-gem/doorkeeper.git
cd doorkeeper
bundle install
bundle exec rake spec

Daily commands: Development: bundle exec rake spec to run the test suite. The repository is the gem itself, not a consumer app—to test integration, install into a Rails app via the Gemfile and run rails generate doorkeeper:install to scaffold OAuth endpoints.

• lib/doorkeeper.rb — Main entry point that initializes the gem and loads all core components.
• lib/doorkeeper/config.rb — Configuration system that defines all OAuth 2 provider behavior and customization points.
• lib/doorkeeper/engine.rb — Rails engine that mounts routes, initializers, and asset pipelines for the OAuth provider.
• app/controllers/doorkeeper/authorizations_controller.rb — Primary authorization endpoint handler for OAuth 2 authorization code flow.
• app/controllers/doorkeeper/tokens_controller.rb — Token endpoint that issues access tokens and refresh tokens for all grant types.
• lib/doorkeeper/models/access_token_mixin.rb — Core mixin that defines access token lifecycle, validation, and expiration logic.
• lib/doorkeeper/grant_flow/registry.rb — Registry pattern that manages pluggable OAuth 2 grant flow implementations.

Add a Custom OAuth Grant Type

1. Create a new grant flow class in lib/doorkeeper/grant_flow/ that inherits from Flow. (lib/doorkeeper/grant_flow/flow.rb)
2. Implement the required method stubs (e.g., authorize, token issuance logic). (lib/doorkeeper/grant_flow/flow.rb)
3. Register the grant type in config/initializers/doorkeeper.rb using Doorkeeper.configure block. (lib/doorkeeper/config.rb)
4. Route the token endpoint POST request through the registered flow via tokens_controller. (app/controllers/doorkeeper/tokens_controller.rb)

Add a New OAuth Endpoint

1. Create a new controller in app/controllers/doorkeeper/ inheriting from ApplicationController. (app/controllers/doorkeeper/application_controller.rb)
2. Implement endpoint action and use doorkeeper_authorize! helper for access control. (lib/doorkeeper/helpers/controller.rb)
3. Mount the route in config/routes.rb inside the doorkeeper_routes block. (lib/doorkeeper/engine.rb)
4. Create corresponding view template in app/views/doorkeeper/ if needed. (app/views/doorkeeper/authorizations/new.html.erb)

Customize Token Behavior & Expiration

1. Create a custom AccessToken model that includes AccessTokenMixin. (lib/doorkeeper/models/access_token_mixin.rb)
2. Override expiration and lookup methods in your model. (lib/doorkeeper/models/concerns/expirable.rb)
3. Configure Doorkeeper to use your custom token class in doorkeeper.rb config. (lib/doorkeeper/config.rb)
4. Tokens controller will automatically use your custom logic. (app/controllers/doorkeeper/tokens_controller.rb)

Add Authorization Scopes & Permissions

1. Define scopes in Doorkeeper.configure block with descriptions. (lib/doorkeeper/config.rb)
2. Override scope validation in your custom flow class. (lib/doorkeeper/grant_flow/flow.rb)
3. Use doorkeeper_authorize! scope: [:read] in protected controller actions. (lib/doorkeeper/helpers/controller.rb)
4. Customize authorization form to show scope descriptions to user. (app/views/doorkeeper/authorizations/new.html.erb)

• Rails Engine — Allows drop-in OAuth provider functionality to existing Rails apps with auto-mounted routes and initializers.
• Mixin Pattern for Models — Enables flexibility for apps to use their own User/Application models while inheriting OAuth behavior.
• Registry Pattern for Grant Flows — Supports pluggable grant type implementations (auth code, client credentials, implicit) without coupling.
• ERB Templates for Authorization UI — Simple server-rendered consent forms with minimal JavaScript overhead, easily customizable.

• Mixin-based model composition instead of STI or composition

  • Why: Allows developers to use their own models without forcing inheritance chains.
  • Consequence: Less DRY than single base class, but maximum flexibility for existing apps.

• Server-rendered authorization form instead of pure API

  • Why: Simpler UX for resource owner consent without requiring SPA on provider side.
  • Consequence: Less decoupled but lower friction for standard OAuth 2 flows.

• In-process token validation instead of central token service

  • Why: Reduces latency and deployment complexity; works with any Rails app.
  • Consequence: Distributed validation; clock skew and token revocation need careful handling.

• OAuth 2.0 client implementation (only provider side)
• OpenID Connect layer (pure OAuth 2.0 only)
• Real-time token revocation across distributed systems
• Multi-tenant provider (single provider per Rails instance)
• Cryptographic key rotation service
• Usage analytics or token audit logging

No major environment variable or service dependencies evident from the file list, but: (1) The gem is a Rails engine—it must be installed in a host Rails app, not run standalone; local development requires generating the engine into a test app. (2) Database migrations are required to set up OAuth tables (access_tokens, applications, authorizations); the .gitignore and Dockerfile suggest Docker is used for CI but not required locally. (3) Review UPGRADE.md carefully when updating versions, as OAuth spec compliance changes can break existing integrations. (4) Security is paramount—any custom configuration in doorkeeper.rb should follow RFC 6819 threat model recommendations.

• OAuth 2.0 Authorization Code Grant Flow — The most common and secure OAuth flow; Doorkeeper's authorizationz and tokens controllers implement this—understanding the redirect dance between user, authorization server, and client is essential for debugging token issuance
• Proof Key for Code Exchange (PKCE) — RFC 7636 extension for protecting public clients (native apps) from authorization code interception attacks; Doorkeeper supports this and the README mentions it, so you need to understand how code_challenge and code_verifier prevent token theft
• Token Introspection (RFC 7662) — The token_info_controller implements this—allows resource servers to query token validity without maintaining state, critical for verifying incoming bearer tokens in protected endpoints
• Scope-based Access Control — OAuth scopes (mentioned in README) allow users to grant granular permissions; you'll need to define scopes in doorkeeper config and enforce them on protected resources, combining them with the authorization policy gem
• Refresh Token Rotation — RFC 6749 section 1.5 covers refresh tokens; Doorkeeper manages these for long-lived sessions without requiring re-authorization, important for mobile and desktop client security
• Token Revocation (RFC 7009) — Users need to revoke granted app access (see authorized_applications_controller); Doorkeeper implements RFC 7009 token revocation allowing clients and users to invalidate tokens immediately
• Rails Mountable Engine Pattern — Doorkeeper is a Rails engine (not a standalone app); understanding how config/routes.rb in the engine mounts into the host app's router and how models/migrations are namespaced under doorkeeper is essential for customization

• omniauth/omniauth — Complementary OAuth 2.0 consumer gem; Doorkeeper is the provider side, OmniAuth is the client-side authentication strategy
• rails-api/rails-api — Rails API template that pairs well with Doorkeeper for building OAuth 2.0–protected API servers without the view layer overhead
• devise/devise — User authentication gem often used alongside Doorkeeper; Devise handles user login, Doorkeeper handles OAuth token issuance for those users
• authorizationz/pundit — Authorization policy gem frequently paired with Doorkeeper tokens to enforce scope-based access control on protected resources
• jnunemaker/httparty — HTTP client library commonly used in test suites and integrations to make OAuth token requests against a Doorkeeper server

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 comprehensive integration tests for doorkeeper/authorizations_controller.rb

The authorizations controller handles critical OAuth 2 flows (authorization, error handling, form_post response). While CI exists, the file structure suggests limited coverage for edge cases like PKCE validation, state parameter tampering, and various grant type authorization flows. This is security-critical for an OAuth provider.

• [ ] Review spec/requests/authorizations_controller_spec.rb for coverage gaps
• [ ] Add tests for PKCE code_challenge validation in app/controllers/doorkeeper/authorizations_controller.rb
• [ ] Add tests for malformed/missing state parameter handling
• [ ] Add tests for authorization form_post.html.erb rendering with different response types
• [ ] Run coverage report to validate >95% line coverage for this controller

Create missing documentation for admin dashboard features in CONTRIBUTING.md

The repo has an admin dashboard (app/views/doorkeeper/applications/*, app/helpers/doorkeeper/dashboard_helper.rb) but CONTRIBUTING.md doesn't explain how to develop/test admin features locally. New contributors won't know how to set up the dashboard UI or test authorization flows through it.

• [ ] Add 'Admin Dashboard Development' section to CONTRIBUTING.md
• [ ] Document how to enable admin routes in a test Rails app (config/routes.rb setup)
• [ ] Add screenshots or instructions for testing app/views/doorkeeper/applications/ CRUD operations
• [ ] Document CSS/stylesheet changes needed in app/assets/stylesheets/doorkeeper/admin/
• [ ] Link to relevant controller files (app/controllers/doorkeeper/applications_controller.rb, etc.)

Add GitHub Action workflow for security vulnerability scanning (SECURITY.md compliance)

The repo has SECURITY.md and AGENTS.md but no dedicated GitHub Action for continuous security scanning. Doorkeeper is an OAuth provider (high-security target). Adding a workflow for gem vulnerability checks and dependency auditing would prevent supply chain issues and align with SECURITY.md guidelines.

• [ ] Create .github/workflows/security.yml with bundler-audit or Dependabot scanning
• [ ] Add step to scan for known CVEs in Gemfile dependencies
• [ ] Add step to check for deprecated Ruby versions in .ruby-version
• [ ] Integrate with .github/dependabot.yml config (already exists but not enforced in CI)
• [ ] Document expected behavior in SECURITY.md under 'Automated Security Checks' section

• Add integration tests for the new RFC 7662 Token Introspection endpoint (app/controllers/doorkeeper/token_info_controller.rb)—check if both valid and invalid token scenarios are covered with distinct response codes and payloads
• Improve dashboard UI in app/views/doorkeeper/admin/ by adding visual indicators for token expiration times and scope permissions; currently the admin views are minimal
• Document PKCE flow example in the README—RFC 8252 is listed as supported but no concrete code example exists for native app developers implementing PKCE with Doorkeeper

Doorkeeper demonstrates a reasonable security posture as an OAuth 2 provider gem with established security disclosure practices (SECURITY.md) and infrastructure monitoring (CI/CD, Dependabot, code climate). Key strengths include proper file structure separation, non-root Docker user, and security-focused documentation. Primary concerns are the reliance on proper user configuration for OAuth security, incomplete Docker hardening (SUID/SGID, bundler security), and limited visibility into dependencies. The security of applications using this gem depends heavily on proper implementation and configuration by developers. Recommend enhanced Docker security hardening, strict dependency validation, and comprehensive security documentation for end-users.

• Medium · Docker Image Uses Alpine Linux with Minimal Security Scanning — Dockerfile. The Dockerfile uses Alpine Linux (ruby:3.3.4-alpine) which has a smaller attack surface but limited security monitoring compared to Debian/Ubuntu variants. While this is generally acceptable, Alpine's smaller ecosystem means fewer security patches and community scrutiny. Fix: Consider using a more widely-used base image like ruby:3.3.4-slim-bullseye or ruby:3.3.4 for better security patch coverage and community support, or maintain strict vulnerability scanning for Alpine packages.
• Medium · Missing SUID/SGID Restrictions in Docker — Dockerfile. The Dockerfile creates a non-root user 'doorkeeper' but does not explicitly disable SUID/SGID bits or implement additional security hardening measures. This could potentially allow privilege escalation if a vulnerability exists in included binaries. Fix: Add security hardening: use '--no-suid' flag during apk add, implement 'RUN find / -perm /6000 -type f -delete' to remove SUID/SGID binaries, and consider using SECURITY_OPTS in docker-compose or --security-opt flags.
• Medium · Bundler Configuration Not Hardened — Dockerfile, line with 'RUN bundle config'. The Dockerfile runs 'bundle config' without specifying security-relevant configurations. No explicit bundler security options are configured, such as disabling insecure sources or enforcing checksum verification. Fix: Configure bundler security settings: 'bundle config set --local frozen true', 'bundle config set --local no_prune true', and verify gemfile.lock is properly committed and validated.
• Low · OAuth 2 Provider - Potential for Misconfiguration — app/controllers/doorkeeper/. As an OAuth 2 provider gem, the security heavily depends on proper configuration by users. The file structure shows authorization and token controllers, which are sensitive components where misconfigurations could lead to token leakage, authorization bypass, or redirect URI validation issues. Fix: Ensure comprehensive documentation of security best practices, default-secure configurations, and security validation in authorization flows. Implement strict CSRF protection, state parameter validation, and redirect URI whitelisting by default.
• Low · Limited Visibility into Dependency Management — Gemfile, doorkeeper.gemspec, and related gem files. The dependencies/package file content was not provided. The security posture cannot be fully assessed without reviewing Gemfile, gemspec, and Gemfile.lock for known vulnerabilities in dependencies. Fix: Regularly run 'bundle audit' or 'bundler-audit' to scan for known vulnerabilities in dependencies. Enable Dependabot alerts (already visible in .github/dependabot.yml) and enforce automated security updates.
• Low · Static Asset Handling Requires XSS Mitigation Verification — app/views/doorkeeper/, app/assets/stylesheets/doorkeeper/. The presence of ERB templates and CSS files (app/views/doorkeeper/ and app/assets/stylesheets/) requires careful review to ensure proper output escaping and content security policy implementation to prevent XSS attacks. Fix: Ensure all user inputs in views are properly escaped using Rails' built-in escaping (default in modern Rails). Implement and enforce Content-Security-Policy headers. Review all ERB templates for proper use of html_safe().

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.