oauth2 2.0.17 → 2.0.18

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 658392d3b9b32646f33f3e35ac1b72a2a70e59ea9191064dd62efe36ba427cba
-  data.tar.gz: 135eb537e72639a92f68af58a953e8e2b6d9d204b8f5d34259e91021b47deba0
+  metadata.gz: f43a3e156646bef90634677d617a155cff1f87d57ca030674f3ee05c160fa4d9
+  data.tar.gz: 5a2d29e7cd920d4e2f515afc23896795477e5cb357e47b6f5c3d0c797194d54c
 SHA512:
-  metadata.gz: 9459b77a1c8f828a844b8884eb9ccaddf8cb6a3ba76840c3ea8a49eeb0c5f57b7b2f4ffd48f4cda50b645d0461b0eb24d433327d18a49560cf1f45e0c3db08a9
-  data.tar.gz: d3fdc9f9748c3e1249de2fd5c17336e663abed93d93db25dcd8e81e04241d749cb5c765c5653d08e94f53ff7f1cf9de5dd0cd65f6cf03af851d9f74c0d7fe845
+  metadata.gz: 471a77bbc0bd8a428ce01ba42ba8e9cb0ad35793eb5f7ae352946b9dda9a448152280c3bdf445255adb47b7f45d65efa11bff2affc2c2200f8e43f57f2a19a91
+  data.tar.gz: 6bae92dd35b1bf9efd38b4d3eceb2451c1016dbd9270947f74ba4ff389fa78420558df095acd8ff7404a2b8b2cdb9438983d1feb59751dd4252f2b7bc75c8d31

data/CHANGELOG.md

@@ -30,6 +30,41 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [2.0.18] - 2025-11-08
+
+- TAG: [v2.0.18][2.0.18t]
+- COVERAGE: 100.00% -- 526/526 lines in 14 files
+- BRANCH COVERAGE: 100.00% -- 178/178 branches in 14 files
+- 90.48% documented
+
+### Added
+
+- [gh!683][gh!683], [gh!684][gh!684] - Improve documentation by @pboling
+- [gh!686][gh!686]- Add Incident Response Plan by @pboling
+- [gh!687][gh!687]- Add Threat Model by @pboling
+
+### Changed
+
+- [gh!685][gh!685] - upgrade kettle-dev v1.1.24 by @pboling
+- upgrade kettle-dev v1.1.52 by @pboling
+  - Add open collective donors to README
+
+### Fixed
+
+- [gh!690][gh!690], [gh!691][gh!691], [gh!692][gh!692] - Add yard-fence
+  - handle braces within code fences in markdown properly by @pboling
+
+### Security
+
+[gh!683]: https://github.com/ruby-oauth/oauth2/pull/683
+[gh!684]: https://github.com/ruby-oauth/oauth2/pull/684
+[gh!685]: https://github.com/ruby-oauth/oauth2/pull/685
+[gh!686]: https://github.com/ruby-oauth/oauth2/pull/686
+[gh!687]: https://github.com/ruby-oauth/oauth2/pull/687
+[gh!690]: https://github.com/ruby-oauth/oauth2/pull/690
+[gh!691]: https://github.com/ruby-oauth/oauth2/pull/691
+[gh!692]: https://github.com/ruby-oauth/oauth2/pull/692
+
 ## [2.0.17] - 2025-09-15
 
 - TAG: [v2.0.17][2.0.17t]
@@ -39,7 +74,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Added
 
-- [gh!682][gh!682] - AccessToken: support Hash-based verb-dependent token transmission mode (e.g., {get: :query, post: :header})
+- [gh!682][gh!682] - AccessToken: support Hash-based verb-dependent token transmission mode (e.g., `{get: :query, post: :header}`)
+
+[gh!682]: https://github.com/ruby-oauth/oauth2/pull/682
 
 ## [2.0.16] - 2025-09-14
 
@@ -701,7 +738,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 [gemfiles/readme]: gemfiles/README.md
 
-[Unreleased]: https://github.com/ruby-oauth/oauth2/compare/v2.0.17...HEAD
+[Unreleased]: https://github.com/ruby-oauth/oauth2/compare/v2.0.18...HEAD
+[2.0.18]: https://github.com/ruby-oauth/oauth2/compare/v2.0.17...v2.0.18
+[2.0.18t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.18
 [2.0.17]: https://github.com/ruby-oauth/oauth2/compare/v2.0.16...v2.0.17
 [2.0.17t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.17
 [2.0.16]: https://github.com/ruby-oauth/oauth2/compare/v2.0.15...v2.0.16

data/CONTRIBUTING.md

@@ -24,31 +24,22 @@ Follow these instructions:
 
 ## Executables vs Rake tasks
 
-Executables shipped by oauth2 can be used with or without generating the binstubs.
-They will work when oauth2 is installed globally (i.e., `gem install oauth2`) and do not require that oauth2 be in your bundle.
+Executables shipped by dependencies, such as kettle-dev, and stone_checksums, are available
+after running `bin/setup`. These include:
 
+- gem_checksums
 - kettle-changelog
 - kettle-commit-msg
-- oauth2-setup
+- kettle-dev-setup
 - kettle-dvcs
 - kettle-pre-release
 - kettle-readme-backers
 - kettle-release
 
-However, the rake tasks provided by oauth2 do require oauth2 to be added as a development dependency and loaded in your Rakefile.
-See the full list of rake tasks in head of Rakefile
+There are many Rake tasks available as well. You can see them by running:
 
-**Gemfile**
-```ruby
-group :development do
-  gem "oauth2", require: false
-end
-```
-
-**Rakefile**
-```ruby
-# Rakefile
-require "oauth2"
+```shell
+bin/rake -T
 ```
 
 ## Environment Variables for Local Development
@@ -77,7 +68,9 @@ GitHub API and CI helpers
 Releasing and signing
 - SKIP_GEM_SIGNING: If set, skip gem signing during build/release
 - GEM_CERT_USER: Username for selecting your public cert in `certs/<USER>.pem` (defaults to $USER)
-- SOURCE_DATE_EPOCH: Reproducible build timestamp. `kettle-release` will set this automatically for the session.
+- SOURCE_DATE_EPOCH: Reproducible build timestamp.
+  - `kettle-release` will set this automatically for the session.
+  - Not needed on bundler >= 2.7.0, as reproducible builds have become the default.
 
 Git hooks and commit message helpers (exe/kettle-commit-msg)
 - GIT_HOOK_BRANCH_VALIDATE: Branch name validation mode (e.g., `jira`) or `false` to disable
@@ -118,10 +111,8 @@ bundle exec rake test
 
 ### Spec organization (required)
 
-- One spec file per class/module. For each class or module under `lib/`, keep all of its unit tests in a single spec file under `spec/` that mirrors the path and file name exactly: `lib/oauth2/release_cli.rb` -> `spec/oauth2/release_cli_spec.rb`.
-- Never add a second spec file for the same class/module. Examples of disallowed names: `*_more_spec.rb`, `*_extra_spec.rb`, `*_status_spec.rb`, or any other suffix that still targets the same class. If you find yourself wanting a second file, merge those examples into the canonical spec file for that class/module.
+- One spec file per class/module. For each class or module under `lib/`, keep all of its unit tests in a single spec file under `spec/` that mirrors the path and file name exactly: `lib/oauth2/my_class.rb` -> `spec/oauth2/my_class_spec.rb`.
 - Exception: Integration specs that intentionally span multiple classes. Place these under `spec/integration/` (or a clearly named integration folder), and do not directly mirror a single class. Name them after the scenario, not a class.
-- Migration note: If a duplicate spec file exists, move all examples into the canonical file and delete the duplicate. Do not leave stubs or empty files behind.
 
 ## Lint It
 
@@ -144,7 +135,7 @@ For more detailed information about using RuboCop in this project, please see th
 Never add `# rubocop:disable ...` / `# rubocop:enable ...` comments to code or specs (except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). Instead:
 
 - Prefer configuration-based exclusions when a rule should not apply to certain paths or files (e.g., via `.rubocop.yml`).
-- When a violation is temporary and you plan to fix it later, record it in `.rubocop_gradual.lock` using the gradual workflow:
+- When a violation is temporary, and you plan to fix it later, record it in `.rubocop_gradual.lock` using the gradual workflow:
   - `bundle exec rake rubocop_gradual:autocorrect` (preferred)
   - `bundle exec rake rubocop_gradual:force_update` (only when you cannot fix the violations immediately)
 
@@ -167,7 +158,7 @@ Also see GitLab Contributors: [https://gitlab.com/ruby-oauth/oauth2/-/graphs/mai
 **IMPORTANT**: To sign a build,
 a public key for signing gems will need to be picked up by the line in the
 `gemspec` defining the `spec.cert_chain` (check the relevant ENV variables there).
-All releases to RubyGems.org are signed releases.
+All releases are signed releases.
 See: [RubyGems Security Guide][🔒️rubygems-security-guide]
 
 NOTE: To build without signing the gem set `SKIP_GEM_SIGNING` to any value in the environment.
@@ -176,9 +167,10 @@ NOTE: To build without signing the gem set `SKIP_GEM_SIGNING` to any value in th
 
 #### Automated process
 
-1. Update version.rb to contian the correct version-to-be-released.
+1. Update version.rb to contain the correct version-to-be-released.
 2. Run `bundle exec kettle-changelog`.
 3. Run `bundle exec kettle-release`.
+4. Stay awake and monitor the release process for any errors, and answer any prompts.
 
 #### Manual process
 
@@ -205,7 +197,7 @@ NOTE: To build without signing the gem set `SKIP_GEM_SIGNING` to any value in th
 12. Sanity check the SHA256, comparing with the output from the `bin/gem_checksums` command:
     - `sha256sum pkg/<gem name>-<version>.gem`
 13. Run `bundle exec rake release` which will create a git tag for the version,
-    push git commits and tags, and push the `.gem` file to [rubygems.org][💎rubygems]
+    push git commits and tags, and push the `.gem` file to the gem host configured in the gemspec.
 
 [📜src-gl]: https://gitlab.com/ruby-oauth/oauth2/
 [📜src-cb]: https://codeberg.org/ruby-oauth/oauth2
@@ -216,7 +208,7 @@ NOTE: To build without signing the gem set `SKIP_GEM_SIGNING` to any value in th
 [🖐contributors]: https://github.com/ruby-oauth/oauth2/graphs/contributors
 [🚎contributors-gl]: https://gitlab.com/ruby-oauth/oauth2/-/graphs/main
 [🖐contributors-img]: https://contrib.rocks/image?repo=ruby-oauth/oauth2
-[💎rubygems]: https://rubygems.org
+[💎gem-coop]: https://gem.coop
 [🔒️rubygems-security-guide]: https://guides.rubygems.org/security/#building-gems
 [🔒️rubygems-checksums-pr]: https://github.com/rubygems/rubygems/pull/6022
 [🔒️rubygems-guides-pr]: https://github.com/rubygems/guides/pull/325

data/FUNDING.md

@@ -6,7 +6,7 @@ Many paths lead to being a sponsor or a backer of this project. Are you on such
 
 [![OpenCollective Backers][🖇osc-backers-i]][🖇osc-backers] [![OpenCollective Sponsors][🖇osc-sponsors-i]][🖇osc-sponsors] [![Sponsor Me on Github][🖇sponsor-img]][🖇sponsor] [![Liberapay Goal Progress][⛳liberapay-img]][⛳liberapay] [![Donate on PayPal][🖇paypal-img]][🖇paypal]
 
-[![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate to my FLOSS or refugee efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS or refugee efforts using Patreon][🖇patreon-img]][🖇patreon]
+[![Buy me a coffee][🖇buyme-small-img]][🖇buyme] [![Donate on Polar][🖇polar-img]][🖇polar] [![Donate to my FLOSS efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS efforts using Patreon][🖇patreon-img]][🖇patreon]
 
 [⛳liberapay-img]: https://img.shields.io/liberapay/goal/pboling.svg?logo=liberapay&color=a51611&style=flat
 [⛳liberapay]: https://liberapay.com/pboling/donate
@@ -31,11 +31,11 @@ Many paths lead to being a sponsor or a backer of this project. Are you on such
 
 <!-- RELEASE-NOTES-FOOTER-END -->
 
-# 🤑 Request for Help
+# 🤑 A request for help
 
 Maintainers have teeth and need to pay their dentists.
-After getting laid off in an RIF in March and filled with many dozens of rejections,
-I'm now spending ~60+ hours a week building open source tools.
+After getting laid off in an RIF in March, and encountering difficulty finding a new one,
+I began spending most of my time building open source tools.
 I'm hoping to be able to pay for my kids' health insurance this month,
 so if you value the work I am doing, I need your support.
 Please consider sponsoring me or the project.
@@ -44,16 +44,13 @@ To join the community or get help 👇️ Join the Discord.
 
 [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite]
 
-To say "thanks for maintaining such a great tool" ☝️ Join the Discord or 👇️ send money.
+To say "thanks!" ☝️ Join the Discord or 👇️ send money.
 
-[![Sponsor ruby-oauth/oauth2 on Open Source Collective][🖇osc-all-bottom-img]][🖇osc] 💌 [![Sponsor me on GitHub Sponsors][🖇sponsor-bottom-img]][🖇sponsor] 💌 [![Sponsor me on Liberapay][⛳liberapay-bottom-img]][⛳liberapay-img] 💌 [![Donate on PayPal][🖇paypal-bottom-img]][🖇paypal-img]
+[![Sponsor ruby-oauth/oauth2 on Open Source Collective][🖇osc-all-bottom-img]][🖇osc] 💌 [![Sponsor me on GitHub Sponsors][🖇sponsor-bottom-img]][🖇sponsor] 💌 [![Sponsor me on Liberapay][⛳liberapay-bottom-img]][⛳liberapay] 💌 [![Donate on PayPal][🖇paypal-bottom-img]][🖇paypal]
 
 # Another Way to Support Open Source Software
 
-> How wonderful it is that nobody need wait a single moment before starting to improve the world.<br/>
->—Anne Frank
-
-I’m driven by a passion to foster a thriving open-source community – a space where people can tackle complex problems, no matter how small.  Revitalizing libraries that have fallen into disrepair, and building new libraries focused on solving real-world challenges, are my passions — totaling 79 hours of FLOSS coding over just the past seven days, a pretty regular week for me.  I was recently affected by layoffs, and the tech jobs market is unwelcoming. I’m reaching out here because your support would significantly aid my efforts to provide for my family, and my farm (11 🐔 chickens, 2 🐶 dogs, 3 🐰 rabbits, 8 🐈‍ cats).
+I’m driven by a passion to foster a thriving open-source community – a space where people can tackle complex problems, no matter how small.  Revitalizing libraries that have fallen into disrepair, and building new libraries focused on solving real-world challenges, are my passions.  I was recently affected by layoffs, and the tech jobs market is unwelcoming. I’m reaching out here because your support would significantly aid my efforts to provide for my family, and my farm (11 🐔 chickens, 2 🐶 dogs, 3 🐰 rabbits, 8 🐈‍ cats).
 
 If you work at a company that uses my work, please encourage them to support me as a corporate sponsor. My work on gems you use might show up in `bundle fund`.
 

data/IRP.md

@@ -0,0 +1,107 @@
+# 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/OIDC.md

@@ -16,11 +16,13 @@ If any other libraries would like to be added to this list, please open an issue
 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.
@@ -29,6 +31,7 @@ Key concepts refresher
   - 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:
@@ -38,6 +41,7 @@ What this gem provides for OIDC
   - 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)
@@ -124,10 +128,12 @@ 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.
+
+- 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.
@@ -136,6 +142,7 @@ Common pitfalls and tips
 - 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/
@@ -150,9 +157,11 @@ Relevant specifications and references
 - 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).