oauth2 2.0.20 → 2.0.21

data/IRP.md

@@ -1,107 +0,0 @@
-# Incident Response Plan (IRP)
-
-Status: Draft
-
-## Purpose
-
-This Incident Response Plan (IRP) defines the steps the project maintainer(s) will follow when handling security incidents related to the `oauth2` gem. It is written for a small project with a single primary maintainer and is intended to be practical, concise, and actionable.
-
-## Scope
-
-Applies to security incidents that affect the `oauth2` codebase, releases (gems), CI/CD infrastructure related to building and publishing the gem, repository credentials, or any compromise of project infrastructure that could impact users.
-
-## Key assumptions
-- This project is maintained primarily by a single maintainer.
-- Public vulnerability disclosure is handled via Tidelift (see `SECURITY.md`).
-- The maintainer will act as incident commander unless otherwise delegated.
-
-## Contact & Roles
-
-- Incident Commander: Primary maintainer (repo owner). Responsible for coordinating triage, remediation, and communications.
-- Secondary Contact: (optional) A trusted collaborator or organization contact if available.
-
-### If you are an external reporter
-- Do not publicly disclose details of an active vulnerability before coordination via Tidelift.
-- See `SECURITY.md` for Tidelift disclosure instructions. If the reporter has questions and cannot use Tidelift, they may open a direct encrypted report as described in `SECURITY.md` (if available) or email the maintainer contact listed in the repository.
-
-## Incident Handling Workflow (high level)
-1. Identification & Reporting
-   - Reports may arrive via Tidelift, issue tracker, direct email, or third-party advisories.
-   - Immediately acknowledge receipt (within 24-72 hours) via the reporting channel.
-
-2. Triage & Initial Assessment (first 72 hours)
-   - Confirm the report is not duplicative and gather: reproducer, affected versions, attack surface, exploitability, and CVSS-like severity estimate.
-   - Verify the issue against the codebase and reproduce locally if possible.
-   - Determine scope: which versions are affected, whether the issue is in code paths executed in common setups, and whether a workaround exists.
-
-3. Containment & Mitigation
-   - If a simple mitigation or workaround (configuration change, safe default, or recommended upgrade) exists, document it clearly in the issue/Tidelift advisory.
-   - If immediate removal of a release is required (rare), consult Tidelift for coordinated takedown and notify package hosts if applicable.
-
-4. Remediation & Patch
-   - Prepare a fix in a branch with tests and changelog entries. Prefer minimal, well-tested changes.
-   - Include tests that reproduce the faulty behavior and demonstrate the fix.
-   - Hardening: add fuzz tests, input validation, or additional checks as appropriate.
-
-5. Release & Disclosure
-   - Coordinate disclosure through Tidelift per `SECURITY.md` timelines. Aim for a coordinated disclosure and patch release to minimize risk to users.
-   - Publish a patch release (increment gem version) and an advisory via Tidelift.
-   - Update `CHANGELOG.md` and repository release notes with non-sensitive details.
-
-6. Post-Incident
-   - Produce a short postmortem: timeline, root cause, actions taken, and follow-ups.
-   - Add/adjust tests and CI checks to prevent regressions.
-   - If credentials or infrastructure were compromised, rotate secrets and audit access.
-
-## Severity classification (guidance)
-- High/Critical: Remote code execution, data exfiltration, or any vulnerability that can be exploited without user interaction. Immediate action and prioritized patching.
-- Medium: Privilege escalation, sensitive information leaks that require specific conditions. Patch in the next release cycle with advisory.
-- Low: Minor information leaks, UI issues, or non-exploitable bugs. Fix normally and include in the next scheduled release.
-
-## Preservation of evidence
-- Preserve all reporter-provided data, logs, and reproducer code in a secure location (local encrypted storage or private branch) for the investigation.
-- Do not publish evidence that would enable exploitation before coordinated disclosure.
-
-## Communication templates
-Acknowledgement (to reporter)
-
-"Thank you for reporting this issue. I've received your report and will triage it within 72 hours. If you can, please provide reproduction steps, affected versions, and any exploit PoC. I will coordinate disclosure through Tidelift per the project's security policy."
-
-Public advisory (after patch is ready)
-
-"A security advisory for oauth2 (versions X.Y.Z) has been published via Tidelift. Please upgrade to version A.B.C which patches [brief description]. See the advisory for details and recommended mitigations."
-
-## Runbook: Quick steps for a maintainer to patch and release
-1. Create a branch: `git checkout -b fix/security-brief-description`
-2. Reproduce the issue locally and add a regression spec in `spec/`.
-3. Implement the fix and run the test suite: `bundle exec rspec` (or the project's preferred test command).
-4. Bump version in `lib/oauth2/version.rb` following semantic versioning.
-5. Update `CHANGELOG.md` with an entry describing the fix (avoid exploit details).
-6. Commit and push the branch, open a PR, and merge after approvals.
-7. Build and push the gem: `gem build oauth2.gemspec && gem push pkg/...` (coordinate with Tidelift before public push if disclosure is coordinated).
-8. Publish a release on GitHub and ensure the Tidelift advisory is posted.
-
-## Operational notes
-- Secrets: Use local encrypted storage for any sensitive reporter data. If repository or CI secrets may be compromised, rotate them immediately and update dependent services.
-- Access control: Limit who can publish gems and who has admin access to the repo. Keep an up-to-date list of collaborators in a secure place.
-
-## Legal & regulatory
-- If the incident involves user data or has legal implications, consult legal counsel or the maintainers' employer as appropriate. The maintainer should document the timeline and all communications.
-
-## Retrospective & continuous improvement
-After an incident, perform a brief post-incident review covering:
-- What happened and why
-- What was done to contain and remediate
-- What tests or process changes will prevent recurrence
-- Assign owners and deadlines for follow-up tasks
-
-## References
-- See `SECURITY.md` for the project's official disclosure channel (Tidelift).
-
-## Appendix: Example checklist for an incident
-- [ ] Acknowledge report to reporter (24-72 hours)
-- [ ] Reproduce and classify severity
-- [ ] Prepare and test a fix in a branch
-- [ ] Coordinate disclosure via Tidelift
-- [ ] Publish patch release and advisory
-- [ ] Postmortem and follow-up actions

data/LICENSE.txt

@@ -1,22 +0,0 @@
-MIT License
-
-Copyright (c) 2017-2026 Peter H. Boling, of Galtzo.com, and oauth2 contributors
-Copyright (c) 2011-2013 Michael Bleigh and Intridea, Inc.
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

data/OIDC.md

@@ -1,167 +0,0 @@
-# OpenID Connect (OIDC) with ruby-oauth/oauth2
-
-## OIDC Libraries
-
-Libraries built on top of the oauth2 gem that implement OIDC.
-
-- [gamora](https://github.com/amco/gamora-rb) - OpenID Connect Relying Party for Rails apps
-- [omniauth-doximity-oauth2](https://github.com/doximity/omniauth-doximity-oauth2) - OmniAuth strategy for Doximity, supporting OIDC, and using PKCE
-- [omniauth-himari](https://github.com/sorah/himari) - OmniAuth strategy to act as OIDC RP and use [Himari](https://github.com/sorah/himari) for OP
-- [omniauth-mit-oauth2](https://github.com/MITLibraries/omniauth-mit-oauth2) - OmniAuth strategy for MIT OIDC
-
-If any other libraries would like to be added to this list, please open an issue or pull request.
-
-## Raw OIDC with ruby-oauth/oauth2
-
-This document complements the inline documentation by focusing on OpenID Connect (OIDC) 1.0 usage patterns when using this gem as an OAuth 2.0 client library.
-
-Scope of this document
-
-- Audience: Developers building an OAuth 2.0/OIDC Relying Party (RP, aka client) in Ruby.
-- Non-goals: This gem does not implement an OIDC Provider (OP, aka Authorization Server); for OP/server see other projects (e.g., doorkeeper + oidc extensions).
-- Status: Informational documentation with links to normative specs. The gem intentionally remains protocol-agnostic beyond OAuth 2.0; OIDC specifics (like ID Token validation) must be handled by your application.
-
-Key concepts refresher
-
-- OAuth 2.0 delegates authorization; it does not define authentication of the end-user.
-- OIDC layers an identity layer on top of OAuth 2.0, introducing:
-  - ID Token: a JWT carrying claims about the authenticated end-user and the authentication event.
-  - Standardized scopes: openid (mandatory), profile, email, address, phone, offline_access, and others.
-  - UserInfo endpoint: a protected resource for retrieving user profile claims.
-  - Discovery and Dynamic Client Registration (optional for providers/clients that support them).
-
-What this gem provides for OIDC
-
-- All OAuth 2.0 client capabilities required for OIDC flows: building authorization requests, exchanging authorization codes, refreshing tokens, and making authenticated resource requests.
-- Transport and parsing conveniences (snaky hash, Faraday integration, error handling, etc.).
-- Optional client authentication schemes useful with OIDC deployments:
-  - basic_auth (default)
-  - request_body (legacy)
-  - tls_client_auth (MTLS)
-  - private_key_jwt (OIDC-compliant when configured per OP requirements)
-
-What you must add in your app for OIDC
-
-- ID Token validation: This gem surfaces id_token values but does not verify them. Your app should:
-  1) Parse the JWT (header, payload, signature)
-  2) Fetch the OP JSON Web Key Set (JWKS) from discovery (or configure statically)
-  3) Select the correct key by kid (when present) and verify the signature and algorithm
-  4) Validate standard claims (iss, aud, exp, iat, nbf, azp, nonce when used, at_hash/c_hash when applicable)
-  5) Enforce expected client_id, issuer, and clock skew policies
-- Nonce handling for Authorization Code flow with OIDC: generate a cryptographically-random nonce, bind it to the user session before redirect, include it in authorize request, and verify it in the ID Token on return.
-- PKCE is best practice and often required by OPs: generate/verifier, send challenge in authorize, send verifier in token request.
-- Session/state management: continue to validate state to mitigate CSRF; use exact redirect_uri matching.
-
-Minimal OIDC Authorization Code example
-
-```ruby
-require "oauth2"
-require "jwt"         # jwt/ruby-jwt
-require "net/http"
-require "json"
-
-client = OAuth2::Client.new(
-  ENV.fetch("OIDC_CLIENT_ID"),
-  ENV.fetch("OIDC_CLIENT_SECRET"),
-  site: ENV.fetch("OIDC_ISSUER"),              # e.g. https://accounts.example.com
-  authorize_url: "/authorize",                 # or discovered
-  token_url: "/token",                         # or discovered
-)
-
-# Step 1: Redirect to OP for consent/auth
-state = SecureRandom.hex(16)
-nonce = SecureRandom.hex(16)
-pkce_verifier = SecureRandom.urlsafe_base64(64)
-pkce_challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(pkce_verifier)).delete("=")
-
-authz_url = client.auth_code.authorize_url(
-  scope: "openid profile email",
-  state: state,
-  nonce: nonce,
-  code_challenge: pkce_challenge,
-  code_challenge_method: "S256",
-  redirect_uri: ENV.fetch("OIDC_REDIRECT_URI"),
-)
-# redirect_to authz_url
-
-# Step 2: Handle callback
-# params[:code], params[:state]
-raise "state mismatch" unless params[:state] == state
-
-token = client.auth_code.get_token(
-  params[:code],
-  redirect_uri: ENV.fetch("OIDC_REDIRECT_URI"),
-  code_verifier: pkce_verifier,
-)
-
-# The token may include: access_token, id_token, refresh_token, etc.
-id_token = token.params["id_token"] || token.params[:id_token]
-
-# Step 3: Validate the ID Token (simplified – add your own checks!)
-# Discover keys (example using .well-known)
-issuer = ENV.fetch("OIDC_ISSUER")
-jwks_uri = JSON.parse(Net::HTTP.get(URI.join(issuer, "/.well-known/openid-configuration"))).
-  fetch("jwks_uri")
-jwks = JSON.parse(Net::HTTP.get(URI(jwks_uri)))
-keys = jwks.fetch("keys")
-
-# Use ruby-jwt JWK loader
-jwk_set = JWT::JWK::Set.new(keys.map { |k| JWT::JWK.import(k) })
-
-decoded, headers = JWT.decode(
-  id_token,
-  nil,
-  true,
-  algorithms: ["RS256", "ES256", "PS256"],
-  jwks: jwk_set,
-  verify_iss: true,
-  iss: issuer,
-  verify_aud: true,
-  aud: ENV.fetch("OIDC_CLIENT_ID"),
-)
-
-# Verify nonce
-raise "nonce mismatch" unless decoded["nonce"] == nonce
-
-# Optionally: call UserInfo
-userinfo = token.get("/userinfo").parsed
-```
-
-Notes on discovery and registration
-
-- Discovery: Most OPs publish configuration at `{issuer}/.well-known/openid-configuration` (OIDC Discovery 1.0). From there, resolve authorization_endpoint, token_endpoint, jwks_uri, userinfo_endpoint, etc.
-- Dynamic Client Registration: Some OPs allow registering clients programmatically (OIDC Dynamic Client Registration 1.0). This gem does not implement registration; use a plain HTTP client or Faraday and store credentials securely.
-
-Common pitfalls and tips
-
-- Always request the openid scope when you expect an ID Token. Without it, the OP may behave as vanilla OAuth 2.0.
-- Validate ID Token signature and claims before trusting any identity data. Do not rely solely on the presence of an id_token field.
-- Prefer Authorization Code + PKCE. Avoid Implicit; it is discouraged in modern guidance and may be disabled by providers.
-- Use exact redirect_uri matching, and keep your allow-list short.
-- For public clients that use refresh tokens, prefer sender-constrained tokens (DPoP/MTLS) or rotation with one-time-use refresh tokens, per modern best practices.
-- When using private_key_jwt, ensure the "aud" (or token_url) and "iss/sub" claims are set per the OP’s rules, and include kid in the JWT header when required so the OP can select the right key.
-
-Relevant specifications and references
-
-- OpenID Connect Core 1.0: https://openid.net/specs/openid-connect-core-1_0.html
-- OIDC Core (final): https://openid.net/specs/openid-connect-core-1_0-final.html
-- How OIDC works: https://openid.net/developers/how-connect-works/
-- OpenID Connect home: https://openid.net/connect/
-- OIDC Discovery 1.0: https://openid.net/specs/openid-connect-discovery-1_0.html
-- OIDC Dynamic Client Registration 1.0: https://openid.net/specs/openid-connect-registration-1_0.html
-- OIDC Session Management 1.0: https://openid.net/specs/openid-connect-session-1_0.html
-- OIDC RP-Initiated Logout 1.0: https://openid.net/specs/openid-connect-rpinitiated-1_0.html
-- OIDC Back-Channel Logout 1.0: https://openid.net/specs/openid-connect-backchannel-1_0.html
-- OIDC Front-Channel Logout 1.0: https://openid.net/specs/openid-connect-frontchannel-1_0.html
-- Auth0 OIDC overview: https://auth0.com/docs/authenticate/protocols/openid-connect-protocol
-- Spring Authorization Server’s list of OAuth2/OIDC specs: https://github.com/spring-projects/spring-authorization-server/wiki/OAuth2-and-OIDC-Specifications
-
-See also
-
-- README sections on OAuth 2.1 notes and OIDC notes
-- Strategy classes under lib/oauth2/strategy for flow helpers
-- Specs under spec/oauth2 for concrete usage patterns
-
-Contributions welcome
-
-- If you discover provider-specific nuances, consider contributing examples or clarifications (without embedding provider-specific hacks into the library).

data/REEK

@@ -1,2 +0,0 @@
-./reek: 1: ./reek:: not found
-./reek: 2: ./reek:: not found

data/THREAT_MODEL.md

@@ -1,94 +0,0 @@
-# Threat Model Outline for oauth2 Ruby Gem
-
-## 1. Overview
-This document outlines the threat model for the `oauth2` Ruby gem, which implements OAuth 2.0, 2.1, and OIDC Core protocols. The gem is used to facilitate secure authorization and authentication in Ruby applications.
-
-## 2. Assets to Protect
-- OAuth access tokens, refresh tokens, and ID tokens
-- User credentials (if handled)
-- Client secrets and application credentials
-- Sensitive user data accessed via OAuth
-- Private keys and certificates (for signing/verifying tokens)
-
-## 3. Potential Threat Actors
-- External attackers (internet-based)
-- Malicious OAuth clients or resource servers
-- Insiders (developers, maintainers)
-- Compromised dependencies
-
-## 4. Attack Surfaces
-- OAuth endpoints (authorization, token, revocation, introspection)
-- HTTP request/response handling
-- Token storage and management
-- Configuration files and environment variables
-- Dependency supply chain
-
-## 5. Threats and Mitigations
-
-### 5.1 Token Leakage
-- **Threat:** Tokens exposed via logs, URLs, or insecure storage
-- **Mitigations:**
-  - Avoid logging sensitive tokens
-  - Use secure storage mechanisms
-  - Never expose tokens in URLs
-
-### 5.2 Token Replay and Forgery
-- **Threat:** Attackers reuse or forge tokens
-- **Mitigations:**
-  - Validate token signatures and claims
-  - Use short-lived tokens and refresh tokens
-  - Implement token revocation
-
-### 5.3 Insecure Communication
-- **Threat:** Data intercepted via MITM attacks
-- **Mitigations:**
-  - Enforce HTTPS for all communications
-  - Validate SSL/TLS certificates
-
-### 5.4 Client Secret Exposure
-- **Threat:** Client secrets leaked in code or version control
-- **Mitigations:**
-  - Store secrets in environment variables or secure vaults
-  - Never commit secrets to source control
-
-### 5.5 Dependency Vulnerabilities
-- **Threat:** Vulnerabilities in third-party libraries
-- **Mitigations:**
-  - Regularly update dependencies
-  - Use tools like `bundler-audit` for vulnerability scanning
-
-### 5.6 Improper Input Validation
-- **Threat:** Injection attacks via untrusted input
-- **Mitigations:**
-  - Validate and sanitize all inputs
-  - Use parameterized queries and safe APIs
-
-### 5.7 Request-Target Trust Boundary Expansion
-- **Threat:** Applications may pass untrusted or insufficiently validated absolute URLs into request paths that can carry OAuth credentials or authenticated state.
-- **Risk:** This can expand trust boundaries, contributing to token leakage, authenticated requests to unintended hosts, or SSRF-like pivoting in the surrounding application.
-- **Mitigations:**
-  - Prefer relative paths where practical
-  - Do not pass untrusted absolute URLs into token-bearing clients
-  - Validate or allowlist outbound request targets at the application layer
-  - Treat request-target validation as a separate concern from log redaction and token storage
-
-### 5.8 Insufficient Logging and Monitoring
-- **Threat:** Attacks go undetected
-- **Mitigations:**
-  - Log security-relevant events (without sensitive data)
-  - Monitor for suspicious activity
-
-## 6. Assumptions
-- The gem is used in a secure environment with up-to-date Ruby and dependencies
-- End-users are responsible for secure configuration and deployment
-
-## 7. Out of Scope
-- Security of external OAuth providers
-- Application-level business logic
-
-## 8. References
-- [OAuth 2.0 Threat Model and Security Considerations (RFC 6819)](https://tools.ietf.org/html/rfc6819)
-- [OWASP Top Ten](https://owasp.org/www-project-top-ten/)
-
----
-This outline should be reviewed and updated regularly as the project evolves.