diff --git a/.aiignore b/.aiignore new file mode 100644 index 00000000..df6bd8b7 --- /dev/null +++ b/.aiignore @@ -0,0 +1,19 @@ +# An .aiignore file follows the same syntax as a .gitignore file. +# .gitignore documentation: https://git-scm.com/docs/gitignore + +# you can ignore files +.DS_Store +*.log +*.tmp + +# or folders +.devcontainer/ +.qlty/ +.yardoc/ +dist/ +build/ +out/ +coverage/ +docs/ +pkg/ +results/ diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000..c5fee1cc --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,26 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the +// README at: https://github.com/devcontainers/templates/tree/main/src/ruby +{ + "name": "Ruby", + // Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile + "image": "mcr.microsoft.com/devcontainers/ruby:1-3-bookworm", + + // Features to add to the dev container. More info: https://containers.dev/features. + // "features": {}, + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + + // Use 'postCreateCommand' to run commands after the container is created. + // "postCreateCommand": "ruby --version", + + // Configure tool-specific properties. + "customizations" : { + "jetbrains" : { + "backend" : "RubyMine" + } + }, + + // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. + // "remoteUser": "root" +} diff --git a/.env.local.example b/.env.local.example new file mode 100644 index 00000000..7729745d --- /dev/null +++ b/.env.local.example @@ -0,0 +1,27 @@ +# +# DO NOT EDIT THIS FILE +# +# COPT THIS FILE TO .env.local +# +# That file is ignored by .gitignore. This file is not. +# +export DEBUG=false # do not allow byebug statements (override in .env.local) +export FLOSS_FUNDING_DEBUG=false # extra logging to help diagnose issues (override in .env.local) +export AUTOGEN_FIXTURE_CLEANUP=false # autogenerated gem fixture cleanup after every RSpec run +export GIT_HOOK_FOOTER_APPEND=false +export GIT_HOOK_FOOTER_APPEND_DEBUG=false +export GIT_HOOK_FOOTER_SENTINEL="⚡️ A message from a fellow meat-based-AI" + +# Tokens used by ci:act and CI helpers for reading workflow/pipeline status via APIs +# GitHub (either GITHUB_TOKEN or GH_TOKEN will be used; fine-grained recommended) +# - Scope/permissions: For fine-grained tokens, grant repository access (Read) and Actions: Read +# - For classic tokens, public repos need no scopes; private repos typically require repo +export GITHUB_TOKEN= +# Alternatively: +# export GH_TOKEN= + +# GitLab (either GITLAB_TOKEN or GL_TOKEN will be used) +# - Scope: read_api is sufficient to read pipelines +export GITLAB_TOKEN= +# Alternatively: +# export GL_TOKEN= diff --git a/.envrc b/.envrc new file mode 100644 index 00000000..6b06e0ae --- /dev/null +++ b/.envrc @@ -0,0 +1,46 @@ +# Run any command in this library's bin/ without the bin/ prefix! +# Prefer exe version over binstub +PATH_add exe +PATH_add bin + +# Only add things to this file that should be shared with the team. + +# **dotenv** (See end of file for .env.local integration) +# .env would override anything in this file, if enabled. +# .env is a DOCKER standard, and if we use it, it would be in deployed, or DOCKER, environments. +# Override and customize anything below in your own .env.local +# If you are using dotenv and not direnv, +# copy the following `export` statements to your own .env file. + +### General Ruby ### +# Turn off Ruby Warnings about deprecated code +# export RUBYOPT="-W0" + +### External Testing Controls +export K_SOUP_COV_DO=true # Means you want code coverage +export K_SOUP_COV_COMMAND_NAME="Test Coverage" +# Available formats are html, xml, rcov, lcov, json, tty +export K_SOUP_COV_FORMATTERS="html,xml,rcov,lcov,json,tty" +export K_SOUP_COV_MIN_BRANCH=78 # Means you want to enforce X% branch coverage +export K_SOUP_COV_MIN_LINE=97 # Means you want to enforce X% line coverage +export K_SOUP_COV_MIN_HARD=true # Means you want the build to fail if the coverage thresholds are not met +export K_SOUP_COV_MULTI_FORMATTERS=true +export K_SOUP_COV_OPEN_BIN= # Means don't try to open coverage results in browser +export MAX_ROWS=1 # Setting for simplecov-console gem for tty output, limits to the worst N rows of bad coverage +export KETTLE_TEST_SILENT=true + +# Internal Debugging Controls +export DEBUG=false # do not allow byebug statements (override in .env.local) +export FLOSS_CFG_FUND_DEBUG=false # extra logging to help diagnose issues (override in .env.local) +export FLOSS_CFG_FUND_LOGFILE=tmp/log/debug.log + +# Concurrently developing the rubocop-lts suite? +export RUBOCOP_LTS_LOCAL=false + +# .env would override anything in this file, if `dotenv` is uncommented below. +# .env is a DOCKER standard, and if we use it, it would be in deployed, or DOCKER, environments, +# and that is why we generally want to leave it commented out. +# dotenv + +# .env.local will override anything in this file. +dotenv_if_exists .env.local diff --git a/.git-hooks/commit-msg b/.git-hooks/commit-msg new file mode 100755 index 00000000..5d160e67 --- /dev/null +++ b/.git-hooks/commit-msg @@ -0,0 +1,54 @@ +#!/usr/bin/env ruby +# vim: set syntax=ruby + +# Do not rely on Bundler; allow running outside a Bundler context +begin + require "rubygems" +rescue LoadError + # continue +end + +begin + # External gems + require "gitmoji/regex" + + full_text = File.read(ARGV[0]) + # Is the first character a GitMoji? + gitmoji_index = full_text =~ Gitmoji::Regex::REGEX + if gitmoji_index == 0 + exit(0) + else + denied = <<~EOM + Oh snap, think again... + + ______ _______ ___ _______ _______ _______ _______ ______ __ + | _ | | | | || || || || || | | | + | | || | ___| | || ___|| ||_ _|| ___|| _ || | + | |_||_ | |___ | || |___ | | | | | |___ | | | || | + | __ || ___| ___| || ___|| _| | | | ___|| |_| ||__| + | | | || |___ | || |___ | |_ | | | |___ | | __ + |___| |_||_______||_______||_______||_______| |___| |_______||______| |__| + + + Did you forget to add a relevant gitmoji? (see https://gitmoji.dev/ for tools) + In this project, a Gitmoji must be the first grapheme of the commit message. + What's a grapheme? + A symbol rendered to be visually identifiable as a single character, but which may be composed of multiple Unicode code points) + Must match: #{Gitmoji::Regex::REGEX} + #{"Found a gitmoji at character index #{gitmoji_index}... not good enough.\n" if gitmoji_index} + Example: git commit -m "✨ My excellent new feature" + + EOM + puts denied + exit(1) + end +rescue LoadError => e + failure = <<~EOM + gitmoji-regex gem not found: #{e.class}: #{e.message}. + Skipping gitmoji check and allowing commit to proceed. + Recommendation: add 'gitmoji-regex' to your development dependencies to enable this check. + + EOM + warn(failure) + exit(0) +end diff --git a/.git-hooks/commit-subjects-goalie.txt b/.git-hooks/commit-subjects-goalie.txt new file mode 100644 index 00000000..54b905aa --- /dev/null +++ b/.git-hooks/commit-subjects-goalie.txt @@ -0,0 +1,8 @@ +🔖 Prepare release v +🔒️ Checksums for v + +# Lines beginning with # are ignored. +# This file is read by .git-hooks/prepare-commit-msg in each project. +# Each line of this file will be matched against the commit subject using `starts_with?`. +# If any `starts_with?` match the project script bin/prepare-commit-msg will run. +# 🔒️ Checksums for v is the standard commit message by stone_checksums. diff --git a/.git-hooks/footer-template.erb.txt b/.git-hooks/footer-template.erb.txt new file mode 100644 index 00000000..36cdb0ad --- /dev/null +++ b/.git-hooks/footer-template.erb.txt @@ -0,0 +1,16 @@ +⚡️ A message from a fellow meat-based-AI ⚡️ +- [❤️] Finely-crafted open-source tools like <%= @gem_name %> (& many more) require time and effort. +- [❤️] Though I adore my work, it lacks financial sustainability. +- [❤️] Please, help me continue enhancing your tools by becoming a sponsor: + - [💲] https://liberapay.com/pboling/donate + - [💲] https://github.com/sponsors/pboling + +<% if ENV["GIT_HOOK_FOOTER_APPEND_DEBUG"] == "true" %> + @pwd = <%= @pwd %> + @gemspecs = <%= @gemspecs %> + @spec = <%= @spec %> + @gemspec_path = <%= @gemspec_path %> + @gem_name <%= @gem_name %> + @spec_name <%= @spec_name %> + @content <%= @content %> +<% end %> diff --git a/.git-hooks/prepare-commit-msg b/.git-hooks/prepare-commit-msg new file mode 100755 index 00000000..dbc30589 --- /dev/null +++ b/.git-hooks/prepare-commit-msg @@ -0,0 +1,8 @@ +#!/bin/sh + +# Fail on error and unset variables +set -eu + +# We are not using direnv exec here because mise and direnv can result in conflicting PATH settings: +# See: https://mise.jdx.dev/direnv.html +exec "kettle-commit-msg" "$@" diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 00000000..5ee55773 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,13 @@ +# These are supported funding model platforms + +buy_me_a_coffee: pboling +community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry +github: [pboling] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] +issuehunt: pboling # Replace with a single IssueHunt username +ko_fi: pboling # Replace with a single Ko-fi username +liberapay: pboling # Replace with a single Liberapay username +open_collective: ruby-oauth +patreon: galtzo # Replace with a single Patreon username +polar: pboling +thanks_dev: u/gh/pboling +tidelift: rubygems/oauth2 diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..956aa5a3 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,13 @@ +version: 2 +updates: + - package-ecosystem: bundler + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 5 + ignore: + - dependency-name: "rubocop-lts" + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" diff --git a/.github/disabled-workflows/danger.yml b/.github/disabled-workflows/danger.yml new file mode 100644 index 00000000..c018d38e --- /dev/null +++ b/.github/disabled-workflows/danger.yml @@ -0,0 +1,44 @@ +name: What's up Danger? + +on: + pull_request: + branches: + - 'main' + - '*-stable' + +jobs: + danger: + runs-on: ubuntu-latest + env: # $BUNDLE_GEMFILE must be set at the job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/${{ matrix.gemfile }}.gemfile + if: false + # if: github.event_name == 'pull_request' # if only run pull request when multiple trigger workflow + strategy: + fail-fast: false + matrix: + gemfile: + - vanilla + rubygems: + - latest + bundler: + - latest + ruby: + - "ruby" + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Setup Ruby & Bundle + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: true + - uses: MeilCli/danger-action@v6 + with: + plugins_file: 'Gemfile' + install_path: 'vendor/bundle' + danger_file: 'Dangerfile' + danger_id: 'danger-pr' + env: + DANGER_GITHUB_API_TOKEN: ${{ secrets.DANGER_GITHUB_API_TOKEN }} diff --git a/.github/disabled-workflows/discord-notifier.yml b/.github/disabled-workflows/discord-notifier.yml new file mode 100644 index 00000000..ad98367a --- /dev/null +++ b/.github/disabled-workflows/discord-notifier.yml @@ -0,0 +1,39 @@ +name: Discord Notify + +on: + check_run: + types: [completed] + discussion: + types: [ created ] + discussion_comment: + types: [ created ] + fork: + gollum: + issues: + types: [ opened ] + issue_comment: + types: [ created ] + pull_request: + types: [ opened, reopened, closed ] + release: + types: [ published ] + watch: + types: [ started ] + +# A workflow run is made up of one or more jobs that can run sequentially or in parallel +jobs: + # This workflow contains a single job called "build" + notify: + if: false + # The type of runner that the job will run on + runs-on: ubuntu-latest + + # Steps represent a sequence of tasks that will be executed as part of the job + steps: + - name: Actions Status Discord + uses: sarisia/actions-status-discord@v1 + if: always() + with: + webhook: ${{ secrets.DISCORD_WEBHOOK }} + status: ${{ job.status }} + username: GitHub Actions diff --git a/.github/workflows/ancient.yml b/.github/workflows/ancient.yml new file mode 100644 index 00000000..31a9e947 --- /dev/null +++ b/.github/workflows/ancient.yml @@ -0,0 +1,82 @@ +name: MRI 2.4, 2.5 (EOL) + +permissions: + contents: read + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Specs ${{ matrix.ruby }} ${{ matrix.appraisal }}${{ matrix.name_extra || '' }} + runs-on: ubuntu-22.04 + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + fail-fast: false + matrix: + include: +# Ruby 2.3 is tested heavily by caboose.yml +# # Ruby 2.3 +# - ruby: "ruby-2.3" +# appraisal: "ruby-2-3" +# exec_cmd: "rake test" +# gemfile: "Appraisal.root" +# rubygems: "3.3.27" +# bundler: "2.3.27" + + # Ruby 2.4 + - ruby: "ruby-2.4" + appraisal: "ruby-2-4" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: "3.3.27" + bundler: "2.3.27" + + # Ruby 2.5 + - ruby: "ruby-2.5" + appraisal: "ruby-2-5" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: "3.3.27" + bundler: "2.3.27" + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle + - name: Appraisal for ${{ matrix.appraisal }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + - name: Tests for ${{ matrix.ruby }} via ${{ matrix.exec_cmd }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/auto-assign.yml b/.github/workflows/auto-assign.yml new file mode 100644 index 00000000..96975f22 --- /dev/null +++ b/.github/workflows/auto-assign.yml @@ -0,0 +1,21 @@ +name: Auto Assign +on: + issues: + types: [opened] + pull_request: + types: [opened] +jobs: + run: + runs-on: ubuntu-latest + permissions: + issues: write + pull-requests: write + steps: + - name: 'Auto-assign issue' + uses: pozil/auto-assign-issue@v2 + with: + repo-token: ${{ secrets.GITHUB_TOKEN }} + assignees: pboling + abortIfPreviousAssignees: true + allowSelfAssign: true + numOfAssignee: 1 \ No newline at end of file diff --git a/.github/workflows/caboose.yml b/.github/workflows/caboose.yml new file mode 100644 index 00000000..f69cafd2 --- /dev/null +++ b/.github/workflows/caboose.yml @@ -0,0 +1,106 @@ +# THE CABOOSE IS AN ABSOLUTE WAGON +name: MRI 2.3 X Hashie WAGON (EOL) + +permissions: + contents: read + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + name: Specs ${{ matrix.ruby }} ${{ matrix.appraisal }}${{ matrix.name_extra || '' }} + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + runs-on: ubuntu-22.04 + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + fail-fast: false + matrix: + include: + # Ruby 2.3 + - ruby: "ruby-2.3" + appraisal: "ruby-2-3-hashie_v0" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: "3.3.27" + bundler: "2.3.27" + + # Ruby 2.3 + - ruby: "ruby-2.3" + appraisal: "ruby-2-3-hashie_v1" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: "3.3.27" + bundler: "2.3.27" + + # Ruby 2.3 + - ruby: "ruby-2.3" + appraisal: "ruby-2-3-hashie_v2" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: "3.3.27" + bundler: "2.3.27" + + # Ruby 2.3 + - ruby: "ruby-2.3" + appraisal: "ruby-2-3-hashie_v3" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: "3.3.27" + bundler: "2.3.27" + + # Ruby 2.3 + - ruby: "ruby-2.3" + appraisal: "ruby-2-3-hashie_v4" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: "3.3.27" + bundler: "2.3.27" + + # Ruby 2.3 + - ruby: "ruby-2.3" + appraisal: "ruby-2-3-hashie_v5" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: "3.3.27" + bundler: "2.3.27" + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle > /dev/null 2>&1 + - name: Appraisal for ${{ matrix.appraisal }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle > /dev/null 2>&1 + - name: Tests for ${{ matrix.ruby }} via ${{ matrix.exec_cmd }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/codeql-analysis.yml b/.github/workflows/codeql-analysis.yml new file mode 100644 index 00000000..f59e5c33 --- /dev/null +++ b/.github/workflows/codeql-analysis.yml @@ -0,0 +1,70 @@ +# For most projects, this workflow file will not need changing; you simply need +# to commit it to your repository. +# +# You may wish to alter this file to override the set of languages analyzed, +# or to provide custom queries or build logic. +# +# ******** NOTE ******** +# We have attempted to detect the languages in your repository. Please check +# the `language` matrix defined below to confirm you have the correct set of +# supported CodeQL languages. +# +name: "CodeQL" + +on: + push: + branches: [ main, '*-stable' ] + pull_request: + # The branches below must be a subset of the branches above + branches: [ main, '*-stable' ] + schedule: + - cron: '35 1 * * 5' + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: [ 'ruby' ] + # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ] + # Learn more about CodeQL language support at https://git.io/codeql-language-support + + steps: + - name: Checkout repository + uses: actions/checkout@v5 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v4 + with: + languages: ${{ matrix.language }} + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + # queries: ./path/to/local/query, your-org/your-repo/queries@main + + # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). + # If this step fails, then you should remove it and run the build manually (see below) + - name: Autobuild + uses: github/codeql-action/autobuild@v4 + + # ℹ️ Command-line programs to run using the OS shell. + # 📚 https://git.io/JvXDl + + # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines + # and modify them (or add more) to build your code if your project + # uses a compiled language + + #- run: | + # make bootstrap + # make release + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v4 diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml new file mode 100644 index 00000000..c9d6a2e1 --- /dev/null +++ b/.github/workflows/coverage.yml @@ -0,0 +1,127 @@ +name: Test Coverage + +permissions: + contents: read + pull-requests: write + id-token: write + +env: + K_SOUP_COV_MIN_BRANCH: 100 + K_SOUP_COV_MIN_LINE: 100 + K_SOUP_COV_MIN_HARD: true + K_SOUP_COV_FORMATTERS: "xml,rcov,lcov,tty" + K_SOUP_COV_DO: true + K_SOUP_COV_MULTI_FORMATTERS: true + K_SOUP_COV_COMMAND_NAME: "Test Coverage" + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + coverage: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Code Coverage on ${{ matrix.ruby }}@current + runs-on: ubuntu-latest + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + fail-fast: false + matrix: + include: + # Coverage + - ruby: "ruby" + appraisal: "coverage" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: latest + bundler: latest + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: "${{ matrix.ruby }}" + rubygems: "${{ matrix.rubygems }}" + bundler: "${{ matrix.bundler }}" + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle + - name: Appraisal for ${{ matrix.appraisal }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + - name: Tests for ${{ matrix.ruby }}@current via ${{ matrix.exec_cmd }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} + + # Do SaaS coverage uploads first + - name: Upload coverage to Coveralls + if: ${{ !env.ACT }} + uses: coverallsapp/github-action@master + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + continue-on-error: ${{ matrix.experimental != 'false' }} + + - name: Upload coverage to QLTY + if: ${{ !env.ACT }} + uses: qltysh/qlty-action/coverage@main + with: + token: ${{secrets.QLTY_COVERAGE_TOKEN}} + files: coverage/.resultset.json + continue-on-error: ${{ matrix.experimental != 'false' }} + + # Build will fail here if coverage upload fails + # which will hopefully be noticed for the lack of code coverage comments + - name: Upload coverage to CodeCov + if: ${{ !env.ACT }} + uses: codecov/codecov-action@v5 + with: + use_oidc: true + fail_ci_if_error: false # optional (default = false) + files: coverage/lcov.info,coverage/coverage.xml + verbose: true # optional (default = false) + + # Then PR comments + - name: Code Coverage Summary Report + if: ${{ !env.ACT && github.event_name == 'pull_request' }} + uses: irongut/CodeCoverageSummary@v1.3.0 + with: + filename: ./coverage/coverage.xml + badge: true + fail_below_min: true + format: markdown + hide_branch_rate: false + hide_complexity: true + indicators: true + output: both + thresholds: '100 100' + continue-on-error: ${{ matrix.experimental != 'false' }} + + - name: Add Coverage PR Comment + uses: marocchino/sticky-pull-request-comment@v2 + if: ${{ !env.ACT && github.event_name == 'pull_request' }} + with: + recreate: true + path: code-coverage-results.md + continue-on-error: ${{ matrix.experimental != 'false' }} diff --git a/.github/workflows/current.yml b/.github/workflows/current.yml new file mode 100644 index 00000000..7dab87e0 --- /dev/null +++ b/.github/workflows/current.yml @@ -0,0 +1,115 @@ +# Targets the evergreen latest release of ruby, truffleruby, and jruby +name: Current + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Specs ${{ matrix.ruby }}@${{ matrix.appraisal }} + runs-on: ubuntu-latest + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + matrix: + include: + # Ruby 3.4 + - ruby: "ruby" + appraisal: "current" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: latest + bundler: latest + + # truffleruby-24.1 (targets Ruby 3.3 compatibility) + - ruby: "truffleruby" + appraisal: "current" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + # jruby-10.0 (targets Ruby 3.4 compatibility) + - ruby: "jruby" + appraisal: "current" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + steps: + - name: Checkout + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle + + - name: "[Attempt 1] Install Root Appraisal" + id: bundleAttempt1 + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle + # Continue to the next step on failure + continue-on-error: true + + # Effectively an automatic retry of the previous step. + - name: "[Attempt 2] Install Root Appraisal" + id: bundleAttempt2 + # If bundleAttempt1 failed, try again here; Otherwise skip. + if: ${{ steps.bundleAttempt1.outcome == 'failure' && (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle + + - name: "[Attempt 1] Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal }}" + id: bundleAppraisalAttempt1 + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + # Continue to the next step on failure + continue-on-error: true + + # Effectively an automatic retry of the previous step. + - name: "[Attempt 2] Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal }}" + id: bundleAppraisalAttempt2 + # If bundleAppraisalAttempt1 failed, try again here; Otherwise skip. + if: ${{ steps.bundleAppraisalAttempt1.outcome == 'failure' && (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + + - name: Tests for ${{ matrix.ruby }} via ${{ matrix.exec_cmd }} + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/dep-heads.yml b/.github/workflows/dep-heads.yml new file mode 100644 index 00000000..a3d03f5f --- /dev/null +++ b/.github/workflows/dep-heads.yml @@ -0,0 +1,117 @@ +# Targets the evergreen latest release of ruby, truffleruby, and jruby +# and tests against the HEAD of runtime dependencies +name: Runtime Deps @ HEAD + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Specs ${{ matrix.ruby }}@${{ matrix.appraisal }}${{ matrix.name_extra || '' }} + runs-on: ubuntu-latest + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + fail-fast: true + matrix: + include: + # Ruby 3.4 + - ruby: "ruby" + appraisal: "dep-heads" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: latest + bundler: latest + + # truffleruby-24.1 (targets Ruby 3.3 compatibility) + - ruby: "truffleruby" + appraisal: "dep-heads" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + # jruby-10.0 (targets Ruby 3.4 compatibility) + - ruby: "jruby" + appraisal: "dep-heads" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + steps: + - name: Checkout + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle + + - name: "[Attempt 1] Install Root Appraisal" + id: bundleAttempt1 + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle + # Continue to the next step on failure + continue-on-error: true + + # Effectively an automatic retry of the previous step. + - name: "[Attempt 2] Install Root Appraisal" + id: bundleAttempt2 + # If bundleAttempt1 failed, try again here; Otherwise skip. + if: ${{ steps.bundleAttempt1.outcome == 'failure' && (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle + + - name: "[Attempt 1] Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal }}" + id: bundleAppraisalAttempt1 + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + # Continue to the next step on failure + continue-on-error: true + + # Effectively an automatic retry of the previous step. + - name: "[Attempt 2] Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal }}" + id: bundleAppraisalAttempt2 + # If bundleAppraisalAttempt1 failed, try again here; Otherwise skip. + if: ${{ steps.bundleAppraisalAttempt1.outcome == 'failure' && (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + + - name: Tests for ${{ matrix.ruby }} via ${{ matrix.exec_cmd }} + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 00000000..046e9c88 --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,20 @@ +# Dependency Review Action +# +# This Action will scan dependency manifest files that change as part of a Pull Request, surfacing known-vulnerable versions of the packages declared or updated in the PR. Once installed, if the workflow run is marked as required, PRs introducing known-vulnerable packages will be blocked from merging. +# +# Source repository: https://github.com/actions/dependency-review-action +# Public documentation: https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review#dependency-review-enforcement +name: 'Dependency Review' +on: [pull_request] + +permissions: + contents: read + +jobs: + dependency-review: + runs-on: ubuntu-latest + steps: + - name: 'Checkout Repository' + uses: actions/checkout@v5 + - name: 'Dependency Review' + uses: actions/dependency-review-action@v4 diff --git a/.github/workflows/heads.yml b/.github/workflows/heads.yml new file mode 100644 index 00000000..104f1a7a --- /dev/null +++ b/.github/workflows/heads.yml @@ -0,0 +1,116 @@ +name: Heads + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Specs ${{ matrix.ruby }}@${{ matrix.appraisal }}${{ matrix.name_extra || '' }} + runs-on: ubuntu-latest + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + fail-fast: true + matrix: + include: + # NOTE: Heads use default rubygems / bundler; their defaults are custom, unreleased, and from the future! + # ruby-head + - ruby: "ruby-head" + appraisal: "head" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + # truffleruby-head + - ruby: "truffleruby-head" + appraisal: "head" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + # jruby-head + - ruby: "jruby-head" + appraisal: "head" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + steps: + - name: Checkout + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle + + - name: "[Attempt 1] Install Root Appraisal" + id: bundleAttempt1 + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle + # Continue to the next step on failure + continue-on-error: true + + # Effectively an automatic retry of the previous step. + - name: "[Attempt 2] Install Root Appraisal" + id: bundleAttempt2 + # If bundleAttempt1 failed, try again here; Otherwise skip. + if: ${{ steps.bundleAttempt1.outcome == 'failure' && (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle + + - name: "[Attempt 1] Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal }}" + id: bundleAppraisalAttempt1 + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + # Continue to the next step on failure + continue-on-error: true + + # Effectively an automatic retry of the previous step. + - name: "[Attempt 2] Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal }}" + id: bundleAppraisalAttempt2 + # If bundleAppraisalAttempt1 failed, try again here; Otherwise skip. + if: ${{ steps.bundleAppraisalAttempt1.outcome == 'failure' && (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + + - name: Tests for ${{ matrix.ruby }} via ${{ matrix.exec_cmd }} + if: ${{ (env.ACT && !(startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) || (!env.ACT && (startsWith(matrix.ruby, 'jruby')) || startsWith(matrix.ruby, 'truffleruby')) }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/jruby.yml b/.github/workflows/jruby.yml new file mode 100644 index 00000000..26cc8f3e --- /dev/null +++ b/.github/workflows/jruby.yml @@ -0,0 +1,72 @@ +name: JRuby + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Specs ${{ matrix.ruby }} ${{ matrix.appraisal }}${{ matrix.name_extra || '' }} + runs-on: ubuntu-22.04 + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + matrix: + include: + # jruby-9.4 (targets Ruby 3.1 compatibility) + - ruby: "jruby-9.4" + appraisal: "ruby-3-1" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + steps: + - name: Checkout + if: ${{ !env.ACT }} + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + if: ${{ !env.ACT }} + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + if: ${{ !env.ACT }} + run: bundle + - name: Appraisal for ${{ matrix.appraisal }} + if: ${{ !env.ACT }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + - name: Tests for ${{ matrix.ruby }} via ${{ matrix.exec_cmd }} + if: ${{ !env.ACT }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/legacy.yml b/.github/workflows/legacy.yml new file mode 100644 index 00000000..f7853f62 --- /dev/null +++ b/.github/workflows/legacy.yml @@ -0,0 +1,76 @@ +name: MRI 3.0, 3.1 (EOL) + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Specs ${{ matrix.ruby }} ${{ matrix.appraisal }}${{ matrix.name_extra || '' }} + runs-on: ubuntu-22.04 + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + fail-fast: false + matrix: + include: + # Ruby 3.0 + - ruby: "ruby-3.0" + appraisal: "ruby-3-0" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: '3.5.23' + bundler: '2.5.23' + + # Ruby 3.1 + - ruby: "ruby-3.1" + appraisal: "ruby-3-1" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: '3.6.9' + bundler: '2.6.9' + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle + - name: Appraisal for ${{ matrix.appraisal }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + - name: Tests for ${{ matrix.ruby }} via ${{ matrix.exec_cmd }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/license-eye.yml b/.github/workflows/license-eye.yml new file mode 100644 index 00000000..d5e667dc --- /dev/null +++ b/.github/workflows/license-eye.yml @@ -0,0 +1,40 @@ +name: Apache SkyWalking Eyes + +permissions: + contents: read + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + license-check: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Check Dependencies' License + uses: apache/skywalking-eyes/dependency@main + with: + config: .licenserc.yaml + # Ruby packages declared as dependencies in gemspecs or Gemfiles are + # typically consumed as binaries; enable weak-compatibility + # so permissive and weak-copyleft combinations are treated as compatible. + flags: --weak-compatible diff --git a/.github/workflows/locked_deps.yml b/.github/workflows/locked_deps.yml new file mode 100644 index 00000000..7d946ad6 --- /dev/null +++ b/.github/workflows/locked_deps.yml @@ -0,0 +1,85 @@ +--- +# Lock/Unlock Deps Pattern +# +# Two often conflicting goals resolved! +# +# - unlocked_deps.yml +# - All runtime & dev dependencies, but does not have a `gemfiles/*.gemfile.lock` committed +# - Uses an Appraisal2 "unlocked_deps" gemfile, and the current MRI Ruby release +# - Know when new dependency releases will break local dev with unlocked dependencies +# - Broken workflow indicates that new releases of dependencies may not work +# +# - locked_deps.yml +# - All runtime & dev dependencies, and has a `Gemfile.lock` committed +# - Uses the project's main Gemfile, and the current MRI Ruby release +# - Matches what contributors and maintainers use locally for development +# - Broken workflow indicates that a new contributor will have a bad time +# +name: Deps Locked + +permissions: + contents: read + +env: + # Running coverage, but not validating minimum coverage, + # because it would be redundant with the coverage workflow. + # Also we can validate all output formats without breaking CodeCov, + # since we aren't submitting these reports anywhere. + K_SOUP_COV_MIN_BRANCH: 71 + K_SOUP_COV_MIN_LINE: 86 + K_SOUP_COV_MIN_HARD: false + K_SOUP_COV_FORMATTERS: "html,xml,rcov,lcov,json,tty" + K_SOUP_COV_DO: true + K_SOUP_COV_MULTI_FORMATTERS: true + K_SOUP_COV_COMMAND_NAME: "Test Coverage" + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Default rake task w/ main Gemfile.lock ${{ matrix.name_extra || '' }} + runs-on: ubuntu-latest + continue-on-error: ${{ matrix.experimental }} + strategy: + fail-fast: false + matrix: + include: + # Ruby + - ruby: "ruby" + exec_cmd: "rake" + rubygems: latest + bundler: latest + experimental: false + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: true + + - name: Checks the kitchen sink via ${{ matrix.exec_cmd }} + run: bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/macos.yml b/.github/workflows/macos.yml new file mode 100644 index 00000000..cf0189ee --- /dev/null +++ b/.github/workflows/macos.yml @@ -0,0 +1,86 @@ +# Targets the evergreen latest release of ruby, truffleruby, and jruby +name: MacOS + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + name: Specs ${{ matrix.ruby }}@${{ matrix.appraisal }} + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + runs-on: macos-latest + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + matrix: + include: + # Ruby 3.4 + - ruby: "ruby" + appraisal: "current" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: latest + bundler: latest + + # truffleruby-24.1 + # (according to documentation: targets Ruby 3.3 compatibility) + # (according to runtime: targets Ruby 3.2 compatibility) + - ruby: "truffleruby" + appraisal: "current" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + # jruby-10.0 (targets Ruby 3.4 compatibility) + - ruby: "jruby" + appraisal: "current" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: default + bundler: default + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle + - name: Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + - name: Tests for ${{ matrix.ruby }}@${{ matrix.appraisal }} via ${{ matrix.exec_cmd }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/opencollective.yml b/.github/workflows/opencollective.yml new file mode 100644 index 00000000..6122df47 --- /dev/null +++ b/.github/workflows/opencollective.yml @@ -0,0 +1,40 @@ +name: Open Collective Backers + +on: + schedule: + # Run once a week on Sunday at 12:00 AM UTC + - cron: '0 0 * * 0' + workflow_dispatch: + +permissions: + contents: write + +jobs: + update-backers: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + with: + persist-credentials: false + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ruby + rubygems: default + bundler: default + bundler-cache: true + + - name: README Update + env: + # Keep GITHUB_TOKEN for any tools/scripts expecting it, mapped to the same secret + GITHUB_TOKEN: ${{ secrets.README_UPDATER_TOKEN }} + README_UPDATER_TOKEN: ${{ secrets.README_UPDATER_TOKEN }} + REPO: ${{ github.repository }} + run: | + git config user.name 'autobolt' + git config user.email 'autobots@9thbit.net' + # Use the configured token for authenticated pushes + git remote set-url origin "https://x-access-token:$%7BREADME_UPDATER_TOKEN%7D@github.com/$%7BREPO%7D.git" + bin/kettle-readme-backers + # Push back to the same branch/ref that triggered the workflow (default branch for schedule) + git push origin HEAD diff --git a/.github/workflows/style.yml b/.github/workflows/style.yml new file mode 100644 index 00000000..4fbef86e --- /dev/null +++ b/.github/workflows/style.yml @@ -0,0 +1,67 @@ +name: Style + +permissions: + contents: read + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + rubocop: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Style on ${{ matrix.ruby }}@current + runs-on: ubuntu-latest + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + fail-fast: false + matrix: + include: + # Style + - ruby: "ruby" + appraisal: "style" + exec_cmd: "rake rubocop_gradual:check" + gemfile: "Appraisal.root" + rubygems: latest + bundler: latest + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle + - name: Appraisal for ${{ matrix.appraisal }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + - name: Run ${{ matrix.appraisal }} checks via ${{ matrix.exec_cmd }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} + - name: Validate RBS Types + run: bundle exec appraisal ${{ matrix.appraisal }} bin/rbs validate diff --git a/.github/workflows/supported.yml b/.github/workflows/supported.yml new file mode 100644 index 00000000..887034b0 --- /dev/null +++ b/.github/workflows/supported.yml @@ -0,0 +1,75 @@ +name: MRI Non-EOL + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Specs ${{ matrix.ruby }} ${{ matrix.appraisal }}${{ matrix.name_extra || '' }} + runs-on: ubuntu-latest + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + matrix: + include: + # Ruby 3.2 + - ruby: "ruby-3.2" + appraisal: "ruby-3-2" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: latest + bundler: latest + + # Ruby 3.3 + - ruby: "ruby-3.3" + appraisal: "ruby-3-3" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: latest + bundler: latest + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle + - name: Appraisal for ${{ matrix.ruby }} ${{ matrix.appraisal }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + - name: Tests for ${{ matrix.ruby }} ${{ matrix.appraisal }} via ${{ matrix.exec_cmd }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/unlocked_deps.yml b/.github/workflows/unlocked_deps.yml new file mode 100644 index 00000000..7faffa13 --- /dev/null +++ b/.github/workflows/unlocked_deps.yml @@ -0,0 +1,84 @@ +--- +# Lock/Unlock Deps Pattern +# +# Two often conflicting goals resolved! +# +# - unlocked_deps.yml +# - All runtime & dev dependencies, but does not have a `gemfiles/*.gemfile.lock` committed +# - Uses an Appraisal2 "unlocked_deps" gemfile, and the current MRI Ruby release +# - Know when new dependency releases will break local dev with unlocked dependencies +# - Broken workflow indicates that new releases of dependencies may not work +# +# - locked_deps.yml +# - All runtime & dev dependencies, and has a `Gemfile.lock` committed +# - Uses the project's main Gemfile, and the current MRI Ruby release +# - Matches what contributors and maintainers use locally for development +# - Broken workflow indicates that a new contributor will have a bad time +# +name: Deps Unlocked + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Default rake task w/ unlocked deps ${{ matrix.name_extra || '' }} + runs-on: ubuntu-latest + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + matrix: + include: + # Ruby + - ruby: "ruby" + appraisal_name: "unlocked_deps" + exec_cmd: "rake" + gemfile: "Appraisal.root" + rubygems: latest + bundler: latest + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle + - name: Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal_name }} + run: bundle exec appraisal ${{ matrix.appraisal_name }} bundle + - name: Run ${{ matrix.exec_cmd }} on ${{ matrix.ruby }}@${{ matrix.appraisal_name }} + run: bundle exec appraisal ${{ matrix.appraisal_name }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/unsupported.yml b/.github/workflows/unsupported.yml new file mode 100644 index 00000000..98336994 --- /dev/null +++ b/.github/workflows/unsupported.yml @@ -0,0 +1,76 @@ +name: MRI 2.6 & 2.7 (EOL) + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + name: Specs ${{ matrix.ruby }} ${{ matrix.appraisal }}${{ matrix.name_extra || '' }} + runs-on: ubuntu-22.04 + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + fail-fast: false + matrix: + include: + # Ruby 2.6 + - ruby: "ruby-2.6" + appraisal: "ruby-2-6" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: '3.4.22' + bundler: '2.4.22' + + # Ruby 2.7 + - ruby: "ruby-2.7" + appraisal: "ruby-2-7" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: '3.4.22' + bundler: '2.4.22' + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle + - name: Appraisal for ${{ matrix.appraisal }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + - name: Tests for ${{ matrix.ruby }} via ${{ matrix.exec_cmd }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.yml new file mode 100644 index 00000000..16e3f07f --- /dev/null +++ b/.github/workflows/windows.yml @@ -0,0 +1,68 @@ +# Targets the evergreen latest release of ruby, truffleruby, and jruby +name: Windows + +permissions: + contents: read + +env: + K_SOUP_COV_DO: false + +on: + push: + branches: + - 'main' + - '*-stable' + tags: + - '!*' # Do not execute on tags + pull_request: + branches: + - '*' + # Allow manually triggering the workflow. + workflow_dispatch: + +# Cancels all previous workflow runs for the same branch that have not yet completed. +concurrency: + # The concurrency group contains the workflow name and the branch name. + group: "${{ github.workflow }}-${{ github.ref }}" + cancel-in-progress: true + +jobs: + test: + name: Specs ${{ matrix.ruby }}@${{ matrix.appraisal }} + if: "!contains(github.event.commits[0].message, '[ci skip]') && !contains(github.event.commits[0].message, '[skip ci]')" + runs-on: windows-latest + continue-on-error: ${{ matrix.experimental || endsWith(matrix.ruby, 'head') }} + env: # $BUNDLE_GEMFILE must be set at job level, so it is set for all steps + BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}.gemfile + strategy: + matrix: + include: + # Ruby 3.4 + - ruby: "ruby" + appraisal: "current" + exec_cmd: "rake test" + gemfile: "Appraisal.root" + rubygems: latest + bundler: latest + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Ruby & RubyGems + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + rubygems: ${{ matrix.rubygems }} + bundler: ${{ matrix.bundler }} + bundler-cache: false + + # Raw `bundle` will use the BUNDLE_GEMFILE set to matrix.gemfile (i.e. Appraisal.root) + # We need to do this first to get appraisal installed. + # NOTE: This does not use the primary Gemfile at all. + - name: Install Root Appraisal + run: bundle + - name: Appraisal for ${{ matrix.ruby }}@${{ matrix.appraisal }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle + - name: Tests for ${{ matrix.ruby }}@${{ matrix.appraisal }} via ${{ matrix.exec_cmd }} + run: bundle exec appraisal ${{ matrix.appraisal }} bundle exec ${{ matrix.exec_cmd }} diff --git a/.gitignore b/.gitignore index 483474f6..068190dc 100644 --- a/.gitignore +++ b/.gitignore @@ -1,35 +1,51 @@ # Build Artifacts /pkg/ /tmp/ - -# rspec failure tracking -.rspec_status +*.gem # Bundler -Gemfile.lock +/vendor/bundle/ /.bundle/ +/gemfiles/*.lock /gemfiles/.bundle/ /gemfiles/.bundle/config /gemfiles/vendor/ - -/gemfiles/*.lock +Appraisal.*.gemfile.lock # Specs +.rspec_status /coverage/ /spec/reports/ +/results/ +.output.txt # Documentation -/.yardoc +/.yardoc/ /_yardoc/ -/doc/ /rdoc/ +/doc/ +/blogs/ -# RVM +# Ruby Version Managers (RVM, rbenv, etc) +# Ignored because we currently use .tool-versions .rvmrc +.ruby-version +.ruby-gemset + +# Benchmarking +/measurement/ + +# Debugger detritus +.byebug_history + +# direnv - brew install direnv +.env.local + +# OS Detritus +.DS_Store # Editors -.idea *~ -# Other -/measurement/ +# Sentinels +.floss_funding.*.lock diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml new file mode 100644 index 00000000..3390138a --- /dev/null +++ b/.gitlab-ci.yml @@ -0,0 +1,136 @@ +# You can override the included template(s) by including variable overrides +# SAST customization: https://docs.gitlab.com/ee/user/application_security/sast/#customizing-the-sast-settings +# Secret Detection customization: https://docs.gitlab.com/ee/user/application_security/secret_detection/#customizing-settings +# Dependency Scanning customization: https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#customizing-the-dependency-scanning-settings +# Container Scanning customization: https://docs.gitlab.com/ee/user/application_security/container_scanning/#customizing-the-container-scanning-settings +# Note that environment variables can be set in several places +# See https://docs.gitlab.com/ee/ci/variables/#cicd-variable-precedence +#stages: +# - test +#sast: +# stage: test +#include: +# - template: Security/SAST.gitlab-ci.yml + +default: + image: ruby + +variables: + BUNDLE_INSTALL_FLAGS: "--quiet --jobs=$(nproc) --retry=3" + BUNDLE_FROZEN: "false" # No lockfile! + BUNDLE_GEMFILE: Appraisal.root.gemfile + K_SOUP_COV_DEBUG: true + K_SOUP_COV_DO: true + K_SOUP_COV_HARD: true + K_SOUP_COV_MIN_BRANCH: 100 + K_SOUP_COV_MIN_LINE: 100 + K_SOUP_COV_VERBOSE: true + K_SOUP_COV_FORMATTERS: "tty" + K_SOUP_COV_MULTI_FORMATTERS: true + K_SOUP_COV_COMMAND_NAME: "RSpec Coverage" + +workflow: + rules: + # For merge requests, create a pipeline. + - if: '$CI_MERGE_REQUEST_IID' + # For the ` main ` branch, create a pipeline (this includes on schedules, pushes, merges, etc.). + - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' + # For tags, create a pipeline. + - if: '$CI_COMMIT_TAG' + +.test_template-current: &test_definition-current + image: ruby:${RUBY_VERSION} + stage: test + script: + # || true so we don't fail here, because it'll probably work even if the gem update fails + - gem update --silent --system > /dev/null 2>&1 || true + - mkdir -p vendor/bundle + - bundle config set path 'vendor/bundle' + - chmod +t -R vendor/bundle + - chmod o-w -R vendor/bundle + # Setup appraisal2 + - bundle install + # Bundle a specific appraisal + - bundle exec appraisal unlocked_deps bundle install + # Light smoke test + - bundle exec appraisal unlocked_deps bin/rake --tasks + # Run tests, skipping those that won't work in CI + - > + bundle exec appraisal unlocked_deps \ + bin/rspec spec \ + --tag \~ci_skip \ + --format progress \ + --format RspecJunitFormatter + cache: + key: ${CI_JOB_IMAGE} + paths: + - vendor/ruby + +.test_template-legacy: &test_definition-legacy + image: ruby:${RUBY_VERSION} + stage: test + script: + # RUBYGEMS_VERSION because we support EOL Ruby still... + # || true so we don't fail here, because it'll probably work even if the gem update fails + - gem install rubygems-update -v ${RUBYGEMS_VERSION} || true + # Actually updates both RubyGems and Bundler! + - update_rubygems + - mkdir -p vendor/bundle + - bundle config set path 'vendor/bundle' + - chmod +t -R vendor/bundle + - chmod o-w -R vendor/bundle + # Setup appraisal2 + - bundle install + # Bundle a specific appraisal + - bundle exec appraisal ${APPRAISAL} bundle install + # Light smoke test + - bundle exec appraisal ${APPRAISAL} bin/rake --tasks + # Run tests, skipping those that won't work in CI + - > + bundle exec appraisal unlocked_deps \ + bin/rspec spec \ + --tag \~ci_skip \ + --format progress \ + --format RspecJunitFormatter + cache: + key: ${CI_JOB_IMAGE} + paths: + - vendor/ruby + +ruby-current: + variables: + K_SOUP_COV_DO: true + <<: *test_definition-current + parallel: + matrix: + - RUBY_VERSION: ["3.2", "3.3", "3.4"] + +ruby-ruby3_1: + variables: + RUBYGEMS_VERSION: "3.6.9" + APPRAISAL: ruby_3_1 + K_SOUP_COV_DO: false + <<: *test_definition-legacy + parallel: + matrix: + - RUBY_VERSION: ["3.1"] + +ruby-ruby3_0: + variables: + RUBYGEMS_VERSION: "3.5.23" + APPRAISAL: ruby_3_0 + K_SOUP_COV_DO: false + <<: *test_definition-legacy + parallel: + matrix: + - RUBY_VERSION: ["3.0"] + +ruby-ruby2_7: + variables: + RUBYGEMS_VERSION: "3.4.22" + APPRAISAL: ruby_2_7 + K_SOUP_COV_DO: false + <<: *test_definition-legacy + parallel: + matrix: + - RUBY_VERSION: ["2.7"] diff --git a/.idea/.gitignore b/.idea/.gitignore new file mode 100755 index 00000000..9df2ac9e --- /dev/null +++ b/.idea/.gitignore @@ -0,0 +1,15 @@ +# Default ignored files +/shelf/ +/workspace.xml +# Editor-based HTTP Client requests +/httpRequests/ +# Datasource local storage ignored files +/dataSources/ +/dataSources.local.xml + +# Zencoder local files +/zencoder/chats +/zencoder-chat-index.xml +/zencoder-chats-dedicated.xml +# Local project config +*.iml diff --git a/.idea/GitLink.xml b/.idea/GitLink.xml new file mode 100755 index 00000000..000fa355 --- /dev/null +++ b/.idea/GitLink.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/GitlabSettingsPlugin.xml b/.idea/GitlabSettingsPlugin.xml new file mode 100644 index 00000000..5ff494ba --- /dev/null +++ b/.idea/GitlabSettingsPlugin.xml @@ -0,0 +1,10 @@ + + + + + + \ No newline at end of file diff --git a/.idea/active-tab-highlighter.xml b/.idea/active-tab-highlighter.xml new file mode 100755 index 00000000..409aba97 --- /dev/null +++ b/.idea/active-tab-highlighter.xml @@ -0,0 +1,13 @@ + + + + + + \ No newline at end of file diff --git a/.idea/codestream.xml b/.idea/codestream.xml new file mode 100755 index 00000000..3ec0bd41 --- /dev/null +++ b/.idea/codestream.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/copilot.data.migration.agent.xml b/.idea/copilot.data.migration.agent.xml new file mode 100644 index 00000000..4ea72a91 --- /dev/null +++ b/.idea/copilot.data.migration.agent.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/copilot.data.migration.ask.xml b/.idea/copilot.data.migration.ask.xml new file mode 100644 index 00000000..7ef04e2e --- /dev/null +++ b/.idea/copilot.data.migration.ask.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/copilot.data.migration.ask2agent.xml b/.idea/copilot.data.migration.ask2agent.xml new file mode 100644 index 00000000..1f2ea11e --- /dev/null +++ b/.idea/copilot.data.migration.ask2agent.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/copilot.data.migration.edit.xml b/.idea/copilot.data.migration.edit.xml new file mode 100644 index 00000000..8648f940 --- /dev/null +++ b/.idea/copilot.data.migration.edit.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/csv-editor.xml b/.idea/csv-editor.xml new file mode 100644 index 00000000..b10a2bac --- /dev/null +++ b/.idea/csv-editor.xml @@ -0,0 +1,16 @@ + + + + + + \ No newline at end of file diff --git a/.idea/dbnavigator.xml b/.idea/dbnavigator.xml new file mode 100644 index 00000000..0910bc64 --- /dev/null +++ b/.idea/dbnavigator.xml @@ -0,0 +1,430 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/.idea/git_toolbox_blame.xml b/.idea/git_toolbox_blame.xml new file mode 100755 index 00000000..75202252 --- /dev/null +++ b/.idea/git_toolbox_blame.xml @@ -0,0 +1,11 @@ + + + + + + \ No newline at end of file diff --git a/.idea/git_toolbox_prj.xml b/.idea/git_toolbox_prj.xml new file mode 100755 index 00000000..02b915b8 --- /dev/null +++ b/.idea/git_toolbox_prj.xml @@ -0,0 +1,15 @@ + + + + + + + \ No newline at end of file diff --git a/.idea/kubernetes-settings.xml b/.idea/kubernetes-settings.xml new file mode 100755 index 00000000..7d8bbbaf --- /dev/null +++ b/.idea/kubernetes-settings.xml @@ -0,0 +1,6 @@ + + + + + \ No newline at end of file diff --git a/.idea/misc.xml b/.idea/misc.xml new file mode 100755 index 00000000..9f467935 --- /dev/null +++ b/.idea/misc.xml @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/.idea/modules.xml b/.idea/modules.xml new file mode 100755 index 00000000..74441e45 --- /dev/null +++ b/.idea/modules.xml @@ -0,0 +1,8 @@ + + + + + + + + \ No newline at end of file diff --git a/.idea/vcs.xml b/.idea/vcs.xml new file mode 100755 index 00000000..7ddfc9ed --- /dev/null +++ b/.idea/vcs.xml @@ -0,0 +1,12 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/.junie/guidelines-rbs.md b/.junie/guidelines-rbs.md new file mode 100644 index 00000000..9de89732 --- /dev/null +++ b/.junie/guidelines-rbs.md @@ -0,0 +1,49 @@ +# Junie Project Guidelines Addendum: RBS Documentation + +This repository ships RBS type signatures under `sig/` which are included in the published gem and referenced by documentation tooling. + +RBS files must contain only valid RBS syntax. Do not embed Ruby code or YARD-style Ruby documentation constructs in `.rbs` files. + +Requirements for RBS documentation and signatures: + +- Use RBS comment style (`# ...`) for notes and documentation inside `.rbs` files. +- Do not use Ruby heredocs (`<<-DOC`, `<<~RUBY`, etc.) or any Ruby code constructs in `.rbs` files. +- Do not use Ruby metaprogramming notation like `class << self` in `.rbs`. For singleton methods, use: + - `def self.method_name: ...` +- Do not use `extend self` or `module self` in `.rbs`. Declare singleton methods explicitly with `def self.method_name: ...`. +- Keep type aliases, interfaces, and method signatures in proper RBS form only (e.g., `def foo: (String) -> Integer`). +- If you need to document parameters or returns, place brief comments above the signature lines using `#` and keep them RBS-friendly (no `@param` / `@return` tags from YARD). + +Examples: + +Valid (RBS): + +``` +module Foo + # Runs tasks + def self.run: () -> void +end +``` + +Invalid (not allowed in .rbs): + +``` +# Ruby syntax – not RBS +class << self + def run: () -> void +end + +# Not supported across RBS versions; avoid in this project +module self + def run: () -> void +end + +# Heredocs or any Ruby bodies are not allowed in .rbs +def self.run: () -> void + <<~DOC +DOC +end +``` + +Enforcement: +- CI and local builds may parse `.rbs` files during gem install or doc generation. Any non-RBS syntax can cause installation to fail. Keep `.rbs` clean to avoid such failures. diff --git a/.junie/guidelines.md b/.junie/guidelines.md new file mode 100644 index 00000000..42844a0a --- /dev/null +++ b/.junie/guidelines.md @@ -0,0 +1,142 @@ +Project: oauth2 — Development Guidelines (for advanced contributors) + +This document captures project-specific knowledge to streamline setup, testing, and ongoing development. + +1. Build and configuration +- ENV is controlled by `direnv`. + - Two files are loaded: + - .envrc — environment variables for local development, committed to source control + - .env.local — environment variables that are not committed to source control. These setting override .envrc. + - Run `direnv allow` after making changes to .envrc or .env.local. + - See .envrc for details. + - See .env.local.example for an example of what to put in .env.local. + - See CONTRIBUTING.md for details on how to set up your local environment. +- Ruby and Bundler + - Runtime supports Ruby >= 2.2.0 + - Development tooling targets Ruby >= 2.3 (minimum supported by setup-ruby GHA). + - Use a recent Ruby (>= 3.4 recommended) for fastest setup and to exercise modern coverage behavior. + - Install dependencies via Bundler in project root: + - bundle install +- Rake tasks (preferred entry points) + - The Rakefile wires common workflows. Useful targets: + - rake spec — run RSpec suite (also aliased via rake test) + - rake coverage — run specs with coverage locally and open a report (requires kettle-soup-cover) + - rake rubocop_gradual:autocorrect — RuboCop-LTS Gradual, with autocorrect as default task + - rake reek and rake reek:update — code smell checks and persisted snapshots in REEK + - rake yard — generate YARD docs for lib and selected extra files + - rake bundle:audit and rake bundle:audit:update — dependency vulnerability checks + - rake build / rake release — gem build/release helper tasks (Bundler + stone_checksums) + - The default rake target runs a curated set of tasks; this varies for CI vs local (see CI env var logic in Rakefile). + - Always run the default rake task prior commits, and after making changes to lib/ code, or *.md files, to allow the linter to autocorrect, and to generate updated documentation. +- Coverage orchestration + - Coverage is controlled by kettle-soup-cover and .simplecov. Thresholds (line and branch) are enforced and can fail the process. + - Thresholds are primarily controlled by environment variables (see .simplecov and comments therein) typically loaded via direnv (.envrc) and CI workflow (.github/workflows/coverage.yml). When running only a test subset, thresholds may fail; see Testing below. +- Gem signing (for releases) + - Signing is enabled unless SKIP_GEM_SIGNING is set. If enabled and certificates are present (certs/.pem), gem build will attempt to sign using ~/.ssh/gem-private_key.pem. + - See CONTRIBUTING.md for releasing details; use SKIP_GEM_SIGNING when building in environments without the private key. + - Important for local testing (to avoid hanging prompts): ALWAYS skip signing when building locally to test the packaging or install process. Without the private key password, the build will wait indefinitely at a signing prompt. + - One-off commands (recommended): + - SKIP_GEM_SIGNING=true gem build oauth2.gemspec + - SKIP_GEM_SIGNING=true bundle exec rake build + - SKIP_GEM_SIGNING=true bundle exec rake release # only to test workflow; do not actually push + - direnv option (optional, not recommended globally): add `export SKIP_GEM_SIGNING=true` to your .env.local when you know you won’t be signing in this environment. + - Remove or unset SKIP_GEM_SIGNING when performing a real, signed release in the environment that has the private key. + +2. Testing +- Framework and helpers + - RSpec 3.13 with custom spec/spec_helper.rb configuration: + - silent_stream: STDOUT is silenced by default for examples to keep logs clean. + - To explicitly test console output, tag the example or group with :check_output. + - DEBUG toggle: Set DEBUG=true to require 'debug' and avoid silencing output during your run. + - Coverage: kettle-soup-cover integrates SimpleCov; .simplecov is invoked from spec_helper when enabled by Kettle::Soup::Cover::DO_COV, which is controlled by K_SOUP_COV_DO being set to true / false. + - RSpec.describe usage: + - Use `describe "#"` to contain a block of specs that test instance method behavior. + - Use `describe "::"` to contain a block of specs that test class method behavior. + - Do not use `describe "."` because the dot is ambiguous w.r.t instance vs. class methods. + - When adding new code or modifying existing code always add tests to cover the updated behavior, including branches, and different types of expected and unexpected inputs. + - Additional test utilities: + - rspec-stubbed_env: Use stub_env to control ENV safely within examples. + - timecop-rspec: Time manipulation is available, and is setup by kettle-test. + - To freeze time use `freeze: Time.new(*args)` tag on an example or group +- Running tests (verified) + - Full suite (recommended to satisfy coverage thresholds): + - bin/rspec + - or: bundle exec rspec + - or: bundle exec rake spec + - Progress format (less verbose): + - bundle exec rspec --format progress + - Focused runs + - You can run a single file or example, but note: coverage thresholds need to be disabled with K_SOUP_COV_MIN_HARD=false + - Example: K_SOUP_COV_MIN_HARD=false bin/rspec spec/oauth2/class_spec.rb:42 + - Output visibility + - To see STDOUT from the code under test, use the :check_output tag on the example or group. + Example: + RSpec.describe "with output", :check_output do + it "has output" do + output = capture(:stderr) {kernel.warn("This is a warning")} + logs = [ "This is a warning\n" ] + expect(output).to(include(*logs)) + end + end + - Alternatively, run with DEBUG=true to disable silencing for the entire run. + - During a spec run, the presence of output about missing activation keys is often expected, since it is literally what this library is for. It only indicates a failure if the spec expected all activation keys to be present, and not all specs do. +- Adding new tests (guidelines) + - Organize specs by class/module. Do not create per-task umbrella spec files; add examples to the existing spec for the class/module under test, or create a new spec file for that class/module if one does not exist. Only create a standalone scenario spec when it intentionally spans multiple classes for an integration/benchmark scenario (e.g., bench_integration_spec), and name it accordingly. + - Spec file names must map to a real class or module under lib/ (mirror the path). Do not introduce specs for non-existent classes or ad-hoc names (e.g., avoid template_helpers_replacements_spec.rb when testing Oauth2::TemplateHelpers; add those examples to template_helpers_spec.rb). + - REQUIRED: Provide unit tests for every class, module, constant, and public method. Place them in spec/ mirroring the path under lib/. When a file under lib/ is added or changed, ensure a corresponding spec file exists/updated for it. + - Add tests for all public methods and add contexts for variations of their arguments, and arity. + - This repository targets near-100% coverage of its public API; when you add new public methods, rake tasks to a rakelib, or config behavior, add or update specs accordingly. + - Place new specs under spec/ mirroring lib/ structure where possible. Do not require "spec_helper" at the top of spec files, as it is automatically loaded by .rspec. + - If your code relies on environment variables that drive activation (see "Activation env vars" below), prefer using rspec-stubbed_env: + - it does not support stubbing with blocks, but it does automatically clean up after itself. + - the below config is included in all spec scenarios by the kettle-test gem, so no need to do it again; it is here for reference: + include_context 'with stubbed env' + - in a before hook, or in an example: + stub_env("FLOSS_FUNDING_MY_NS" => "Free-as-in-beer") + + # example code continues + + - If your spec needs to assert on console output, tag it with :check_output. By default, STDOUT is silenced. + - Use Timecop for deterministic time-sensitive behavior as needed (require config/timecop is already done by spec_helper). + +- Types and documentation + - REQUIRED: All public APIs must have RBS type signatures checked into sig/ under the corresponding path. When you add a new public method or change a signature, update the matching .rbs file. + - REQUIRED: All public methods must include inline YARD docs with @param/@return (and @yield/@option where applicable). Generate docs with `bundle exec rake yard` to verify formatting. + +3. Additional development information +- Code style and static analysis + - RuboCop-LTS (Gradual) is integrated. Use: + - bundle exec rake rubocop_gradual:autocorrect + - bundle exec rake rubocop_gradual:force_update # only run if there are still linting violations the default rake task, which includes autocorrect locally, or a standalone autocorrect task, has run, and failed, and the violations won't be fixed + - Reek is configured to scan {lib,spec,tests}/**/*.rb. Use: + - bundle exec rake reek + - bundle exec rake reek:update # writes current output to REEK, fails on smells + - Keep REEK file updated with intentional smells snapshot when appropriate (e.g., after refactors). + - Locally, the default rake task includes reek:update. +- Documentation + - Generate YARD docs with: bundle exec rake yard. It includes lib/**/*.rb and extra docs like README.md, CHANGELOG.md, RUBOCOP.md, REEK, etc. +- Appraisal and multi-gemfile testing + - appraisal2 is present to manage multiple dependency sets; see Appraisals and gemfiles/modular/*.gemfile. If you need to verify against alternate dependency versions, use Appraisal to install and run rspec under those Gemfiles. + - You can run a single github workflow by running `act -W /github/workflows/.yml` +- CI/local differences and defaults + - The Rakefile adjusts default tasks based on CI env var. Locally, rake default may include coverage, reek:update, yard, etc. On CI, it tends to just run spec. + +Quick start +1) bundle install +2) K_SOUP_COV_FORMATTERS="json" bin/rspec (generates a JSON coverage report with both line and branch data in coverage/. Use this single format.) +3) Static analysis: bundle exec rake rubocop_gradual:check && bundle exec rake reek + +Notes +- ALWAYS Run bundle exec rake rubocop_gradual:autocorrect as the final step before completing a task, to lint and autocorrect any remaining issues. Then if there are new lint failures, attempt to correct them manually. +- NEVER run vanilla rubocop, as it won't handle the linting config properly. Always run rubocop_gradual:autocorrect or rubocop_gradual. +- Running only a subset of specs is supported but in order to bypass the hard failure due to coverage thresholds, you need to run with K_SOUP_COV_MIN_HARD=false. +- When adding code that writes to STDOUT, remember most specs silence output unless tagged with :check_output or DEBUG=true. +- Completion criteria after changes: Only consider your change “done” when the relevant examples pass, as verified by .rspec_status. Do not rely on STDOUT impressions; consult .rspec_status (and example IDs) to confirm green results for the affected files/examples. If you ran a subset, re-run the full suite before finalizing to restore coverage thresholds. +- Coverage reports: NEVER review the HTML report. Use JSON (preferred), XML, LCOV, or RCOV. For this project, always run tests with K_SOUP_COV_FORMATTERS set to "json". +- Do NOT modify .envrc in tasks; when running tests locally or in scripts, manually prefix each run, e.g.: K_SOUP_COV_FORMATTERS="json" bin/rspec +- For all the kettle-soup-cover options, see .envrc and find the K_SOUP_COV_* env vars. +- NEVER modify ENV variables in tests directly. Always use the stub_env macro from the rspec-stubbed_env gem (more details in the testing section above). + +Important documentation rules +- Do NOT edit files under docs/ manually; they are generated by `bundle exec rake yard` as part of the default rake task. +- Clarification: Executable scripts provided by this gem (exe/* and installed binstubs) work when the gem is installed as a system gem (gem install oauth2). However, the Rake tasks provided by this gem require oauth2 to be declared as a development dependency in the host project's Gemfile and loaded in the project's Rakefile. diff --git a/.licenserc.yaml b/.licenserc.yaml new file mode 100644 index 00000000..0eb99818 --- /dev/null +++ b/.licenserc.yaml @@ -0,0 +1,7 @@ +header: + license: + spdx-id: MIT + +dependency: + files: + - Gemfile.lock diff --git a/.opencollective.yml b/.opencollective.yml new file mode 100644 index 00000000..30032d6b --- /dev/null +++ b/.opencollective.yml @@ -0,0 +1,3 @@ +collective: "ruby-oauth" +readme-backers-commit-subject: "💸 Thanks 🙏 to our new backers 🎒 and subscribers 📜" +readme-osc-tag: "OPENCOLLECTIVE" diff --git a/.overcommit.yml b/.overcommit.yml new file mode 100644 index 00000000..9fbb7f23 --- /dev/null +++ b/.overcommit.yml @@ -0,0 +1,31 @@ +# Use this file to configure the Overcommit hooks you wish to use. This will +# extend the default configuration defined in: +# https://github.com/sds/overcommit/blob/master/config/default.yml +# +# At the topmost level of this YAML file is a key representing type of hook +# being run (e.g. pre-commit, commit-msg, etc.). Within each type you can +# customize each hook, such as whether to only run it on certain files (via +# `include`), whether to only display output if it fails (via `quiet`), etc. +# +# For a complete list of hooks, see: +# https://github.com/sds/overcommit/tree/master/lib/overcommit/hook +# +# For a complete list of options that you can use to customize hooks, see: +# https://github.com/sds/overcommit#configuration +# +# Uncomment the following lines to make the configuration take effect. + +PreCommit: + RuboCop: + enabled: true + on_warn: fail # Treat all warnings as failures + + TrailingWhitespace: + enabled: true + +PostCheckout: + ALL: # Special hook name that customizes all hooks of this type + quiet: true # Change all post-checkout hooks to only display output on failure +# +# IndexTags: +# enabled: true # Generate a tags file with `ctags` each time HEAD changes diff --git a/.qlty/qlty.toml b/.qlty/qlty.toml new file mode 100644 index 00000000..9ae9cae8 --- /dev/null +++ b/.qlty/qlty.toml @@ -0,0 +1,79 @@ +# For a guide to configuration, visit https://qlty.sh/d/config +# Or for a full reference, visit https://qlty.sh/d/qlty-toml +config_version = "0" + +exclude_patterns = [ + "*_min.*", + "*-min.*", + "*.min.*", + "**/.yarn/**", + "**/*.d.ts", + "**/assets/**", + "**/bin/**", + "**/bower_components/**", + "**/build/**", + "**/cache/**", + "**/config/**", + "**/.devcontainer", + "**/db/**", + "**/deps/**", + "**/dist/**", + "**/doc/**", + "**/docs/**", + "**/extern/**", + "**/external/**", + "**/generated/**", + "**/Godeps/**", + "**/gradlew/**", + "**/mvnw/**", + "**/node_modules/**", + "**/protos/**", + "**/seed/**", + "**/target/**", + "**/templates/**", + "**/testdata/**", + "**/vendor/**", + ".github/workflows/codeql-analysis.yml" +] + +test_patterns = [ + "**/test/**", + "**/spec/**", + "**/*.test.*", + "**/*.spec.*", + "**/*_test.*", + "**/*_spec.*", + "**/test_*.*", + "**/spec_*.*", +] + +[smells] +mode = "comment" + +[smells.boolean_logic] +threshold = 4 +enabled = true + +[smells.file_complexity] +threshold = 55 +enabled = false + +[smells.return_statements] +threshold = 4 +enabled = true + +[smells.nested_control_flow] +threshold = 4 +enabled = true + +[smells.function_parameters] +threshold = 4 +enabled = true + +[smells.function_complexity] +threshold = 5 +enabled = true + +[smells.duplication] +enabled = true +threshold = 20 \ No newline at end of file diff --git a/.rspec b/.rspec index 2db90875..a43744c2 100644 --- a/.rspec +++ b/.rspec @@ -1,4 +1,9 @@ ---format documentation ---require spec_helper +--format progress --color --order random +--require spec_helper +--warnings +--format html +--out results/test_results.html +--format RspecJunitFormatter +--out results/test_results.xml diff --git a/.rubocop.yml b/.rubocop.yml index c6a41973..485f75b4 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -1,30 +1,36 @@ -require: rubocop-rspec +inherit_gem: + rubocop-lts: config/rubygem_rspec.yml + inherit_from: - - .rubocop_todo.yml - .rubocop_rspec.yml + +plugins: rubocop-on-rbs + +RBS: + Enabled: true + AllCops: DisplayCopNames: true # Display the name of the failing cops - TargetRubyVersion: 2.1 Exclude: - 'gemfiles/vendor/**/*' - 'vendor/**/*' - '**/.irbrc' -Gemspec/RequiredRubyVersion: - Enabled: false +Layout/IndentationConsistency: + Exclude: ['*.md'] Metrics/BlockLength: Enabled: false +Gemspec/RequiredRubyVersion: + Enabled: false + Metrics/BlockNesting: Max: 2 -Metrics/LineLength: +Layout/LineLength: Enabled: false -Metrics/MethodLength: - Max: 15 - Metrics/ParameterLists: Max: 4 @@ -44,11 +50,10 @@ Lint/UnusedBlockArgument: - 'vendor/**/*' - '**/.irbrc' -RSpec/DescribeClass: - Exclude: - - 'spec/examples/*' - -RSpec/NestedGroups: +# Test if we can turn this back on after upgrading rubocop-md. +# It is still an open issue, so not expecting it to be fixed. +# See: https://github.com/rubocop/rubocop-md/issues/28 +Layout/InitialIndentation: Enabled: false Style/ClassVars: @@ -73,8 +78,23 @@ Style/EmptyMethod: Style/Encoding: Enabled: false +# Does not work with older rubies +#Style/MapToHash: +# Enabled: false + +# Does not work with older rubies +#Style/RedundantBegin: +# Enabled: false + Style/TrailingCommaInArrayLiteral: EnforcedStyleForMultiline: comma Style/TrailingCommaInHashLiteral: EnforcedStyleForMultiline: comma + +Gemspec/DependencyVersion: + Enabled: false + +Lint/LiteralInInterpolation: + Exclude: + - 'spec/**/*.rb' diff --git a/.rubocop_gradual.lock b/.rubocop_gradual.lock new file mode 100644 index 00000000..ae390c31 --- /dev/null +++ b/.rubocop_gradual.lock @@ -0,0 +1,92 @@ +{ + "bin/bundle:3976421676": [ + [66, 5, 20, "ThreadSafety/ClassInstanceVariable: Avoid class instance variables.", 2485198147], + [78, 5, 74, "Style/InvertibleUnlessCondition: Prefer `if Gem.rubygems_version >= Gem::Version.new(\"2.7.0\")` over `unless Gem.rubygems_version < Gem::Version.new(\"2.7.0\")`.", 2453573257] + ], + "lib/oauth2.rb:2435263975": [ + [73, 11, 7, "ThreadSafety/ClassInstanceVariable: Avoid class instance variables.", 651502127] + ], + "lib/oauth2/access_token.rb:1962777363": [ + [64, 13, 5, "Style/IdenticalConditionalBranches: Move `t_key` out of the conditional.", 183811513], + [70, 13, 5, "Style/IdenticalConditionalBranches: Move `t_key` out of the conditional.", 183811513] + ], + "lib/oauth2/authenticator.rb:158201238": [ + [59, 5, 113, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 734523108] + ], + "lib/oauth2/filtered_attributes.rb:321265140": [ + [13, 5, 63, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 2901108034], + [24, 9, 25, "ThreadSafety/ClassInstanceVariable: Avoid class instance variables.", 2012823020], + [31, 9, 25, "ThreadSafety/ClassInstanceVariable: Avoid class instance variables.", 2012823020] + ], + "lib/oauth2/response.rb:2054901929": [ + [53, 5, 204, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 996912427] + ], + "spec/oauth2/access_token_spec.rb:3152504592": [ + [3, 1, 34, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/access_token*_spec.rb`.", 1972107547], + [854, 13, 25, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 770233088], + [924, 9, 101, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 3022740639], + [928, 9, 79, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 2507338967] + ], + "spec/oauth2/authenticator_spec.rb:853320290": [ + [3, 1, 36, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/authenticator*_spec.rb`.", 819808017], + [51, 15, 20, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 482779785], + [60, 15, 33, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 297534737], + [69, 15, 38, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 1480816240], + [79, 13, 23, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 2314399065] + ], + "spec/oauth2/client_spec.rb:2143306493": [ + [6, 1, 29, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/client*_spec.rb`.", 439549885], + [175, 7, 492, "RSpec/NoExpectationExample: No expectation found in this example.", 1272021224], + [194, 7, 592, "RSpec/NoExpectationExample: No expectation found in this example.", 3428877205], + [207, 15, 20, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 2320605227], + [222, 15, 20, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 1276531672], + [237, 15, 43, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 1383956904], + [252, 15, 43, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 3376202107], + [839, 5, 360, "RSpec/NoExpectationExample: No expectation found in this example.", 536201463], + [848, 5, 461, "RSpec/NoExpectationExample: No expectation found in this example.", 3392600621], + [859, 5, 340, "RSpec/NoExpectationExample: No expectation found in this example.", 244592251], + [987, 11, 99, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 3084776886], + [991, 11, 82, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 1524553529], + [999, 7, 89, "RSpec/NoExpectationExample: No expectation found in this example.", 4609419], + [1087, 11, 99, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 3084776886], + [1091, 11, 82, "Style/ClassMethodsDefinitions: Use `class << self` to define a class method.", 1524553529], + [1171, 17, 12, "RSpec/ContextWording: Context description should match /^when\\b/, /^with\\b/, or /^without\\b/.", 664794325] + ], + "spec/oauth2/error_spec.rb:1692696277": [ + [23, 1, 28, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/error*_spec.rb`.", 3385870076], + [93, 11, 460, "RSpec/NoExpectationExample: No expectation found in this example.", 3630511675], + [108, 11, 210, "RSpec/NoExpectationExample: No expectation found in this example.", 3948582233], + [240, 11, 534, "RSpec/NoExpectationExample: No expectation found in this example.", 3347340910], + [256, 11, 210, "RSpec/NoExpectationExample: No expectation found in this example.", 3948582233], + [314, 11, 534, "RSpec/NoExpectationExample: No expectation found in this example.", 3347340910], + [375, 11, 534, "RSpec/NoExpectationExample: No expectation found in this example.", 3347340910], + [391, 11, 210, "RSpec/NoExpectationExample: No expectation found in this example.", 3948582233] + ], + "spec/oauth2/response_spec.rb:4032173622": [ + [3, 1, 31, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/response*_spec.rb`.", 3190869319] + ], + "spec/oauth2/strategy/assertion_spec.rb:3524328522": [ + [6, 1, 42, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/strategy/assertion*_spec.rb`.", 3665690869] + ], + "spec/oauth2/strategy/auth_code_spec.rb:142083698": [ + [4, 1, 41, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/strategy/auth_code*_spec.rb`.", 1553708922] + ], + "spec/oauth2/strategy/base_spec.rb:2524881749": [ + [3, 1, 37, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/strategy/base*_spec.rb`.", 1951594922] + ], + "spec/oauth2/strategy/client_credentials_spec.rb:2609739899": [ + [3, 1, 50, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/strategy/client_credentials*_spec.rb`.", 690311422] + ], + "spec/oauth2/strategy/implicit_spec.rb:1595799281": [ + [3, 1, 41, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/strategy/implicit*_spec.rb`.", 3731171632] + ], + "spec/oauth2/strategy/password_spec.rb:331601826": [ + [3, 1, 41, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/strategy/password*_spec.rb`.", 3463323840] + ], + "spec/oauth2/version_spec.rb:1001406821": [ + [3, 1, 30, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2/version*_spec.rb`.", 1099517182] + ], + "spec/oauth2_spec.rb:4211477230": [ + [3, 1, 21, "RSpec/SpecFilePathFormat: Spec path should end with `o_auth2*_spec.rb`.", 3359091140] + ] +} diff --git a/.rubocop_rspec.yml b/.rubocop_rspec.yml index 347777dc..45f84ad3 100644 --- a/.rubocop_rspec.yml +++ b/.rubocop_rspec.yml @@ -1,6 +1,3 @@ -RSpec/FilePath: - Enabled: false - RSpec/MultipleExpectations: Enabled: false @@ -21,6 +18,17 @@ RSpec/InstanceVariable: RSpec/NestedGroups: Enabled: false - + RSpec/ExpectInHook: Enabled: false + +RSpec/DescribeClass: + Exclude: + - 'spec/examples/*' + +RSpec/MultipleMemoizedHelpers: + Enabled: false + +RSpec/SpecFilePathFormat: + CustomTransform: + "OAuth": "oauth" diff --git a/.rubocop_todo.yml b/.rubocop_todo.yml deleted file mode 100644 index e7701734..00000000 --- a/.rubocop_todo.yml +++ /dev/null @@ -1,15 +0,0 @@ -Style/HashSyntax: - EnforcedStyle: hash_rockets - -Style/Lambda: - Enabled: false - -Style/SymbolArray: - Enabled: false - -Style/EachWithObject: - Enabled: false - -# Once we drop Rubies that lack support for __dir__ we can turn this on. -Style/ExpandPathArguments: - Enabled: false diff --git a/.ruby-version b/.ruby-version deleted file mode 100644 index 24ba9a38..00000000 --- a/.ruby-version +++ /dev/null @@ -1 +0,0 @@ -2.7.0 diff --git a/.simplecov b/.simplecov new file mode 100644 index 00000000..af5bd1c0 --- /dev/null +++ b/.simplecov @@ -0,0 +1,7 @@ +require "kettle/soup/cover/config" + +# Minimum coverage thresholds are set by kettle-soup-cover. +# It is controlled by ENV variables, which are set in .envrc and loaded via `direnv allow` +# If the values for minimum coverage need to change, they should be changed both there, +# and in 2 places in .github/workflows/coverage.yml. +SimpleCov.start diff --git a/.tool-versions b/.tool-versions new file mode 100755 index 00000000..048c75ee --- /dev/null +++ b/.tool-versions @@ -0,0 +1,2 @@ +direnv 2.32.2 +ruby 3.4.7 diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 1e2c74fd..00000000 --- a/.travis.yml +++ /dev/null @@ -1,71 +0,0 @@ -before_install: - # rubygems 2.7.8 and greater include bundler - # - Ruby 2.2, and under, get RubyGems ~> 2.7.10, (includes bundler 1.17.3) - # - Anything else, including Ruby 2.3, and above, gets RubyGems ~> 3, and update bundler to latest - # - NOTE ON JRUBY: identifies as RUBY_VERSION ~> 1.9, 2.0, 2.3, or 2.5. - # - NOTE ON TRUFFLERUBY: identifies as RUBY_VERSION ~> 2.6 - - | - rv="$(ruby -e 'STDOUT.write RUBY_VERSION')" - echo "Discovered Ruby Version of =====> $rv" - if [ "$rv" \< "2.3" ]; then - gem update --system 2.7.10 - elif [ "$rv" \< "2.4" ]; then - gem update --system 2.7.10 --no-document - elif [ "$rv" = "2.5.3" ]; then - # JRUBY 9.2 Identifies as 2.5.3, and it fails to update rubygems - gem install --no-document bundler "bundler:>=2.0" - else - gem update --system --no-document --conservative - gem install --no-document bundler "bundler:>=2.0" - fi - -before_script: - - curl -L https://codeclimate.com/downloads/test-reporter/test-reporter-latest-linux-amd64 > ./cc-test-reporter - - chmod +x ./cc-test-reporter - - ./cc-test-reporter before-build - -after_script: - - ./cc-test-reporter after-build --exit-code $TRAVIS_TEST_RESULT - -bundler_args: --no-deployment --jobs 3 --retry 3 - -cache: bundler - -env: - global: - - JRUBY_OPTS="$JRUBY_OPTS -Xcli.debug=true --debug" - - CC_TEST_REPORTER_ID=29caf9cf27d27ae609c088feb9d4ba34460f7a39251f2e8615c9a16f3075530e - -language: ruby - -matrix: - allow_failures: - - rvm: jruby-head - - rvm: ruby-head - - rvm: truffleruby - - rvm: jruby-9.1 # jruby-9.1 often fails to download, thus failing the build. - - rvm: jruby-9.2 # jruby-9.2 often fails to download, thus failing the build. - fast_finish: true - include: - - rvm: 2.2 - gemfile: gemfiles/ruby_2.2.gemfile - - rvm: jruby-9.1 # targets MRI v2.3 - gemfile: gemfiles/jruby_9.1.gemfile - - rvm: 2.3 - gemfile: gemfiles/ruby_2.3.gemfile - - rvm: 2.4 - gemfile: gemfiles/ruby_2.4.gemfile - - rvm: jruby-9.2 # targets MRI v2.5 - gemfile: gemfiles/jruby_9.2.gemfile - - rvm: 2.5 - gemfile: gemfiles/ruby_2.5.gemfile - - rvm: 2.6 - gemfile: gemfiles/ruby_2.6.gemfile - - rvm: 2.7 - gemfile: gemfiles/ruby_2.7.gemfile - - rvm: jruby-head - gemfile: gemfiles/jruby_head.gemfile - - rvm: ruby-head - gemfile: gemfiles/ruby_head.gemfile - - rvm: truffleruby - gemfile: gemfiles/truffleruby.gemfile diff --git a/.yardopts b/.yardopts new file mode 100644 index 00000000..ab259161 --- /dev/null +++ b/.yardopts @@ -0,0 +1,12 @@ +--plugin fence +-e yard/fence/hoist.rb +--plugin junk +--plugin relative_markdown_links +--readme tmp/yard-fence/README.md +--charset utf-8 +--markup markdown +--output docs +'lib/**/*.rb' +- +'tmp/yard-fence/*.md' +'tmp/yard-fence/*.txt' diff --git a/Appraisal.root.gemfile b/Appraisal.root.gemfile new file mode 100644 index 00000000..a0001cd0 --- /dev/null +++ b/Appraisal.root.gemfile @@ -0,0 +1,12 @@ +# frozen_string_literal: true + +git_source(:github) { |repo_name| "https://github.com/#{repo_name}" } + +source "https://gem.coop/" + +# Appraisal Root Gemfile is for running appraisal to generate the Appraisal Gemfiles +# in gemfiles/*gemfile. +# On CI, we use it for the Appraisal-based builds. +# We do not load the standard Gemfile, as it is tailored for local development. + +gemspec diff --git a/Appraisals b/Appraisals new file mode 100644 index 00000000..5cacc191 --- /dev/null +++ b/Appraisals @@ -0,0 +1,219 @@ +# frozen_string_literal: true + +# HOW TO UPDATE APPRAISALS (will run rubocop_gradual's autocorrect afterward): +# bin/rake appraisals:update + +# Lock/Unlock Deps Pattern +# +# Two often conflicting goals resolved! +# +# - unlocked_deps.yml +# - All runtime & dev dependencies, but does not have a `gemfiles/*.gemfile.lock` committed +# - Uses an Appraisal2 "unlocked_deps" gemfile, and the current MRI Ruby release +# - Know when new dependency releases will break local dev with unlocked dependencies +# - Broken workflow indicates that new releases of dependencies may not work +# +# - locked_deps.yml +# - All runtime & dev dependencies, and has a `Gemfile.lock` committed +# - Uses the project's main Gemfile, and the current MRI Ruby release +# - Matches what contributors and maintainers use locally for development +# - Broken workflow indicates that a new contributor will have a bad time +# +appraise "unlocked_deps" do + eval_gemfile "modular/coverage.gemfile" + eval_gemfile "modular/documentation.gemfile" + eval_gemfile "modular/style.gemfile" + eval_gemfile "modular/optional.gemfile" + eval_gemfile "modular/x_std_libs.gemfile" +end + +# Used for head (nightly) releases of ruby, truffleruby, and jruby. +# Split into discrete appraisals if one of them needs a dependency locked discretely. +appraise "head" do + # Why is gem "cgi" here? See: https://github.com/vcr/vcr/issues/1057 + gem "cgi", ">= 0.5" + gem "benchmark", "~> 0.4", ">= 0.4.1" + eval_gemfile "modular/runtime_heads.gemfile" +end + +# Used for current releases of ruby, truffleruby, and jruby. +# Split into discrete appraisals if one of them needs a dependency locked discretely. +appraise "current" do + eval_gemfile "modular/x_std_libs.gemfile" +end + +# Test current Rubies against head versions of runtime dependencies +appraise "dep-heads" do + eval_gemfile "modular/runtime_heads.gemfile" +end + +appraise "ruby-2-4" do + eval_gemfile "modular/faraday_v1.gemfile" + eval_gemfile "modular/hashie_v1.gemfile" + eval_gemfile "modular/jwt_v1.gemfile" + eval_gemfile "modular/logger_v1_2.gemfile" + eval_gemfile "modular/multi_xml_v0_5.gemfile" + eval_gemfile "modular/rack_v1_6.gemfile" + eval_gemfile "modular/x_std_libs/r2.4/libs.gemfile" +end + +appraise "ruby-2-5" do + eval_gemfile "modular/faraday_v1.gemfile" + eval_gemfile "modular/hashie_v2.gemfile" + eval_gemfile "modular/jwt_v2.gemfile" + eval_gemfile "modular/logger_v1_5.gemfile" + eval_gemfile "modular/multi_xml_v0_6.gemfile" + eval_gemfile "modular/rack_v2.gemfile" + eval_gemfile "modular/x_std_libs/r2.6/libs.gemfile" +end + +appraise "ruby-2-6" do + eval_gemfile "modular/faraday_v2.gemfile" + eval_gemfile "modular/hashie_v3.gemfile" + eval_gemfile "modular/jwt_v2.gemfile" + eval_gemfile "modular/logger_v1_5.gemfile" + eval_gemfile "modular/multi_xml_v0_6.gemfile" + eval_gemfile "modular/rack_v3.gemfile" + eval_gemfile "modular/x_std_libs/r2.6/libs.gemfile" +end + +appraise "ruby-2-7" do + eval_gemfile "modular/faraday_v2.gemfile" + eval_gemfile "modular/hashie_v4.gemfile" + eval_gemfile "modular/jwt_v2.gemfile" + eval_gemfile "modular/logger_v1_7.gemfile" + eval_gemfile "modular/multi_xml_v0_6.gemfile" + eval_gemfile "modular/rack_v3.gemfile" + eval_gemfile "modular/x_std_libs/r2/libs.gemfile" +end + +appraise "ruby-3-0" do + eval_gemfile "modular/faraday_v2.gemfile" + eval_gemfile "modular/hashie_v5.gemfile" + eval_gemfile "modular/jwt_v2.gemfile" + eval_gemfile "modular/logger_v1_7.gemfile" + eval_gemfile "modular/multi_xml_v0_6.gemfile" + eval_gemfile "modular/rack_v3.gemfile" + eval_gemfile "modular/x_std_libs/r3.1/libs.gemfile" +end + +appraise "ruby-3-1" do + eval_gemfile "modular/faraday_v2.gemfile" + eval_gemfile "modular/hashie_v5.gemfile" + eval_gemfile "modular/jwt_v2.gemfile" + eval_gemfile "modular/logger_v1_7.gemfile" + eval_gemfile "modular/multi_xml_v0_6.gemfile" + eval_gemfile "modular/rack_v3.gemfile" + eval_gemfile "modular/x_std_libs/r3.1/libs.gemfile" +end + +appraise "ruby-3-2" do + eval_gemfile "modular/faraday_v2.gemfile" + eval_gemfile "modular/hashie_v5.gemfile" + eval_gemfile "modular/jwt_v2.gemfile" + eval_gemfile "modular/logger_v1_7.gemfile" + eval_gemfile "modular/multi_xml_v0_7.gemfile" + eval_gemfile "modular/rack_v3.gemfile" + eval_gemfile "modular/x_std_libs/r3/libs.gemfile" +end + +appraise "ruby-3-3" do + eval_gemfile "modular/faraday_v2.gemfile" + eval_gemfile "modular/hashie_v5.gemfile" + eval_gemfile "modular/jwt_v2.gemfile" + eval_gemfile "modular/logger_v1_7.gemfile" + eval_gemfile "modular/multi_xml_v0_7.gemfile" + eval_gemfile "modular/rack_v3.gemfile" + eval_gemfile "modular/x_std_libs/r3/libs.gemfile" +end + +# Only run security audit on the latest version of Ruby +appraise "audit" do + eval_gemfile "modular/audit.gemfile" + eval_gemfile "modular/faraday_v2.gemfile" + eval_gemfile "modular/hashie_v5.gemfile" + eval_gemfile "modular/jwt_v2.gemfile" + eval_gemfile "modular/logger_v1_7.gemfile" + eval_gemfile "modular/multi_xml_v0_7.gemfile" + eval_gemfile "modular/rack_v3.gemfile" + eval_gemfile "modular/x_std_libs.gemfile" +end + +# Only run coverage on the latest version of Ruby +appraise "coverage" do + eval_gemfile "modular/coverage.gemfile" + eval_gemfile "modular/faraday_v2.gemfile" + eval_gemfile "modular/hashie_v5.gemfile" + eval_gemfile "modular/jwt_v2.gemfile" + eval_gemfile "modular/logger_v1_7.gemfile" + eval_gemfile "modular/multi_xml_v0_7.gemfile" + eval_gemfile "modular/optional.gemfile" + eval_gemfile "modular/rack_v3.gemfile" + eval_gemfile "modular/x_std_libs.gemfile" +end + +# Only run linter on the latest version of Ruby (but, in support of oldest supported Ruby version) +appraise "style" do + eval_gemfile "modular/style.gemfile" + eval_gemfile "modular/x_std_libs.gemfile" +end + +appraise "ruby-2-3-hashie_v0" do + eval_gemfile "modular/faraday_v0.gemfile" + eval_gemfile "modular/hashie_v0.gemfile" + eval_gemfile "modular/jwt_v1.gemfile" + eval_gemfile "modular/logger_v1_2.gemfile" + eval_gemfile "modular/multi_xml_v0_5.gemfile" + eval_gemfile "modular/rack_v1_2.gemfile" + eval_gemfile "modular/x_std_libs/r2.3/libs.gemfile" +end + +appraise "ruby-2-3-hashie_v1" do + eval_gemfile "modular/faraday_v0.gemfile" + eval_gemfile "modular/hashie_v1.gemfile" + eval_gemfile "modular/jwt_v1.gemfile" + eval_gemfile "modular/logger_v1_2.gemfile" + eval_gemfile "modular/multi_xml_v0_5.gemfile" + eval_gemfile "modular/rack_v1_2.gemfile" + eval_gemfile "modular/x_std_libs/r2.3/libs.gemfile" +end + +appraise "ruby-2-3-hashie_v2" do + eval_gemfile "modular/faraday_v0.gemfile" + eval_gemfile "modular/hashie_v2.gemfile" + eval_gemfile "modular/jwt_v1.gemfile" + eval_gemfile "modular/logger_v1_2.gemfile" + eval_gemfile "modular/multi_xml_v0_5.gemfile" + eval_gemfile "modular/rack_v1_2.gemfile" + eval_gemfile "modular/x_std_libs/r2.3/libs.gemfile" +end + +appraise "ruby-2-3-hashie_v3" do + eval_gemfile "modular/faraday_v0.gemfile" + eval_gemfile "modular/hashie_v3.gemfile" + eval_gemfile "modular/jwt_v1.gemfile" + eval_gemfile "modular/logger_v1_2.gemfile" + eval_gemfile "modular/multi_xml_v0_5.gemfile" + eval_gemfile "modular/rack_v1_2.gemfile" + eval_gemfile "modular/x_std_libs/r2.3/libs.gemfile" +end + +appraise "ruby-2-3-hashie_v4" do + eval_gemfile "modular/faraday_v0.gemfile" + eval_gemfile "modular/hashie_v4.gemfile" + eval_gemfile "modular/jwt_v1.gemfile" + eval_gemfile "modular/logger_v1_2.gemfile" + eval_gemfile "modular/multi_xml_v0_5.gemfile" + eval_gemfile "modular/rack_v1_2.gemfile" + eval_gemfile "modular/x_std_libs/r2.3/libs.gemfile" +end + +appraise "ruby-2-3-hashie_v5" do + eval_gemfile "modular/faraday_v0.gemfile" + eval_gemfile "modular/hashie_v5.gemfile" + eval_gemfile "modular/jwt_v1.gemfile" + eval_gemfile "modular/logger_v1_2.gemfile" + eval_gemfile "modular/multi_xml_v0_5.gemfile" + eval_gemfile "modular/rack_v1_2.gemfile" + eval_gemfile "modular/x_std_libs/r2.3/libs.gemfile" +end diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ab56755..01e26c92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,56 +1,597 @@ -# Change Log +# Changelog + +[![SemVer 2.0.0][📌semver-img]][📌semver] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog] + All notable changes to this project will be documented in this file. -## [unreleased] +The format is based on [Keep a Changelog][📗keep-changelog], +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html), +and [yes][📌major-versions-not-sacred], platform and engine support are part of the [public API][📌semver-breaking]. +Please file a bug if you notice a violation of semantic versioning. + +[📌semver]: https://semver.org/spec/v2.0.0.html +[📌semver-img]: https://img.shields.io/badge/semver-2.0.0-FFDD67.svg?style=flat +[📌semver-breaking]: https://github.com/semver/semver/issues/716#issuecomment-869336139 +[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html +[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/ +[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-FFDD67.svg?style=flat + +## [Unreleased] + +### Added + +### Changed + +### Deprecated + +### Removed + +### Fixed + +### 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] +- COVERAGE: 100.00% -- 526/526 lines in 14 files +- BRANCH COVERAGE: 100.00% -- 178/178 branches in 14 files +- 90.48% documented + +### Added + +- [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 + +- TAG: [v2.0.16][2.0.16t] +- COVERAGE: 100.00% -- 520/520 lines in 14 files +- BRANCH COVERAGE: 100.00% -- 176/176 branches in 14 files +- 90.48% documented + +### Added + +- [gh!680][gh!680] - E2E example using mock test server added in v2.0.11 by @pboling + - mock-oauth2-server upgraded to v2.3.0 + - https://github.com/navikt/mock-oauth2-server + - `docker compose -f docker-compose-ssl.yml up -d --wait` + - `ruby examples/e2e.rb` + - `docker compose -f docker-compose-ssl.yml down` + - mock server readiness wait is 90s + - override via E2E_WAIT_TIMEOUT +- [gh!676][gh!676], [gh!679][gh!679] - Apache SkyWalking Eyes dependency license check by @pboling + +### Changed + +- [gh!678][gh!678] - Many improvements to make CI more resilient (past/future proof) by @pboling +- [gh!681][gh!681] - Upgrade to kettle-dev v1.1.19 + +[gh!676]: https://github.com/ruby-oauth/oauth2/pull/676 +[gh!678]: https://github.com/ruby-oauth/oauth2/pull/678 +[gh!679]: https://github.com/ruby-oauth/oauth2/pull/679 +[gh!680]: https://github.com/ruby-oauth/oauth2/pull/680 +[gh!681]: https://github.com/ruby-oauth/oauth2/pull/681 + +## [2.0.15] - 2025-09-08 + +- TAG: [v2.0.15][2.0.15t] +- COVERAGE: 100.00% -- 519/519 lines in 14 files +- BRANCH COVERAGE: 100.00% -- 174/174 branches in 14 files +- 90.48% documented + +### Added + +- [gh!671][gh!671] - Complete documentation example for Instagram by @pboling +- .env.local.example for contributor happiness +- note lack of builds for JRuby 9.2, 9.3 & Truffleruby 22.3, 23.0 + - [actions/runner - issues/2347][GHA-continue-on-error-ui] + - [community/discussions/15452][GHA-allow-failure] +- [gh!670][gh!670] - AccessToken: verb-dependent token transmission mode by @mrj + - e.g., Instagram GET=:query, POST/DELETE=:header + +### Changed + +- [gh!669][gh!669] - Upgrade to kettle-dev v1.1.9 by @pboling + +### Fixed + +- Remove accidentally duplicated lines, and fix typos in CHANGELOG.md +- point badge to the correct workflow for Ruby 2.3 (caboose.yml) + +[gh!669]: https://github.com/ruby-oauth/oauth2/pull/669 +[gh!670]: https://github.com/ruby-oauth/oauth2/pull/670 +[gh!671]: https://github.com/ruby-oauth/oauth2/pull/671 +[GHA-continue-on-error-ui]: https://github.com/actions/runner/issues/2347 +[GHA-allow-failure]: https://github.com/orgs/community/discussions/15452 + +## [2.0.14] - 2025-08-31 + +- TAG: [v2.0.14][2.0.14t] +- COVERAGE: 100.00% -- 519/519 lines in 14 files +- BRANCH COVERAGE: 100.00% -- 174/174 branches in 14 files +- 90.48% documented + +### Added + +- improved documentation by @pboling +- [gh!665][gh!665] - Document Mutual TLS (mTLS) usage with example in README (connection_opts.ssl client_cert/client_key and auth_scheme: :tls_client_auth) by @pboling +- [gh!666][gh!666] - Document usage of flat query params using Faraday::FlatParamsEncoder, with example URI, in README by @pboling + - Spec: verify flat params are preserved with Faraday::FlatParamsEncoder (skips on Faraday without FlatParamsEncoder) +- [gh!662][gh!662] - documentation notes in code comments and README highlighting OAuth 2.1 differences, with references, by @pboling + - PKCE required for auth code, + - exact redirect URI match, + - implicit/password grants omitted, + - avoid bearer tokens in query, + - refresh token guidance for public clients, + - simplified client definitions +- [gh!663][gh!663] - document how to implement an OIDC client with this gem in OIDC.md by @pboling + - also, list libraries built on top of the oauth2 gem that implement OIDC +- [gh!664][gh!664] - README: Add example for JHipster UAA (Spring Cloud) password grant, converted from Postman/Net::HTTP by @pboling + +[gh!662]: https://github.com/ruby-oauth/oauth2/pull/662 +[gh!663]: https://github.com/ruby-oauth/oauth2/pull/663 +[gh!664]: https://github.com/ruby-oauth/oauth2/pull/664 +[gh!665]: https://github.com/ruby-oauth/oauth2/pull/665 +[gh!666]: https://github.com/ruby-oauth/oauth2/pull/666 + +## [2.0.13] - 2025-08-30 + +- TAG: [v2.0.13][2.0.13t] +- COVERAGE: 100.00% -- 519/519 lines in 14 files +- BRANCH COVERAGE: 100.00% -- 174/174 branches in 14 files +- 90.48% documented + +### Added + +- [gh!656][gh!656] - Support revocation with URL-encoded parameters +- [gh!660][gh!660] - Inline yard documentation by @pboling +- [gh!660][gh!660] - Complete RBS types documentation by @pboling +- [gh!660][gh!660]- (more) Comprehensive documentation / examples by @pboling +- [gh!657][gh!657] - Updated documentation for org-rename by @pboling +- More funding links by @Aboling0 +- Documentation: Added docs/OIDC.md with OIDC 1.0 overview, example, and references + +### Changed + +- Upgrade Code of Conduct to Contributor Covenant 2.1 by @pboling +- [gh!660][gh!660] - Shrink post-install message by 4 lines by @pboling + +### Fixed + +- [gh!660][gh!660] - Links in README (including link to HEAD documentation) by @pboling + +### Security + +[gh!660]: https://github.com/ruby-oauth/oauth2/pull/660 +[gh!657]: https://github.com/ruby-oauth/oauth2/pull/657 +[gh!656]: https://github.com/ruby-oauth/oauth2/pull/656 + +## [2.0.12] - 2025-05-31 + +- TAG: [v2.0.12][2.0.12t] +- Line Coverage: 100.0% (520 / 520) +- Branch Coverage: 100.0% (174 / 174) +- 80.00% documented + +### Added + +- [gh!652][gh!652] - Support IETF rfc7515 JSON Web Signature - JWS by @mridang + - Support JWT `kid` for key discovery and management +- More Documentation by @pboling + - Documented Serialization Extensions + - Added Gatzo.com FLOSS logo by @Aboling0, CC BY-SA 4.0 +- Documentation site @ https://oauth2.galtzo.com now complete + +### Changed + +- Updates to gemspec (email, funding url, post install message) + +### Fixed + +- Documentation Typos by @pboling + +[gh!652]: https://github.com/ruby-oauth/oauth2/pull/652 + +## [2.0.11] - 2025-05-23 + +- TAG: [v2.0.11][2.0.11t] +- COVERAGE: 100.00% -- 518/518 lines in 14 files +- BRANCH COVERAGE: 100.00% -- 172/172 branches in 14 files +- 80.00% documented + +### Added + +- [gh!651](https://github.com/ruby-oauth/oauth2/pull/651) - `:snaky_hash_klass` option (@pboling) +- More documentation +- Codeberg as ethical mirror (@pboling) + - https://codeberg.org/ruby-oauth/oauth2 +- Don't check for cert if SKIP_GEM_SIGNING is set (@pboling) +- All runtime deps, including oauth-xx sibling gems, are now tested against HEAD (@pboling) +- All runtime deps, including ruby-oauth sibling gems, are now tested against HEAD (@pboling) +- YARD config, GFM compatible with relative file links (@pboling) +- Documentation site on GitHub Pages (@pboling) + - [oauth2.galtzo.com](https://oauth2.galtzo.com) +- [!649](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/649) - Test compatibility with all key minor versions of Hashie v0, v1, v2, v3, v4, v5, HEAD (@pboling) +- [gh!651](https://github.com/ruby-oauth/oauth2/pull/651) - Mock OAuth2 server for testing (@pboling) + - https://github.com/navikt/mock-oauth2-server + +### Changed + +- [gh!651](https://github.com/ruby-oauth/oauth2/pull/651) - Upgraded to snaky_hash v2.0.3 (@pboling) + - Provides solution for serialization issues +- Updated `spec.homepage_uri` in gemspec to GitHub Pages YARD documentation site (@pboling) + +### Fixed + +- [gh!650](https://github.com/ruby-oauth/oauth2/pull/650) - Regression in return type of `OAuth2::Response#parsed` (@pboling) +- Incorrect documentation related to silencing warnings (@pboling) + +## [2.0.10] - 2025-05-17 + +- TAG: [v2.0.10][2.0.10t] +- COVERAGE: 100.00% -- 518/518 lines in 14 files +- BRANCH COVERAGE: 100.00% -- 170/170 branches in 14 files +- 79.05% documented + +### Added + +- [gh!632](https://github.com/ruby-oauth/oauth2/pull/632) - Added `funding.yml` (@Aboling0) +- [!635](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/635) - Added `.gitlab-ci.yml` (@jessieay) +- [#638](https://gitlab.com/ruby-oauth/oauth2/-/issues/638) - Documentation of support for **ILO Fundamental Principles of Rights at Work** (@pboling) +- [!642](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/642) - 20-year certificate for signing gem releases, expires 2045-04-29 (@pboling) + - Gemspec metadata + - funding_uri + - news_uri + - mailing_list_uri + - SHA256 and SHA512 Checksums for release +- [!643](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/643) - Add `token_name` option (@pboling) + - Specify the parameter name that identifies the access token +- [!645](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/645) - Add `OAuth2::OAUTH_DEBUG` constant, based on `ENV["OAUTH_DEBUG"] (@pboling) +- [!646](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/646) - Add `OAuth2.config.silence_extra_tokens_warning`, default: false (@pboling) +- [!647](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/647) - Add IETF RFC 7009 Token Revocation compliant (@pboling) + - `OAuth2::Client#revoke_token` + - `OAuth2::AccessToken#revoke` + - See: https://datatracker.ietf.org/doc/html/rfc7009 +- [gh!644](https://github.com/ruby-oauth/oauth2/pull/644), [gh!645](https://github.com/ruby-oauth/oauth2/pull/645) - Added CITATION.cff (@Aboling0) +- [!648](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/648) - Improved documentation (@pboling) + +### Changed + +- Default value of `OAuth2.config.silence_extra_tokens_warning` was `false`, now `true` (@pboling) +- Gem releases are now cryptographically signed, with a 20-year cert (@pboling) + - Allow linux distros to build release without signing, as their package managers sign independently +- [!647](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/647) - `OAuth2::AccessToken#refresh` now supports block param pass through (@pboling) +- [!647](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/647) - `OAuth2.config` is no longer writable (@pboling) +- [!647](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/647) - Errors raised by `OAuth2::AccessToken` are now always `OAuth2::Error` and have better metadata (@pboling) + +### Fixed + +- [#95](https://gitlab.com/ruby-oauth/oauth2/-/issues/95) - restoring an access token via `AccessToken#from_hash` (@pboling) + - This was a 13 year old bug report. 😘 +- [#619](https://gitlab.com/ruby-oauth/oauth2/-/issues/619) - Internal options (like `snaky`, `raise_errors`, and `parse`) are no longer included in request (@pboling) +- [!633](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/633) - Spaces will now be encoded as `%20` instead of `+` (@nov.matake) +- [!634](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/634) - `CHANGELOG.md` documentation fix (@skuwa229) +- [!638](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/638) - fix `expired?` when `expires_in` is `0` (@disep) +- [!639](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/639) - Only instantiate `OAuth2::Error` if `raise_errors` option is `true` (@glytch2) +- [#639](https://gitlab.com/ruby-oauth/oauth2/-/issues/639) - `AccessToken#to_hash` is now serializable, just a regular Hash (@pboling) +- [!640](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/640) - `README.md` documentation fix (@martinezcoder) +- [!641](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/641) - Do not include sensitive information in the `inspect` (@manuelvanrijn) +- [#641](https://gitlab.com/ruby-oauth/oauth2/-/issues/641) - Made default JSON response parser more resilient (@pboling) +- [#645](https://gitlab.com/ruby-oauth/oauth2/-/issues/645) - Response no longer becomes a snaky hash (@pboling) +- [gh!646](https://github.com/ruby-oauth/oauth2/pull/646) - Change `require` to `require_relative` (improve performance) (@Aboling0) + +## [2.0.9] - 2022-09-16 + +- TAG: [v2.0.9][2.0.9t] + +### Added + +- More specs (@pboling) + +### Changed + +- Complete migration to main branch as default (@pboling) +- Complete migration to Gitlab, updating all links, and references in VCS-managed files (@pboling) + +## [2.0.8] - 2022-09-01 + +- TAG: [v2.0.8][2.0.8t] + +### Changed + +- [!630](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/630) - Extract snaky_hash to external dependency (@pboling) + +### Added + +- [!631](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/631) - New global configuration option OAuth2.config.silence_extra_tokens_warning (default: false) fixes [#628](https://gitlab.com/ruby-oauth/oauth2/-/issues/628) + +## [2.0.7] - 2022-08-22 + +- TAG: [v2.0.7][2.0.7t] + +### Added + +- [!629](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/629) - Allow POST of JSON to get token (@pboling, @terracatta) + +### Fixed + +- [!626](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/626) - Fixes a regression in 2.0.6. Will now prefer the key order from the lookup, not the hash keys (@rickselby) + - Note: This fixes compatibility with `omniauth-oauth2` and AWS +- [!625](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/625) - Fixes the printed version in the post install message (@hasghari) + +## [2.0.6] - 2022-07-13 + +- TAG: [v2.0.6][2.0.6t] + +### Fixed + +- [!624](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/624) - Fixes a [regression](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/623) in v2.0.5, where an error would be raised in refresh_token flows due to (legitimate) lack of access_token (@pboling) + +## [2.0.5] - 2022-07-07 + +- TAG: [v2.0.5][2.0.5t] + +### Fixed + +- [!620](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/620) - Documentation improvements, to help with upgrading (@swanson) +- [!621](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/621) - Fixed [#528](https://gitlab.com/ruby-oauth/oauth2/-/issues/528) and [#619](https://gitlab.com/ruby-oauth/oauth2/-/issues/619) (@pboling) + - All data in responses is now returned, with the access token removed and set as `token` + - `refresh_token` is no longer dropped + - **BREAKING**: Microsoft's `id_token` is no longer left as `access_token['id_token']`, but moved to the standard `access_token.token` that all other strategies use + - Remove `parse` and `snaky` from options so they don't get included in response + - There is now 100% test coverage, for lines _and_ branches, and it will stay that way. + +## [2.0.4] - 2022-07-01 + +- TAG: [v2.0.4][2.0.4t] + +### Fixed + +- [!618](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/618) - In some scenarios the `snaky` option default value was not applied (@pboling) + +## [2.0.3] - 2022-06-28 + +- TAG: [v2.0.3][2.0.3t] -- Update testing infrastructure for all supported Rubies (@pboling and @josephpage) -- **Breaking**: Set `:basic_auth` as default for `:auth_scheme` instead of `:request_body`. This was default behavior before 1.3.0. See [#285](https://github.com/oauth-xx/oauth2/issues/285) (@tetsuya, @wy193777) -- Token is expired if `expired_at` time is now (@davestevens) -- Set the response object on the access token on Client#get_token (@cpetschnig) -- Fix "Unexpected middleware set" issue with Faraday when `OAUTH_DEBUG=true` (@spectator, @gafrom) -- Oauth2::Error : Error codes are strings instead of symbols (@NobodysNightmare) -- _Dependency_: Upgrade Faraday to 0.13.x (@zacharywelch) -- _Dependency_: Upgrade jwt to 2.x.x (@travisofthenorth) -- Fix logging to `$stdout` of request and response bodies via Faraday's logger and `ENV["OAUTH_DEBUG"] == 'true'` (@pboling) -- **Security**: Add checks to enforce `client_secret` is *never* passed in authorize_url query params (@dfockler) +### Added + +- [!611](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/611) - Proper deprecation warnings for `extract_access_token` argument (@pboling) +- [!612](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/612) - Add `snaky: false` option to skip conversion to `OAuth2::SnakyHash` (default: true) (@pboling) + +### Fixed + +- [!608](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/608) - Wrap `Faraday::TimeoutError` in `OAuth2::TimeoutError` (@nbibler) +- [!615](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/615) - Fix support for requests with blocks, see `Faraday::Connection#run_request` (@pboling) + +## [2.0.2] - 2022-06-24 + +- TAG: [v2.0.2][2.0.2t] + +### Fixed + +- [!604](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/604) - Wrap `Faraday::TimeoutError` in `OAuth2::TimeoutError` (@stanhu) +- [!606](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/606) - Ruby 2.7 deprecation warning fix: Move `access_token_class` parameter into `Client` constructor (@stanhu) +- [!607](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/607) - CHANGELOG correction, reference to `OAuth2::ConnectionError` (@zavan) + +## [2.0.1] - 2022-06-22 + +- TAG: [v2.0.1][2.0.1t] + +### Added + +- Documentation improvements (@pboling) +- Increased test coverage to 99% (@pboling) + +## [2.0.0] - 2022-06-21 + +- TAG: [v2.0.0][2.0.0t] + +### Added + +- [!158](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/158), [!344](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/344) - Optionally pass raw response to parsers (@niels) +- [!190](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/190), [!332](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/332), [!334](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/334), [!335](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/335), [!360](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/360), [!426](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/426), [!427](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/427), [!461](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/461) - Documentation (@josephpage, @pboling, @meganemura, @joshRpowell, @elliotcm) +- [!220](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/220) - Support IETF rfc7523 JWT Bearer Tokens Draft 04+ (@jhmoore) +- [!298](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/298) - Set the response object on the access token on Client#get_token for debugging (@cpetschnig) +- [!305](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/305) - Option: `OAuth2::Client#get_token` - `:access_token_class` (`AccessToken`); user specified class to use for all calls to `get_token` (@styd) +- [!346](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/571) - Modern gem structure (@pboling) +- [!351](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/351) - Support Jruby 9k (@pboling) +- [!362](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/362) - Support SemVer release version scheme (@pboling) +- [!363](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/363) - New method `OAuth2::AccessToken#refresh!` same as old `refresh`, with backwards compatibility alias (@pboling) +- [!364](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/364) - Support `application/hal+json` format (@pboling) +- [!365](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/365) - Support `application/vnd.collection+json` format (@pboling) +- [!376](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/376) - _Documentation_: Example / Test for Google 2-legged JWT (@jhmoore) +- [!381](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/381) - Spec for extra header params on client credentials (@nikz) +- [!394](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/394) - Option: `OAuth2::AccessToken#initialize` - `:expires_latency` (`nil`); number of seconds by which AccessToken validity will be reduced to offset latency (@klippx) +- [!412](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/412) - Support `application/vdn.api+json` format (from jsonapi.org) (@david-christensen) +- [!413](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/413) - _Documentation_: License scan and report (@meganemura) +- [!442](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/442) - Option: `OAuth2::Client#initialize` - `:logger` (`::Logger.new($stdout)`) logger to use when OAUTH_DEBUG is enabled (for parity with `1-4-stable` branch) (@rthbound) +- [!494](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/494) - Support [OIDC 1.0 Private Key JWT](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication); based on the OAuth JWT assertion specification [(RFC 7523)](https://tools.ietf.org/html/rfc7523) (@SteveyblamWork) +- [!549](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/549) - Wrap `Faraday::ConnectionFailed` in `OAuth2::ConnectionError` (@nikkypx) +- [!550](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/550) - Raise error if location header not present when redirecting (@stanhu) +- [!552](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/552) - Add missing `version.rb` require (@ahorek) +- [!553](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/553) - Support `application/problem+json` format (@janz93) +- [!560](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/560) - Support IETF rfc6749, section 2.3.1 - don't set auth params when `nil` (@bouk) +- [!571](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/571) - Support Ruby 3.1 (@pboling) +- [!575](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/575) - Support IETF rfc7231, section 7.1.2 - relative location in redirect (@pboling) +- [!581](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/581) - _Documentation_: of breaking changes (@pboling) + +### Changed + +- [!191](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/191) - **BREAKING**: Token is expired if `expired_at` time is `now` (@davestevens) +- [!312](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/312) - **BREAKING**: Set `:basic_auth` as default for `:auth_scheme` instead of `:request_body`. This was default behavior before 1.3.0. (@tetsuya, @wy193777) +- [!317](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/317) - _Dependency_: Upgrade `jwt` to 2.x.x (@travisofthenorth) +- [!338](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/338) - _Dependency_: Switch from `Rack::Utils.escape` to `CGI.escape` (@josephpage) +- [!339](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/339), [!368](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/368), [!424](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/424), [!479](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/479), [!493](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/493), [!539](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/539), [!542](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/542), [!553](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/553) - CI Updates, code coverage, linting, spelling, type fixes, New VERSION constant (@pboling, @josephpage, @ahorek) +- [!410](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/410) - **BREAKING**: Removed the ability to call .error from an OAuth2::Response object (@jhmoore) +- [!414](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/414) - Use Base64.strict_encode64 instead of custom internal logic (@meganemura) +- [!469](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/469) - **BREAKING**: Default value for option `OAuth2::Client` - `:authorize_url` removed leading slash to work with relative paths by default (`'oauth/authorize'`) (@ghost) +- [!469](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/469) - **BREAKING**: Default value for option `OAuth2::Client` - `:token_url` removed leading slash to work with relative paths by default (`'oauth/token'`) (@ghost) +- [!507](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/507), [!575](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/575) - **BREAKING**: Transform keys to snake case, always, by default (ultimately via `rash_alt` gem) + - Original keys will still work as previously, in most scenarios, thanks to `rash_alt` gem. + - However, this is a _breaking_ change if you rely on `response.parsed.to_h`, as the keys in the result will be snake case. + - As of version 2.0.4 you can turn key transformation off with the `snaky: false` option. +- [!576](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/576) - **BREAKING**: Stop rescuing parsing errors (@pboling) +- [!591](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/576) - _DEPRECATION_: `OAuth2::Client` - `:extract_access_token` option is deprecated + +### Fixed + +- [!158](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/158), [!344](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/344) - Handling of errors when using `omniauth-facebook` (@niels) +- [!294](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/294) - Fix: "Unexpected middleware set" issue with Faraday when `OAUTH_DEBUG=true` (@spectator, @gafrom) +- [!300](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/300) - _Documentation_: `Oauth2::Error` - Error codes are strings, not symbols (@NobodysNightmare) +- [!318](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/318), [!326](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/326), [!343](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/343), [!347](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/347), [!397](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/397), [!464](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/464), [!561](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/561), [!565](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/565) - _Dependency_: Support all versions of `faraday` (see [gemfiles/README.md][gemfiles/readme] for compatibility matrix with Ruby engines & versions) (@pboling, @raimondasv, @zacharywelch, @Fudoshiki, @ryogift, @sj26, @jdelStrother) +- [!322](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/322), [!331](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/331), [!337](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/337), [!361](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/361), [!371](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/371), [!377](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/377), [!383](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/383), [!392](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/392), [!395](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/395), [!400](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/400), [!401](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/401), [!403](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/403), [!415](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/415), [!567](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/567) - Updated Rubocop, Rubocop plugins and improved code style (@pboling, @bquorning, @lautis, @spectator) +- [!328](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/328) - _Documentation_: Homepage URL is SSL (@amatsuda) +- [!339](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/339), [!479](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/479) - Update testing infrastructure for all supported Rubies (@pboling and @josephpage) +- [!366](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/366) - **Security**: Fix logging to `$stdout` of request and response bodies via Faraday's logger and `ENV["OAUTH_DEBUG"] == 'true'` (@pboling) +- [!380](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/380) - Fix: Stop attempting to encode non-encodable objects in `Oauth2::Error` (@jhmoore) +- [!399](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/399) - Fix: Stop duplicating `redirect_uri` in `get_token` (@markus) +- [!410](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/410) - Fix: `SystemStackError` caused by circular reference between Error and Response classes (@jhmoore) +- [!460](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/460) - Fix: Stop throwing errors when `raise_errors` is set to `false`; analog of [!524](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/524) for `1-4-stable` branch (@joaolrpaulo) +- [!472](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/472) - **Security**: Add checks to enforce `client_secret` is *never* passed in authorize_url query params for `implicit` and `auth_code` grant types (@dfockler) +- [!482](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/482) - _Documentation_: Update last of `intridea` links to `ruby-oauth` (@pboling) +- [!536](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/536) - **Security**: Compatibility with more (and recent) Ruby OpenSSL versions, Github Actions, Rubocop updated, analogous to [!535](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/535) on `1-4-stable` branch (@pboling) +- [!595](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/595) - Graceful handling of empty responses from `Client#get_token`, respecting `:raise_errors` config (@stanhu) +- [!596](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/596) - Consistency between `AccessToken#refresh` and `Client#get_token` named arguments (@stanhu) +- [!598](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/598) - Fix unparseable data not raised as error in `Client#get_token`, respecting `:raise_errors` config (@stanhu) + +### Removed + +- [!341](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/341) - Remove Rdoc & Jeweler related files (@josephpage) +- [!342](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/342) - **BREAKING**: Dropped support for Ruby 1.8 (@josephpage) +- [!539](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/539) - Remove reliance on globally included OAuth2 in tests, analog of [!538](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/538) for 1-4-stable (@anderscarling) +- [!566](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/566) - _Dependency_: Removed `wwtd` (@bquorning) +- [!589](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/589), [!593](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/593) - Remove support for expired MAC token draft spec (@stanhu) +- [!590](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/590) - _Dependency_: Removed `multi_json` (@stanhu) + +## [1.4.11] - 2022-09-16 + +- TAG: [v1.4.11][1.4.11t] +- Complete migration to main branch as default (@pboling) +- Complete migration to Gitlab, updating all links, and references in VCS-managed files (@pboling) + +## [1.4.10] - 2022-07-01 + +- TAG: [v1.4.10][1.4.10t] +- FIPS Compatibility [!587](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/587) (@akostadinov) + +## [1.4.9] - 2022-02-20 + +- TAG: [v1.4.9][1.4.9t] +- Fixes compatibility with Faraday v2 [572](https://gitlab.com/ruby-oauth/oauth2/-/issues/572) +- Includes supported versions of Faraday in test matrix: + - Faraday ~> 2.2.0 with Ruby >= 2.6 + - Faraday ~> 1.10 with Ruby >= 2.4 + - Faraday ~> 0.17.3 with Ruby >= 1.9 +- Add Windows and MacOS to test matrix + +## [1.4.8] - 2022-02-18 + +- TAG: [v1.4.8][1.4.8t] +- MFA is now required to push new gem versions (@pboling) +- README overhaul w/ new Ruby Version and Engine compatibility policies (@pboling) +- [!569](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/569) Backport fixes ([!561](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/561) by @ryogift), and add more fixes, to allow faraday 1.x and 2.x (@jrochkind) +- Improve Code Coverage tracking (Coveralls, CodeCov, CodeClimate), and enable branch coverage (@pboling) +- Add CodeQL, Security Policy, Funding info (@pboling) +- Added Ruby 3.1, jruby, jruby-head, truffleruby, truffleruby-head to build matrix (@pboling) +- [!543](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/543) - Support for more modern Open SSL libraries (@pboling) + +## [1.4.7] - 2021-03-19 + +- TAG: [v1.4.7][1.4.7t] +- [!541](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/541) - Backport fix to expires_at handling [!533](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/533) to 1-4-stable branch. (@dobon) + +## [1.4.6] - 2021-03-19 + +- TAG: [v1.4.6][1.4.6t] +- [!540](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/540) - Add VERSION constant (@pboling) +- [!537](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/537) - Fix crash in OAuth2::Client#get_token (@anderscarling) +- [!538](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/538) - Remove reliance on globally included OAuth2 in tests, analogous to [!539](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/539) on main branch (@anderscarling) + +## [1.4.5] - 2021-03-18 + +- TAG: [v1.4.5][1.4.5t] +- [!535](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/535) - Compatibility with range of supported Ruby OpenSSL versions, Rubocop updates, Github Actions, analogous to [!536](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/536) on main branch (@pboling) +- [!518](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/518) - Add extract_access_token option to OAuth2::Client (@jonspalmer) +- [!507](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/507) - Fix camel case content type, response keys (@anvox) +- [!500](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/500) - Fix YARD documentation formatting (@olleolleolle) ## [1.4.4] - 2020-02-12 -- [#408](https://github.com/oauth-xx/oauth2/pull/408) - Fixed expires_at for formatted time (@Lomey) +- TAG: [v1.4.4][1.4.4t] +- [!408](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/408) - Fixed expires_at for formatted time (@Lomey) ## [1.4.3] - 2020-01-29 -- [#483](https://github.com/oauth-xx/oauth2/pull/483) - add project metadata to gemspec (@orien) -- [#495](https://github.com/oauth-xx/oauth2/pull/495) - support additional types of access token requests (@SteveyblamFreeagent, @thomcorley, @dgholz) - - Adds support for private_key_jwt and tls_client_auth -- [#433](https://github.com/oauth-xx/oauth2/pull/433) - allow field names with square brackets and numbers in params (@asm256) +- TAG: [v1.4.3][1.4.3t] +- [!483](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/483) - add project metadata to gemspec (@orien) +- [!495](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/495) - support additional types of access token requests (@SteveyblamFreeagent, @thomcorley, @dgholz) + - Adds support for private_key_jwt and tls_client_auth +- [!433](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/433) - allow field names with square brackets and numbers in params (@asm256) ## [1.4.2] - 2019-10-01 -- [#478](https://github.com/oauth-xx/oauth2/pull/478) - support latest version of faraday & fix build (@pboling) - - Officially support Ruby 2.6 and truffleruby +- TAG: [v1.4.2][1.4.2t] +- [!478](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/478) - support latest version of faraday & fix build (@pboling) + - Officially support Ruby 2.6 and truffleruby ## [1.4.1] - 2018-10-13 -- [#417](https://github.com/oauth-xx/oauth2/pull/417) - update jwt dependency (@thewoolleyman) -- [#419](https://github.com/oauth-xx/oauth2/pull/419) - remove rubocop dependency (temporary, added back in [#423](https://github.com/oauth-xx/oauth2/pull/423)) (@pboling) -- [#418](https://github.com/oauth-xx/oauth2/pull/418) - update faraday dependency (@pboling) -- [#420](https://github.com/oauth-xx/oauth2/pull/420) - update [oauth2.gemspec](https://github.com/oauth-xx/oauth2/blob/1-4-stable/oauth2.gemspec) (@pboling) -- [#421](https://github.com/oauth-xx/oauth2/pull/421) - fix [CHANGELOG.md](https://github.com/oauth-xx/oauth2/blob/1-4-stable/CHANGELOG.md) for previous releases (@pboling) -- [#422](https://github.com/oauth-xx/oauth2/pull/422) - update [LICENSE](https://github.com/oauth-xx/oauth2/blob/1-4-stable/LICENSE) and [README.md](https://github.com/oauth-xx/oauth2/blob/1-4-stable/README.md) (@pboling) -- [#423](https://github.com/oauth-xx/oauth2/pull/423) - update [builds](https://travis-ci.org/oauth-xx/oauth2/builds), [Rakefile](https://github.com/oauth-xx/oauth2/blob/1-4-stable/Rakefile) (@pboling) - - officially document supported Rubies - * Ruby 1.9.3 - * Ruby 2.0.0 - * Ruby 2.1 - * Ruby 2.2 - * [JRuby 1.7][jruby-1.7] (targets MRI v1.9) - * [JRuby 9.0][jruby-9.0] (targets MRI v2.0) - * Ruby 2.3 - * Ruby 2.4 - * Ruby 2.5 - * [JRuby 9.1][jruby-9.1] (targets MRI v2.3) - * [JRuby 9.2][jruby-9.2] (targets MRI v2.5) +- TAG: [v1.4.1][1.4.1t] +- [!417](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/417) - update jwt dependency (@thewoolleyman) +- [!419](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/419) - remove rubocop dependency (temporary, added back in [!423](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/423)) (@pboling) +- [!418](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/418) - update faraday dependency (@pboling) +- [!420](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/420) - update [oauth2.gemspec](https://gitlab.com/ruby-oauth/oauth2/-/blob/1-4-stable/oauth2.gemspec) (@pboling) +- [!421](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/421) - fix [CHANGELOG.md](https://gitlab.com/ruby-oauth/oauth2/-/blob/1-4-stable/CHANGELOG.md) for previous releases (@pboling) +- [!422](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/422) - update [LICENSE](https://gitlab.com/ruby-oauth/oauth2/-/blob/1-4-stable/LICENSE) and [README.md](https://gitlab.com/ruby-oauth/oauth2/-/blob/1-4-stable/README.md) (@pboling) +- [!423](https://gitlab.com/ruby-oauth/oauth2/-/merge_requests/423) - update [builds](https://travis-ci.org/ruby-oauth/oauth2/builds), [Rakefile](https://gitlab.com/ruby-oauth/oauth2/-/blob/1-4-stable/Rakefile) (@pboling) + - officially document supported Rubies + * Ruby 1.9.3 + * Ruby 2.0.0 + * Ruby 2.1 + * Ruby 2.2 + * [JRuby 1.7][jruby-1.7] (targets MRI v1.9) + * [JRuby 9.0][jruby-9.0] (targets MRI v2.0) + * Ruby 2.3 + * Ruby 2.4 + * Ruby 2.5 + * [JRuby 9.1][jruby-9.1] (targets MRI v2.3) + * [JRuby 9.2][jruby-9.2] (targets MRI v2.5) [jruby-1.7]: https://www.jruby.org/2017/05/11/jruby-1-7-27.html [jruby-9.0]: https://www.jruby.org/2016/01/26/jruby-9-0-5-0.html @@ -59,6 +600,7 @@ All notable changes to this project will be documented in this file. ## [1.4.0] - 2017-06-09 +- TAG: [v1.4.0][1.4.0t] - Drop Ruby 1.8.7 support (@sferik) - Fix some RuboCop offenses (@sferik) - _Dependency_: Remove Yardstick (@sferik) @@ -66,11 +608,13 @@ All notable changes to this project will be documented in this file. ## [1.3.1] - 2017-03-03 +- TAG: [v1.3.1][1.3.1t] - Add support for Ruby 2.4.0 (@pschambacher) - _Dependency_: Upgrade Faraday to Faraday 0.11 (@mcfiredrill, @rhymes, @pschambacher) ## [1.3.0] - 2016-12-28 +- TAG: [v1.3.0][1.3.0t] - Add support for header-based authentication to the `Client` so it can be used across the library (@bjeanes) - Default to header-based authentication when getting a token from an authorisation code (@maletor) - **Breaking**: Allow an `auth_scheme` (`:basic_auth` or `:request_body`) to be set on the client, defaulting to `:request_body` to maintain backwards compatibility (@maletor, @bjeanes) @@ -81,86 +625,229 @@ All notable changes to this project will be documented in this file. ## [1.2.0] - 2016-07-01 +- TAG: [v1.2.0][1.2.0t] - Properly handle encoding of error responses (so we don't blow up, for example, when Google's response includes a ∞) (@Motoshi-Nishihira) - Make a copy of the options hash in `AccessToken#from_hash` to avoid accidental mutations (@Linuus) - Use `raise` rather than `fail` to throw exceptions (@sferik) ## [1.1.0] - 2016-01-30 +- TAG: [v1.1.0][1.1.0t] - Various refactors (eliminating `Hash#merge!` usage in `AccessToken#refresh!`, use `yield` instead of `#call`, freezing mutable objects in constants, replacing constants with class variables) (@sferik) - Add support for Rack 2, and bump various other dependencies (@sferik) ## [1.0.0] - 2014-07-09 +- TAG: [v1.0.0][1.0.0t] + ### Added + - Add an implementation of the MAC token spec. ### Fixed + - Fix Base64.strict_encode64 incompatibility with Ruby 1.8.7. ## [0.5.0] - 2011-07-29 +- TAG: [v0.5.0][0.5.0t] + ### Changed -- [breaking] `oauth_token` renamed to `oauth_bearer`. -- [breaking] `authorize_path` Client option renamed to `authorize_url`. -- [breaking] `access_token_path` Client option renamed to `token_url`. -- [breaking] `access_token_method` Client option renamed to `token_method`. -- [breaking] `web_server` renamed to `auth_code`. + +- *breaking* `oauth_token` renamed to `oauth_bearer`. +- *breaking* `authorize_path` Client option renamed to `authorize_url`. +- *breaking* `access_token_path` Client option renamed to `token_url`. +- *breaking* `access_token_method` Client option renamed to `token_method`. +- *breaking* `web_server` renamed to `auth_code`. ## [0.4.1] - 2011-04-20 +- TAG: [v0.4.1][0.4.1t] + ## [0.4.0] - 2011-04-20 +- TAG: [v0.4.0][0.4.0t] + ## [0.3.0] - 2011-04-08 +- TAG: [v0.3.0][0.3.0t] + ## [0.2.0] - 2011-04-01 +- TAG: [v0.2.0][0.2.0t] + ## [0.1.1] - 2011-01-12 +- TAG: [v0.1.1][0.1.1t] + ## [0.1.0] - 2010-10-13 -## [0.0.13] + [0.0.12] + [0.0.11] - 2010-08-17 +- TAG: [v0.1.0][0.1.0t] + +## [0.0.13] - 2010-08-17 + +- TAG: [v0.0.13][0.0.13t] + +## [0.0.12] - 2010-08-17 + +- TAG: [v0.0.12][0.0.12t] + +## [0.0.11] - 2010-08-17 + +- TAG: [v0.0.11][0.0.11t] ## [0.0.10] - 2010-06-19 +- TAG: [v0.0.10][0.0.10t] + ## [0.0.9] - 2010-06-18 -## [0.0.8] + [0.0.7] - 2010-04-27 +- TAG: [v0.0.9][0.0.9t] + +## [0.0.8] - 2010-04-27 + +- TAG: [v0.0.8][0.0.8t] + +## [0.0.7] - 2010-04-27 + +- TAG: [v0.0.7][0.0.7t] ## [0.0.6] - 2010-04-25 +- TAG: [v0.0.6][0.0.6t] + ## [0.0.5] - 2010-04-23 -## [0.0.4] + [0.0.3] + [0.0.2] + [0.0.1] - 2010-04-22 - - -[0.0.1]: https://github.com/oauth-xx/oauth2/compare/311d9f4...v0.0.1 -[0.0.2]: https://github.com/oauth-xx/oauth2/compare/v0.0.1...v0.0.2 -[0.0.3]: https://github.com/oauth-xx/oauth2/compare/v0.0.2...v0.0.3 -[0.0.4]: https://github.com/oauth-xx/oauth2/compare/v0.0.3...v0.0.4 -[0.0.5]: https://github.com/oauth-xx/oauth2/compare/v0.0.4...v0.0.5 -[0.0.6]: https://github.com/oauth-xx/oauth2/compare/v0.0.5...v0.0.6 -[0.0.7]: https://github.com/oauth-xx/oauth2/compare/v0.0.6...v0.0.7 -[0.0.8]: https://github.com/oauth-xx/oauth2/compare/v0.0.7...v0.0.8 -[0.0.9]: https://github.com/oauth-xx/oauth2/compare/v0.0.8...v0.0.9 -[0.0.10]: https://github.com/oauth-xx/oauth2/compare/v0.0.9...v0.0.10 -[0.0.11]: https://github.com/oauth-xx/oauth2/compare/v0.0.10...v0.0.11 -[0.0.12]: https://github.com/oauth-xx/oauth2/compare/v0.0.11...v0.0.12 -[0.0.13]: https://github.com/oauth-xx/oauth2/compare/v0.0.12...v0.0.13 -[0.1.0]: https://github.com/oauth-xx/oauth2/compare/v0.0.13...v0.1.0 -[0.1.1]: https://github.com/oauth-xx/oauth2/compare/v0.1.0...v0.1.1 -[0.2.0]: https://github.com/oauth-xx/oauth2/compare/v0.1.1...v0.2.0 -[0.3.0]: https://github.com/oauth-xx/oauth2/compare/v0.2.0...v0.3.0 -[0.4.0]: https://github.com/oauth-xx/oauth2/compare/v0.3.0...v0.4.0 -[0.4.1]: https://github.com/oauth-xx/oauth2/compare/v0.4.0...v0.4.1 -[0.5.0]: https://github.com/oauth-xx/oauth2/compare/v0.4.1...v0.5.0 -[1.0.0]: https://github.com/oauth-xx/oauth2/compare/v0.9.4...v1.0.0 -[1.1.0]: https://github.com/oauth-xx/oauth2/compare/v1.0.0...v1.1.0 -[1.2.0]: https://github.com/oauth-xx/oauth2/compare/v1.1.0...v1.2.0 -[1.3.0]: https://github.com/oauth-xx/oauth2/compare/v1.2.0...v1.3.0 -[1.3.1]: https://github.com/oauth-xx/oauth2/compare/v1.3.0...v1.3.1 -[1.4.0]: https://github.com/oauth-xx/oauth2/compare/v1.3.1...v1.4.0 -[1.4.1]: https://github.com/oauth-xx/oauth2/compare/v1.4.0...v1.4.1 -[1.4.2]: https://github.com/oauth-xx/oauth2/compare/v1.4.1...v1.4.2 -[1.4.3]: https://github.com/oauth-xx/oauth2/compare/v1.4.2...v1.4.3 -[unreleased]: https://github.com/oauth-xx/oauth2/compare/v1.4.1...HEAD +- TAG: [v0.0.5][0.0.5t] + +## [0.0.4] - 2010-04-22 + +- TAG: [v0.0.4][0.0.4t] + +## [0.0.3] - 2010-04-22 + +- TAG: [v0.0.3][0.0.3t] + +## [0.0.2] - 2010-04-22 + +- TAG: [v0.0.2][0.0.2t] + +## [0.0.1] - 2010-04-22 + +- TAG: [v0.0.1][0.0.1t] + +[gemfiles/readme]: gemfiles/README.md + +[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 +[2.0.16t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.16 +[2.0.15]: https://github.com/ruby-oauth/oauth2/compare/v2.0.14...v2.0.15 +[2.0.15t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.15 +[2.0.14]: https://github.com/ruby-oauth/oauth2/compare/v2.0.13...v2.0.14 +[2.0.14t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.14 +[2.0.13]: https://github.com/ruby-oauth/oauth2/compare/v2.0.12...v2.0.13 +[2.0.13t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.13 +[2.0.12]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.11...v2.0.12 +[2.0.12t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.12 +[2.0.11]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.10...v2.0.11 +[2.0.11t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.11 +[2.0.10]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.9...v2.0.10 +[2.0.10t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.10 +[2.0.9]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.8...v2.0.9 +[2.0.9t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.9 +[2.0.8]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.7...v2.0.8 +[2.0.8t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.8 +[2.0.7]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.6...v2.0.7 +[2.0.7t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.7 +[2.0.6]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.5...v2.0.6 +[2.0.6t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.6 +[2.0.5]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.4...v2.0.5 +[2.0.5t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.5 +[2.0.4]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.3...v2.0.4 +[2.0.4t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.4 +[2.0.3]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.2...v2.0.3 +[2.0.3t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.3 +[2.0.2]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.1...v2.0.2 +[2.0.2t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.2 +[2.0.1]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v2.0.0...v2.0.1 +[2.0.1t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.1 +[2.0.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.11...v2.0.0 +[2.0.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v2.0.0 +[1.4.11]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.10...v1.4.11 +[1.4.11t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.11 +[1.4.10]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.9...v1.4.10 +[1.4.10t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.10 +[1.4.9]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.8...v1.4.9 +[1.4.9t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.9 +[1.4.8]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.7...v1.4.8 +[1.4.8t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.8 +[1.4.7]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.6...v1.4.7 +[1.4.7t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.7 +[1.4.6]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.5...v1.4.6 +[1.4.6t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.6 +[1.4.5]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.4...v1.4.5 +[1.4.5t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.5 +[1.4.4]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.3...v1.4.4 +[1.4.4t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.4 +[1.4.3]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.2...v1.4.3 +[1.4.3t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.3 +[1.4.2]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.1...v1.4.2 +[1.4.2t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.2 +[1.4.1]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.4.0...v1.4.1 +[1.4.1t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.1 +[1.4.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.3.1...v1.4.0 +[1.4.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.4.0 +[1.3.1]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.3.0...v1.3.1 +[1.3.1t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.3.1 +[1.3.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.2.0...v1.3.0 +[1.3.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.3.0 +[1.2.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.1.0...v1.2.0 +[1.2.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.2.0 +[1.1.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v1.0.0...v1.1.0 +[1.1.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.1.0 +[1.0.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.9.4...v1.0.0 +[1.0.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v1.0.0 +[0.5.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.4.1...v0.5.0 +[0.5.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.5.0 +[0.4.1]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.4.0...v0.4.1 +[0.4.1t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.4.1 +[0.4.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.3.0...v0.4.0 +[0.4.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.4.0 +[0.3.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.2.0...v0.3.0 +[0.3.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.3.0 +[0.2.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.1.1...v0.2.0 +[0.2.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.2.0 +[0.1.1]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.1.0...v0.1.1 +[0.1.1t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.1.1 +[0.1.0]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.13...v0.1.0 +[0.1.0t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.1.0 +[0.0.13]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.12...v0.0.13 +[0.0.13t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.13 +[0.0.12]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.11...v0.0.12 +[0.0.12t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.12 +[0.0.11]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.10...v0.0.11 +[0.0.11t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.11 +[0.0.10]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.9...v0.0.10 +[0.0.10t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.10 +[0.0.9]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.8...v0.0.9 +[0.0.9t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.9 +[0.0.8]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.7...v0.0.8 +[0.0.8t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.8 +[0.0.7]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.6...v0.0.7 +[0.0.7t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.7 +[0.0.6]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.5...v0.0.6 +[0.0.6t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.6 +[0.0.5]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.4...v0.0.5 +[0.0.5t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.5 +[0.0.4]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.3...v0.0.4 +[0.0.4t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.4 +[0.0.3]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.2...v0.0.3 +[0.0.3t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.3 +[0.0.2]: https://gitlab.com/ruby-oauth/oauth2/-/compare/v0.0.1...v0.0.2 +[0.0.2t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.2 +[0.0.1]: https://github.com/ruby-oauth/oauth2/compare/311d9f4...v0.0.1 +[0.0.1t]: https://github.com/ruby-oauth/oauth2/releases/tag/v0.0.1 diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 00000000..c06c0f3f --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,20 @@ +cff-version: 1.2.0 +title: oauth2 +message: >- + If you use this work and you want to cite it, + then you can use the metadata from this file. +type: software +authors: + - given-names: Peter Hurn + family-names: Boling + email: peter@railsbling.com + affiliation: railsbling.com + orcid: 'https://orcid.org/0009-0008-8519-441X' +identifiers: + - type: url + value: 'https://github.com/ruby-oauth/oauth2' + description: oauth2 +repository-code: 'https://github.com/ruby-oauth/oauth2' +abstract: >- + oauth2 +license: See license file diff --git a/CNAME b/CNAME new file mode 100644 index 00000000..9e32e7bf --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +oauth2.galtzo.com \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 395b407d..7ad4c15e 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,73 +2,133 @@ ## Our Pledge -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. ## Our Standards -Examples of behavior that contributes to creating a positive environment -include: +Examples of behavior that contributes to a positive environment for our +community include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community -Examples of unacceptable behavior by participants include: +Examples of unacceptable behavior include: -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission +* Publishing others' private information, such as a physical or email address, + without their explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting -## Our Responsibilities +## Enforcement Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. ## Scope -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at peter.boling@gmail.com. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. +reported to the community leaders responsible for enforcement at +[![Contact Maintainer][🚂maint-contact-img]][🚂maint-contact]. +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations +[🚂maint-contact]: http://www.railsbling.com/contact +[🚂maint-contact-img]: https://img.shields.io/badge/Contact-Maintainer-0093D0.svg?style=flat&logo=rubyonrails&logoColor=red diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 61aa667f..fbc87e94 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,221 @@ -## Submitting a Pull Request -1. [Fork the repository.][fork] -2. [Create a topic branch.][branch] -3. Add specs for your unimplemented feature or bug fix. -4. Run `bundle exec rake spec`. If your specs pass, return to step 3. -5. Implement your feature or bug fix. -6. Run `bundle exec rake`. If your specs fail, return to step 5. -7. Run `open coverage/index.html`. If your changes are not completely covered - by your tests, return to step 3. -8. Add documentation for your feature or bug fix. -9. Run `bundle exec rake verify_measurements`. If your changes are not 100% - documented, go back to step 8. -10. Commit and push your changes. -11. [Submit a pull request.][pr] - -[fork]: http://help.github.com/fork-a-repo/ -[branch]: http://learn.github.com/p/branching.html -[pr]: http://help.github.com/send-pull-requests/ +# Contributing + +Bug reports and pull requests are welcome on [CodeBerg][📜src-cb], [GitLab][📜src-gl], or [GitHub][📜src-gh]. +This project should be a safe, welcoming space for collaboration, so contributors agree to adhere to +the [code of conduct][🤝conduct]. + +To submit a patch, please fork the project, create a patch with tests, and send a pull request. + +Remember to [![Keep A Changelog][📗keep-changelog-img]][📗keep-changelog] if you make changes. + +## Help out! + +Take a look at the `reek` list which is the file called `REEK` and find something to improve. + +Follow these instructions: + +1. Fork the repository +2. Create a feature branch (`git checkout -b my-new-feature`) +3. Make some fixes. +4. Commit changes (`git commit -am 'Added some feature'`) +5. Push to the branch (`git push origin my-new-feature`) +6. Make sure to add tests for it. This is important, so it doesn't break in a future release. +7. Create new Pull Request. + +## Executables vs Rake tasks + +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 +- kettle-dev-setup +- kettle-dvcs +- kettle-pre-release +- kettle-readme-backers +- kettle-release + +There are many Rake tasks available as well. You can see them by running: + +```shell +bin/rake -T +``` + +## Environment Variables for Local Development + +Below are the primary environment variables recognized by stone_checksums (and its integrated tools). Unless otherwise noted, set boolean values to the string "true" to enable. + +General/runtime +- DEBUG: Enable extra internal logging for this library (default: false) +- REQUIRE_BENCH: Enable `require_bench` to profile requires (default: false) +- CI: When set to true, adjusts default rake tasks toward CI behavior + +Coverage (kettle-soup-cover / SimpleCov) +- K_SOUP_COV_DO: Enable coverage collection (default: true in .envrc) +- K_SOUP_COV_FORMATTERS: Comma-separated list of formatters (html, xml, rcov, lcov, json, tty) +- K_SOUP_COV_MIN_LINE: Minimum line coverage threshold (integer, e.g., 100) +- K_SOUP_COV_MIN_BRANCH: Minimum branch coverage threshold (integer, e.g., 100) +- K_SOUP_COV_MIN_HARD: Fail the run if thresholds are not met (true/false) +- K_SOUP_COV_MULTI_FORMATTERS: Enable multiple formatters at once (true/false) +- K_SOUP_COV_OPEN_BIN: Path to browser opener for HTML (empty disables auto-open) +- MAX_ROWS: Limit console output rows for simplecov-console (e.g., 1) + Tip: When running a single spec file locally, you may want `K_SOUP_COV_MIN_HARD=false` to avoid failing thresholds for a partial run. + +GitHub API and CI helpers +- GITHUB_TOKEN or GH_TOKEN: Token used by `ci:act` and release workflow checks to query GitHub Actions status at higher rate limits + +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/.pem` (defaults to $USER) +- 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 +- GIT_HOOK_FOOTER_APPEND: Append a footer to commit messages when goalie allows (true/false) +- GIT_HOOK_FOOTER_SENTINEL: Required when footer append is enabled — a unique first-line sentinel to prevent duplicates +- GIT_HOOK_FOOTER_APPEND_DEBUG: Extra debug output in the footer template (true/false) + +For a quick starting point, this repository’s `.envrc` shows sane defaults, and `.env.local` can override them locally. + +## Appraisals + +From time to time the [appraisal2][🚎appraisal2] gemfiles in `gemfiles/` will need to be updated. +They are created and updated with the commands: + +```console +bin/rake appraisal:update +``` + +When adding an appraisal to CI, check the [runner tool cache][🏃‍♂️runner-tool-cache] to see which runner to use. + +## The Reek List + +Take a look at the `reek` list which is the file called `REEK` and find something to improve. + +To refresh the `reek` list: + +```console +bundle exec reek > REEK +``` + +## Run Tests + +To run all tests + +```console +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/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. + +## Lint It + +Run all the default tasks, which includes running the gradually autocorrecting linter, `rubocop-gradual`. + +```console +bundle exec rake +``` + +Or just run the linter. + +```console +bundle exec rake rubocop_gradual:autocorrect +``` + +For more detailed information about using RuboCop in this project, please see the [RUBOCOP.md](RUBOCOP.md) guide. This project uses `rubocop_gradual` instead of vanilla RuboCop, which requires specific commands for checking violations. + +### Important: Do not add inline RuboCop disables + +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: + - `bundle exec rake rubocop_gradual:autocorrect` (preferred) + - `bundle exec rake rubocop_gradual:force_update` (only when you cannot fix the violations immediately) + +As a general rule, fix style issues rather than ignoring them. For example, our specs should follow RSpec conventions like using `described_class` for the class under test. + +## Contributors + +Your picture could be here! + +[![Contributors][🖐contributors-img]][🖐contributors] + +Made with [contributors-img][🖐contrib-rocks]. + +Also see GitLab Contributors: [https://gitlab.com/ruby-oauth/oauth2/-/graphs/main][🚎contributors-gl] + +## For Maintainers + +### One-time, Per-maintainer, Setup + +**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 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. + +### To release a new version: + +#### Automated process + +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 + +1. Run `bin/setup && bin/rake` as a "test, coverage, & linting" sanity check +2. Update the version number in `version.rb`, and ensure `CHANGELOG.md` reflects changes +3. Run `bin/setup && bin/rake` again as a secondary check, and to update `Gemfile.lock` +4. Run `git commit -am "🔖 Prepare release v"` to commit the changes +5. Run `git push` to trigger the final CI pipeline before release, and merge PRs + - NOTE: Remember to [check the build][🧪build]. +6. Run `export GIT_TRUNK_BRANCH_NAME="$(git remote show origin | grep 'HEAD branch' | cut -d ' ' -f5)" && echo $GIT_TRUNK_BRANCH_NAME` +7. Run `git checkout $GIT_TRUNK_BRANCH_NAME` +8. Run `git pull origin $GIT_TRUNK_BRANCH_NAME` to ensure latest trunk code +9. Optional for older Bundler (< 2.7.0): Set `SOURCE_DATE_EPOCH` so `rake build` and `rake release` use the same timestamp and generate the same checksums + - If your Bundler is >= 2.7.0, you can skip this; builds are reproducible by default. + - Run `export SOURCE_DATE_EPOCH=$EPOCHSECONDS && echo $SOURCE_DATE_EPOCH` + - If the echo above has no output, then it didn't work. + - Note: `zsh/datetime` module is needed, if running `zsh`. + - In older versions of `bash` you can use `date +%s` instead, i.e. `export SOURCE_DATE_EPOCH=$(date +%s) && echo $SOURCE_DATE_EPOCH` +10. Run `bundle exec rake build` +11. Run `bin/gem_checksums` (more context [1][🔒️rubygems-checksums-pr], [2][🔒️rubygems-guides-pr]) + to create SHA-256 and SHA-512 checksums. This functionality is provided by the `stone_checksums` + [gem][💎stone_checksums]. + - The script automatically commits but does not push the checksums +12. Sanity check the SHA256, comparing with the output from the `bin/gem_checksums` command: + - `sha256sum pkg/-.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 the gem host configured in the gemspec. + +[📜src-gl]: https://gitlab.com/ruby-oauth/oauth2/ +[📜src-cb]: https://codeberg.org/ruby-oauth/oauth2 +[📜src-gh]: https://github.com/ruby-oauth/oauth2 +[🧪build]: https://github.com/ruby-oauth/oauth2/actions +[🤝conduct]: https://gitlab.com/ruby-oauth/oauth2/-/blob/main/CODE_OF_CONDUCT.md +[🖐contrib-rocks]: https://contrib.rocks +[🖐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 +[💎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 +[💎stone_checksums]: https://github.com/galtzo-floss/stone_checksums +[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/ +[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-FFDD67.svg?style=flat +[📌semver-breaking]: https://github.com/semver/semver/issues/716#issuecomment-869336139 +[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html +[🚎appraisal2]: https://github.com/appraisal-rb/appraisal2 +[🏃‍♂️runner-tool-cache]: https://github.com/ruby/ruby-builder/releases/tag/toolcache diff --git a/Dangerfile b/Dangerfile new file mode 100644 index 00000000..a01a246d --- /dev/null +++ b/Dangerfile @@ -0,0 +1,15 @@ +# frozen_string_literal: true + +# Ideas... +# 1. Check for hashtags in PR title, and disallow changes to changelog? +# e.g. github.pr_title.include? "#trivial" + +# Make it more obvious that a PR is a work in progress and shouldn't be merged yet +warn("PR is classed as Work in Progress") if github.pr_title.include?("[WIP]") + +# Warn when there is a big PR +warn("Big PR") if git.lines_of_code > 500 + +# Don't let testing shortcuts get into main by accident +raise("fdescribe left in tests") if %x(grep -r fdescribe specs/).length > 1 +raise("fit left in tests") if %x(grep -r fit specs/).length > 1 diff --git a/FUNDING.md b/FUNDING.md new file mode 100644 index 00000000..5ddd4bca --- /dev/null +++ b/FUNDING.md @@ -0,0 +1,74 @@ + + +Official Discord 👉️ [![Live Chat on Discord][✉️discord-invite-img]][✉️discord-invite] + +Many paths lead to being a sponsor or a backer of this project. Are you on such a path? + +[![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 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 +[🖇osc-backers]: https://opencollective.com/ruby-oauth#backer +[🖇osc-backers-i]: https://opencollective.com/ruby-oauth/backers/badge.svg?style=flat +[🖇osc-sponsors]: https://opencollective.com/ruby-oauth#sponsor +[🖇osc-sponsors-i]: https://opencollective.com/ruby-oauth/sponsors/badge.svg?style=flat +[🖇sponsor-img]: https://img.shields.io/badge/Sponsor_Me!-pboling.svg?style=social&logo=github +[🖇sponsor]: https://github.com/sponsors/pboling +[🖇polar-img]: https://img.shields.io/badge/polar-donate-a51611.svg?style=flat +[🖇polar]: https://polar.sh/pboling +[🖇kofi-img]: https://img.shields.io/badge/ko--fi-%E2%9C%93-a51611.svg?style=flat +[🖇kofi]: https://ko-fi.com/O5O86SNP4 +[🖇patreon-img]: https://img.shields.io/badge/patreon-donate-a51611.svg?style=flat +[🖇patreon]: https://patreon.com/galtzo +[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-%E2%9C%93-a51611.svg?style=flat +[🖇buyme]: https://www.buymeacoffee.com/pboling +[🖇paypal-img]: https://img.shields.io/badge/donate-paypal-a51611.svg?style=flat&logo=paypal +[🖇paypal]: https://www.paypal.com/paypalme/peterboling +[✉️discord-invite]: https://discord.gg/3qme4XHNKN +[✉️discord-invite-img]: https://img.shields.io/discord/1373797679469170758?style=flat + + + +# 🤑 A request for help + +Maintainers have teeth and need to pay their dentists. +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. + +To join the community or get help 👇️ Join the Discord. + +[![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] + +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] 💌 [![Donate on PayPal][🖇paypal-bottom-img]][🖇paypal] + +# Another Way to Support Open Source Software + +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`. + +I’m developing a new library, [floss_funding][🖇floss-funding-gem], designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look. + +**[Floss-Funding.dev][🖇floss-funding.dev]: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags** + +[⛳liberapay-bottom-img]: https://img.shields.io/liberapay/goal/pboling.svg?style=for-the-badge&logo=liberapay&color=a51611 +[🖇osc-all-img]: https://img.shields.io/opencollective/all/ruby-oauth +[🖇osc-sponsors-img]: https://img.shields.io/opencollective/sponsors/ruby-oauth +[🖇osc-backers-img]: https://img.shields.io/opencollective/backers/ruby-oauth +[🖇osc-all-bottom-img]: https://img.shields.io/opencollective/all/ruby-oauth?style=for-the-badge +[🖇osc-sponsors-bottom-img]: https://img.shields.io/opencollective/sponsors/ruby-oauth?style=for-the-badge +[🖇osc-backers-bottom-img]: https://img.shields.io/opencollective/backers/ruby-oauth?style=for-the-badge +[🖇osc]: https://opencollective.com/ruby-oauth +[🖇sponsor-bottom-img]: https://img.shields.io/badge/Sponsor_Me!-pboling-blue?style=for-the-badge&logo=github +[🖇buyme-img]: https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20latte&emoji=&slug=pboling&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff +[🖇paypal-bottom-img]: https://img.shields.io/badge/donate-paypal-a51611.svg?style=for-the-badge&logo=paypal&color=0A0A0A +[🖇floss-funding.dev]: https://floss-funding.dev +[🖇floss-funding-gem]: https://github.com/galtzo-floss/floss_funding +[✉️discord-invite-img-ftb]: https://img.shields.io/discord/1373797679469170758?style=for-the-badge diff --git a/Gemfile b/Gemfile index 9d6c338f..be6c1816 100644 --- a/Gemfile +++ b/Gemfile @@ -1,22 +1,31 @@ -source 'https://rubygems.org/' +# frozen_string_literal: true -git_source(:github) { |repo_name| "https://github.com/#{repo_name}" } +source "https://gem.coop/" -group :test do - gem 'coveralls' - gem 'simplecov', '>= 0.9' -end +git_source(:codeberg) { |repo_name| "https://codeberg.org/#{repo_name}" } +git_source(:gitlab) { |repo_name| "https://gitlab.com/#{repo_name}" } -ruby_version = Gem::Version.new(RUBY_VERSION) -debuggable_version = Gem::Version.new('2.6') +#### IMPORTANT ####################################################### +# Gemfile is for local development ONLY; Gemfile is NOT loaded in CI # +####################################################### IMPORTANT #### -group :development, :test do - if ruby_version >= debuggable_version - gem 'pry' - gem 'byebug' - gem 'pry-byebug' - end -end - -# Specify non-special dependencies in oauth2.gemspec +# Include dependencies from .gemspec gemspec + +# Debugging +eval_gemfile "gemfiles/modular/debug.gemfile" + +# Code Coverage +eval_gemfile "gemfiles/modular/coverage.gemfile" + +# Linting +eval_gemfile "gemfiles/modular/style.gemfile" + +# Documentation +eval_gemfile "gemfiles/modular/documentation.gemfile" + +# Optional +eval_gemfile "gemfiles/modular/optional.gemfile" + +### Std Lib Extracted Gems +eval_gemfile "gemfiles/modular/x_std_libs.gemfile" diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 00000000..936086a3 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,365 @@ +GIT + remote: https://github.com/pboling/yard-junk.git + revision: 54ccebabbfa9a9cd44d0b991687ebbfd22c32b55 + branch: next + specs: + yard-junk (0.0.10) + backports (>= 3.18) + benchmark + ostruct + rainbow + yard + +PATH + remote: . + specs: + oauth2 (2.0.18) + faraday (>= 0.17.3, < 4.0) + jwt (>= 1.0, < 4.0) + logger (~> 1.2) + multi_xml (~> 0.5) + rack (>= 1.2, < 4) + snaky_hash (~> 2.0, >= 2.0.3) + version_gem (~> 1.1, >= 1.1.9) + +GEM + remote: https://gem.coop/ + specs: + addressable (2.8.7) + public_suffix (>= 2.0.2, < 7.0) + ansi (1.5.0) + appraisal2 (3.0.0) + bundler (>= 1.17.3) + rake (>= 10) + thor (>= 0.14) + ast (2.4.3) + backports (3.25.2) + base64 (0.3.0) + benchmark (0.5.0) + bigdecimal (3.3.1) + bundler-audit (0.9.2) + bundler (>= 1.2.0, < 3) + thor (~> 1.0) + concurrent-ruby (1.3.5) + date (3.5.0) + debug (1.11.0) + irb (~> 1.10) + reline (>= 0.3.8) + delegate (0.4.0) + diff-lcs (1.6.2) + diffy (3.4.4) + docile (1.4.1) + dry-configurable (1.3.0) + dry-core (~> 1.1) + zeitwerk (~> 2.6) + dry-core (1.1.0) + concurrent-ruby (~> 1.0) + logger + zeitwerk (~> 2.6) + dry-inflector (1.2.0) + dry-initializer (3.2.0) + dry-logic (1.6.0) + bigdecimal + concurrent-ruby (~> 1.0) + dry-core (~> 1.1) + zeitwerk (~> 2.6) + dry-schema (1.14.1) + concurrent-ruby (~> 1.0) + dry-configurable (~> 1.0, >= 1.0.1) + dry-core (~> 1.1) + dry-initializer (~> 3.2) + dry-logic (~> 1.5) + dry-types (~> 1.8) + zeitwerk (~> 2.6) + dry-types (1.8.3) + bigdecimal (~> 3.0) + concurrent-ruby (~> 1.0) + dry-core (~> 1.0) + dry-inflector (~> 1.0) + dry-logic (~> 1.4) + zeitwerk (~> 2.6) + erb (5.1.3) + faraday (2.14.0) + faraday-net_http (>= 2.0, < 3.5) + json + logger + faraday-net_http (3.4.2) + net-http (~> 0.5) + gem_bench (2.0.5) + bundler (>= 1.14) + version_gem (~> 1.1, >= 1.1.4) + gitmoji-regex (1.0.3) + version_gem (~> 1.1, >= 1.1.8) + hashie (5.0.0) + io-console (0.8.1) + irb (1.15.3) + pp (>= 0.6.0) + rdoc (>= 4.0.0) + reline (>= 0.4.2) + json (2.16.0) + jwt (3.1.2) + base64 + kettle-dev (1.1.52) + kettle-soup-cover (1.0.10) + simplecov (~> 0.22) + simplecov-cobertura (~> 3.0) + simplecov-console (~> 0.9, >= 0.9.3) + simplecov-html (~> 0.13, >= 0.13.1) + simplecov-lcov (~> 0.8) + simplecov-rcov (~> 0.3, >= 0.3.7) + simplecov_json_formatter (~> 0.1, >= 0.1.4) + version_gem (~> 1.1, >= 1.1.8) + kettle-test (1.0.6) + appraisal2 (~> 3.0) + backports (~> 3.0) + rspec (~> 3.0) + rspec-block_is_expected (~> 1.0, >= 1.0.6) + rspec-pending_for (~> 0.1, >= 0.1.19) + rspec-stubbed_env (~> 1.0, >= 1.0.4) + rspec_junit_formatter (~> 0.6) + silent_stream (~> 1.0, >= 1.0.12) + timecop-rspec (~> 1.0, >= 1.0.3) + version_gem (~> 1.1, >= 1.1.9) + kramdown (2.5.1) + rexml (>= 3.3.9) + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + language_server-protocol (3.17.0.5) + lint_roller (1.1.0) + logger (1.7.0) + multi_xml (0.7.2) + bigdecimal (~> 3.1) + mutex_m (0.3.0) + net-http (0.7.0) + uri + nkf (0.2.0) + nokogiri (1.18.10-x86_64-linux-gnu) + racc (~> 1.4) + ostruct (0.6.3) + parallel (1.27.0) + parser (3.3.10.0) + ast (~> 2.4.1) + racc + pp (0.6.3) + prettyprint + prettyprint (0.2.0) + prism (1.6.0) + psych (5.2.6) + date + stringio + public_suffix (6.0.2) + racc (1.8.1) + rack (3.2.4) + rainbow (3.1.1) + rake (13.3.1) + rbs (3.9.5) + logger + rdoc (6.15.1) + erb + psych (>= 4.0.0) + tsort + reek (6.5.0) + dry-schema (~> 1.13) + logger (~> 1.6) + parser (~> 3.3.0) + rainbow (>= 2.0, < 4.0) + rexml (~> 3.1) + regexp_parser (2.11.3) + reline (0.6.2) + io-console (~> 0.5) + require_bench (1.0.4) + version_gem (>= 1.1.3, < 4) + rexml (3.4.4) + rspec (3.13.2) + rspec-core (~> 3.13.0) + rspec-expectations (~> 3.13.0) + rspec-mocks (~> 3.13.0) + rspec-block_is_expected (1.0.6) + rspec-core (3.13.6) + rspec-support (~> 3.13.0) + rspec-expectations (3.13.5) + diff-lcs (>= 1.2.0, < 2.0) + rspec-support (~> 3.13.0) + rspec-mocks (3.13.7) + diff-lcs (>= 1.2.0, < 2.0) + rspec-support (~> 3.13.0) + rspec-pending_for (0.1.19) + rspec-core (~> 3.0) + ruby_engine (~> 2.0) + ruby_version (~> 1.0) + version_gem (~> 1.1, >= 1.1.8) + rspec-stubbed_env (1.0.4) + rspec-support (3.13.6) + rspec_junit_formatter (0.6.0) + rspec-core (>= 2, < 4, != 2.12.0) + rubocop (1.80.2) + json (~> 2.3) + language_server-protocol (~> 3.17.0.2) + lint_roller (~> 1.1.0) + parallel (~> 1.10) + parser (>= 3.3.0.2) + rainbow (>= 2.2.2, < 4.0) + regexp_parser (>= 2.9.3, < 3.0) + rubocop-ast (>= 1.46.0, < 2.0) + ruby-progressbar (~> 1.7) + unicode-display_width (>= 2.4.0, < 4.0) + rubocop-ast (1.48.0) + parser (>= 3.3.7.2) + prism (~> 1.4) + rubocop-gradual (0.3.6) + diff-lcs (>= 1.2.0, < 2.0) + diffy (~> 3.0) + parallel (~> 1.10) + rainbow (>= 2.2.2, < 4.0) + rubocop (~> 1.0) + rubocop-lts (8.1.1) + rubocop-ruby2_2 (>= 2.0.3, < 3) + standard-rubocop-lts (>= 1.0.3, < 3) + version_gem (>= 1.1.2, < 3) + rubocop-md (1.2.4) + rubocop (>= 1.45) + rubocop-on-rbs (1.8.0) + lint_roller (~> 1.1) + rbs (~> 3.5) + rubocop (>= 1.72.1, < 2.0) + zlib + rubocop-packaging (0.6.0) + lint_roller (~> 1.1.0) + rubocop (>= 1.72.1, < 2.0) + rubocop-performance (1.25.0) + lint_roller (~> 1.1) + rubocop (>= 1.75.0, < 2.0) + rubocop-ast (>= 1.38.0, < 2.0) + rubocop-rake (0.7.1) + lint_roller (~> 1.1) + rubocop (>= 1.72.1) + rubocop-rspec (3.7.0) + lint_roller (~> 1.1) + rubocop (~> 1.72, >= 1.72.1) + rubocop-ruby2_2 (2.0.5) + rubocop-gradual (~> 0.3, >= 0.3.1) + rubocop-md (~> 1.2) + rubocop-rake (~> 0.6) + rubocop-shopify (~> 2.14) + rubocop-thread_safety (~> 0.5, >= 0.5.1) + standard-rubocop-lts (~> 1.0, >= 1.0.7) + version_gem (>= 1.1.3, < 3) + rubocop-shopify (2.18.0) + rubocop (~> 1.62) + rubocop-thread_safety (0.7.3) + lint_roller (~> 1.1) + rubocop (~> 1.72, >= 1.72.1) + rubocop-ast (>= 1.44.0, < 2.0) + ruby-progressbar (1.13.0) + ruby_engine (2.0.3) + ruby_version (1.0.3) + silent_stream (1.0.12) + logger (~> 1.2) + version_gem (>= 1.1.8, < 3) + simplecov (0.22.0) + docile (~> 1.1) + simplecov-html (~> 0.11) + simplecov_json_formatter (~> 0.1) + simplecov-cobertura (3.1.0) + rexml + simplecov (~> 0.19) + simplecov-console (0.9.4) + ansi + simplecov + terminal-table + simplecov-html (0.13.2) + simplecov-lcov (0.9.0) + simplecov-rcov (0.3.7) + simplecov (>= 0.4.1) + simplecov_json_formatter (0.1.4) + snaky_hash (2.0.3) + hashie (>= 0.1.0, < 6) + version_gem (>= 1.1.8, < 3) + standard (1.51.1) + language_server-protocol (~> 3.17.0.2) + lint_roller (~> 1.0) + rubocop (~> 1.80.2) + standard-custom (~> 1.0.0) + standard-performance (~> 1.8) + standard-custom (1.0.2) + lint_roller (~> 1.0) + rubocop (~> 1.50) + standard-performance (1.8.0) + lint_roller (~> 1.1) + rubocop-performance (~> 1.25.0) + standard-rubocop-lts (1.0.10) + rspec-block_is_expected (~> 1.0, >= 1.0.5) + standard (>= 1.35.1, < 2) + standard-custom (>= 1.0.2, < 2) + standard-performance (>= 1.3.1, < 2) + version_gem (>= 1.1.4, < 3) + stone_checksums (1.0.3) + version_gem (~> 1.1, >= 1.1.9) + stringio (3.1.7) + terminal-table (4.0.0) + unicode-display_width (>= 1.1.1, < 4) + thor (1.4.0) + timecop (0.9.10) + timecop-rspec (1.0.3) + delegate (~> 0.1) + rspec (~> 3.0) + timecop (>= 0.7, < 1) + tsort (0.2.0) + unicode-display_width (3.2.0) + unicode-emoji (~> 4.1) + unicode-emoji (4.1.0) + uri (1.1.1) + version_gem (1.1.9) + yard (0.9.37) + yard-fence (0.8.0) + rdoc (~> 6.11) + version_gem (~> 1.1, >= 1.1.9) + yard (~> 0.9, >= 0.9.37) + yard-relative_markdown_links (0.5.0) + nokogiri (>= 1.14.3, < 2) + zeitwerk (2.7.3) + zlib (3.2.2) + +PLATFORMS + x86_64-linux + +DEPENDENCIES + addressable (~> 2.8, >= 2.8.7, >= 2.8, < 3) + appraisal2 (~> 3.0) + backports (~> 3.25, >= 3.25.1) + benchmark (~> 0.4, >= 0.4.1) + bundler-audit (~> 0.9.2) + debug (>= 1.1) + erb (~> 5.0) + gem_bench (~> 2.0, >= 2.0.5) + gitmoji-regex (~> 1.0, >= 1.0.3) + irb (~> 1.15, >= 1.15.2) + kettle-dev (~> 1.1) + kettle-soup-cover (~> 1.0, >= 1.0.10) + kettle-test (~> 1.0, >= 1.0.6) + kramdown (~> 2.5, >= 2.5.1) + kramdown-parser-gfm (~> 1.1) + mutex_m (~> 0.2) + nkf (~> 0.2) + oauth2! + rake (~> 13.0) + rdoc (~> 6.11) + reek (~> 6.5) + require_bench (~> 1.0, >= 1.0.4) + rexml (~> 3.2, >= 3.2.5) + rubocop-lts (~> 8.0) + rubocop-on-rbs (~> 1.8) + rubocop-packaging (~> 0.6, >= 0.6.0) + rubocop-rspec (~> 3.6) + rubocop-ruby2_2 + ruby-progressbar (~> 1.13) + standard (>= 1.50) + stone_checksums (~> 1.0, >= 1.0.2) + stringio (>= 3.0) + yard (~> 0.9, >= 0.9.37) + yard-fence (~> 0.4) + yard-junk (~> 0.0, >= 0.0.10)! + yard-relative_markdown_links (~> 0.5.0) + +BUNDLED WITH + 2.7.2 diff --git a/IRP.md b/IRP.md new file mode 100644 index 00000000..7bd10973 --- /dev/null +++ b/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 diff --git a/LICENSE b/LICENSE.txt similarity index 88% rename from LICENSE rename to LICENSE.txt index 6dda5ca1..41c8a807 100644 --- a/LICENSE +++ b/LICENSE.txt @@ -1,7 +1,7 @@ MIT License -Copyright (c) 2011 - 2013 Michael Bleigh and Intridea, Inc. -Copyright (c) 2017 - 2018 oauth-xx organization, https://github.com/oauth-xx +Copyright (c) 2017-2025 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 diff --git a/OIDC.md b/OIDC.md new file mode 100644 index 00000000..22e31d11 --- /dev/null +++ b/OIDC.md @@ -0,0 +1,167 @@ +# 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("https://github.com/OIDC_CLIENT_ID"), + ENV.fetch("https://github.com/OIDC_CLIENT_SECRET"), + site: ENV.fetch("https://github.com/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("https://github.com/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("https://github.com/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("https://github.com/OIDC_ISSUER") +jwks_uri = JSON.parse(Net::HTTP.get(URI.join(issuer, "/.well-known/openid-configuration"))). + fetch("https://github.com/jwks_uri") +jwks = JSON.parse(Net::HTTP.get(URI(jwks_uri))) +keys = jwks.fetch("https://github.com/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("https://github.com/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). diff --git a/README.md b/README.md index d9094115..82cbb176 100644 --- a/README.md +++ b/README.md @@ -1,128 +1,607 @@ -⚠️ **_WARNING_**: You are viewing the README of the master branch which contains unreleased changes for version 2.0.0. -Please help us reach the [2.0.0 release milestone](https://github.com/oauth-xx/oauth2/milestone/1) by submitting PRs, or reviewing PRs and issues. +| 📍 NOTE | +|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| RubyGems (the [GitHub org][rubygems-org], not the website) [suffered][draper-security] a [hostile takeover][ellen-takeover] in September 2025. | +| Ultimately [4 maintainers][simi-removed] were [hard removed][martin-removed] and a reason has been given for only 1 of those, while 2 others resigned in protest. | +| It is a [complicated story][draper-takeover] which is difficult to [parse quickly][draper-lies]. | +| I'm adding notes like this to gems because I [don't condone theft][draper-theft] of repositories or gems from their rightful owners. | +| If a similar theft happened with my repos/gems, I'd hope some would stand up for me. | +| Disenfranchised former-maintainers have started [gem.coop][gem-coop]. | +| Once available I will publish there exclusively; unless RubyCentral makes amends with the community. | +| The ["Technology for Humans: Joel Draper"][reinteractive-podcast] podcast episode by [reinteractive][reinteractive] is the most cogent summary I'm aware of. | +| See [here][gem-naming], [here][gem-coop] and [here][martin-ann] for more info on what comes next. | +| What I'm doing: A (WIP) proposal for [bundler/gem scopes][gem-scopes], and a (WIP) proposal for a federated [gem server][gem-server]. | + +[rubygems-org]: https://github.com/rubygems/ +[draper-security]: https://joel.drapper.me/p/ruby-central-security-measures/ +[draper-takeover]: https://joel.drapper.me/p/ruby-central-takeover/ +[ellen-takeover]: https://pup-e.com/blog/goodbye-rubygems/ +[simi-removed]: https://www.reddit.com/r/ruby/s/gOk42POCaV +[martin-removed]: https://bsky.app/profile/martinemde.com/post/3m3occezxxs2q +[draper-lies]: https://joel.drapper.me/p/ruby-central-fact-check/ +[draper-theft]: https://joel.drapper.me/p/ruby-central/ +[reinteractive]: https://reinteractive.com/ruby-on-rails +[gem-coop]: https://gem.coop +[gem-naming]: https://github.com/gem-coop/gem.coop/issues/12 +[martin-ann]: https://martinemde.com/2025/10/05/announcing-gem-coop.html +[gem-scopes]: https://github.com/galtzo-floss/bundle-namespace +[gem-server]: https://github.com/galtzo-floss/gem-server +[reinteractive-podcast]: https://youtu.be/_H4qbtC5qzU?si=BvuBU90R2wAqD2E6 + +[![Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0][🖼️galtzo-i]][🖼️galtzo-discord] [![ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5][🖼️ruby-lang-i]][🖼️ruby-lang] [![oauth2 Logo by Chris Messina, CC BY-SA 3.0][🖼️oauth2-i]][🖼️oauth2] + +[🖼️galtzo-i]: https://logos.galtzo.com/assets/images/galtzo-floss/avatar-192px.svg +[🖼️galtzo-discord]: https://discord.gg/3qme4XHNKN +[🖼️ruby-lang-i]: https://logos.galtzo.com/assets/images/ruby-lang/avatar-192px.svg +[🖼️ruby-lang]: https://www.ruby-lang.org/ +[🖼️oauth2-i]: https://logos.galtzo.com/assets/images/oauth/oauth2/avatar-192px.svg +[🖼️oauth2]: https://github.com/ruby-oauth/oauth2 + +# 🔐 OAuth 2.0 Authorization Framework + +⭐️ including OAuth 2.1 draft spec & OpenID Connect (OIDC) + +[![Version][👽versioni]][👽version] [![GitHub tag (latest SemVer)][⛳️tag-img]][⛳️tag] [![License: MIT][📄license-img]][📄license-ref] [![Downloads Rank][👽dl-ranki]][👽dl-rank] [![Open Source Helpers][👽oss-helpi]][👽oss-help] [![CodeCov Test Coverage][🏀codecovi]][🏀codecov] [![Coveralls Test Coverage][🏀coveralls-img]][🏀coveralls] [![QLTY Test Coverage][🏀qlty-covi]][🏀qlty-cov] [![QLTY Maintainability][🏀qlty-mnti]][🏀qlty-mnt] [![CI Heads][🚎3-hd-wfi]][🚎3-hd-wf] [![CI Runtime Dependencies @ HEAD][🚎12-crh-wfi]][🚎12-crh-wf] [![CI Current][🚎11-c-wfi]][🚎11-c-wf] [![CI JRuby][🚎10-j-wfi]][🚎10-j-wf] [![Deps Locked][🚎13-🔒️-wfi]][🚎13-🔒️-wf] [![Deps Unlocked][🚎14-🔓️-wfi]][🚎14-🔓️-wf] [![CI Supported][🚎6-s-wfi]][🚎6-s-wf] [![CI Legacy][🚎4-lg-wfi]][🚎4-lg-wf] [![CI Unsupported][🚎7-us-wfi]][🚎7-us-wf] [![CI Ancient][🚎1-an-wfi]][🚎1-an-wf] [![CI Test Coverage][🚎2-cov-wfi]][🚎2-cov-wf] [![CI Style][🚎5-st-wfi]][🚎5-st-wf] [![CodeQL][🖐codeQL-img]][🖐codeQL] [![Apache SkyWalking Eyes License Compatibility Check][🚎15-🪪-wfi]][🚎15-🪪-wf] + +`if ci_badges.map(&:color).detect { it != "green"}` ☝️ [let me know][🖼️galtzo-discord], as I may have missed the [discord notification][🖼️galtzo-discord]. --- -# OAuth2 +`if ci_badges.map(&:color).all? { it == "green"}` 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job. -If you need the readme for a released version of the gem please find it below: +[![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 at ko-fi.com][🖇kofi-img]][🖇kofi] -| Version | Release Date | Readme | -|----------|--------------|----------------------------------------------------------| -| 1.4.4 | Feb 12, 2020 | https://github.com/oauth-xx/oauth2/blob/v1.4.4/README.md | -| 1.4.3 | Jan 29, 2020 | https://github.com/oauth-xx/oauth2/blob/v1.4.3/README.md | -| 1.4.2 | Oct 1, 2019 | https://github.com/oauth-xx/oauth2/blob/v1.4.2/README.md | -| 1.4.1 | Oct 13, 2018 | https://github.com/oauth-xx/oauth2/blob/v1.4.1/README.md | -| 1.4.0 | Jun 9, 2017 | https://github.com/oauth-xx/oauth2/blob/v1.4.0/README.md | -| 1.3.1 | Mar 3, 2017 | https://github.com/oauth-xx/oauth2/blob/v1.3.1/README.md | -| 1.3.0 | Dec 27, 2016 | https://github.com/oauth-xx/oauth2/blob/v1.3.0/README.md | -| 1.2.0 | Jun 30, 2016 | https://github.com/oauth-xx/oauth2/blob/v1.2.0/README.md | -| 1.1.0 | Jan 30, 2016 | https://github.com/oauth-xx/oauth2/blob/v1.1.0/README.md | -| 1.0.0 | May 23, 2014 | https://github.com/oauth-xx/oauth2/blob/v1.0.0/README.md | -| < 1.0.0 | Find here | https://github.com/oauth-xx/oauth2/tags | +## 🌻 Synopsis -[![Gem Version](http://img.shields.io/gem/v/oauth2.svg)][gem] -[![Total Downloads](https://img.shields.io/gem/dt/oauth2.svg)][gem] -[![Downloads Today](https://img.shields.io/gem/rt/oauth2.svg)][gem] -[![Build Status](http://img.shields.io/travis/oauth-xx/oauth2.svg)][travis] -[![Test Coverage](https://api.codeclimate.com/v1/badges/688c612528ff90a46955/test_coverage)][codeclimate-coverage] -[![Maintainability](https://api.codeclimate.com/v1/badges/688c612528ff90a46955/maintainability)][codeclimate-maintainability] -[![Depfu](https://badges.depfu.com/badges/6d34dc1ba682bbdf9ae2a97848241743/count.svg)][depfu] -[![Open Source Helpers](https://www.codetriage.com/oauth-xx/oauth2/badges/users.svg)][code-triage] -[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)][source-license] -[![Documentation](http://inch-ci.org/github/oauth-xx/oauth2.png)][inch-ci] -[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Foauth-xx%2Foauth2.svg?type=shield)][fossa1] +OAuth 2.0 is the industry-standard protocol for authorization. +OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, + desktop applications, mobile phones, and living room devices. +This is a RubyGem for implementing OAuth 2.0 clients (not servers) in Ruby applications. -[gem]: https://rubygems.org/gems/oauth2 -[travis]: http://travis-ci.org/oauth-xx/oauth2 -[coveralls]: https://coveralls.io/r/oauth-xx/oauth2 -[codeclimate-maintainability]: https://codeclimate.com/github/oauth-xx/oauth2/maintainability -[codeclimate-coverage]: https://codeclimate.com/github/oauth-xx/oauth2/test_coverage -[depfu]: https://depfu.com/github/oauth-xx/oauth2 -[source-license]: https://opensource.org/licenses/MIT -[inch-ci]: http://inch-ci.org/github/oauth-xx/oauth2 -[code-triage]: https://www.codetriage.com/oauth-xx/oauth2 -[fossa1]: https://app.fossa.io/projects/git%2Bgithub.com%2Foauth-xx%2Foauth2?ref=badge_shield +### Quick Examples -### Oauth2 gem is looking for additional maintainers. See [#307](https://github.com/oauth-xx/oauth2/issues/307). +
+ Convert the following `curl` command into a token request using this gem... -A Ruby wrapper for the OAuth 2.0 specification. +```shell +curl --request POST \ + --url 'https://login.microsoftonline.com/REDMOND_REDACTED/oauth2/token' \ + --header 'content-type: application/x-www-form-urlencoded' \ + --data grant_type=client_credentials \ + --data client_id=REDMOND_CLIENT_ID \ + --data client_secret=REDMOND_CLIENT_SECRET \ + --data resource=REDMOND_RESOURCE_UUID +``` + +NOTE: In the ruby version below, certain params are passed to the `get_token` call, instead of the client creation. + +```ruby +OAuth2::Client.new( + "REDMOND_CLIENT_ID", # client_id + "REDMOND_CLIENT_SECRET", # client_secret + auth_scheme: :request_body, # Other modes are supported: :basic_auth, :tls_client_auth, :private_key_jwt + token_url: "oauth2/token", # relative path, except with leading `/`, then absolute path + site: "https://login.microsoftonline.com/REDMOND_REDACTED", +). # The base path for token_url when it is relative + client_credentials. # There are many other types to choose from! + get_token(resource: "REDMOND_RESOURCE_UUID") +``` + +NOTE: `header` - The content type specified in the `curl` is already the default! + +
+ +
+Complete E2E single file script against mock-oauth2-server + +- E2E example uses [navikt/mock-oauth2-server](https://github.com/navikt/mock-oauth2-server), which was added in v2.0.11 +- E2E example does not ship with the released gem, so clone the source to play with it. + +```console +docker compose -f docker-compose-ssl.yml up -d --wait +ruby examples/e2e.rb +# If your machine is slow or Docker pulls are cold, increase the wait: +E2E_WAIT_TIMEOUT=120 ruby examples/e2e.rb +# The mock server serves HTTP on 8080; the example points to http://localhost:8080 by default. +``` + +The output should be something like this: + +```console +➜ ruby examples/e2e.rb +Access token (truncated): eyJraWQiOiJkZWZhdWx0... +userinfo status: 200 +userinfo body: {"sub" => "demo-sub", "aud" => ["demo-aud"], "nbf" => 1757816758000, "iss" => "http://localhost:8080/default", "exp" => 1757820358000, "iat" => 1757816758000, "jti" => "d63b97a7-ebe5-4dea-93e6-d542caba6104"} +E2E complete +``` + +Make sure to shut down the mock server when you are done: + +```console +docker compose -f docker-compose-ssl.yml down +``` + +Troubleshooting: validate connectivity to the mock server + +- Check container status and port mapping: + - `docker compose -f docker-compose-ssl.yml ps` +- From the host, try the discovery URL directly (this is what the example uses by default): + - `curl -v http://localhost:8080/default/.well-known/openid-configuration` + - If that fails immediately, also try: `curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration` +- From inside the container (to distinguish container vs. host networking): + - `docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration` +- Simple TCP probe from the host: + - `nc -vz localhost 8080 # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"'` +- Inspect which host port 8080 is bound to (should be 8080): + - `docker inspect -f '{{ (index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }}' oauth2-mock-oauth2-server-1` +- Look at server logs for readiness/errors: + - `docker logs -n 200 oauth2-mock-oauth2-server-1` +- On Linux, ensure nothing else is bound to 8080 and that firewall/SELinux aren’t blocking: + - `ss -ltnp | grep :8080` + +Notes + +- Discovery URL pattern is: `http://localhost:8080//.well-known/openid-configuration`, where `` defaults to `default`. +- You can change these with env vars when running the example: + - `E2E_ISSUER_BASE` (default: http://localhost:8080) + - `E2E_REALM` (default: default) + +
+ +If it seems like you are in the wrong place, you might try one of these: + +* [OAuth 2.0 Spec][oauth2-spec] +* [doorkeeper gem][doorkeeper-gem] for OAuth 2.0 server/provider implementation. +* [oauth sibling gem][sibling-gem] for OAuth 1.0a implementations in Ruby. + +[oauth2-spec]: https://oauth.net/2/ +[sibling-gem]: https://gitlab.com/ruby-oauth/oauth +[doorkeeper-gem]: https://github.com/doorkeeper-gem/doorkeeper + +## 💡 Info you can shake a stick at + +| Tokens to Remember | [![Gem name][⛳️name-img]][⛳️gem-name] [![Gem namespace][⛳️namespace-img]][⛳️gem-namespace] | +|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Works with JRuby | ![JRuby 9.1 Compat][💎jruby-9.1i] ![JRuby 9.2 Compat][💎jruby-9.2i] ![JRuby 9.3 Compat][💎jruby-9.3i]
[![JRuby 9.4 Compat][💎jruby-9.4i]][🚎10-j-wf] [![JRuby 10.0 Compat][💎jruby-c-i]][🚎11-c-wf] [![JRuby HEAD Compat][💎jruby-headi]][🚎3-hd-wf] | +| Works with Truffle Ruby | ![Truffle Ruby 22.3 Compat][💎truby-22.3i] ![Truffle Ruby 23.0 Compat][💎truby-23.0i] ![Truffle Ruby 23.1 Compat][💎truby-23.1i]
[![Truffle Ruby 24.1 Compat][💎truby-c-i]][🚎11-c-wf] | +| Works with MRI Ruby 3 | [![Ruby 3.0 Compat][💎ruby-3.0i]][🚎4-lg-wf] [![Ruby 3.1 Compat][💎ruby-3.1i]][🚎6-s-wf] [![Ruby 3.2 Compat][💎ruby-3.2i]][🚎6-s-wf] [![Ruby 3.3 Compat][💎ruby-3.3i]][🚎6-s-wf] [![Ruby 3.4 Compat][💎ruby-c-i]][🚎11-c-wf] [![Ruby HEAD Compat][💎ruby-headi]][🚎3-hd-wf] | +| Works with MRI Ruby 2 | ![Ruby 2.2 Compat][💎ruby-2.2i]
[![Ruby 2.3 Compat][💎ruby-2.3i]][🚎1-an-wf] [![Ruby 2.4 Compat][💎ruby-2.4i]][🚎1-an-wf] [![Ruby 2.5 Compat][💎ruby-2.5i]][🚎1-an-wf] [![Ruby 2.6 Compat][💎ruby-2.6i]][🚎7-us-wf] [![Ruby 2.7 Compat][💎ruby-2.7i]][🚎7-us-wf] | +| Support & Community | [![Join Me on Daily.dev's RubyFriends][✉️ruby-friends-img]][✉️ruby-friends] [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork] [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor] | +| Source | [![Source on GitLab.com][📜src-gl-img]][📜src-gl] [![Source on CodeBerg.org][📜src-cb-img]][📜src-cb] [![Source on Github.com][📜src-gh-img]][📜src-gh] [![The best SHA: dQw4w9WgXcQ!][🧮kloc-img]][🧮kloc] | +| Documentation | [![Current release on RubyDoc.info][📜docs-cr-rd-img]][🚎yard-current] [![YARD on Galtzo.com][📜docs-head-rd-img]][🚎yard-head] [![Maintainer Blog][🚂maint-blog-img]][🚂maint-blog] [![GitLab Wiki][📜gl-wiki-img]][📜gl-wiki] [![GitHub Wiki][📜gh-wiki-img]][📜gh-wiki] | +| Compliance | [![License: MIT][📄license-img]][📄license-ref] [![Compatible with Apache Software Projects: Verified by SkyWalking Eyes][📄license-compat-img]][📄license-compat] [![📄ilo-declaration-img]][📄ilo-declaration] [![Security Policy][🔐security-img]][🔐security] [![Contributor Covenant 2.1][🪇conduct-img]][🪇conduct] [![SemVer 2.0.0][📌semver-img]][📌semver] | +| Style | [![Enforced Code Style Linter][💎rlts-img]][💎rlts] [![Keep-A-Changelog 1.0.0][📗keep-changelog-img]][📗keep-changelog] [![Gitmoji Commits][📌gitmoji-img]][📌gitmoji] [![Compatibility appraised by: appraisal2][💎appraisal2-img]][💎appraisal2] | +| Maintainer 🎖️ | [![Follow Me on LinkedIn][💖🖇linkedin-img]][💖🖇linkedin] [![Follow Me on Ruby.Social][💖🐘ruby-mast-img]][💖🐘ruby-mast] [![Follow Me on Bluesky][💖🦋bluesky-img]][💖🦋bluesky] [![Contact Maintainer][🚂maint-contact-img]][🚂maint-contact] [![My technical writing][💖💁🏼‍♂️devto-img]][💖💁🏼‍♂️devto] | +| `...` 💖 | [![Find Me on WellFound:][💖✌️wellfound-img]][💖✌️wellfound] [![Find Me on CrunchBase][💖💲crunchbase-img]][💖💲crunchbase] [![My LinkTree][💖🌳linktree-img]][💖🌳linktree] [![More About Me][💖💁🏼‍♂️aboutme-img]][💖💁🏼‍♂️aboutme] [🧊][💖🧊berg] [🐙][💖🐙hub] [🛖][💖🛖hut] [🧪][💖🧪lab] | + +### Compatibility + +Compatible with MRI Ruby 2.2.0+, and concordant releases of JRuby, and TruffleRuby. + +| 🚚 _Amazing_ test matrix was brought to you by | 🔎 appraisal2 🔎 and the color 💚 green 💚 | +|------------------------------------------------|--------------------------------------------------------| +| 👟 Check it out! | ✨ [github.com/appraisal-rb/appraisal2][💎appraisal2] ✨ | + +### Federated DVCS + +
+ Find this repo on federated forges (Coming soon!) + +| Federated [DVCS][💎d-in-dvcs] Repository | Status | Issues | PRs | Wiki | CI | Discussions | +|-------------------------------------------------|-----------------------------------------------------------------------|---------------------------|--------------------------|---------------------------|--------------------------|------------------------------| +| 🧪 [ruby-oauth/oauth2 on GitLab][📜src-gl] | The Truth | [💚][🤝gl-issues] | [💚][🤝gl-pulls] | [💚][📜gl-wiki] | 🐭 Tiny Matrix | ➖ | +| 🧊 [ruby-oauth/oauth2 on CodeBerg][📜src-cb] | An Ethical Mirror ([Donate][🤝cb-donate]) | [💚][🤝cb-issues] | [💚][🤝cb-pulls] | ➖ | ⭕️ No Matrix | ➖ | +| 🐙 [ruby-oauth/oauth2 on GitHub][📜src-gh] | Another Mirror | [💚][🤝gh-issues] | [💚][🤝gh-pulls] | [💚][📜gh-wiki] | 💯 Full Matrix | [💚][gh-discussions] | +| 🎮️ [Discord Server][✉️discord-invite] | [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] | [Let's][✉️discord-invite] | [talk][✉️discord-invite] | [about][✉️discord-invite] | [this][✉️discord-invite] | [library!][✉️discord-invite] | + +
+ +[gh-discussions]: https://github.com/ruby-oauth/oauth2/discussions + +### Enterprise Support [![Tidelift](https://tidelift.com/badges/package/rubygems/oauth2)](https://tidelift.com/subscription/pkg/rubygems-oauth2?utm_source=rubygems-oauth2&utm_medium=referral&utm_campaign=readme) + +Available as part of the Tidelift Subscription. + +
+ Need enterprise-level guarantees? + +The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. + +[![Get help from me on Tidelift][🏙️entsup-tidelift-img]][🏙️entsup-tidelift] -## Installation +- 💡Subscribe for support guarantees covering _all_ your FLOSS dependencies +- 💡Tidelift is part of [Sonar][🏙️entsup-tidelift-sonar] +- 💡Tidelift pays maintainers to maintain the software you depend on!
📊`@`Pointy Haired Boss: An [enterprise support][🏙️entsup-tidelift] subscription is "[never gonna let you down][🧮kloc]", and *supports* open source maintainers - gem install oauth2 +Alternatively: -Or inside Gemfile +- [![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] +- [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork] +- [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor] - gem 'oauth2' +
-## Resources -* [View Source on GitHub][code] -* [Report Issues on GitHub][issues] -* [Read More at the Wiki][wiki] +## ✨ Installation -[code]: https://github.com/oauth-xx/oauth2 -[issues]: https://github.com/oauth-xx/oauth2/issues -[wiki]: https://github.com/oauth-xx/oauth2/wiki +Install the gem and add to the application's Gemfile by executing: -## Usage Examples +```console +bundle add oauth2 +``` + +If bundler is not being used to manage dependencies, install the gem by executing: + +```console +gem install oauth2 +``` + +### 🔒 Secure Installation + +
+ For Medium or High Security Installations + +This gem is cryptographically signed, and has verifiable [SHA-256 and SHA-512][💎SHA_checksums] checksums by +[stone_checksums][💎stone_checksums]. Be sure the gem you install hasn’t been tampered with +by following the instructions below. + +Add my public key (if you haven’t already, expires 2045-04-29) as a trusted certificate: + +```console +gem cert --add <(curl -Ls https://raw.github.com/galtzo-floss/certs/main/pboling.pem) +``` + +You only need to do that once. Then proceed to install with: + +```console +gem install oauth2 -P MediumSecurity +``` + +The `MediumSecurity` trust profile will verify signed gems, but allow the installation of unsigned dependencies. + +This is necessary because not all of `oauth2`’s dependencies are signed, so we cannot use `HighSecurity`. + +If you want to up your security game full-time: + +```console +bundle config set --global trust-policy MediumSecurity +``` + +`MediumSecurity` instead of `HighSecurity` is necessary if not all the gems you use are signed. + +NOTE: Be prepared to track down certs for signed gems and add them the same way you added mine. + +
+ +## What is new for v2.0? + +- Works with Ruby versions >= 2.2 +- Drop support for the expired MAC Draft (all versions) +- Support IETF rfc7515 JSON Web Signature - JWS (since v2.0.12) + - Support JWT `kid` for key discovery and management +- Support IETF rfc7523 JWT Bearer Tokens (since v2.0.0) +- Support IETF rfc7231 Relative Location in Redirect (since v2.0.0) +- Support IETF rfc6749 Don't set oauth params when nil (since v2.0.0) +- Support IETF rfc7009 Token Revocation (since v2.0.10, updated in v2.0.13 to support revocation via URL-encoded parameters) +- Support [OIDC 1.0 Private Key JWT](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication); based on the OAuth JWT assertion specification [(RFC 7523)](https://tools.ietf.org/html/rfc7523) +- Support new formats, including from [jsonapi.org](http://jsonapi.org/format/): `application/vdn.api+json`, `application/vnd.collection+json`, `application/hal+json`, `application/problem+json` +- Adds option to `OAuth2::Client#get_token`: + - `:access_token_class` (`AccessToken`); user specified class to use for all calls to `get_token` +- Adds option to `OAuth2::AccessToken#initialize`: + - `:expires_latency` (`nil`); number of seconds by which AccessToken validity will be reduced to offset latency +- By default, keys are transformed to snake case. + - Original keys will still work as previously, in most scenarios, thanks to [snaky_hash][snaky_hash] gem. + - However, this is a _breaking_ change if you rely on `response.parsed.to_h` to retain the original case, and the original wasn't snake case, as the keys in the result will be snake case. + - As of version 2.0.4 you can turn key transformation off with the `snaky: false` option. +- By default, the `:auth_scheme` is now `:basic_auth` (instead of `:request_body`) + - Third-party strategies and gems may need to be updated if a provider was requiring client id/secret in the request body +- [... A lot more](https://gitlab.com/ruby-oauth/oauth2/-/blob/main/CHANGELOG.md#200-2022-06-21-tag) + +[snaky_hash]: https://gitlab.com/ruby-oauth/snaky_hash + +## Compatibility + +Targeted ruby compatibility is non-EOL versions of Ruby, currently 3.2, 3.3, and 3.4. +Compatibility is further distinguished as "Best Effort Support" or "Incidental Support" for older versions of Ruby. +This gem will install on Ruby versions >= v2.2 for 2.x releases. +See `1-4-stable` branch for older rubies. + +
+ Ruby Engine Compatibility Policy + +This gem is tested against MRI, JRuby, and Truffleruby. +Each of those has varying versions that target a specific version of MRI Ruby. +This gem should work in the just-listed Ruby engines according to the targeted MRI compatibility in the table below. +If you would like to add support for additional engines, +see [gemfiles/README.md](gemfiles/README.md), then submit a PR to the correct maintenance branch as according to the table below. + +
+ +
+ Ruby Version Compatibility Policy + +If something doesn't work on one of these interpreters, it's a bug. + +This library may inadvertently work (or seem to work) on other Ruby +implementations; however, support will only be provided for the versions listed +above. + +If you would like this library to support another Ruby version, you may +volunteer to be a maintainer. Being a maintainer entails making sure all tests +run and pass on that implementation. When something breaks on your +implementation, you will be responsible for providing patches in a timely +fashion. If critical issues for a particular implementation exist at the time +of a major release, support for that Ruby version may be dropped. + +
+ +| | Ruby OAuth2 Version | Maintenance Branch | Targeted Support | Best Effort Support | Incidental Support | +|:----|---------------------|--------------------|----------------------|-------------------------|------------------------------| +| 1️⃣ | 2.0.x | `main` | 3.2, 3.3, 3.4 | 2.5, 2.6, 2.7, 3.0, 3.1 | 2.2, 2.3, 2.4 | +| 2️⃣ | 1.4.x | `1-4-stable` | 3.2, 3.3, 3.4 | 2.5, 2.6, 2.7, 3.0, 3.1 | 1.9, 2.0, 2.1, 2.2, 2.3, 2.4 | +| 3️⃣ | older | N/A | Best of luck to you! | Please upgrade! | | + +NOTE: The 1.4 series will only receive critical security updates. +See [SECURITY.md][🔐security] and [IRP.md][🔐irp]. + +## ⚙️ Configuration + +You can turn on additional warnings. ```ruby -require 'oauth2' -client = OAuth2::Client.new('client_id', 'client_secret', :site => 'https://example.org/') +OAuth2.configure do |config| + # Turn on a warning like: + # OAuth2::AccessToken.from_hash: `hash` contained more than one 'token' key + config.silence_extra_tokens_warning = false # default: true + # Set to true if you want to also show warnings about no tokens + config.silence_no_tokens_warning = false # default: true, +end +``` + +The "extra tokens" problem comes from ambiguity in the spec about which token is the right token. +Some OAuth 2.0 standards legitimately have multiple tokens. +You may need to subclass `OAuth2::AccessToken`, or write your own custom alternative to it, and pass it in. +Specify your custom class with the `access_token_class` option. + +If you only need one token, you can, as of v2.0.10, +specify the exact token name you want to extract via the `OAuth2::AccessToken` using +the `token_name` option. -client.auth_code.authorize_url(https://github.com/:redirect_uri%20=%3E%20'http://localhost:8080/oauth2/callback') -# => "https://example.org/oauth/authorization?response_type=code&client_id=client_id&redirect_uri=http://localhost:8080/oauth2/callback" +You'll likely need to do some source diving. +This gem has 100% test coverage for lines and branches, so the specs are a great place to look for ideas. +If you have time and energy, please contribute to the documentation! -token = client.auth_code.get_token('authorization_code_value', :redirect_uri => 'http://localhost:8080/oauth2/callback', :headers => {'Authorization' => 'Basic some_password'}) -response = token.get('/api/resource', :params => { 'query_foo' => 'bar' }) +## 🔧 Basic Usage + +### `authorize_url` and `token_url` are on site root (Just Works!) + +```ruby +require "oauth2" +client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/") +# => # "https://example.org/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code" + +access = client.auth_code.get_token("authorization_code_value", redirect_uri: "http://localhost:8080/oauth2/callback", headers: {"Authorization" => "Basic some_password"}) +response = access.get("/api/resource", params: {"query_foo" => "bar"}) response.class.name # => OAuth2::Response ``` -### DEBUGGING +### Relative `authorize_url` and `token_url` (Not on site root, Just Works!) + +In the above example, the default Authorization URL is `oauth/authorize` and default Access Token URL is `oauth/token`, and, as they are missing a leading `/`, both are relative. + +```ruby +client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/nested/directory/on/your/server") +# => # "https://example.org/nested/directory/on/your/server/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code" +``` + +### Customize `authorize_url` and `token_url` + +You can specify custom URLs for authorization and access token, and when using a leading `/` they will _not be relative_, as shown below: + +```ruby +client = OAuth2::Client.new( + "client_id", + "client_secret", + site: "https://example.org/nested/directory/on/your/server", + authorize_url: "/jaunty/authorize/", + token_url: "/stirrups/access_token", +) +# => # "https://example.org/jaunty/authorize/?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code" +client.class.name +# => OAuth2::Client +``` + +### snake_case and indifferent access in Response#parsed + +```ruby +response = access.get("/api/resource", params: {"query_foo" => "bar"}) +# Even if the actual response is CamelCase. it will be made available as snaky: +JSON.parse(response.body) # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"} +response.parsed # => {"access_token"=>"aaaaaaaa", "additional_data"=>"additional"} +response.parsed.access_token # => "aaaaaaaa" +response.parsed[:access_token] # => "aaaaaaaa" +response.parsed.additional_data # => "additional" +response.parsed[:additional_data] # => "additional" +response.parsed.class.name # => SnakyHash::StringKeyed (from snaky_hash gem) +``` + +#### Serialization + +As of v2.0.11, if you need to serialize the parsed result, you can! + +There are two ways to do this, globally, or discretely. The discrete way is recommended. + +##### Global Serialization Config + +Globally configure `SnakyHash::StringKeyed` to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails). + +```ruby +SnakyHash::StringKeyed.class_eval do + extend SnakyHash::Serializer +end +``` + +##### Discrete Serialization Config -Set an environment variable, however you would [normally do that](https://github.com/bkeepers/dotenv). +Discretely configure a custom Snaky Hash class to use the serializer. + +```ruby +class MySnakyHash < SnakyHash::StringKeyed + # Give this hash class `dump` and `load` abilities! + extend SnakyHash::Serializer +end + +# And tell your client to use the custom class in each call: +client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/oauth2") +token = client.get_token({snaky_hash_klass: MySnakyHash}) +``` + +##### Serialization Extensions + +These extensions work regardless of whether you used the global or discrete config above. + +There are a few hacks you may need in your class to support Ruby < 2.4.2 or < 2.6. +They are likely not needed if you are on a newer Ruby. +Expand the examples below, or the [ruby-oauth/snaky_hash](https://gitlab.com/ruby-oauth/snaky_hash) gem, +or [response_spec.rb](https://github.com/ruby-oauth/oauth2/blob/main/spec/oauth2/response_spec.rb), for more ideas, especially if you need to study the hacks for older Rubies. + +
+ See Examples + +```ruby +class MySnakyHash < SnakyHash::StringKeyed + # Give this hash class `dump` and `load` abilities! + extend SnakyHash::Serializer + + #### Serialization Extentions + # + # Act on the non-hash values (including the values of hashes) as they are dumped to JSON + # In other words, this retains nested hashes, and only the deepest leaf nodes become bananas. + # WARNING: This is a silly example! + dump_value_extensions.add(:to_fruit) do |value| + "banana" # => Make values "banana" on dump + end + + # Act on the non-hash values (including the values of hashes) as they are loaded from the JSON dump + # In other words, this retains nested hashes, and only the deepest leaf nodes become ***. + # WARNING: This is a silly example! + load_value_extensions.add(:to_stars) do |value| + "***" # Turn dumped bananas into *** when they are loaded + end + + # Act on the entire hash as it is prepared for dumping to JSON + # WARNING: This is a silly example! + dump_hash_extensions.add(:to_cheese) do |value| + if value.is_a?(Hash) + value.transform_keys do |key| + split = key.split("_") + first_word = split[0] + key.sub(first_word, "cheese") + end + else + value + end + end + + # Act on the entire hash as it is loaded from the JSON dump + # WARNING: This is a silly example! + load_hash_extensions.add(:to_pizza) do |value| + if value.is_a?(Hash) + res = klass.new + value.keys.each_with_object(res) do |key, result| + split = key.split("_") + last_word = split[-1] + new_key = key.sub(last_word, "pizza") + result[new_key] = value[key] + end + res + else + value + end + end +end +``` + +
+ +#### Prefer camelCase over snake_case? => snaky: false + +```ruby +response = access.get("/api/resource", params: {"query_foo" => "bar"}, snaky: false) +JSON.parse(response.body) # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"} +response.parsed # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"} +response.parsed["accessToken"] # => "aaaaaaaa" +response.parsed["additionalData"] # => "additional" +response.parsed.class.name # => Hash (just, regular old Hash) +``` + +
+ Debugging & Logging + +Set an environment variable as per usual (e.g. with [dotenv](https://github.com/bkeepers/dotenv)). ```ruby # will log both request and response, including bodies -ENV['OAUTH_DEBUG'] = 'true' +ENV["OAUTH_DEBUG"] = "true" ``` By default, debug output will go to `$stdout`. This can be overridden when initializing your OAuth2::Client. ```ruby -require 'oauth2' +require "oauth2" client = OAuth2::Client.new( - 'client_id', - 'client_secret', - :site => 'https://example.org/', - :logger => Logger.new('example.log', 'weekly') + "client_id", + "client_secret", + site: "https://example.org/", + logger: Logger.new("example.log", "weekly"), ) ``` -## OAuth2::Response +
+ +### OAuth2::Response The `AccessToken` methods `#get`, `#post`, `#put` and `#delete` and the generic `#request` will return an instance of the #OAuth2::Response class. This instance contains a `#parsed` method that will parse the response body and -return a Hash if the `Content-Type` is `application/x-www-form-urlencoded` or if +return a Hash-like [`SnakyHash::StringKeyed`](https://gitlab.com/ruby-oauth/snaky_hash/-/blob/main/lib/snaky_hash/string_keyed.rb) if the `Content-Type` is `application/x-www-form-urlencoded` or if the body is a JSON object. It will return an Array if the body is a JSON array. Otherwise, it will return the original body string. The original response body, headers, and status can be accessed via their respective methods. -## OAuth2::AccessToken +### OAuth2::AccessToken If you have an existing Access Token for a user, you can initialize an instance using various class methods including the standard new, `from_hash` (if you have a hash of the values), or `from_kvform` (if you have an `application/x-www-form-urlencoded` encoded string of the values). -## OAuth2::Error +Options (since v2.0.x unless noted): + +- `expires_latency` (Integer | nil): Seconds to subtract from expires_in when computing #expired? to offset latency. +- `token_name` (String | Symbol | nil): When multiple token-like fields exist in responses, select the field name to use as the access token (since v2.0.10). +- `mode` (Symbol | Proc | Hash): Controls how the token is transmitted on requests made via this AccessToken instance. + - `:header` — Send as Authorization: Bearer header (default and preferred by OAuth 2.1 draft guidance). + - `:query` — Send as access_token query parameter (discouraged in general, but required by some providers). + - Verb-dependent (since v2.0.15): Provide either: + - a `Proc` taking `|verb|` and returning `:header` or `:query`, or + - a `Hash` with verb symbols as keys, for example `{get: :query, post: :header, delete: :header}`. + +Note: Verb-dependent mode supports providers like Instagram that require query mode for `GET` and header mode for `POST`/`DELETE` + +- Verb-dependent mode via `Proc` was added in v2.0.15 +- Verb-dependent mode via `Hash` was added in v2.0.16 + +### OAuth2::Error On 400+ status code responses, an `OAuth2::Error` will be raised. If it is a standard OAuth2 error response, the body will be parsed and `#code` and `#description` will contain the values provided from the error and @@ -134,125 +613,905 @@ option on initialization of the client. In this case the `OAuth2::Response` instance will be returned as usual and on 400+ status code responses, the Response instance will contain the `OAuth2::Error` instance. -## Authorization Grants +### Authorization Grants -Currently the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion -authentication grant types have helper strategy classes that simplify client -use. They are available via the `#auth_code`, `#implicit`, `#password`, `#client_credentials`, and `#assertion` methods respectively. +Note on OAuth 2.1 (draft): -```ruby -auth_url = client.auth_code.authorize_url(https://github.com/:redirect_uri%20=%3E%20'http://localhost:8080/oauth/callback') -token = client.auth_code.get_token('code_value', :redirect_uri => 'http://localhost:8080/oauth/callback') +- PKCE is required for all OAuth clients using the authorization code flow (especially public clients). Implement PKCE in your app when required by your provider. See RFC 7636 and RFC 8252. +- Redirect URIs must be compared using exact string matching by the Authorization Server. +- The Implicit grant (response_type=token) and the Resource Owner Password Credentials grant are omitted from OAuth 2.1; they remain here for OAuth 2.0 compatibility but should be avoided for new apps. +- Bearer tokens in the query string are omitted due to security risks; prefer Authorization header usage. +- Refresh tokens for public clients must either be sender-constrained (e.g., DPoP/MTLS) or one-time use. +- The definitions of public and confidential clients are simplified to refer only to whether the client has credentials. -auth_url = client.implicit.authorize_url(https://github.com/:redirect_uri%20=%3E%20'http://localhost:8080/oauth/callback') -# get the token params in the callback and -token = OAuth2::AccessToken.from_kvform(client, query_string) +References: + +- OAuth 2.1 draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13 +- Aaron Parecki: https://aaronparecki.com/2019/12/12/21/its-time-for-oauth-2-dot-1 +- FusionAuth: https://fusionauth.io/blog/2020/04/15/whats-new-in-oauth-2-1 +- Okta: https://developer.okta.com/blog/2019/12/13/oauth-2-1-how-many-rfcs +- Video: https://www.youtube.com/watch?v=g_aVPdwBTfw +- Differences overview: https://fusionauth.io/learn/expert-advice/oauth/differences-between-oauth-2-oauth-2-1/ + +Currently, the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion +authentication grant types have helper strategy classes that simplify client +use. They are available via the [`#auth_code`](https://gitlab.com/ruby-oauth/oauth2/-/blob/main/lib/oauth2/strategy/auth_code.rb), +[`#implicit`](https://gitlab.com/ruby-oauth/oauth2/-/blob/main/lib/oauth2/strategy/implicit.rb), +[`#password`](https://gitlab.com/ruby-oauth/oauth2/-/blob/main/lib/oauth2/strategy/password.rb), +[`#client_credentials`](https://gitlab.com/ruby-oauth/oauth2/-/blob/main/lib/oauth2/strategy/client_credentials.rb), and +[`#assertion`](https://gitlab.com/ruby-oauth/oauth2/-/blob/main/lib/oauth2/strategy/assertion.rb) methods respectively. -token = client.password.get_token('username', 'password') +These aren't full examples, but demonstrative of the differences between usage for each strategy. -token = client.client_credentials.get_token +```ruby +auth_url = client.auth_code.authorize_url(https://github.com/redirect_uri:%20%22http://localhost:8080/oauth/callback") +access = client.auth_code.get_token("code_value", redirect_uri: "http://localhost:8080/oauth/callback") -token = client.assertion.get_token(assertion_params) +auth_url = client.implicit.authorize_url(https://github.com/redirect_uri:%20%22http://localhost:8080/oauth/callback") +# get the token params in the callback and +access = OAuth2::AccessToken.from_kvform(client, query_string) + +access = client.password.get_token("username", "password") + +access = client.client_credentials.get_token + +# Client Assertion Strategy +# see: https://tools.ietf.org/html/rfc7523 +claimset = { + iss: "http://localhost:3001/", + aud: "http://localhost:8080/oauth2/token", + sub: "me@example.com", + exp: Time.now.utc.to_i + 3600, +} +assertion_params = [claimset, "HS256", "secret_key"] +access = client.assertion.get_token(assertion_params) + +# The `access` (i.e. access token) is then used like so: +access.token # actual access_token string, if you need it somewhere +access.get("/api/stuff") # making api calls with access token ``` If you want to specify additional headers to be sent out with the request, add a 'headers' hash under 'params': ```ruby -token = client.auth_code.get_token('code_value', :redirect_uri => 'http://localhost:8080/oauth/callback', :headers => {'Some' => 'Header'}) +access = client.auth_code.get_token("code_value", redirect_uri: "http://localhost:8080/oauth/callback", headers: {"Some" => "Header"}) ``` You can always use the `#request` method on the `OAuth2::Client` instance to make requests for tokens for any Authentication grant type. +## 📘 Comprehensive Usage -## Supported Ruby Versions +### Common Flows (end-to-end) -This library aims to support and is [tested against][travis] the following Ruby -implementations: +- Authorization Code (server-side web app): -### Rubies with support ending at Oauth2 1.x +```ruby +require "oauth2" +client = OAuth2::Client.new( + ENV["CLIENT_ID"], + ENV["CLIENT_SECRET"], + site: "https://provider.example.com/", + redirect_uri: "https://my.app.example.com/oauth/callback", +) -For information on supported Rubies for the current 1.x release of oauth2 see the [README for 1.4.x](https://github.com/oauth-xx/oauth2/blob/1-4-stable/README.md) +# Step 1: redirect user to consent +state = SecureRandom.hex(16) +auth_url = client.auth_code.authorize_url(/service/scope: "openid profile email", state: state) +# redirect_to auth_url ---- +# Step 2: handle the callback +# params[:code], params[:state] +raise "state mismatch" unless params[:state] == state +access = client.auth_code.get_token(params[:code]) -### Rubies with continued support past Oauth2 2.x +# Step 3: call APIs +profile = access.get("/api/v1/me").parsed +``` -* Ruby 2.2 - Support ends with version 2.x series -* Ruby 2.3 - Support ends with version 3.x series - - [JRuby 9.1][jruby-9.1] (targets MRI v2.3) -* Ruby 2.4 - Support ends with version 4.x series -* Ruby 2.5 - Support ends with version 5.x series - - [JRuby 9.2][jruby-9.2] (targets MRI v2.5) - - [truffleruby][truffleruby] (targets MRI 2.5) -* Ruby 2.6 - Support ends with version 6.x series -* Ruby 2.7 - Support ends with version 7.x series +- Client Credentials (machine-to-machine): -[jruby-1.7]: https://www.jruby.org/2017/05/11/jruby-1-7-27.html -[jruby-9.0]: https://www.jruby.org/2016/01/26/jruby-9-0-5-0.html -[jruby-9.1]: https://www.jruby.org/2017/05/16/jruby-9-1-9-0.html -[jruby-9.2]: https://www.jruby.org/2018/05/24/jruby-9-2-0-0.html -[truffleruby]: https://github.com/oracle/truffleruby +```ruby +client = OAuth2::Client.new(ENV["CLIENT_ID"], ENV["CLIENT_SECRET"], site: "https://provider.example.com/") +access = client.client_credentials.get_token(audience: "https://api.example.com/") +resp = access.get("/v1/things") +``` -If something doesn't work on one of these interpreters, it's a bug. +- Resource Owner Password (legacy; avoid when possible): -This library may inadvertently work (or seem to work) on other Ruby -implementations, however support will only be provided for the versions listed -above. +```ruby +access = client.password.get_token("jdoe", "s3cret", scope: "read") +``` -If you would like this library to support another Ruby version, you may -volunteer to be a maintainer. Being a maintainer entails making sure all tests -run and pass on that implementation. When something breaks on your -implementation, you will be responsible for providing patches in a timely -fashion. If critical issues for a particular implementation exist at the time -of a major release, support for that Ruby version may be dropped. +#### Examples -## Versioning +
+JHipster UAA (Spring Cloud) password grant example (legacy; avoid when possible) -This library aims to adhere to [Semantic Versioning 2.0.0][semver]. -Violations of this scheme should be reported as bugs. Specifically, -if a minor or patch version is released that breaks backward -compatibility, a new version should be immediately released that -restores compatibility. Breaking changes to the public API will -only be introduced with new major versions. +```ruby +# This converts a Postman/Net::HTTP multipart token request to oauth2 gem usage. +# JHipster UAA typically exposes the token endpoint at /uaa/oauth/token. +# The original snippet included: +# - Basic Authorization header for the client (web_app:changeit) +# - X-XSRF-TOKEN header from a cookie (some deployments require it) +# - grant_type=password with username/password and client_id +# Using oauth2 gem, you don't need to build multipart bodies; the gem sends +# application/x-www-form-urlencoded as required by RFC 6749. -As a result of this policy, you can (and should) specify a -dependency on this gem using the [Pessimistic Version Constraint][pvc] with two digits of precision. +require "oauth2" -For example: +client = OAuth2::Client.new( + "web_app", # client_id + "changeit", # client_secret + site: "http://localhost:8080/uaa", + token_url: "/oauth/token", # absolute under site (or "oauth/token" relative) + auth_scheme: :basic_auth, # sends HTTP Basic Authorization header +) + +# If your UAA requires an XSRF header for the token call, provide it as a header. +# Often this is not required for token endpoints, but if your gateway enforces it, +# obtain the value from the XSRF-TOKEN cookie and pass it here. +xsrf_token = ENV["X_XSRF_TOKEN"] # e.g., pulled from a prior set-cookie value + +access = client.password.get_token( + "admin", # username + "admin", # password + headers: xsrf_token ? {"X-XSRF-TOKEN" => xsrf_token} : {}, + # JHipster commonly also accepts/needs the client_id in the body; include if required: + # client_id: "web_app", +) + +puts access.token +puts access.to_hash # full token response +``` + +Notes: + +- Resource Owner Password Credentials (ROPC) is deprecated in OAuth 2.1 and discouraged. Prefer Authorization Code + PKCE. +- If your deployment strictly demands the X-XSRF-TOKEN header, first fetch it from an endpoint that sets the XSRF-TOKEN cookie (often "/" or a login page) and pass it to headers. +- For Basic auth, auth_scheme: :basic_auth handles the Authorization header; you do not need to base64-encode manually. + +
+ +### Instagram API (verb‑dependent token mode) + +Providers like Instagram require the access token to be sent differently depending on the HTTP verb: + +- GET requests: token must be in the query string (?access_token=...) +- POST/DELETE requests: token must be in the Authorization header (Bearer ...) + +Since v2.0.15, you can configure an AccessToken with a verb‑dependent mode. The gem will choose how to send the token based on the request method. + +Example: exchanging and refreshing long‑lived Instagram tokens, and making API calls + +```ruby +require "oauth2" + +# NOTE: Users authenticate via Facebook Login to obtain a short‑lived user token (not shown here). +# See Facebook Login docs for obtaining the initial short‑lived token. + +client = OAuth2::Client.new(nil, nil, site: "https://graph.instagram.com/") + +# Start with a short‑lived token you already obtained via Facebook Login +short_lived = OAuth2::AccessToken.new( + client, + ENV["IG_SHORT_LIVED_TOKEN"], + # Key part: verb‑dependent mode + mode: {get: :query, post: :header, delete: :header}, +) + +# 1) Exchange for a long‑lived token (Instagram requires GET with access_token in query) +# Endpoint: GET https://graph.instagram.com/access_token +# Params: grant_type=ig_exchange_token, client_secret=APP_SECRET +exchange = short_lived.get( + "/access_token", + params: { + grant_type: "ig_exchange_token", + client_secret: ENV["IG_APP_SECRET"], + # access_token param will be added automatically by the AccessToken (mode => :query for GET) + }, +) +long_lived_token_value = exchange.parsed["access_token"] + +long_lived = OAuth2::AccessToken.new( + client, + long_lived_token_value, + mode: {get: :query, post: :header, delete: :header}, +) + +# 2) Refresh the long‑lived token (Instagram uses GET with token in query) +# Endpoint: GET https://graph.instagram.com/refresh_access_token +refresh_resp = long_lived.get( + "/refresh_access_token", + params: {grant_type: "ig_refresh_token"}, +) +long_lived = OAuth2::AccessToken.new( + client, + refresh_resp.parsed["access_token"], + mode: {get: :query, post: :header, delete: :header}, +) + +# 3) Typical API GET request (token in query automatically) +me = long_lived.get("/me", params: {fields: "id,username"}).parsed + +# 4) Example POST (token sent via Bearer header automatically) +# Note: Replace the path/params with a real Instagram Graph API POST you need, +# such as publishing media via the Graph API endpoints. +# long_lived.post("/me/media", body: {image_url: "https://.../", caption: "hello"}) +``` + +Tips: + +- Avoid query‑string bearer tokens unless required by your provider. Instagram explicitly requires it for `GET` requests. +- If you need a custom rule, you can pass a `Proc` for `mode`, e.g. `mode: ->(verb) { verb == :get ? :query : :header }`. + +### Refresh Tokens + +When the server issues a refresh_token, you can refresh manually or implement an auto-refresh wrapper. + +- Manual refresh: + +```ruby +if access.expired? + access = access.refresh +end +``` + +- Auto-refresh wrapper pattern: + +```ruby +class AutoRefreshingToken + def initialize(token_provider, store: nil) + @token = token_provider + @store = store # e.g., something that responds to read/write for token data + end + + def with(&blk) + tok = ensure_fresh! + blk ? blk.call(tok) : tok + rescue OAuth2::Error => e + # If a 401 suggests token invalidation, try one refresh and retry once + if e.response && e.response.status == 401 && @token.refresh_token + @token = @token.refresh + @store.write(@token.to_hash) if @store + retry + end + raise + end + +private + + def ensure_fresh! + if @token.expired? && @token.refresh_token + @token = @token.refresh + @store.write(@token.to_hash) if @store + end + @token + end +end + +# usage +keeper = AutoRefreshingToken.new(access) +keeper.with { |tok| tok.get("/v1/protected") } +``` + +Persist the token across processes using `AccessToken#to_hash` and `AccessToken.from_hash(client, hash)`. + +### Token Revocation (RFC 7009) + +You can revoke either the access token or the refresh token. + +```ruby +# Revoke the current access token +access.revoke(token_type_hint: :access_token) + +# Or explicitly revoke the refresh token (often also invalidates associated access tokens) +access.revoke(token_type_hint: :refresh_token) +``` + +### Client Configuration Tips + +#### Mutual TLS (mTLS) client authentication + +Some providers require OAuth requests (including the token request and subsequent API calls) to be sender‑constrained using mutual TLS (mTLS). With this gem, you enable mTLS by providing a client certificate/private key to Faraday via connection_opts.ssl and, if your provider requires it for client authentication, selecting the tls_client_auth auth_scheme. + +Example using PEM files (certificate and key): + +```ruby +require "oauth2" +require "openssl" + +client = OAuth2::Client.new( + ENV.fetch("https://github.com/CLIENT_ID"), + ENV.fetch("https://github.com/CLIENT_SECRET"), + site: "https://example.com/", + authorize_url: "/oauth/authorize/", + token_url: "/oauth/token/", + auth_scheme: :tls_client_auth, # if your AS requires mTLS-based client authentication + connection_opts: { + ssl: { + client_cert: OpenSSL::X509::Certificate.new(File.read("localhost.pem")), + client_key: OpenSSL::PKey::RSA.new(File.read("localhost-key.pem")), + # Optional extras, uncomment as needed: + # ca_file: "/path/to/ca-bundle.pem", # custom CA(s) + # verify: true # enable server cert verification (recommended) + }, + }, +) + +# Example token request (any grant type can be used). The mTLS handshake +# will occur automatically on HTTPS calls using the configured cert/key. +access = client.client_credentials.get_token + +# Subsequent resource requests will also use mTLS on HTTPS endpoints of `site`: +resp = access.get("/v1/protected") +``` + +Notes: + +- Files must contain the appropriate PEMs. The private key may be encrypted; if so, pass a password to `OpenSSL::PKey::RSA.new(File.read(path), ENV["KEY_PASSWORD"])`. +- If your certificate and key are in a PKCS#12/PFX bundle, you can load them like: + - `p12 = OpenSSL::PKCS12.new(File.read("client.p12"), ENV["P12_PASSWORD"])` + - `client_cert = p12.certificate; client_key = p12.key` +- Server trust: + - If your environment does not have system CAs, specify `ca_file` or `ca_path` inside the `ssl:` hash. + - Keep `verify: true` in production. Set `verify: false` only for local testing. +- Faraday adapter: Any adapter that supports Ruby’s OpenSSL should work. `net_http` (default) and `net_http_persistent` are common choices. +- Scope of mTLS: The SSL client cert is applied to any HTTPS request made by this client (token and resource requests) to the configured site base URL (and absolute URLs you call with the same client). +- OIDC tie-in: Some OPs require tls_client_auth at the token endpoint per OIDC/OAuth specifications. That is enabled via `auth_scheme: :tls_client_auth` as shown above. + +#### Authentication schemes for the token request + +```ruby +OAuth2::Client.new( + id, + secret, + site: "https://provider.example.com/", + auth_scheme: :basic_auth, # default. Alternatives: :request_body, :tls_client_auth, :private_key_jwt +) +``` + +#### Faraday connection, timeouts, proxy, custom adapter/middleware: + +```ruby +client = OAuth2::Client.new( + id, + secret, + site: "https://provider.example.com/", + connection_opts: { + request: {open_timeout: 5, timeout: 15}, + proxy: ENV["HTTPS_PROXY"], + ssl: {verify: true}, + }, +) do |faraday| + faraday.request(:url_encoded) + # faraday.response :logger, Logger.new($stdout) # see OAUTH_DEBUG below + faraday.adapter(:net_http_persistent) # or any Faraday adapter you need +end +``` + +##### Using flat query params (`Faraday::FlatParamsEncoder`) + +Some APIs expect repeated key parameters to be sent as flat params rather than arrays. Faraday provides `FlatParamsEncoder` for this purpose. You can configure the oauth2 client to use it when building requests. + +```ruby +require "faraday" + +client = OAuth2::Client.new( + id, + secret, + site: "https://api.example.com/", + # Pass Faraday connection options to make FlatParamsEncoder the default + connection_opts: { + request: {params_encoder: Faraday::FlatParamsEncoder}, + }, +) do |faraday| + faraday.request(:url_encoded) + faraday.adapter(:net_http) +end + +access = client.client_credentials.get_token + +# Example of a GET with two flat filter params (not an array): +# Results in: ?filter=order.clientCreatedTime%3E1445006997000&filter=order.clientCreatedTime%3C1445611797000 +resp = access.get( + "/v1/orders", + params: { + # Provide the values as an array; FlatParamsEncoder expands them as repeated keys + filter: [ + "order.clientCreatedTime>1445006997000", + "order.clientCreatedTime<1445611797000", + ], + }, +) +``` + +If you instead need to build a raw Faraday connection yourself, the equivalent configuration is: + +```ruby +conn = Faraday.new("https://api.example.com/", request: {params_encoder: Faraday::FlatParamsEncoder}) +``` + +#### Redirection + +The library follows up to `max_redirects` (default 5). +You can override per-client via `options[:max_redirects]`. + +### Handling Responses and Errors + +- Parsing: + +```ruby +resp = access.get("/v1/thing") +resp.status # Integer +resp.headers # Hash +resp.body # String +resp.parsed # SnakyHash::StringKeyed or Array when JSON array +``` + +- Error handling: + +```ruby +begin + access.get("/v1/forbidden") +rescue OAuth2::Error => e + e.code # OAuth2 error code (when present) + e.description # OAuth2 error description (when present) + e.response # OAuth2::Response (full access to status/headers/body) +end +``` + +- Disable raising on 4xx/5xx to inspect the response yourself: + +```ruby +client = OAuth2::Client.new(id, secret, site: site, raise_errors: false) +res = client.request(:get, "/v1/maybe-errors") +if res.status == 429 + sleep res.headers["retry-after"].to_i +end +``` + +### Making Raw Token Requests + +If a provider requires non-standard parameters or headers, you can call `client.get_token` directly: ```ruby -spec.add_dependency 'oauth2', '~> 1.4' +access = client.get_token({ + grant_type: "client_credentials", + audience: "https://api.example.com/", + headers: {"X-Custom" => "value"}, + parse: :json, # override parsing +}) ``` -[semver]: http://semver.org/ -[pvc]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint +### OpenID Connect (OIDC) Notes + +- If the token response includes an `id_token` (a JWT), this gem surfaces it but does not validate the signature. Use a JWT library and your provider's JWKs to verify it. +- For private_key_jwt client authentication, provide `auth_scheme: :private_key_jwt` and ensure your key configuration matches the provider requirements. +- See [OIDC.md](OIDC.md) for a more complete OIDC overview, example, and links to the relevant specifications. + +### Debugging + +- Set environment variable `OAUTH_DEBUG=true` to enable verbose Faraday logging (uses the client-provided logger). +- To mirror a working curl request, ensure you set the same auth scheme, params, and content type. The Quick Example at the top shows a curl-to-ruby translation. + +--- + +## 🦷 FLOSS Funding + +While ruby-oauth tools are free software and will always be, the project would benefit immensely from some funding. +Raising a monthly budget of... "dollars" would make the project more sustainable. + +We welcome both individual and corporate sponsors! We also offer a +wide array of funding channels to account for your preferences +(although currently [Open Collective][🖇osc] is our preferred funding platform). + +**If you're working in a company that's making significant use of ruby-oauth tools we'd +appreciate it if you suggest to your company to become a ruby-oauth sponsor.** -## License +You can support the development of ruby-oauth tools via +[GitHub Sponsors][🖇sponsor], +[Liberapay][⛳liberapay], +[PayPal][🖇paypal], +[Open Collective][🖇osc] +and [Tidelift][🏙️entsup-tidelift]. -[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)][source-license] +| 📍 NOTE | +|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| If doing a sponsorship in the form of donation is problematic for your company
from an accounting standpoint, we'd recommend the use of Tidelift,
where you can get a support-like subscription instead. | -- Copyright (c) 2011-2013 Michael Bleigh and Intridea, Inc. -- Copyright (c) 2017-2018 [oauth-xx organization][oauth-xx] -- See [LICENSE][license] for details. +### Open Collective for Individuals -[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Foauth-xx%2Foauth2.svg?type=large)][fossa2] +Support us with a monthly donation and help us continue our activities. [[Become a backer](https://opencollective.com/ruby-oauth#backer)] -[license]: LICENSE -[oauth-xx]: https://github.com/oauth-xx -[fossa2]: https://app.fossa.io/projects/git%2Bgithub.com%2Foauth-xx%2Foauth2?ref=badge_large +NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically. -## Development + +No backers yet. Be the first! + -After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. +### Open Collective for Organizations -To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then 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](https://rubygems.org). +Become a sponsor and get your logo on our README on GitHub with a link to your site. [[Become a sponsor](https://opencollective.com/ruby-oauth#sponsor)] -## Contributing +NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically. -Bug reports and pull requests are welcome on GitHub at https://github.com/oauth-xx/oauth2. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct. + +No sponsors yet. Be the first! -## Code of Conduct +### Open Collective for Donors + +[Bill Woika](https://opencollective.com/bill-woika) + + +[kettle-readme-backers]: https://github.com/ruby-oauth/oauth2/blob/main/exe/kettle-readme-backers + +### Another way to support open-source + +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`. + +I’m developing a new library, [floss_funding][🖇floss-funding-gem], designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look. + +**[Floss-Funding.dev][🖇floss-funding.dev]: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags** + +[![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 efforts at ko-fi.com][🖇kofi-img]][🖇kofi] [![Donate to my FLOSS efforts using Patreon][🖇patreon-img]][🖇patreon] + +## 🔐 Security + +To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). +Tidelift will coordinate the fix and disclosure. + +For more see [SECURITY.md][🔐security], [THREAT_MODEL.md][🔐threat-model], and [IRP.md][🔐irp]. + +## 🤝 Contributing + +If you need some ideas of where to help, you could work on adding more code coverage, +or if it is already 💯 (see [below](#code-coverage)) check [reek](REEK), [issues][🤝gh-issues], or [PRs][🤝gh-pulls], +or use the gem and think about how it could be better. + +We [![Keep A Changelog][📗keep-changelog-img]][📗keep-changelog] so if you make changes, remember to update it. + +See [CONTRIBUTING.md][🤝contributing] for more detailed instructions. + +### 🚀 Release Instructions + +See [CONTRIBUTING.md][🤝contributing]. + +### Code Coverage + +[![Coverage Graph][🏀codecov-g]][🏀codecov] + +[![Coveralls Test Coverage][🏀coveralls-img]][🏀coveralls] + +[![QLTY Test Coverage][🏀qlty-covi]][🏀qlty-cov] + +### 🪇 Code of Conduct + +Everyone interacting with this project's codebases, issue trackers, +chat rooms and mailing lists agrees to follow the [![Contributor Covenant 2.1][🪇conduct-img]][🪇conduct]. + +## 🌈 Contributors + +[![Contributors][🖐contributors-img]][🖐contributors] + +Made with [contributors-img][🖐contrib-rocks]. + +Also see GitLab Contributors: [https://gitlab.com/ruby-oauth/oauth2/-/graphs/main][🚎contributors-gl] + +
+ ⭐️ Star History + + + + + + Star History Chart + + + +
+ +## 📌 Versioning + +This Library adheres to [![Semantic Versioning 2.0.0][📌semver-img]][📌semver]. +Violations of this scheme should be reported as bugs. +Specifically, if a minor or patch version is released that breaks backward compatibility, +a new version should be immediately released that restores compatibility. +Breaking changes to the public API will only be introduced with new major versions. + +> dropping support for a platform is both obviously and objectively a breaking change
+>—Jordan Harband ([@ljharb](https://github.com/ljharb), maintainer of SemVer) [in SemVer issue 716][📌semver-breaking] + +I understand that policy doesn't work universally ("exceptions to every rule!"), +but it is the policy here. +As such, in many cases it is good to specify a dependency on this library using +the [Pessimistic Version Constraint][📌pvc] with two digits of precision. + +For example: + +```ruby +spec.add_dependency("oauth2", "~> 2.0") +``` -Everyone interacting in the OAuth2 project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/oauth-xx/oauth2/blob/master/CODE_OF_CONDUCT.md). +
+📌 Is "Platform Support" part of the public API? More details inside. + +SemVer should, IMO, but doesn't explicitly, say that dropping support for specific Platforms +is a *breaking change* to an API, and for that reason the bike shedding is endless. + +To get a better understanding of how SemVer is intended to work over a project's lifetime, +read this article from the creator of SemVer: + +- ["Major Version Numbers are Not Sacred"][📌major-versions-not-sacred] + +
+ +See [CHANGELOG.md][📌changelog] for a list of releases. + +## 📄 License + +The gem is available as open source under the terms of +the [MIT License][📄license] [![License: MIT][📄license-img]][📄license-ref]. +See [LICENSE.txt][📄license] for the official [Copyright Notice][📄copyright-notice-explainer]. + +### © Copyright + +
    +
  • + Copyright (c) 2017 – 2025 Peter H. Boling, of + + Galtzo.com + + Galtzo.com Logo (Wordless) by Aboling0, CC BY-SA 4.0 + + , and oauth2 contributors. +
    • +
  • + Copyright (c) 2011 - 2013 Michael Bleigh and Intridea, Inc. +
    • +
+ +## 🤑 A request for help + +Maintainers have teeth and need to pay their dentists. +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. + +To join the community or get help 👇️ Join the Discord. + +[![Live Chat on Discord][✉️discord-invite-img-ftb]][✉️discord-invite] + +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] 💌 [![Donate on PayPal][🖇paypal-bottom-img]][🖇paypal] + +### Please give the project a star ⭐ ♥. + +Thanks for RTFM. ☺️ + +[⛳liberapay-img]: https://img.shields.io/liberapay/goal/pboling.svg?logo=liberapay&color=a51611&style=flat +[⛳liberapay-bottom-img]: https://img.shields.io/liberapay/goal/pboling.svg?style=for-the-badge&logo=liberapay&color=a51611 +[⛳liberapay]: https://liberapay.com/pboling/donate +[🖇osc-all-img]: https://img.shields.io/opencollective/all/ruby-oauth +[🖇osc-sponsors-img]: https://img.shields.io/opencollective/sponsors/ruby-oauth +[🖇osc-backers-img]: https://img.shields.io/opencollective/backers/ruby-oauth +[🖇osc-backers]: https://opencollective.com/ruby-oauth#backer +[🖇osc-backers-i]: https://opencollective.com/ruby-oauth/backers/badge.svg?style=flat +[🖇osc-sponsors]: https://opencollective.com/ruby-oauth#sponsor +[🖇osc-sponsors-i]: https://opencollective.com/ruby-oauth/sponsors/badge.svg?style=flat +[🖇osc-all-bottom-img]: https://img.shields.io/opencollective/all/ruby-oauth?style=for-the-badge +[🖇osc-sponsors-bottom-img]: https://img.shields.io/opencollective/sponsors/ruby-oauth?style=for-the-badge +[🖇osc-backers-bottom-img]: https://img.shields.io/opencollective/backers/ruby-oauth?style=for-the-badge +[🖇osc]: https://opencollective.com/ruby-oauth +[🖇sponsor-img]: https://img.shields.io/badge/Sponsor_Me!-pboling.svg?style=social&logo=github +[🖇sponsor-bottom-img]: https://img.shields.io/badge/Sponsor_Me!-pboling-blue?style=for-the-badge&logo=github +[🖇sponsor]: https://github.com/sponsors/pboling +[🖇polar-img]: https://img.shields.io/badge/polar-donate-a51611.svg?style=flat +[🖇polar]: https://polar.sh/pboling +[🖇kofi-img]: https://img.shields.io/badge/ko--fi-%E2%9C%93-a51611.svg?style=flat +[🖇kofi]: https://ko-fi.com/O5O86SNP4 +[🖇patreon-img]: https://img.shields.io/badge/patreon-donate-a51611.svg?style=flat +[🖇patreon]: https://patreon.com/galtzo +[🖇buyme-small-img]: https://img.shields.io/badge/buy_me_a_coffee-%E2%9C%93-a51611.svg?style=flat +[🖇buyme-img]: https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20latte&emoji=&slug=pboling&button_colour=FFDD00&font_colour=000000&font_family=Cookie&outline_colour=000000&coffee_colour=ffffff +[🖇buyme]: https://www.buymeacoffee.com/pboling +[🖇paypal-img]: https://img.shields.io/badge/donate-paypal-a51611.svg?style=flat&logo=paypal +[🖇paypal-bottom-img]: https://img.shields.io/badge/donate-paypal-a51611.svg?style=for-the-badge&logo=paypal&color=0A0A0A +[🖇paypal]: https://www.paypal.com/paypalme/peterboling +[🖇floss-funding.dev]: https://floss-funding.dev +[🖇floss-funding-gem]: https://github.com/galtzo-floss/floss_funding +[✉️discord-invite]: https://discord.gg/3qme4XHNKN +[✉️discord-invite-img-ftb]: https://img.shields.io/discord/1373797679469170758?style=for-the-badge&logo=discord +[✉️ruby-friends-img]: https://img.shields.io/badge/daily.dev-%F0%9F%92%8E_Ruby_Friends-0A0A0A?style=for-the-badge&logo=dailydotdev&logoColor=white +[✉️ruby-friends]: https://app.daily.dev/squads/rubyfriends + +[⛳gg-discussions]: https://groups.google.com/g/oauth-ruby +[⛳gg-discussions-img]: https://img.shields.io/badge/google-group-0093D0.svg?style=for-the-badge&logo=google&logoColor=orange + +[✇bundle-group-pattern]: https://gist.github.com/pboling/4564780 +[⛳️gem-namespace]: https://github.com/ruby-oauth/oauth2 +[⛳️namespace-img]: https://img.shields.io/badge/namespace-OAuth2-3C2D2D.svg?style=square&logo=ruby&logoColor=white +[⛳️gem-name]: https://bestgems.org/gems/oauth2 +[⛳️name-img]: https://img.shields.io/badge/name-oauth2-3C2D2D.svg?style=square&logo=rubygems&logoColor=red +[⛳️tag-img]: https://img.shields.io/github/tag/ruby-oauth/oauth2.svg +[⛳️tag]: http://github.com/ruby-oauth/oauth2/releases +[🚂maint-blog]: http://www.railsbling.com/tags/oauth2 +[🚂maint-blog-img]: https://img.shields.io/badge/blog-railsbling-0093D0.svg?style=for-the-badge&logo=rubyonrails&logoColor=orange +[🚂maint-contact]: http://www.railsbling.com/contact +[🚂maint-contact-img]: https://img.shields.io/badge/Contact-Maintainer-0093D0.svg?style=flat&logo=rubyonrails&logoColor=red +[💖🖇linkedin]: http://www.linkedin.com/in/peterboling +[💖🖇linkedin-img]: https://img.shields.io/badge/PeterBoling-LinkedIn-0B66C2?style=flat&logo=newjapanprowrestling +[💖✌️wellfound]: https://wellfound.com/u/peter-boling +[💖✌️wellfound-img]: https://img.shields.io/badge/peter--boling-orange?style=flat&logo=wellfound +[💖💲crunchbase]: https://www.crunchbase.com/person/peter-boling +[💖💲crunchbase-img]: https://img.shields.io/badge/peter--boling-purple?style=flat&logo=crunchbase +[💖🐘ruby-mast]: https://ruby.social/@galtzo +[💖🐘ruby-mast-img]: https://img.shields.io/mastodon/follow/109447111526622197?domain=https://ruby.social&style=flat&logo=mastodon&label=Ruby%20@galtzo +[💖🦋bluesky]: https://bsky.app/profile/galtzo.com +[💖🦋bluesky-img]: https://img.shields.io/badge/@galtzo.com-0285FF?style=flat&logo=bluesky&logoColor=white +[💖🌳linktree]: https://linktr.ee/galtzo +[💖🌳linktree-img]: https://img.shields.io/badge/galtzo-purple?style=flat&logo=linktree +[💖💁🏼‍♂️devto]: https://dev.to/galtzo +[💖💁🏼‍♂️devto-img]: https://img.shields.io/badge/dev.to-0A0A0A?style=flat&logo=devdotto&logoColor=white +[💖💁🏼‍♂️aboutme]: https://about.me/peter.boling +[💖💁🏼‍♂️aboutme-img]: https://img.shields.io/badge/about.me-0A0A0A?style=flat&logo=aboutme&logoColor=white +[💖🧊berg]: https://codeberg.org/pboling +[💖🐙hub]: https://github.org/pboling +[💖🛖hut]: https://sr.ht/~galtzo/ +[💖🧪lab]: https://gitlab.com/pboling +[👨🏼‍🏫expsup-upwork]: https://www.upwork.com/freelancers/~014942e9b056abdf86?mp_source=share +[👨🏼‍🏫expsup-upwork-img]: https://img.shields.io/badge/UpWork-13544E?style=for-the-badge&logo=Upwork&logoColor=white +[👨🏼‍🏫expsup-codementor]: https://www.codementor.io/peterboling?utm_source=github&utm_medium=button&utm_term=peterboling&utm_campaign=github +[👨🏼‍🏫expsup-codementor-img]: https://img.shields.io/badge/CodeMentor-Get_Help-1abc9c?style=for-the-badge&logo=CodeMentor&logoColor=white +[🏙️entsup-tidelift]: https://tidelift.com/subscription/pkg/rubygems-oauth2?utm_source=rubygems-oauth2&utm_medium=referral&utm_campaign=readme +[🏙️entsup-tidelift-img]: https://img.shields.io/badge/Tidelift_and_Sonar-Enterprise_Support-FD3456?style=for-the-badge&logo=sonar&logoColor=white +[🏙️entsup-tidelift-sonar]: https://blog.tidelift.com/tidelift-joins-sonar +[💁🏼‍♂️peterboling]: http://www.peterboling.com +[🚂railsbling]: http://www.railsbling.com +[📜src-gl-img]: https://img.shields.io/badge/GitLab-FBA326?style=for-the-badge&logo=Gitlab&logoColor=orange +[📜src-gl]: https://gitlab.com/ruby-oauth/oauth2/ +[📜src-cb-img]: https://img.shields.io/badge/CodeBerg-4893CC?style=for-the-badge&logo=CodeBerg&logoColor=blue +[📜src-cb]: https://codeberg.org/ruby-oauth/oauth2 +[📜src-gh-img]: https://img.shields.io/badge/GitHub-238636?style=for-the-badge&logo=Github&logoColor=green +[📜src-gh]: https://github.com/ruby-oauth/oauth2 +[📜docs-cr-rd-img]: https://img.shields.io/badge/RubyDoc-Current_Release-943CD2?style=for-the-badge&logo=readthedocs&logoColor=white +[📜docs-head-rd-img]: https://img.shields.io/badge/YARD_on_Galtzo.com-HEAD-943CD2?style=for-the-badge&logo=readthedocs&logoColor=white +[📜gl-wiki]: https://gitlab.com/ruby-oauth/oauth2/-/wikis/home +[📜gh-wiki]: https://github.com/ruby-oauth/oauth2/wiki +[📜gl-wiki-img]: https://img.shields.io/badge/wiki-examples-943CD2.svg?style=for-the-badge&logo=gitlab&logoColor=white +[📜gh-wiki-img]: https://img.shields.io/badge/wiki-examples-943CD2.svg?style=for-the-badge&logo=github&logoColor=white +[👽dl-rank]: https://bestgems.org/gems/oauth2 +[👽dl-ranki]: https://img.shields.io/gem/rd/oauth2.svg +[👽oss-help]: https://www.codetriage.com/ruby-oauth/oauth2 +[👽oss-helpi]: https://www.codetriage.com/ruby-oauth/oauth2/badges/users.svg +[👽version]: https://bestgems.org/gems/oauth2 +[👽versioni]: https://img.shields.io/gem/v/oauth2.svg +[🏀qlty-mnt]: https://qlty.sh/gh/ruby-oauth/projects/oauth2 +[🏀qlty-mnti]: https://qlty.sh/gh/ruby-oauth/projects/oauth2/maintainability.svg +[🏀qlty-cov]: https://qlty.sh/gh/ruby-oauth/projects/oauth2/metrics/code?sort=coverageRating +[🏀qlty-covi]: https://qlty.sh/gh/ruby-oauth/projects/oauth2/coverage.svg +[🏀codecov]: https://codecov.io/gh/ruby-oauth/oauth2 +[🏀codecovi]: https://codecov.io/gh/ruby-oauth/oauth2/graph/badge.svg +[🏀coveralls]: https://coveralls.io/github/ruby-oauth/oauth2?branch=main +[🏀coveralls-img]: https://coveralls.io/repos/github/ruby-oauth/oauth2/badge.svg?branch=main +[🖐codeQL]: https://github.com/ruby-oauth/oauth2/security/code-scanning +[🖐codeQL-img]: https://github.com/ruby-oauth/oauth2/actions/workflows/codeql-analysis.yml/badge.svg +[🚎1-an-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/ancient.yml +[🚎1-an-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/ancient.yml/badge.svg +[🚎2-cov-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/coverage.yml +[🚎2-cov-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/coverage.yml/badge.svg +[🚎3-hd-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/heads.yml +[🚎3-hd-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/heads.yml/badge.svg +[🚎4-lg-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/legacy.yml +[🚎4-lg-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/legacy.yml/badge.svg +[🚎5-st-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/style.yml +[🚎5-st-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/style.yml/badge.svg +[🚎6-s-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/supported.yml +[🚎6-s-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/supported.yml/badge.svg +[🚎7-us-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/unsupported.yml +[🚎7-us-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/unsupported.yml/badge.svg +[🚎8-ho-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/hoary.yml +[🚎8-ho-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/hoary.yml/badge.svg +[🚎10-j-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/jruby.yml +[🚎10-j-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/jruby.yml/badge.svg +[🚎11-c-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/current.yml +[🚎11-c-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/current.yml/badge.svg +[🚎12-crh-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/dep-heads.yml +[🚎12-crh-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/dep-heads.yml/badge.svg +[🚎13-cbs-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/caboose.yml +[🚎13-cbs-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/caboose.yml/badge.svg +[🚎13-🔒️-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/locked_deps.yml +[🚎13-🔒️-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/locked_deps.yml/badge.svg +[🚎14-🔓️-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/unlocked_deps.yml +[🚎14-🔓️-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/unlocked_deps.yml/badge.svg +[🚎15-🪪-wf]: https://github.com/ruby-oauth/oauth2/actions/workflows/license-eye.yml +[🚎15-🪪-wfi]: https://github.com/ruby-oauth/oauth2/actions/workflows/license-eye.yml/badge.svg +[💎ruby-2.2i]: https://img.shields.io/badge/Ruby-2.2_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-2.3i]: https://img.shields.io/badge/Ruby-2.3-DF00CA?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-2.4i]: https://img.shields.io/badge/Ruby-2.4-DF00CA?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-2.5i]: https://img.shields.io/badge/Ruby-2.5-DF00CA?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-2.6i]: https://img.shields.io/badge/Ruby-2.6-DF00CA?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-2.7i]: https://img.shields.io/badge/Ruby-2.7-DF00CA?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-3.0i]: https://img.shields.io/badge/Ruby-3.0-CC342D?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-3.1i]: https://img.shields.io/badge/Ruby-3.1-CC342D?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-3.2i]: https://img.shields.io/badge/Ruby-3.2-CC342D?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-3.3i]: https://img.shields.io/badge/Ruby-3.3-CC342D?style=for-the-badge&logo=ruby&logoColor=white +[💎ruby-c-i]: https://img.shields.io/badge/Ruby-current-CC342D?style=for-the-badge&logo=ruby&logoColor=green +[💎ruby-headi]: https://img.shields.io/badge/Ruby-HEAD-CC342D?style=for-the-badge&logo=ruby&logoColor=blue +[💎truby-22.3i]: https://img.shields.io/badge/Truffle_Ruby-22.3_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=pink +[💎truby-23.0i]: https://img.shields.io/badge/Truffle_Ruby-23.0_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=pink +[💎truby-23.1i]: https://img.shields.io/badge/Truffle_Ruby-23.1_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=pink +[💎truby-c-i]: https://img.shields.io/badge/Truffle_Ruby-current-34BCB1?style=for-the-badge&logo=ruby&logoColor=green +[💎truby-headi]: https://img.shields.io/badge/Truffle_Ruby-HEAD-34BCB1?style=for-the-badge&logo=ruby&logoColor=blue +[💎jruby-9.1i]: https://img.shields.io/badge/JRuby-9.1_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=red +[💎jruby-9.2i]: https://img.shields.io/badge/JRuby-9.2_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=red +[💎jruby-9.3i]: https://img.shields.io/badge/JRuby-9.3_(%F0%9F%9A%ABCI)-AABBCC?style=for-the-badge&logo=ruby&logoColor=red +[💎jruby-9.4i]: https://img.shields.io/badge/JRuby-9.4-FBE742?style=for-the-badge&logo=ruby&logoColor=red +[💎jruby-c-i]: https://img.shields.io/badge/JRuby-current-FBE742?style=for-the-badge&logo=ruby&logoColor=green +[💎jruby-headi]: https://img.shields.io/badge/JRuby-HEAD-FBE742?style=for-the-badge&logo=ruby&logoColor=blue +[🤝gh-issues]: https://github.com/ruby-oauth/oauth2/issues +[🤝gh-pulls]: https://github.com/ruby-oauth/oauth2/pulls +[🤝gl-issues]: https://gitlab.com/ruby-oauth/oauth2/-/issues +[🤝gl-pulls]: https://gitlab.com/ruby-oauth/oauth2/-/merge_requests +[🤝cb-issues]: https://codeberg.org/ruby-oauth/oauth2/issues +[🤝cb-pulls]: https://codeberg.org/ruby-oauth/oauth2/pulls +[🤝cb-donate]: https://donate.codeberg.org/ +[🤝contributing]: CONTRIBUTING.md +[🏀codecov-g]: https://codecov.io/gh/ruby-oauth/oauth2/graphs/tree.svg +[🖐contrib-rocks]: https://contrib.rocks +[🖐contributors]: https://github.com/ruby-oauth/oauth2/graphs/contributors +[🖐contributors-img]: https://contrib.rocks/image?repo=ruby-oauth/oauth2 +[🚎contributors-gl]: https://gitlab.com/ruby-oauth/oauth2/-/graphs/main +[🪇conduct]: CODE_OF_CONDUCT.md +[🪇conduct-img]: https://img.shields.io/badge/Contributor_Covenant-2.1-259D6C.svg +[📌pvc]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint +[📌semver]: https://semver.org/spec/v2.0.0.html +[📌semver-img]: https://img.shields.io/badge/semver-2.0.0-259D6C.svg?style=flat +[📌semver-breaking]: https://github.com/semver/semver/issues/716#issuecomment-869336139 +[📌major-versions-not-sacred]: https://tom.preston-werner.com/2022/05/23/major-version-numbers-are-not-sacred.html +[📌changelog]: CHANGELOG.md +[📗keep-changelog]: https://keepachangelog.com/en/1.0.0/ +[📗keep-changelog-img]: https://img.shields.io/badge/keep--a--changelog-1.0.0-34495e.svg?style=flat +[📌gitmoji]: https://gitmoji.dev +[📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square +[🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ +[🧮kloc-img]: https://img.shields.io/badge/KLOC-0.526-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue +[🔐security]: SECURITY.md +[🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat +[🔐irp]: IRP.md +[🔐irp-img]: https://img.shields.io/badge/IRP-259D6C.svg?style=flat +[🔐threat-model]: THREAT_MODEL.md +[🔐threat-model-img]: https://img.shields.io/badge/threat-model-259D6C.svg?style=flat +[📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year +[📄license]: LICENSE.txt +[📄license-ref]: https://opensource.org/licenses/MIT +[📄license-img]: https://img.shields.io/badge/License-MIT-259D6C.svg +[📄license-compat]: https://dev.to/galtzo/how-to-check-license-compatibility-41h0 +[📄license-compat-img]: https://img.shields.io/badge/Apache_Compatible:_Category_A-%E2%9C%93-259D6C.svg?style=flat&logo=Apache +[📄ilo-declaration]: https://www.ilo.org/declaration/lang--en/index.htm +[📄ilo-declaration-img]: https://img.shields.io/badge/ILO_Fundamental_Principles-✓-259D6C.svg?style=flat +[🚎yard-current]: http://rubydoc.info/gems/oauth2 +[🚎yard-head]: https://oauth2.galtzo.com +[💎stone_checksums]: https://github.com/galtzo-floss/stone_checksums +[💎SHA_checksums]: https://gitlab.com/ruby-oauth/oauth2/-/tree/main/checksums +[💎rlts]: https://github.com/rubocop-lts/rubocop-lts +[💎rlts-img]: https://img.shields.io/badge/code_style_&_linting-rubocop--lts-34495e.svg?plastic&logo=ruby&logoColor=white +[💎appraisal2]: https://github.com/appraisal-rb/appraisal2 +[💎appraisal2-img]: https://img.shields.io/badge/appraised_by-appraisal2-34495e.svg?plastic&logo=ruby&logoColor=white +[💎d-in-dvcs]: https://railsbling.com/posts/dvcs/put_the_d_in_dvcs/ + +
+ + rel="me" Social Proofs + + + + + +
diff --git a/REEK b/REEK new file mode 100644 index 00000000..e69de29b diff --git a/RUBOCOP.md b/RUBOCOP.md new file mode 100644 index 00000000..f15b9801 --- /dev/null +++ b/RUBOCOP.md @@ -0,0 +1,71 @@ +# RuboCop Usage Guide + +## Overview + +A tale of two RuboCop plugin gems. + +### RuboCop Gradual + +This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file. + +### RuboCop LTS + +This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2. +RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more. + +## Checking RuboCop Violations + +To check for RuboCop violations in this project, always use: + +```bash +bundle exec rake rubocop_gradual:check +``` + +**Do not use** the standard RuboCop commands like: +- `bundle exec rubocop` +- `rubocop` + +## Understanding the Lock File + +The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to: + +1. Prevent new violations while gradually fixing existing ones +2. Track progress on code style improvements +3. Ensure CI builds don't fail due to pre-existing violations + +## Common Commands + +- **Check violations** + - `bundle exec rake rubocop_gradual` + - `bundle exec rake rubocop_gradual:check` +- **(Safe) Autocorrect violations, and update lockfile if no new violations** + - `bundle exec rake rubocop_gradual:autocorrect` +- **Force update the lock file (w/o autocorrect) to match violations present in code** + - `bundle exec rake rubocop_gradual:force_update` + +## Workflow + +1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect` + a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task. +2. If there are new violations, either: + - Fix them in your code + - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately) +3. Commit the updated `.rubocop_gradual.lock` file along with your changes + +## Never add inline RuboCop disables + +Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways: + +- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide. +- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow: + - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced) + - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately) + +In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test. + +## Benefits of rubocop_gradual + +- Allows incremental adoption of code style rules +- Prevents CI failures due to pre-existing violations +- Provides a clear record of code style debt +- Enables focused efforts on improving code quality over time diff --git a/Rakefile b/Rakefile index 1066a1b6..631e8b13 100644 --- a/Rakefile +++ b/Rakefile @@ -1,45 +1,66 @@ -# encoding: utf-8 +# frozen_string_literal: true -# !/usr/bin/env rake +# kettle-dev Rakefile v1.1.51 - 2025-11-07 +# Ruby 2.3 (Safe Navigation) or higher required +# +# MIT License (see License.txt) +# +# Copyright (c) 2025 Peter H. Boling (galtzo.com) +# +# Expected to work in any project that uses Bundler. +# +# Sets up tasks for appraisal, floss_funding, rspec, minitest, rubocop, reek, yard, and stone_checksums. +# +# rake appraisal:update # Update Appraisal gemfiles and run RuboCop... +# rake bench # Run all benchmarks (alias for bench:run) +# rake bench:list # List available benchmark scripts +# rake bench:run # Run all benchmark scripts (skips on CI) +# rake build:generate_checksums # Generate both SHA256 & SHA512 checksums i... +# rake bundle:audit:check # Checks the Gemfile.lock for insecure depe... +# rake bundle:audit:update # Updates the bundler-audit vulnerability d... +# rake ci:act[opt] # Run 'act' with a selected workflow +# rake coverage # Run specs w/ coverage and open results in... +# rake default # Default tasks aggregator +# rake install # Build and install kettle-dev-1.0.0.gem in... +# rake install:local # Build and install kettle-dev-1.0.0.gem in... +# rake kettle:dev:install # Install kettle-dev GitHub automation and ... +# rake kettle:dev:template # Template kettle-dev files into the curren... +# rake reek # Check for code smells +# rake reek:update # Run reek and store the output into the RE... +# rake release[remote] # Create tag v1.0.0 and build and push kett... +# rake rubocop_gradual # Run RuboCop Gradual +# rake rubocop_gradual:autocorrect # Run RuboCop Gradual with autocorrect (onl... +# rake rubocop_gradual:autocorrect_all # Run RuboCop Gradual with autocorrect (saf... +# rake rubocop_gradual:check # Run RuboCop Gradual to check the lock file +# rake rubocop_gradual:force_update # Run RuboCop Gradual to force update the l... +# rake rubocop_gradual_debug # Run RuboCop Gradual +# rake rubocop_gradual_debug:autocorrect # Run RuboCop Gradual with autocorrect (onl... +# rake rubocop_gradual_debug:autocorrect_all # Run RuboCop Gradual with autocorrect (saf... +# rake rubocop_gradual_debug:check # Run RuboCop Gradual to check the lock file +# rake rubocop_gradual_debug:force_update # Run RuboCop Gradual to force update the l... +# rake spec # Run RSpec code examples +# rake test # Run tests +# rake yard # Generate YARD Documentation +# -require 'bundler/gem_tasks' +require "bundler/gem_tasks" if !Dir[File.join(__dir__, "*.gemspec")].empty? -begin - require 'wwtd/tasks' -rescue LoadError - puts 'failed to load wwtd' +# Define a base default task early so other files can enhance it. +desc "Default tasks aggregator" +task :default do + puts "Default task complete." end -begin - require 'rspec/core/rake_task' - RSpec::Core::RakeTask.new(:spec) -rescue LoadError - task :spec do - warn 'rspec is disabled' - end -end -task :test => :spec +# External gems that define tasks - add here! +require "kettle/dev" +### RELEASE TASKS +# Setup stone_checksums begin - require 'rubocop/rake_task' - RuboCop::RakeTask.new do |task| - task.options = ['-D'] # Display the name of the failing cops - end + require "stone_checksums" rescue LoadError - task :rubocop do - warn 'RuboCop is disabled' + desc("(stub) build:generate_checksums is unavailable") + task("build:generate_checksums") do + warn("NOTE: stone_checksums isn't installed, or is disabled for #{RUBY_VERSION} in the current environment") end end - -namespace :doc do - require 'rdoc/task' - require File.expand_path('../lib/oauth2/version', __FILE__) - RDoc::Task.new do |rdoc| - rdoc.rdoc_dir = 'rdoc' - rdoc.title = "oauth2 #{OAuth2::Version}" - rdoc.main = 'README.md' - rdoc.rdoc_files.include('README.md', 'LICENSE.md', 'lib/**/*.rb') - end -end - -task :default => [:test, :rubocop] diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..e295726c --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,24 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +|----------|-----------| +| 1.latest | ✅ | + +## Security contact information + +To report a security vulnerability, please use the +[Tidelift security contact](https://tidelift.com/security). +Tidelift will coordinate the fix and disclosure. + +More detailed explanation of the process is in [IRP.md][IRP] + +## Additional Support + +If you are interested in support for versions older than the latest release, +please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate, +or find other sponsorship links in the [README]. + +[README]: README.md +[IRP]: IRP.md diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md new file mode 100644 index 00000000..9b1f8830 --- /dev/null +++ b/THREAT_MODEL.md @@ -0,0 +1,85 @@ +# 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 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. diff --git a/bin/appraisal b/bin/appraisal new file mode 100755 index 00000000..bc7d25bd --- /dev/null +++ b/bin/appraisal @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'appraisal' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("appraisal2", "appraisal") diff --git a/bin/bundle b/bin/bundle new file mode 100755 index 00000000..4a95618e --- /dev/null +++ b/bin/bundle @@ -0,0 +1,116 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'bundle' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +require "rubygems" + +m = Module.new do +module_function + + def invoked_as_script? + File.expand_path($PROGRAM_NAME) == File.expand_path(__FILE__) + end + + def env_var_version + ENV["BUNDLER_VERSION"] + end + + def cli_arg_version + return unless invoked_as_script? # don't want to hijack other binstubs + return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update` + + bundler_version = nil + update_index = nil + ARGV.each_with_index do |a, i| + bundler_version = a if update_index && update_index.succ == i && a =~ Gem::Version::ANCHORED_VERSION_PATTERN + next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/o + + bundler_version = Regexp.last_match(1) + update_index = i + end + bundler_version + end + + def gemfile + gemfile = ENV["BUNDLE_GEMFILE"] + return gemfile if gemfile && !gemfile.empty? + + File.expand_path("../Gemfile", __dir__) + end + + def lockfile + lockfile = + case File.basename(gemfile) + when "gems.rb" then gemfile.sub(/\.rb$/, gemfile) + else "#{gemfile}.lock" + end + File.expand_path(lockfile) + end + + def lockfile_version + return unless File.file?(lockfile) + + lockfile_contents = File.read(lockfile) + return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/o + + Regexp.last_match(1) + end + + def bundler_requirement + @bundler_requirement ||= + env_var_version || cli_arg_version || + bundler_requirement_for(lockfile_version) + end + + def bundler_requirement_for(version) + return "#{Gem::Requirement.default}.a" unless version + + bundler_gem_version = Gem::Version.new(version) + + requirement = bundler_gem_version.approximate_recommendation + + return requirement unless Gem.rubygems_version < Gem::Version.new("2.7.0") + + requirement += ".a" if bundler_gem_version.prerelease? + + requirement + end + + def load_bundler! + ENV["BUNDLE_GEMFILE"] ||= gemfile + + activate_bundler + end + + def activate_bundler + gem_error = activation_error_handling do + gem("bundler", bundler_requirement) + end + return if gem_error.nil? + + require_error = activation_error_handling do + require "bundler/version" + end + return if require_error.nil? && Gem::Requirement.new(bundler_requirement).satisfied_by?(Gem::Version.new(Bundler::VERSION)) + + warn("Activating bundler (#{bundler_requirement}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_requirement}'`") + exit(42) + end + + def activation_error_handling + yield + nil + rescue StandardError, LoadError => e + e + end +end + +m.load_bundler! + +load Gem.bin_path("bundler", "bundle") if m.invoked_as_script? diff --git a/bin/bundle-audit b/bin/bundle-audit new file mode 100755 index 00000000..a0e7ba0e --- /dev/null +++ b/bin/bundle-audit @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'bundle-audit' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("bundler-audit", "bundle-audit") diff --git a/bin/bundler-audit b/bin/bundler-audit new file mode 100755 index 00000000..334a7378 --- /dev/null +++ b/bin/bundler-audit @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'bundler-audit' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("bundler-audit", "bundler-audit") diff --git a/bin/code_climate_reek b/bin/code_climate_reek new file mode 100755 index 00000000..afe0d79f --- /dev/null +++ b/bin/code_climate_reek @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'code_climate_reek' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("reek", "code_climate_reek") diff --git a/bin/coderay b/bin/coderay new file mode 100755 index 00000000..b13b22e9 --- /dev/null +++ b/bin/coderay @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'coderay' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("coderay", "coderay") diff --git a/bin/console b/bin/console index f1158589..53fc8fd9 100755 --- a/bin/console +++ b/bin/console @@ -1,7 +1,8 @@ #!/usr/bin/env ruby +# frozen_string_literal: true -require 'bundler/setup' -require 'oauth2' +require "bundler/setup" +require "oauth2" # You can add fixtures and/or initialization code here to make experimenting # with your gem easier. You can also use a different console, if you like. @@ -10,5 +11,5 @@ require 'oauth2' # require "pry" # Pry.start -require 'irb' +require "irb" IRB.start(__FILE__) diff --git a/bin/erb b/bin/erb new file mode 100755 index 00000000..58e756ae --- /dev/null +++ b/bin/erb @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'erb' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("erb", "erb") diff --git a/bin/gem_checksums b/bin/gem_checksums new file mode 100755 index 00000000..45a1d2ac --- /dev/null +++ b/bin/gem_checksums @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'gem_checksums' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("stone_checksums", "gem_checksums") diff --git a/bin/github-markup b/bin/github-markup new file mode 100755 index 00000000..5cb47930 --- /dev/null +++ b/bin/github-markup @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'github-markup' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("github-markup", "github-markup") diff --git a/bin/htmldiff b/bin/htmldiff new file mode 100755 index 00000000..0aeaec87 --- /dev/null +++ b/bin/htmldiff @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'htmldiff' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("diff-lcs", "htmldiff") diff --git a/bin/irb b/bin/irb new file mode 100755 index 00000000..e7de6d6c --- /dev/null +++ b/bin/irb @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'irb' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("irb", "irb") diff --git a/bin/kettle-changelog b/bin/kettle-changelog new file mode 100755 index 00000000..0e7fcc4d --- /dev/null +++ b/bin/kettle-changelog @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'kettle-changelog' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("kettle-dev", "kettle-changelog") diff --git a/bin/kettle-commit-msg b/bin/kettle-commit-msg new file mode 100755 index 00000000..b228ad67 --- /dev/null +++ b/bin/kettle-commit-msg @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'kettle-commit-msg' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("kettle-dev", "kettle-commit-msg") diff --git a/bin/kettle-dev-setup b/bin/kettle-dev-setup new file mode 100755 index 00000000..276319a7 --- /dev/null +++ b/bin/kettle-dev-setup @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'kettle-dev-setup' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("kettle-dev", "kettle-dev-setup") diff --git a/bin/kettle-dvcs b/bin/kettle-dvcs new file mode 100755 index 00000000..b572d48c --- /dev/null +++ b/bin/kettle-dvcs @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'kettle-dvcs' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("kettle-dev", "kettle-dvcs") diff --git a/bin/kettle-pre-release b/bin/kettle-pre-release new file mode 100755 index 00000000..1b98ad61 --- /dev/null +++ b/bin/kettle-pre-release @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'kettle-pre-release' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("kettle-dev", "kettle-pre-release") diff --git a/bin/kettle-readme-backers b/bin/kettle-readme-backers new file mode 100755 index 00000000..fec80bd5 --- /dev/null +++ b/bin/kettle-readme-backers @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'kettle-readme-backers' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("kettle-dev", "kettle-readme-backers") diff --git a/bin/kettle-release b/bin/kettle-release new file mode 100755 index 00000000..1f5758a8 --- /dev/null +++ b/bin/kettle-release @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'kettle-release' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("kettle-dev", "kettle-release") diff --git a/bin/kramdown b/bin/kramdown new file mode 100755 index 00000000..547fd063 --- /dev/null +++ b/bin/kramdown @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'kramdown' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("kramdown", "kramdown") diff --git a/bin/ldiff b/bin/ldiff new file mode 100755 index 00000000..8173edec --- /dev/null +++ b/bin/ldiff @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'ldiff' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("diff-lcs", "ldiff") diff --git a/bin/nokogiri b/bin/nokogiri new file mode 100755 index 00000000..8b72331f --- /dev/null +++ b/bin/nokogiri @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'nokogiri' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("nokogiri", "nokogiri") diff --git a/bin/pry b/bin/pry new file mode 100755 index 00000000..41bfde55 --- /dev/null +++ b/bin/pry @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'pry' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("pry", "pry") diff --git a/bin/racc b/bin/racc new file mode 100755 index 00000000..81900158 --- /dev/null +++ b/bin/racc @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'racc' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("racc", "racc") diff --git a/bin/rake b/bin/rake new file mode 100755 index 00000000..51e10c4a --- /dev/null +++ b/bin/rake @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'rake' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/ + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("rake", "rake") diff --git a/bin/rbs b/bin/rbs new file mode 100755 index 00000000..ffc95a0d --- /dev/null +++ b/bin/rbs @@ -0,0 +1,16 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'rbs' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("rbs", "rbs") diff --git a/bin/rdbg b/bin/rdbg new file mode 100755 index 00000000..5e3b279f --- /dev/null +++ b/bin/rdbg @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'rdbg' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("debug", "rdbg") diff --git a/bin/rdoc b/bin/rdoc new file mode 100755 index 00000000..d2b6bcf8 --- /dev/null +++ b/bin/rdoc @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'rdoc' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("rdoc", "rdoc") diff --git a/bin/redcarpet b/bin/redcarpet new file mode 100755 index 00000000..76a1cb80 --- /dev/null +++ b/bin/redcarpet @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'redcarpet' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("redcarpet", "redcarpet") diff --git a/bin/reek b/bin/reek new file mode 100755 index 00000000..2ec45920 --- /dev/null +++ b/bin/reek @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'reek' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("reek", "reek") diff --git a/bin/ri b/bin/ri new file mode 100755 index 00000000..72e25813 --- /dev/null +++ b/bin/ri @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'ri' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("rdoc", "ri") diff --git a/bin/rspec b/bin/rspec new file mode 100755 index 00000000..757e79b3 --- /dev/null +++ b/bin/rspec @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'rspec' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/ + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("rspec-core", "rspec") diff --git a/bin/rubocop b/bin/rubocop new file mode 100755 index 00000000..2b1fa1f7 --- /dev/null +++ b/bin/rubocop @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'rubocop' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/ + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("rubocop", "rubocop") diff --git a/bin/rubocop-gradual b/bin/rubocop-gradual new file mode 100755 index 00000000..07520055 --- /dev/null +++ b/bin/rubocop-gradual @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'rubocop-gradual' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("rubocop-gradual", "rubocop-gradual") diff --git a/bin/ruby-parse b/bin/ruby-parse new file mode 100755 index 00000000..d8ebc68d --- /dev/null +++ b/bin/ruby-parse @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'ruby-parse' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("parser", "ruby-parse") diff --git a/bin/ruby-rewrite b/bin/ruby-rewrite new file mode 100755 index 00000000..b4574aba --- /dev/null +++ b/bin/ruby-rewrite @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'ruby-rewrite' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("parser", "ruby-rewrite") diff --git a/bin/standardrb b/bin/standardrb new file mode 100755 index 00000000..b329561c --- /dev/null +++ b/bin/standardrb @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'standardrb' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("standard", "standardrb") diff --git a/bin/thor b/bin/thor new file mode 100755 index 00000000..ec401151 --- /dev/null +++ b/bin/thor @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'thor' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("thor", "thor") diff --git a/bin/yard b/bin/yard new file mode 100755 index 00000000..ea9daf5f --- /dev/null +++ b/bin/yard @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'yard' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("yard", "yard") diff --git a/bin/yard-junk b/bin/yard-junk new file mode 100755 index 00000000..be420a5c --- /dev/null +++ b/bin/yard-junk @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'yard-junk' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("yard-junk", "yard-junk") diff --git a/bin/yardoc b/bin/yardoc new file mode 100755 index 00000000..e1324dc1 --- /dev/null +++ b/bin/yardoc @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'yardoc' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("yard", "yardoc") diff --git a/bin/yri b/bin/yri new file mode 100755 index 00000000..f968fde1 --- /dev/null +++ b/bin/yri @@ -0,0 +1,27 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +# +# This file was generated by Bundler. +# +# The application 'yri' is installed as part of a gem, and +# this file is here to facilitate running it. +# + +ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__) + +bundle_binstub = File.expand_path("bundle", __dir__) + +if File.file?(bundle_binstub) + if File.read(bundle_binstub, 300).include?("This file was generated by Bundler") + load(bundle_binstub) + else + abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run. +Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.") + end +end + +require "rubygems" +require "bundler/setup" + +load Gem.bin_path("yard", "yri") diff --git a/certs/pboling.pem b/certs/pboling.pem new file mode 100644 index 00000000..d5c7e8bb --- /dev/null +++ b/certs/pboling.pem @@ -0,0 +1,27 @@ +-----BEGIN CERTIFICATE----- +MIIEgDCCAuigAwIBAgIBATANBgkqhkiG9w0BAQsFADBDMRUwEwYDVQQDDAxwZXRl +ci5ib2xpbmcxFTATBgoJkiaJk/IsZAEZFgVnbWFpbDETMBEGCgmSJomT8ixkARkW +A2NvbTAeFw0yNTA1MDQxNTMzMDlaFw00NTA0MjkxNTMzMDlaMEMxFTATBgNVBAMM +DHBldGVyLmJvbGluZzEVMBMGCgmSJomT8ixkARkWBWdtYWlsMRMwEQYKCZImiZPy +LGQBGRYDY29tMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEAruUoo0WA +uoNuq6puKWYeRYiZekz/nsDeK5x/0IEirzcCEvaHr3Bmz7rjo1I6On3gGKmiZs61 +LRmQ3oxy77ydmkGTXBjruJB+pQEn7UfLSgQ0xa1/X3kdBZt6RmabFlBxnHkoaGY5 +mZuZ5+Z7walmv6sFD9ajhzj+oIgwWfnEHkXYTR8I6VLN7MRRKGMPoZ/yvOmxb2DN +coEEHWKO9CvgYpW7asIihl/9GMpKiRkcYPm9dGQzZc6uTwom1COfW0+ZOFrDVBuV +FMQRPswZcY4Wlq0uEBLPU7hxnCL9nKK6Y9IhdDcz1mY6HZ91WImNslOSI0S8hRpj +yGOWxQIhBT3fqCBlRIqFQBudrnD9jSNpSGsFvbEijd5ns7Z9ZMehXkXDycpGAUj1 +to/5cuTWWw1JqUWrKJYoifnVhtE1o1DZ+LkPtWxHtz5kjDG/zR3MG0Ula0UOavlD +qbnbcXPBnwXtTFeZ3C+yrWpE4pGnl3yGkZj9SMTlo9qnTMiPmuWKQDatAgMBAAGj +fzB9MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgSwMB0GA1UdDgQWBBQE8uWvNbPVNRXZ +HlgPbc2PCzC4bjAhBgNVHREEGjAYgRZwZXRlci5ib2xpbmdAZ21haWwuY29tMCEG +A1UdEgQaMBiBFnBldGVyLmJvbGluZ0BnbWFpbC5jb20wDQYJKoZIhvcNAQELBQAD +ggGBAJbnUwfJQFPkBgH9cL7hoBfRtmWiCvdqdjeTmi04u8zVNCUox0A4gT982DE9 +wmuN12LpdajxZONqbXuzZvc+nb0StFwmFYZG6iDwaf4BPywm2e/Vmq0YG45vZXGR +L8yMDSK1cQXjmA+ZBKOHKWavxP6Vp7lWvjAhz8RFwqF9GuNIdhv9NpnCAWcMZtpm +GUPyIWw/Cw/2wZp74QzZj6Npx+LdXoLTF1HMSJXZ7/pkxLCsB8m4EFVdb/IrW/0k +kNSfjtAfBHO8nLGuqQZVH9IBD1i9K6aSs7pT6TW8itXUIlkIUI2tg5YzW6OFfPzq +QekSkX3lZfY+HTSp/o+YvKkqWLUV7PQ7xh1ZYDtocpaHwgxe/j3bBqHE+CUPH2vA +0V/FwdTRWcwsjVoOJTrYcff8pBZ8r2MvtAc54xfnnhGFzeRHfcltobgFxkAXdE6p +DVjBtqT23eugOqQ73umLcYDZkc36vnqGxUBSsXrzY9pzV5gGr2I8YUxMqf6ATrZt +L9nRqA== +-----END CERTIFICATE----- diff --git a/checksums/oauth2-2.0.10.gem.sha256 b/checksums/oauth2-2.0.10.gem.sha256 new file mode 100644 index 00000000..9518c3cf --- /dev/null +++ b/checksums/oauth2-2.0.10.gem.sha256 @@ -0,0 +1 @@ +8f132679598d21885d4bcc68d7e7e6ef0a29f9a782abca00d67d884280dc3a42 \ No newline at end of file diff --git a/checksums/oauth2-2.0.10.gem.sha512 b/checksums/oauth2-2.0.10.gem.sha512 new file mode 100644 index 00000000..e0ccb654 --- /dev/null +++ b/checksums/oauth2-2.0.10.gem.sha512 @@ -0,0 +1 @@ +e692f68ab79677ee7fa9300bbd5e0c41de08642d51659a49ca7fd742230445601ad3c2d271ee110718d58a27383aba0c25ddbdbef5b13f7c18585cdfda74850b \ No newline at end of file diff --git a/checksums/oauth2-2.0.11.gem.sha256 b/checksums/oauth2-2.0.11.gem.sha256 new file mode 100644 index 00000000..3c55aeeb --- /dev/null +++ b/checksums/oauth2-2.0.11.gem.sha256 @@ -0,0 +1 @@ +29e0505c2a39bc78dfb655dbf85a826b4408e55e7c3d02ce07b3dfd9b40da16c \ No newline at end of file diff --git a/checksums/oauth2-2.0.11.gem.sha512 b/checksums/oauth2-2.0.11.gem.sha512 new file mode 100644 index 00000000..04fb46aa --- /dev/null +++ b/checksums/oauth2-2.0.11.gem.sha512 @@ -0,0 +1 @@ +048743f9efd89460231738885c9c0de7b36433055eefc66331b91eee343885cd9145bbac239c6121d13b716633fb8385fa886ce854bf14142f9894e6c8f19ba2 \ No newline at end of file diff --git a/checksums/oauth2-2.0.12.gem.sha256 b/checksums/oauth2-2.0.12.gem.sha256 new file mode 100644 index 00000000..2703132b --- /dev/null +++ b/checksums/oauth2-2.0.12.gem.sha256 @@ -0,0 +1 @@ +f7edb8549c7912724d07087d808c3fa6756298fd64d55d4968324df69c64ab3f \ No newline at end of file diff --git a/checksums/oauth2-2.0.12.gem.sha512 b/checksums/oauth2-2.0.12.gem.sha512 new file mode 100644 index 00000000..072f0b2d --- /dev/null +++ b/checksums/oauth2-2.0.12.gem.sha512 @@ -0,0 +1 @@ +a209c7a0c4b9d46ccb00e750af8899c01d52648ca77a0d40b934593de53edc4f2774440fc50733c0e5098672c6c5a4a20f8709046be427fcf032f45922dff2d2 \ No newline at end of file diff --git a/checksums/oauth2-2.0.13.gem.sha256 b/checksums/oauth2-2.0.13.gem.sha256 new file mode 100644 index 00000000..21424bc6 --- /dev/null +++ b/checksums/oauth2-2.0.13.gem.sha256 @@ -0,0 +1 @@ +e6588fe5902c07bac542a4a1197f558c319cb479b7fbe53f43f883b1a211be25 \ No newline at end of file diff --git a/checksums/oauth2-2.0.13.gem.sha512 b/checksums/oauth2-2.0.13.gem.sha512 new file mode 100644 index 00000000..d3cf1b62 --- /dev/null +++ b/checksums/oauth2-2.0.13.gem.sha512 @@ -0,0 +1 @@ +3bfe481d98f859f37f3b90ced2b8856a843eef0f2e0263163cccc14430047bc3cd03d28597f48daa3d623b52d692c3b3e7c2dc26df5eb588dd82d28608fba639 \ No newline at end of file diff --git a/checksums/oauth2-2.0.14.gem.sha256 b/checksums/oauth2-2.0.14.gem.sha256 new file mode 100644 index 00000000..1b02972d --- /dev/null +++ b/checksums/oauth2-2.0.14.gem.sha256 @@ -0,0 +1 @@ +9bcb7983048cb1ea1823f9b973762cf01ac79315d9991a0721e864747293e720 \ No newline at end of file diff --git a/checksums/oauth2-2.0.14.gem.sha512 b/checksums/oauth2-2.0.14.gem.sha512 new file mode 100644 index 00000000..6f119be2 --- /dev/null +++ b/checksums/oauth2-2.0.14.gem.sha512 @@ -0,0 +1 @@ +5ce561a6b103a123d9b96e1e4725c07094bd6e58c135cc775ae9d5a055c031169ca6d6de379c2569daf1dd8ab2727079db3c80aa8568d6947e94a0c06b4c6d2b \ No newline at end of file diff --git a/checksums/oauth2-2.0.15.gem.sha256 b/checksums/oauth2-2.0.15.gem.sha256 new file mode 100644 index 00000000..b7238cca --- /dev/null +++ b/checksums/oauth2-2.0.15.gem.sha256 @@ -0,0 +1 @@ +96ce2ca86cd06e80b0452e17c5bc0a1e349815d29c875a7951cdd8ff04743eab \ No newline at end of file diff --git a/checksums/oauth2-2.0.15.gem.sha512 b/checksums/oauth2-2.0.15.gem.sha512 new file mode 100644 index 00000000..f3899877 --- /dev/null +++ b/checksums/oauth2-2.0.15.gem.sha512 @@ -0,0 +1 @@ +287a5d2cff87b4f37dde7b97f0fc31ee4c79edcc451b33694d1ba6f13d218cd04848780a857b94b93b656d6d81de4f4fcb4e8345f432cee17a6d96bd3f313df2 \ No newline at end of file diff --git a/checksums/oauth2-2.0.16.gem.sha256 b/checksums/oauth2-2.0.16.gem.sha256 new file mode 100644 index 00000000..71c6c586 --- /dev/null +++ b/checksums/oauth2-2.0.16.gem.sha256 @@ -0,0 +1 @@ +b45ce8b22e4c198ad372d6ba99134633a83c35aae365addbead0db27948f4294 \ No newline at end of file diff --git a/checksums/oauth2-2.0.16.gem.sha512 b/checksums/oauth2-2.0.16.gem.sha512 new file mode 100644 index 00000000..80c78a90 --- /dev/null +++ b/checksums/oauth2-2.0.16.gem.sha512 @@ -0,0 +1 @@ +49788bf25c3afcc08171f92c3c8a21b4bcd322aae0834f69ae77c08963f54be6c9155588ca66f82022af897ddd0bf28b0c5ee254bc9fe533d1a37b1d52f409be \ No newline at end of file diff --git a/checksums/oauth2-2.0.17.gem.sha256 b/checksums/oauth2-2.0.17.gem.sha256 new file mode 100644 index 00000000..d27197ef --- /dev/null +++ b/checksums/oauth2-2.0.17.gem.sha256 @@ -0,0 +1 @@ +c4e182aeabc06dfdafce9a15095c30edc3a1a21fc3c4f0ea49d9295429e79835 \ No newline at end of file diff --git a/checksums/oauth2-2.0.17.gem.sha512 b/checksums/oauth2-2.0.17.gem.sha512 new file mode 100644 index 00000000..414622a7 --- /dev/null +++ b/checksums/oauth2-2.0.17.gem.sha512 @@ -0,0 +1 @@ +6385dfb2d4cb0309745de2d442d99c6148744abaca5599bd1e4f6038e99734d9cf90d1de83d1833e416e2682f0e3d6ae83e10a5a55d6e884b9cdc54e6070fb8b \ No newline at end of file diff --git a/checksums/oauth2-2.0.18.gem.sha256 b/checksums/oauth2-2.0.18.gem.sha256 new file mode 100644 index 00000000..a1201909 --- /dev/null +++ b/checksums/oauth2-2.0.18.gem.sha256 @@ -0,0 +1 @@ +bacf11e470dfb963f17348666d0a75c7b29ca65bc48fd47be9057cf91a403287 \ No newline at end of file diff --git a/checksums/oauth2-2.0.18.gem.sha512 b/checksums/oauth2-2.0.18.gem.sha512 new file mode 100644 index 00000000..efb96235 --- /dev/null +++ b/checksums/oauth2-2.0.18.gem.sha512 @@ -0,0 +1 @@ +1db20c4bfe395f45e01ee2fbdcd4922aff6480c8071af404b324d4f5b6582b476359bf9bbcf38cd3537f26d15d413d31de4ea9c7e1b215bb0cf8a623a0d2e44e \ No newline at end of file diff --git a/config-ssl.json b/config-ssl.json new file mode 100644 index 00000000..f906d9e2 --- /dev/null +++ b/config-ssl.json @@ -0,0 +1,21 @@ +{ + "interactiveLogin": true, + "httpServer": { + "type": "NettyWrapper" + }, + "tokenCallbacks": [ + { + "issuerId": "default", + "requestMappings": [ + { + "requestParam": "grant_type", + "match": "client_credentials", + "claims": { + "sub": "demo-sub", + "aud": ["demo-aud"] + } + } + ] + } + ] +} diff --git a/docker-compose-ssl.yml b/docker-compose-ssl.yml new file mode 100644 index 00000000..f482d41d --- /dev/null +++ b/docker-compose-ssl.yml @@ -0,0 +1,12 @@ +services: + mock-oauth2-server: + image: ghcr.io/navikt/mock-oauth2-server:2.3.0 + restart: unless-stopped + ports: + - "8080:8080" + volumes: + - ./config-ssl.json:/app/config.json:Z + environment: + LOG_LEVEL: "debug" + SERVER_PORT: 8080 + JSON_CONFIG_PATH: /app/config.json diff --git a/docs/CNAME b/docs/CNAME new file mode 100644 index 00000000..9e32e7bf --- /dev/null +++ b/docs/CNAME @@ -0,0 +1 @@ +oauth2.galtzo.com \ No newline at end of file diff --git a/docs/OAuth2.html b/docs/OAuth2.html new file mode 100644 index 00000000..e69de29b diff --git a/docs/OAuth2/AccessToken.html b/docs/OAuth2/AccessToken.html new file mode 100644 index 00000000..733a4c74 --- /dev/null +++ b/docs/OAuth2/AccessToken.html @@ -0,0 +1,3093 @@ + + + + + + + Class: OAuth2::AccessToken + + — Documentation by YARD 0.9.37 + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + +

Class: OAuth2::AccessToken + + + +

+
+ +
+
Inherits:
+
+ Object + +
    +
  • Object
    • + + + +
+ show all + +
+
+ + + + + + +
+
Includes:
+
FilteredAttributes
+
+ + + + + + +
+
Defined in:
+
lib/oauth2/access_token.rb
+
+ +
+ +

Overview

+
+

rubocop:disable Metrics/ClassLength

+ + +
+
+
+ + +
+ +

+ Constant Summary + collapse +

+ +
+ +
TOKEN_KEYS_STR = + +
+ 
%w[access_token id_token token accessToken idToken].freeze
+ +
TOKEN_KEYS_SYM = + +
+ 
%i[access_token id_token token accessToken idToken].freeze
+ +
TOKEN_KEY_LOOKUP = + +
+ 
TOKEN_KEYS_STR + TOKEN_KEYS_SYM
+ +
+ + + + + +

Instance Attribute Summary collapse

+
    + +
  • + + + #client ⇒ Object + + + + + + + + + readonly + + + + + + + + + +

    Returns the value of attribute client.

    +
     + +
    • + + +
  • + + + #expires_at ⇒ Object + + + + + + + + + readonly + + + + + + + + + +

    Returns the value of attribute expires_at.

    +
     + +
    • + + +
  • + + + #expires_in ⇒ Object + + + + + + + + + readonly + + + + + + + + + +

    Returns the value of attribute expires_in.

    +
     + +
    • + + +
  • + + + #expires_latency ⇒ Object + + + + + + + + + readonly + + + + + + + + + +

    Returns the value of attribute expires_latency.

    +
     + +
    • + + +
  • + + + #options ⇒ Object + + + + + + + + + + + + + + + + +

    Returns the value of attribute options.

    +
     + +
    • + + +
  • + + + #params ⇒ Object + + + + + + + + + readonly + + + + + + + + + +

    Returns the value of attribute params.

    +
     + +
    • + + +
  • + + + #refresh_token ⇒ Object + + + + + + + + + + + + + + + + +

    Returns the value of attribute refresh_token.

    +
     + +
    • + + +
  • + + + #response ⇒ Object + + + + + + + + + + + + + + + + +

    Returns the value of attribute response.

    +
     + +
    • + + +
  • + + + #token ⇒ Object + + + + + + + + + readonly + + + + + + + + + +

    Returns the value of attribute token.

    +
     + +
    • + + +
+ + + + + +

+ Class Method Summary + collapse +

+ + + +

+ Instance Method Summary + collapse +

+ + + + + + + + + + + + + +

Methods included from FilteredAttributes

+

included, #inspect

+
+

Constructor Details

+ +
+

+ + #initialize(client, token, opts = {}) ⇒ AccessToken + + + + + +

+
+ +
+ Note: +

For “soon-to-expire”/”clock-skew” functionality see the :expires_latency option.

+
+
+ +
+ Note: +

If no token is provided, the AccessToken will be considered invalid.
+This is to prevent the possibility of a token being accidentally
+created with no token value.
+If you want to create an AccessToken with no token value,
+you can pass in an empty string or nil for the token value.
+If you want to create an AccessToken with no token value and
+no refresh token, you can pass in an empty string or nil for the
+token value and nil for the refresh token, and raise_errors: false.

+
+
+ +

Initialize an AccessToken

+ + +
+
+
+ +
+

Examples:

+ + +

Verb-dependent Hash mode

+
+ + 
# Send token in query for GET, in header for POST/DELETE, in body for PUT/PATCH
+OAuth2::AccessToken.new(client, token, mode: {get: :query, post: :header, delete: :header, put: :body, patch: :body})
+ +
+

Parameters:

+
    + +
  • + + client + + + (Client) + + + + — +

    the OAuth2::Client instance

    +
    + +
    • + +
  • + + token + + + (String) + + + + — +

    the Access Token value (optional, may not be used in refresh flows)

    +
    + +
    • + +
  • + + opts + + + (Hash) + + + (defaults to: {}) + + + — +

    the options to create the Access Token with

    +
    + +
    • + +
+ + + + + + + + +

Options Hash (opts):

+
    + +
  • + :refresh_token + (String) + + + — default: + nil + + + + —

    the refresh_token value

    +
    + +
    • + +
  • + :expires_in + (FixNum, String) + + + — default: + nil + + + + —

    the number of seconds in which the AccessToken will expire

    +
    + +
    • + +
  • + :expires_at + (FixNum, String) + + + — default: + nil + + + + —

    the epoch time in seconds in which AccessToken will expire

    +
    + +
    • + +
  • + :expires_latency + (FixNum, String) + + + — default: + nil + + + + —

    the number of seconds by which AccessToken validity will be reduced to offset latency, @version 2.0+

    +
    + +
    • + +
  • + :mode + (Symbol, Hash, or callable) + + + — default: + :header + + + + —

    the transmission mode of the Access Token parameter value:
    +either one of :header, :body or :query; or a Hash with verb symbols as keys mapping to one of these symbols
    +(e.g., {get: :query, post: :header, delete: :header}); or a callable that accepts a request-verb parameter
    +and returns one of these three symbols.

    +
    + +
    • + +
  • + :header_format + (String) + + + — default: + 'Bearer %s' + + + + —

    the string format to use for the Authorization header

    +
    + +
    • + +
  • + :param_name + (String) + + + — default: + 'access_token' + + + + —

    the parameter name to use for transmission of the
    +Access Token value in :body or :query transmission mode

    +
    + +
    • + +
  • + :token_name + (String) + + + — default: + nil + + + + —

    the name of the response parameter that identifies the access token
    +When nil one of TOKEN_KEY_LOOKUP will be used

    +
    + +
    • + +
+ + + +
+ + + + +
+ 
+
+
+148
+149
+150
+151
+152
+153
+154
+155
+156
+157
+158
+159
+160
+161
+162
+163
+164
+165
+166
+167
+168
+169
+170
+171
+172
+173
+174
+175
+176
+177
+178
+179
+180
+181
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 148
+
+def initialize(client, token, opts = {})
+  @client = client
+  @token = token.to_s
+  opts = opts.dup
+  %i[refresh_token expires_in expires_at expires_latency].each do |arg|
+    instance_variable_set("@#{arg}", opts.delete(arg) || opts.delete(arg.to_s))
+  end
+  no_tokens = (@token.nil? || @token.empty?) && (@refresh_token.nil? || @refresh_token.empty?)
+  if no_tokens
+    if @client.options[:raise_errors]
+      raise Error.new({
+        error: "OAuth2::AccessToken has no token",
+        error_description: "Options are: #{opts.inspect}",
+      })
+    elsif !OAuth2.config.silence_no_tokens_warning
+      warn("OAuth2::AccessToken has no token")
+    end
+  end
+  # @option opts [Fixnum, String] :expires is deprecated
+  @expires_in ||= opts.delete("expires")
+  @expires_in &&= @expires_in.to_i
+  @expires_at &&= convert_expires_at(@expires_at)
+  @expires_latency &&= @expires_latency.to_i
+  @expires_at ||= Time.now.to_i + @expires_in if @expires_in && !@expires_in.zero?
+  @expires_at -= @expires_latency if @expires_latency
+  @options = {
+    mode: opts.delete(:mode) || :header,
+    header_format: opts.delete(:header_format) || "Bearer %s",
+    param_name: opts.delete(:param_name) || "access_token",
+  }
+  @options[:token_name] = opts.delete(:token_name) if opts.key?(:token_name)
+
+  @params = opts
+end
+
+
+ +
+ +
+

Instance Attribute Details

+ + + +
+

+ + #client ⇒ Object (readonly) + + + + + +

+
+

Returns the value of attribute client.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+26
+27
+28
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 26
+
+def client
+  @client
+end
+
+
+ + + +
+

+ + #expires_at ⇒ Object (readonly) + + + + + +

+
+

Returns the value of attribute expires_at.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+26
+27
+28
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 26
+
+def expires_at
+  @expires_at
+end
+
+
+ + + +
+

+ + #expires_in ⇒ Object (readonly) + + + + + +

+
+

Returns the value of attribute expires_in.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+26
+27
+28
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 26
+
+def expires_in
+  @expires_in
+end
+
+
+ + + +
+

+ + #expires_latency ⇒ Object (readonly) + + + + + +

+
+

Returns the value of attribute expires_latency.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+26
+27
+28
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 26
+
+def expires_latency
+  @expires_latency
+end
+
+
+ + + +
+

+ + #options ⇒ Object + + + + + +

+
+

Returns the value of attribute options.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+27
+28
+29
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 27
+
+def options
+  @options
+end
+
+
+ + + +
+

+ + #params ⇒ Object (readonly) + + + + + +

+
+

Returns the value of attribute params.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+26
+27
+28
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 26
+
+def params
+  @params
+end
+
+
+ + + +
+

+ + #refresh_token ⇒ Object + + + + + +

+
+

Returns the value of attribute refresh_token.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+27
+28
+29
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 27
+
+def refresh_token
+  @refresh_token
+end
+
+
+ + + +
+

+ + #response ⇒ Object + + + + + +

+
+

Returns the value of attribute response.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+27
+28
+29
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 27
+
+def response
+  @response
+end
+
+
+ + + +
+

+ + #token ⇒ Object (readonly) + + + + + +

+
+

Returns the value of attribute token.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+26
+27
+28
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 26
+
+def token
+  @token
+end
+
+
+ +
+ + +
+

Class Method Details

+ + +
+

+ + .from_hash(client, hash) ⇒ OAuth2::AccessToken + + + + + +

+
+ +
+ Note: +

The method will use the first found token key in the following order:
+‘access_token’, ‘id_token’, ‘token’ (or their symbolic versions)

+
+
+ +
+ Note: +

If multiple token keys are present, a warning will be issued unless
+OAuth2.config.silence_extra_tokens_warning is true

+
+
+ +
+ Note: +

If no token keys are present, a warning will be issued unless
+OAuth2.config.silence_no_tokens_warning is true

+
+
+ +
+ Note: +

For “soon-to-expire”/”clock-skew” functionality see the :expires_latency option.

+
+
+ +
+ Note: +

If snaky key conversion is being used, token_name needs to match the converted key.

+
+
+ +

Initializes an AccessToken from a Hash

+ + +
+
+
+ +
+

Examples:

+ + + 
hash = { 'access_token' => 'token_value', 'refresh_token' => 'refresh_value' }
+access_token = OAuth2::AccessToken.from_hash(client, hash)
+ +
+

Parameters:

+
    + +
  • + + client + + + (OAuth2::Client) + + + + — +

    the OAuth2::Client instance

    +
    + +
    • + +
  • + + hash + + + (Hash) + + + + — +

    a hash containing the token and other properties

    +
    + +
    • + +
+ + + + + + +

Options Hash (hash):

+
    + +
  • + 'access_token' + (String) + + + + + —

    the access token value

    +
    + +
    • + +
  • + 'id_token' + (String) + + + + + —

    alternative key for the access token value

    +
    + +
    • + +
  • + 'token' + (String) + + + + + —

    alternative key for the access token value

    +
    + +
    • + +
  • + 'refresh_token' + (String) + + + — default: + optional + + + + —

    the refresh token value

    +
    + +
    • + +
  • + 'expires_in' + (Integer, String) + + + — default: + optional + + + + —

    number of seconds until token expires

    +
    + +
    • + +
  • + 'expires_at' + (Integer, String) + + + — default: + optional + + + + —

    epoch time in seconds when token expires

    +
    + +
    • + +
  • + 'expires_latency' + (Integer, String) + + + — default: + optional + + + + —

    seconds to reduce token validity by

    +
    + +
    • + +
+ + +

Returns:

+ + +
+ + + + +
+ 
+
+
+57
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+68
+69
+70
+71
+72
+73
+74
+75
+76
+77
+78
+79
+80
+81
+82
+83
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 57
+
+def from_hash(client, hash)
+  fresh = hash.dup
+  # If token_name is present, then use that key name
+  key =
+    if fresh.key?(:token_name)
+      t_key = fresh[:token_name]
+      no_tokens_warning(fresh, t_key)
+      t_key
+    else
+      # Otherwise, if one of the supported default keys is present, use whichever has precedence
+      supported_keys = TOKEN_KEY_LOOKUP & fresh.keys
+      t_key = supported_keys[0]
+      extra_tokens_warning(supported_keys, t_key)
+      t_key
+    end
+  # :nocov:
+  # TODO: Get rid of this branching logic when dropping Hashie < v3.2
+  token = if !defined?(Hashie::VERSION) # i.e. <= "1.1.0"; the first Hashie to ship with a VERSION constant
+    warn("snaky_hash and oauth2 will drop support for Hashie v0 in the next major version. Please upgrade to a modern Hashie.")
+    # There is a bug in Hashie v0, which is accounts for.
+    fresh.delete(key) || fresh[key] || ""
+  else
+    fresh.delete(key) || ""
+  end
+  # :nocov:
+  new(client, token, fresh)
+end
+
+
+ +
+

+ + .from_kvform(client, kvform) ⇒ AccessToken + + + + + +

+
+

Initializes an AccessToken from a key/value application/x-www-form-urlencoded string

+ + +
+
+
+

Parameters:

+
    + +
  • + + client + + + (Client) + + + + — +

    the OAuth2::Client instance

    +
    + +
    • + +
  • + + kvform + + + (String) + + + + — +

    the application/x-www-form-urlencoded string

    +
    + +
    • + +
+ +

Returns:

+
    + +
  • + + + (AccessToken) + + + + — +

    the initialized AccessToken

    +
    + +
    • + +
+ +
+ + + + +
+ 
+
+
+90
+91
+92
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 90
+
+def from_kvform(client, kvform)
+  from_hash(client, Rack::Utils.parse_query(kvform))
+end
+
+
+ +
+ +
+

Instance Method Details

+ + +
+

+ + #[](key) ⇒ Object + + + + + +

+
+

Indexer to additional params present in token response

+ + +
+
+
+

Parameters:

+
    + +
  • + + key + + + (String) + + + + — +

    entry key to Hash

    +
    + +
    • + +
+ + +
+ + + + +
+ 
+
+
+186
+187
+188
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 186
+
+def [](key)
+  @params[key]
+end
+
+
+ +
+

+ + #delete(path, opts = {}, &block) ⇒ Object + + + + + +

+
+

Make a DELETE request with the Access Token

+ + +
+
+
+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+368
+369
+370
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 368
+
+def delete(path, opts = {}, &block)
+  request(:delete, path, opts, &block)
+end
+
+
+ +
+

+ + #expired? ⇒ Boolean + + + + + +

+
+

Check if token is expired

+ + +
+
+
+ +

Returns:

+
    + +
  • + + + (Boolean) + + + + — +

    true if the token is expired, false otherwise

    +
    + +
    • + +
+ +
+ + + + +
+ 
+
+
+200
+201
+202
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 200
+
+def expired?
+  expires? && (expires_at <= Time.now.to_i)
+end
+
+
+ +
+

+ + #expires? ⇒ Boolean + + + + + +

+
+

Whether the token expires

+ + +
+
+
+ +

Returns:

+
    + +
  • + + + (Boolean) + + + +
    • + +
+ +
+ + + + +
+ 
+
+
+193
+194
+195
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 193
+
+def expires?
+  !!@expires_at
+end
+
+
+ +
+

+ + #get(path, opts = {}, &block) ⇒ Object + + + + + +

+
+

Make a GET request with the Access Token

+ + +
+
+
+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+340
+341
+342
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 340
+
+def get(path, opts = {}, &block)
+  request(:get, path, opts, &block)
+end
+
+
+ +
+

+ + #headers ⇒ Object + + + + + +

+
+

Get the headers hash (includes Authorization token)

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+373
+374
+375
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 373
+
+def headers
+  {"Authorization" => options[:header_format] % token}
+end
+
+
+ +
+

+ + #patch(path, opts = {}, &block) ⇒ Object + + + + + +

+
+

Make a PATCH request with the Access Token

+ + +
+
+
+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+361
+362
+363
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 361
+
+def patch(path, opts = {}, &block)
+  request(:patch, path, opts, &block)
+end
+
+
+ +
+

+ + #post(path, opts = {}, &block) ⇒ Object + + + + + +

+
+

Make a POST request with the Access Token

+ + +
+
+
+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+347
+348
+349
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 347
+
+def post(path, opts = {}, &block)
+  request(:post, path, opts, &block)
+end
+
+
+ +
+

+ + #put(path, opts = {}, &block) ⇒ Object + + + + + +

+
+

Make a PUT request with the Access Token

+ + +
+
+
+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+354
+355
+356
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 354
+
+def put(path, opts = {}, &block)
+  request(:put, path, opts, &block)
+end
+
+
+ +
+

+ + #refresh(params = {}, access_token_opts = {}) {|opts| ... } ⇒ OAuth2::AccessToken + + + + Also known as: + refresh! + + + + +

+
+ +
+ Note: +

current token’s options are carried over to the new AccessToken

+
+
+ +

Refreshes the current Access Token

+ + +
+
+
+

Parameters:

+
    + +
  • + + params + + + (Hash) + + + (defaults to: {}) + + + — +

    additional params to pass to the refresh token request

    +
    + +
    • + +
  • + + access_token_opts + + + (Hash) + + + (defaults to: {}) + + + — +

    options that will be passed to the AccessToken initialization

    +
    + +
    • + +
+ +

Yields:

+
    + +
  • + + + (opts) + + + + — +

    The block to modify the refresh token request options

    +
    + +
    • + +
+

Yield Parameters:

+
    + +
  • + + opts + + + (Hash) + + + + — +

    The options hash that can be modified

    +
    + +
    • + +
+

Returns:

+ +

Raises:

+ + +
+ + + + +
+ 
+
+
+215
+216
+217
+218
+219
+220
+221
+222
+223
+224
+225
+226
+227
+228
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 215
+
+def refresh(params = {}, access_token_opts = {}, &block)
+  raise OAuth2::Error.new({error: "A refresh_token is not available"}) unless refresh_token
+
+  params[:grant_type] = "refresh_token"
+  params[:refresh_token] = refresh_token
+  new_token = @client.get_token(params, access_token_opts, &block)
+  new_token.options = options
+  if new_token.refresh_token
+    # Keep it if there is one
+  else
+    new_token.refresh_token = refresh_token
+  end
+  new_token
+end
+
+
+ +
+

+ + #request(verb, path, opts = {}) {|req| ... } ⇒ OAuth2::Response + + + + + +

+
+

Make a request with the Access Token

+ + +
+
+
+

Parameters:

+
    + +
  • + + verb + + + (Symbol) + + + + — +

    the HTTP request method

    +
    + +
    • + +
  • + + path + + + (String) + + + + — +

    the HTTP URL path of the request

    +
    + +
    • + +
  • + + opts + + + (Hash) + + + (defaults to: {}) + + + — +

    the options to make the request with

    +
    + +
    • + +
+ + + + + + + + +

Options Hash (opts):

+
    + +
  • + :params + (Hash) + + + + + —

    additional URL parameters

    +
    + +
    • + +
  • + :body + (Hash, String) + + + + + —

    the request body

    +
    + +
    • + +
  • + :headers + (Hash) + + + + + —

    request headers

    +
    + +
    • + +
+ + +

Yields:

+
    + +
  • + + + (req) + + + + — +

    The block to modify the request

    +
    + +
    • + +
+

Yield Parameters:

+
    + +
  • + + req + + + (Faraday::Request) + + + + — +

    The request object that can be modified

    +
    + +
    • + +
+

Returns:

+
    + +
  • + + + (OAuth2::Response) + + + + — +

    the response from the request

    +
    + +
    • + +
+ +

See Also:

+ + +
+ + + + +
+ 
+
+
+332
+333
+334
+335
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 332
+
+def request(verb, path, opts = {}, &block)
+  configure_authentication!(opts, verb)
+  @client.request(verb, path, opts, &block)
+end
+
+
+ +
+

+ + #revoke(params = {}) {|req| ... } ⇒ OAuth2::Response + + + + Also known as: + revoke! + + + + +

+
+ +
+ Note: +

If the token passed to the request
+is an access token, the server MAY revoke the respective refresh
+token as well.

+
+
+ +
+ Note: +

If the token passed to the request
+is a refresh token and the authorization server supports the
+revocation of access tokens, then the authorization server SHOULD
+also invalidate all access tokens based on the same authorization
+grant

+
+
+ +
+ Note: +

If the server responds with HTTP status code 503, your code must
+assume the token still exists and may retry after a reasonable delay.
+The server may include a “Retry-After” header in the response to
+indicate how long the service is expected to be unavailable to the
+requesting client.

+
+
+ +

Revokes the token at the authorization server

+ + +
+
+
+

Parameters:

+
    + +
  • + + params + + + (Hash) + + + (defaults to: {}) + + + — +

    additional parameters to be sent during revocation

    +
    + +
    • + +
+ + + + +

Options Hash (params):

+
    + +
  • + :token_type_hint + (String, Symbol, nil) + + + — default: + 'access_token' or 'refresh_token' + + + + —

    hint about which token to revoke

    +
    + +
    • + +
  • + :token_method + (Symbol) + + + — default: + :post_with_query_string + + + + —

    overrides OAuth2::Client#options[:token_method]

    +
    + +
    • + +
+ + +

Yields:

+
    + +
  • + + + (req) + + + + — +

    The block is passed the request being made, allowing customization

    +
    + +
    • + +
+

Yield Parameters:

+
    + +
  • + + req + + + (Faraday::Request) + + + + — +

    The request object that can be modified

    +
    + +
    • + +
+

Returns:

+ +

Raises:

+
    + +
  • + + + (OAuth2::Error) + + + + — +

    if token_type_hint is invalid or the specified token is not available

    +
    + +
    • + +
+ +

See Also:

+ + +
+ + + + +
+ 
+
+
+264
+265
+266
+267
+268
+269
+270
+271
+272
+273
+274
+275
+276
+277
+278
+279
+280
+281
+282
+283
+284
+285
+286
+287
+288
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 264
+
+def revoke(params = {}, &block)
+  token_type_hint_orig = params.delete(:token_type_hint)
+  token_type_hint = nil
+  revoke_token = case token_type_hint_orig
+  when "access_token", :access_token
+    token_type_hint = "access_token"
+    token
+  when "refresh_token", :refresh_token
+    token_type_hint = "refresh_token"
+    refresh_token
+  when nil
+    if token
+      token_type_hint = "access_token"
+      token
+    elsif refresh_token
+      token_type_hint = "refresh_token"
+      refresh_token
+    end
+  else
+    raise OAuth2::Error.new({error: "token_type_hint must be one of [nil, :refresh_token, :access_token], so if you need something else consider using a subclass or entirely custom AccessToken class."})
+  end
+  raise OAuth2::Error.new({error: "#{token_type_hint || "unknown token type"} is not available for revoking"}) unless revoke_token && !revoke_token.empty?
+
+  @client.revoke_token(revoke_token, token_type_hint, params, &block)
+end
+
+
+ +
+

+ + #to_hash ⇒ Hash + + + + + +

+
+ +
+ Note: +

Don’t return expires_latency because it has already been deducted from expires_at

+
+
+ +

Convert AccessToken to a hash which can be used to rebuild itself with AccessToken.from_hash

+ + +
+
+
+ +

Returns:

+
    + +
  • + + + (Hash) + + + + — +

    a hash of AccessToken property values

    +
    + +
    • + +
+ +
+ + + + +
+ 
+
+
+298
+299
+300
+301
+302
+303
+304
+305
+306
+307
+308
+309
+310
+311
+312
+313
+314
+315
+ 		+ 
# File 'lib/oauth2/access_token.rb', line 298
+
+def to_hash
+  hsh = {
+    access_token: token,
+    refresh_token: refresh_token,
+    expires_at: expires_at,
+    mode: options[:mode],
+    header_format: options[:header_format],
+    param_name: options[:param_name],
+  }
+  hsh[:token_name] = options[:token_name] if options.key?(:token_name)
+  # TODO: Switch when dropping Ruby < 2.5 support
+  # params.transform_keys(&:to_sym) # Ruby 2.5 only
+  # Old Ruby transform_keys alternative:
+  sheesh = @params.each_with_object({}) { |(k, v), memo|
+    memo[k.to_sym] = v
+  }
+  sheesh.merge(hsh)
+end
+
+
+ +
+ +
+ + + +
+ + \ No newline at end of file diff --git a/docs/OAuth2/Authenticator.html b/docs/OAuth2/Authenticator.html new file mode 100644 index 00000000..e69de29b diff --git a/docs/OAuth2/Client.html b/docs/OAuth2/Client.html new file mode 100644 index 00000000..ac07320c --- /dev/null +++ b/docs/OAuth2/Client.html @@ -0,0 +1,1908 @@ + + + + + + + Class: OAuth2::Client + + — Documentation by YARD 0.9.37 + + + + + + + + + + + + + + + + + +
+ +
+
+ +
+ + +

Class: OAuth2::Client + + + +

+
+ +
+
Inherits:
+
+ Object + +
    +
  • Object
    • + + + +
+ show all + +
+
+ + + + + + +
+
Includes:
+
FilteredAttributes
+
+ + + + + + +
+
Defined in:
+
lib/oauth2/client.rb
+
+ +
+ +

Overview

+
+

The OAuth2::Client class

+ + +
+
+
+ + +
+ +

+ Constant Summary + collapse +

+ +
+ +
RESERVED_REQ_KEYS = +
+
+

rubocop:disable Metrics/ClassLength

+ + +
+
+
+ + +
+
+ 
%w[body headers params redirect_count].freeze
+ +
RESERVED_PARAM_KEYS = + +
+ 
(RESERVED_REQ_KEYS + %w[parse snaky snaky_hash_klass token_method]).freeze
+ +
+ + + + + +

Instance Attribute Summary collapse

+
    + +
  • + + + #connection ⇒ Faraday::Connection + + + + + + + + + + + + + + + + +

    The Faraday connection object.

    +
     + +
    • + + +
  • + + + #id ⇒ Object + + + + + + + + + readonly + + + + + + + + + +

    Returns the value of attribute id.

    +
     + +
    • + + +
  • + + + #options ⇒ Object + + + + + + + + + + + + + + + + +

    Returns the value of attribute options.

    +
     + +
    • + + +
  • + + + #secret ⇒ Object + + + + + + + + + readonly + + + + + + + + + +

    Returns the value of attribute secret.

    +
     + +
    • + + +
  • + + + #site ⇒ Object + + + + + + + + + + + + + + + + +

    Returns the value of attribute site.

    +
     + +
    • + + +
+ + + + + +

+ Instance Method Summary + collapse +

+ + + + + + + + + + + + + +

Methods included from FilteredAttributes

+

included, #inspect

+
+

Constructor Details

+ +
+

+ + #initialize(client_id, client_secret, options = {}) {|builder| ... } ⇒ Client + + + + + +

+
+

Initializes a new OAuth2::Client instance using the Client ID and Client Secret registered to your application.

+ + +
+
+
+

Parameters:

+
    + +
  • + + client_id + + + (String) + + + + — +

    the client_id value

    +
    + +
    • + +
  • + + client_secret + + + (String) + + + + — +

    the client_secret value

    +
    + +
    • + +
  • + + options + + + (Hash) + + + (defaults to: {}) + + + — +

    the options to configure the client

    +
    + +
    • + +
+ + + + + + + + +

Options Hash (options):

+
    + +
  • + :site + (String) + + + + + —

    the OAuth2 provider site host

    +
    + +
    • + +
  • + :authorize_url + (String) + + + — default: + '/oauth/authorize' + + + + —

    absolute or relative URL path to the Authorization endpoint

    +
    + +
    • + +
  • + :revoke_url + (String) + + + — default: + '/oauth/revoke' + + + + —

    absolute or relative URL path to the Revoke endpoint

    +
    + +
    • + +
  • + :token_url + (String) + + + — default: + '/oauth/token' + + + + —

    absolute or relative URL path to the Token endpoint

    +
    + +
    • + +
  • + :token_method + (Symbol) + + + — default: + :post + + + + —

    HTTP method to use to request token (:get, :post, :post_with_query_string)

    +
    + +
    • + +
  • + :auth_scheme + (Symbol) + + + — default: + :basic_auth + + + + —

    the authentication scheme (:basic_auth, :request_body, :tls_client_auth, :private_key_jwt)

    +
    + +
    • + +
  • + :connection_opts + (Hash) + + + — default: + {} + + + + —

    Hash of connection options to pass to initialize Faraday

    +
    + +
    • + +
  • + :raise_errors + (Boolean) + + + — default: + true + + + + —

    whether to raise an OAuth2::Error on responses with 400+ status codes

    +
    + +
    • + +
  • + :max_redirects + (Integer) + + + — default: + 5 + + + + —

    maximum number of redirects to follow

    +
    + +
    • + +
  • + :logger + (Logger) + + + — default: + ::Logger.new($stdout) + + + + —

    Logger instance for HTTP request/response output; requires OAUTH_DEBUG to be true

    +
    + +
    • + +
  • + :access_token_class + (Class) + + + — default: + AccessToken + + + + —

    class to use for access tokens; you can subclass OAuth2::AccessToken, @version 2.0+

    +
    + +
    • + +
  • + :ssl + (Hash) + + + + + —

    SSL options for Faraday

    +
    + +
    • + +
+ + +

Yields:

+
    + +
  • + + + (builder) + + + + — +

    The Faraday connection builder

    +
    + +
    • + +
+ +
+ + + + +
+ 
+
+
+50
+51
+52
+53
+54
+55
+56
+57
+58
+59
+60
+61
+62
+63
+64
+65
+66
+67
+68
+69
+70
+71
+ 		+ 
# File 'lib/oauth2/client.rb', line 50
+
+def initialize(client_id, client_secret, options = {}, &block)
+  opts = options.dup
+  @id = client_id
+  @secret = client_secret
+  @site = opts.delete(:site)
+  ssl = opts.delete(:ssl)
+  warn("OAuth2::Client#initialize argument `extract_access_token` will be removed in oauth2 v3. Refactor to use `access_token_class`.") if opts[:extract_access_token]
+  @options = {
+    authorize_url: "oauth/authorize",
+    revoke_url: "oauth/revoke",
+    token_url: "oauth/token",
+    token_method: :post,
+    auth_scheme: :basic_auth,
+    connection_opts: {},
+    connection_build: block,
+    max_redirects: 5,
+    raise_errors: true,
+    logger: ::Logger.new($stdout),
+    access_token_class: AccessToken,
+  }.merge(opts)
+  @options[:connection_opts][:ssl] = ssl if ssl
+end
+
+
+ +
+ +
+

Instance Attribute Details

+ + + +
+

+ + #connection ⇒ Faraday::Connection + + + + + +

+
+

The Faraday connection object

+ + +
+
+
+ +

Returns:

+
    + +
  • + + + (Faraday::Connection) + + + + — +

    the initialized Faraday connection

    +
    + +
    • + +
+ +
+ + + + +
+ 
+
+
+85
+86
+87
+88
+89
+90
+91
+92
+93
+94
+95
+96
+ 		+ 
# File 'lib/oauth2/client.rb', line 85
+
+def connection
+  @connection ||=
+    Faraday.new(site, options[:connection_opts]) do |builder|
+      oauth_debug_logging(builder)
+      if options[:connection_build]
+        options[:connection_build].call(builder)
+      else
+        builder.request(:url_encoded)             # form-encode POST params
+        builder.adapter(Faraday.default_adapter)  # make requests with Net::HTTP
+      end
+    end
+end
+
+
+ + + +
+

+ + #id ⇒ Object (readonly) + + + + + +

+
+

Returns the value of attribute id.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+26
+27
+28
+ 		+ 
# File 'lib/oauth2/client.rb', line 26
+
+def id
+  @id
+end
+
+
+ + + +
+

+ + #options ⇒ Object + + + + + +

+
+

Returns the value of attribute options.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+27
+28
+29
+ 		+ 
# File 'lib/oauth2/client.rb', line 27
+
+def options
+  @options
+end
+
+
+ + + +
+

+ + #secret ⇒ Object (readonly) + + + + + +

+
+

Returns the value of attribute secret.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+26
+27
+28
+ 		+ 
# File 'lib/oauth2/client.rb', line 26
+
+def secret
+  @secret
+end
+
+
+ + + +
+

+ + #site ⇒ Object + + + + + +

+
+

Returns the value of attribute site.

+ + +
+
+
+ + +
+ + + + +
+ 
+
+
+26
+27
+28
+ 		+ 
# File 'lib/oauth2/client.rb', line 26
+
+def site
+  @site
+end
+
+
+ +
+ + +
+

Instance Method Details

+ + +
+

+ + #assertion ⇒ OAuth2::Strategy::Assertion + + + + + +

+
+

The Assertion strategy

+ +

This allows for assertion-based authentication where an identity provider
+asserts the identity of the user or client application seeking access.

+ + +
+
+
+ +

Returns:

+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+314
+315
+316
+ 		+ 
# File 'lib/oauth2/client.rb', line 314
+
+def assertion
+  @assertion ||= OAuth2::Strategy::Assertion.new(self)
+end
+
+
+ +
+

+ + #auth_code ⇒ Object + + + + + +

+
+

The Authorization Code strategy

+ + +
+
+
+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+280
+281
+282
+ 		+ 
# File 'lib/oauth2/client.rb', line 280
+
+def auth_code
+  @auth_code ||= OAuth2::Strategy::AuthCode.new(self)
+end
+
+
+ +
+

+ + #authorize_url(params = {}) ⇒ String + + + + + +

+
+

The authorize endpoint URL of the OAuth2 provider

+ + +
+
+
+

Parameters:

+
    + +
  • + + params + + + (Hash) + + + (defaults to: {}) + + + — +

    additional query parameters

    +
    + +
    • + +
+ +

Returns:

+
    + +
  • + + + (String) + + + + — +

    the constructed authorize URL

    +
    + +
    • + +
+ +
+ + + + +
+ 
+
+
+102
+103
+104
+105
+ 		+ 
# File 'lib/oauth2/client.rb', line 102
+
+def authorize_url(params = {})
+  params = (params || {}).merge(redirection_params)
+  connection.build_url(options[:authorize_url], params).to_s
+end
+
+
+ +
+

+ + #client_credentials ⇒ Object + + + + + +

+
+

The Client Credentials strategy

+ + +
+
+
+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+301
+302
+303
+ 		+ 
# File 'lib/oauth2/client.rb', line 301
+
+def client_credentials
+  @client_credentials ||= OAuth2::Strategy::ClientCredentials.new(self)
+end
+
+
+ +
+

+ + #get_token(params, access_token_opts = {}, extract_access_token = nil) {|opts| ... } ⇒ AccessToken? + + + + + +

+
+ +
+ Note: +

The extract_access_token parameter is deprecated and will be removed in oauth2 v3.
+Use access_token_class on initialization instead.

+
+
+ +

Retrieves an access token from the token endpoint using the specified parameters

+ + +
+
+
+ +
+

Examples:

+ + + 
client.get_token(
+  'grant_type' => 'authorization_code',
+  'code' => 'auth_code_value',
+  'headers' => {'Authorization' => 'Basic ...'}
+)
+ +
+

Parameters:

+
    + +
  • + + params + + + (Hash) + + + + — +

    a Hash of params for the token endpoint

    +
      +
    • params can include a ‘headers’ key with a Hash of request headers
      • +
    • params can include a ‘parse’ key with the Symbol name of response parsing strategy (default: :automatic)
      • +
    • params can include a ‘snaky’ key to control snake_case conversion (default: false)
      • +
    +
    + +
    • + +
  • + + access_token_opts + + + (Hash) + + + (defaults to: {}) + + + — +

    options that will be passed to the AccessToken initialization

    +
    + +
    • + +
  • + + extract_access_token + + + (Proc) + + + (defaults to: nil) + + + — +

    (deprecated) a proc that can extract the access token from the response

    +
    + +
    • + +
+ +

Yields:

+
    + +
  • + + + (opts) + + + + — +

    The block is passed the options being used to make the request

    +
    + +
    • + +
+

Yield Parameters:

+
    + +
  • + + opts + + + (Hash) + + + + — +

    options being passed to the http library

    +
    + +
    • + +
+

Returns:

+
    + +
  • + + + (AccessToken, nil) + + + + — +

    the initialized AccessToken instance, or nil if token extraction fails
    +and raise_errors is false

    +
    + +
    • + +
+ +
+ + + + +
+ 
+
+
+208
+209
+210
+211
+212
+213
+214
+215
+216
+217
+218
+219
+220
+221
+222
+ 		+ 
# File 'lib/oauth2/client.rb', line 208
+
+def get_token(params, access_token_opts = {}, extract_access_token = nil, &block)
+  warn("OAuth2::Client#get_token argument `extract_access_token` will be removed in oauth2 v3. Refactor to use `access_token_class` on #initialize.") if extract_access_token
+  extract_access_token ||= options[:extract_access_token]
+  req_opts = params_to_req_opts(params)
+  response = request(http_method, token_url, req_opts, &block)
+
+  # In v1.4.x, the deprecated extract_access_token option retrieves the token from the response.
+  # We preserve this behavior here, but a custom access_token_class that implements #from_hash
+  # should be used instead.
+  if extract_access_token
+    parse_response_legacy(response, access_token_opts, extract_access_token)
+  else
+    parse_response(response, access_token_opts)
+  end
+end
+
+
+ +
+

+ + #http_method ⇒ Symbol + + + + + +

+
+

The HTTP Method of the request

+ + +
+
+
+ +

Returns:

+
    + +
  • + + + (Symbol) + + + + — +

    HTTP verb, one of [:get, :post, :put, :delete]

    +
    + +
    • + +
+ +
+ + + + +
+ 
+
+
+270
+271
+272
+273
+274
+275
+ 		+ 
# File 'lib/oauth2/client.rb', line 270
+
+def http_method
+  http_meth = options[:token_method].to_sym
+  return :post if http_meth == :post_with_query_string
+
+  http_meth
+end
+
+
+ +
+

+ + #implicit ⇒ Object + + + + + +

+
+

The Implicit strategy

+ + +
+
+
+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+287
+288
+289
+ 		+ 
# File 'lib/oauth2/client.rb', line 287
+
+def implicit
+  @implicit ||= OAuth2::Strategy::Implicit.new(self)
+end
+
+
+ +
+

+ + #password ⇒ Object + + + + + +

+
+

The Resource Owner Password Credentials strategy

+ + +
+
+
+ + +

See Also:

+ + +
+ + + + +
+ 
+
+
+294
+295
+296
+ 		+ 
# File 'lib/oauth2/client.rb', line 294
+
+def password
+  @password ||= OAuth2::Strategy::Password.new(self)
+end
+
+
+ +
+

+ + #redirection_params ⇒ Hash + + + + + +

+
+

The redirect_uri parameters, if configured

+ +

The redirect_uri query parameter is OPTIONAL (though encouraged) when
+requesting authorization. If it is provided at authorization time it MUST
+also be provided with the token exchange request.

+ +

OAuth 2.1 note: Authorization Servers must compare redirect URIs using exact string matching.
+This client simply forwards the configured redirect_uri; the exact-match validation happens server-side.

+ +

Providing :redirect_uri to the OAuth2::Client instantiation will take
+care of managing this.

+ + +
+
+
+ +

Returns:

+
    + +
  • + + + (Hash) + + + + — +

    the params to add to a request or URL

    +
    + +
    • + +
+ +

See Also:

+ + +
+ + + ",""],legend:[1,"
","
"],thead:[1,"
+ 
+
+
+339
+340
+341
+342
+343
+344
+345
+ 		+ 
# File 'lib/oauth2/client.rb', line 339
+
+def redirection_params
+  if opt
\ No newline at end of file
diff --git a/docs/OAuth2/Error.html b/docs/OAuth2/Error.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/OAuth2/FilteredAttributes.html b/docs/OAuth2/FilteredAttributes.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/OAuth2/FilteredAttributes/ClassMethods.html b/docs/OAuth2/FilteredAttributes/ClassMethods.html
new file mode 100644
index 00000000..c37b47e7
--- /dev/null
+++ b/docs/OAuth2/FilteredAttributes/ClassMethods.html
@@ -0,0 +1,290 @@
+
+
+  
+    
+
+
+  Module: OAuth2::FilteredAttributes::ClassMethods
+  
+    — Documentation by YARD 0.9.37
+  
+
+
+  
+
+  
+
+
+
+
+  
+
+  
+
+
+  
+  
+    

+      
+      

+    

+
+    

+      
+
+      
Module: OAuth2::FilteredAttributes::ClassMethods
+  
+  
+  
+

+

+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  

+    
Defined in:

+    
lib/oauth2/filtered_attributes.rb

+  

+  
+

+
+
Overview

+  

+    
Class-level helpers for configuring filtered attributes.

+
+
+  

+

+

+  
+
+

+
+
+
+
+
+
+  
+    

+      Instance Method Summary
+      collapse
+    

+
+    
+  
+
+
+
+  

+    
Instance Method Details

+
+    
+      

+  

+  
+    #filtered_attribute_names  ⇒ Array<Symbol> 
+  
+
+  
+
+  
+

+  

+    
The configured attribute names to filter.

+
+
+  

+

+

+  
+
Returns:

+
    
+  
+    
  • 
+      
+      
+        (Array<Symbol>)
+      
+      
+      
+    
    • 
+  
+

+
+

+  
+    
+    
+  
+

+      
+
+
+30
+31
+32

+    		
+      
# File 'lib/oauth2/filtered_attributes.rb', line 30
+
+def filtered_attribute_names
+  @filtered_attribute_names || []
+end

+    

+

+    
+      

+  

+  
+    #filtered_attributes(*attributes)  ⇒ void 
+  
+
+  
+
+  
+

+  

+    
This method returns an undefined value.
Declare attributes that should be redacted in inspect output.

+
+
+  

+

+

+  
Parameters:

+
    
+  
+    
  • 
+      
+        attributes
+      
+      
+        (Array<Symbol, String>)
+      
+      
+      
+        —
+        
    One or more attribute names
    
+
    
+      
+    
    • 
+  
+

+
+
+

+  
+    
+    
+  
+

+      
+
+
+23
+24
+25

+    		
+      
# File 'lib/oauth2/filtered_attributes.rb', line 23
+
+def filtered_attributes(*attributes)
+  @filtered_attribute_names = attributes.map(&:to_sym)
+end

+    

+

+    
+  

+
+

+
+      
+
+    

+  
+
\ No newline at end of file
diff --git a/docs/OAuth2/Response.html b/docs/OAuth2/Response.html
new file mode 100644
index 00000000..388127f3
--- /dev/null
+++ b/docs/OAuth2/Response.html
@@ -0,0 +1,367 @@
+
+
+  
+    
+
+
+  Class: OAuth2::Response
+  
+    — Documentation by YARD 0.9.37
+  
+
+
+  
+
+  
+
+
+
+
+  
+
+  
+
+
+  
+  
+    

+      
+      

+    

+
+    

+      
+
+      
Class: OAuth2::Response
+  
+  
+  
+

+

+  
+  

+    
Inherits:

+    

+      Object
+      
+        
    
+          
  • Object
    • 
+          
+            
+          
+        

+        show all
+      
+    

+  

+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  

+    
Defined in:

+    
lib/oauth2/response.rb

+  

+  
+

+
+
Overview

+  

+    
The Response class handles HTTP responses in the OAuth2 gem, providing methods

+to access and parse response data in various formats.

+
+
+  

+

+

+  
+
Since:

+
    
+  
+    
  • 
+      
+      
+      
+      
+        
+        
    1.0.0
    
+
    
+      
+    
    • 
+  
+

+
+

+  
+    

+      Constant Summary
+      collapse
+    

+
+    

+      
+        
DEFAULT_OPTIONS =
+          

+  

+    
Default configuration options for Response instances

+
+
+  

+

+

+  
+
Returns:

+
    
+  
+    
  • 
+      
+      
+        (Hash)
+      
+      
+      
+        —
+        
    The default options hash
    
+
    
+      
+    
    • 
+  
+

+
Since:

+
    
+  
+    
  • 
+      
+      
+      
+      
+        
+        
    1.0.0
    
+
    
+      
+    
    • 
+  
+

+
+

+        

+        
{
+  parse: :automatic,
+  snaky: true,
+  snaky_hash_klass: SnakyHash::StringKeyed,
+}.freeze

+      
+        
@@parsers =
+          

+  

+    
Storage for response body parser procedures

+
+
+  

+

+

+  
+
Returns:

+
    
+  
+    
  • 
+      
+      
+        (Hash<Symbol, Proc>)
+      
+      
+      
+        —
+        
    Hash of parser procs keyed by format symbol
    
+
    
+      
+    
    • 
+  
+

+
Since:

+
    
+  
+    
  • 
+      
+      
+      
+      
+        
+        
    1.0.0
    
+
    
+      
+    
    • 
+  
+

+
+

+        

+        
{
+  query: ->(body) { Rack::Utils.parse_query(body) },
+  text: ->(body) { body },
+}

+      
+        
@@content_types =
+          

+  

+    
Maps content types to parser symbols

+
+
+  

+

+

+  
+
Returns:

+
    
+  
+    
  • 
+      
+      
+        (Hash<String, Symbol>)
+      
+      
+      
+        —
+        
    Hash of content types mapped to parser symbols
    
+
    
+      
+    
    • 
+  
+

+
Since:

+
    
+  
+    
  • 
+      
+      
+      
+      
+        
+        
    1.0.0
    
+
    
+      
+    
    • 
+  
+

+
+

+        

+        
{
+  "application/x-www-form-urlencoded" => :query,
+  "text/plain" => :text,
+}

+      
+    

+  
+
+
+
+
+  
Instance Attribute Summary collapse

+  
+
+
+
+
+  
+    

+      Class Method Summary
+      collapse
+    

+
+    
    
+      
+        
  • 
+  
+    
+      
+
+
+  Module: OAuth2::Version
+  
+    — Documentation by YARD 0.9.37
+  
+
+
+  
+
+  
+
+
+
+
+  
+
+  
+
+
+  
+  
+    
    
+      
+      
    
+    
    
+
+    
    
+      
+
+      
    Module: OAuth2::Version
+  
+  
+  
+
    
+
    
+  
+
+  
+  
+  
+  
+  
+
+  
+
+  
+  
    
+    
    Defined in:
    
+    
    lib/oauth2/version.rb
    
+  
    
+  
+
    
+
+
+  
+    
    
+      Constant Summary
+      collapse
+    
    
+
+    
    
+      
+        
    VERSION =
+          
+        
    
+        
    "2.0.18"
    
+      
+    
    
+  
+
+
+
+
+
+
+
+
+
+
    
+
+      
+
+    
    
+  
+
\ No newline at end of file
diff --git a/docs/_index.html b/docs/_index.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/class_list.html b/docs/class_list.html
new file mode 100644
index 00000000..df1ca243
--- /dev/null
+++ b/docs/class_list.html
@@ -0,0 +1,54 @@
+
+
+  
+    
+    
+    
+      
+    
+      
+    
+
+    
+      
+    
+      
+    
+
+    Class List
+    
+  
+  
+    
    
+      
    
+        
    Class List
    
+        
+
+        
+      
    
+
+      
+    
    
+  
+
diff --git a/docs/css/common.css b/docs/css/common.css
new file mode 100644
index 00000000..cf25c452
--- /dev/null
+++ b/docs/css/common.css
@@ -0,0 +1 @@
+/* Override this file with custom rules */
\ No newline at end of file
diff --git a/docs/css/full_list.css b/docs/css/full_list.css
new file mode 100644
index 00000000..6eef5e4a
--- /dev/null
+++ b/docs/css/full_list.css
@@ -0,0 +1,58 @@
+body {
+  margin: 0;
+  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
+  font-size: 13px;
+  height: 101%;
+  overflow-x: hidden;
+  background: #fafafa;
+}
+
+h1 { padding: 12px 10px; padding-bottom: 0; margin: 0; font-size: 1.4em; }
+.clear { clear: both; }
+.fixed_header { position: fixed; background: #fff; width: 100%; padding-bottom: 10px; margin-top: 0; top: 0; z-index: 9999; height: 70px; }
+#search { position: absolute; right: 5px; top: 9px; padding-left: 24px; }
+#content.insearch #search, #content.insearch #noresults { background: url(data:image/gif;base64,R0lGODlhEAAQAPYAAP///wAAAPr6+pKSkoiIiO7u7sjIyNjY2J6engAAAI6OjsbGxjIyMlJSUuzs7KamppSUlPLy8oKCghwcHLKysqSkpJqamvT09Pj4+KioqM7OzkRERAwMDGBgYN7e3ujo6Ly8vCoqKjY2NkZGRtTU1MTExDw8PE5OTj4+PkhISNDQ0MrKylpaWrS0tOrq6nBwcKysrLi4uLq6ul5eXlxcXGJiYoaGhuDg4H5+fvz8/KKiohgYGCwsLFZWVgQEBFBQUMzMzDg4OFhYWBoaGvDw8NbW1pycnOLi4ubm5kBAQKqqqiQkJCAgIK6urnJyckpKSjQ0NGpqatLS0sDAwCYmJnx8fEJCQlRUVAoKCggICLCwsOTk5ExMTPb29ra2tmZmZmhoaNzc3KCgoBISEiIiIgAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACH/C05FVFNDQVBFMi4wAwEAAAAh/hpDcmVhdGVkIHdpdGggYWpheGxvYWQuaW5mbwAh+QQJCAAAACwAAAAAEAAQAAAHaIAAgoMgIiYlg4kACxIaACEJCSiKggYMCRselwkpghGJBJEcFgsjJyoAGBmfggcNEx0flBiKDhQFlIoCCA+5lAORFb4AJIihCRbDxQAFChAXw9HSqb60iREZ1omqrIPdJCTe0SWI09GBACH5BAkIAAAALAAAAAAQABAAAAdrgACCgwc0NTeDiYozCQkvOTo9GTmDKy8aFy+NOBA7CTswgywJDTIuEjYFIY0JNYMtKTEFiRU8Pjwygy4ws4owPyCKwsMAJSTEgiQlgsbIAMrO0dKDGMTViREZ14kYGRGK38nHguHEJcvTyIEAIfkECQgAAAAsAAAAABAAEAAAB2iAAIKDAggPg4iJAAMJCRUAJRIqiRGCBI0WQEEJJkWDERkYAAUKEBc4Po1GiKKJHkJDNEeKig4URLS0ICImJZAkuQAhjSi/wQyNKcGDCyMnk8u5rYrTgqDVghgZlYjcACTA1sslvtHRgQAh+QQJCAAAACwAAAAAEAAQAAAHZ4AAgoOEhYaCJSWHgxGDJCQARAtOUoQRGRiFD0kJUYWZhUhKT1OLhR8wBaaFBzQ1NwAlkIszCQkvsbOHL7Y4q4IuEjaqq0ZQD5+GEEsJTDCMmIUhtgk1lo6QFUwJVDKLiYJNUd6/hoEAIfkECQgAAAAsAAAAABAAEAAAB2iAAIKDhIWGgiUlh4MRgyQkjIURGRiGGBmNhJWHm4uen4ICCA+IkIsDCQkVACWmhwSpFqAABQoQF6ALTkWFnYMrVlhWvIKTlSAiJiVVPqlGhJkhqShHV1lCW4cMqSkAR1ofiwsjJyqGgQAh+QQJCAAAACwAAAAAEAAQAAAHZ4AAgoOEhYaCJSWHgxGDJCSMhREZGIYYGY2ElYebi56fhyWQniSKAKKfpaCLFlAPhl0gXYNGEwkhGYREUywag1wJwSkHNDU3D0kJYIMZQwk8MjPBLx9eXwuETVEyAC/BOKsuEjYFhoEAIfkECQgAAAAsAAAAABAAEAAAB2eAAIKDhIWGgiUlh4MRgyQkjIURGRiGGBmNhJWHm4ueICImip6CIQkJKJ4kigynKaqKCyMnKqSEK05StgAGQRxPYZaENqccFgIID4KXmQBhXFkzDgOnFYLNgltaSAAEpxa7BQoQF4aBACH5BAkIAAAALAAAAAAQABAAAAdogACCg4SFggJiPUqCJSWGgkZjCUwZACQkgxGEXAmdT4UYGZqCGWQ+IjKGGIUwPzGPhAc0NTewhDOdL7Ykji+dOLuOLhI2BbaFETICx4MlQitdqoUsCQ2vhKGjglNfU0SWmILaj43M5oEAOwAAAAAAAAAAAA==) no-repeat center left; }
+#full_list { padding: 0; list-style: none; margin-left: 0; margin-top: 80px; font-size: 1.1em; }
+#full_list ul { padding: 0; }
+#full_list li { padding: 0; margin: 0; list-style: none; }
+#full_list li .item { padding: 5px 5px 5px 12px; }
+#noresults { padding: 7px 12px; background: #fff; }
+#content.insearch #noresults { margin-left: 7px; }
+li.collapsed ul { display: none; }
+li a.toggle { cursor: default; position: relative; left: -5px; top: 4px; text-indent: -999px; width: 10px; height: 9px; margin-left: -10px; display: block; float: left; background: url(data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABQAAAASCAYAAABb0P4QAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAK8AAACvABQqw0mAAAABx0RVh0U29mdHdhcmUAQWRvYmUgRmlyZXdvcmtzIENTM5jWRgMAAAAVdEVYdENyZWF0aW9uIFRpbWUAMy8xNC8wOeNZPpQAAAE2SURBVDiNrZTBccIwEEXfelIAHUA6CZ24BGaWO+FuzZAK4k6gg5QAdGAq+Bxs2Yqx7BzyL7Llp/VfzZeQhCTc/ezuGzKKnKSzpCxXJM8fwNXda3df5RZETlIt6YUzSQDs93sl8w3wBZxCCE10GM1OcWbWjB2mWgEH4Mfdyxm3PSepBHibgQE2wLe7r4HjEidpnXMYdQPKEMJcsZ4zs2POYQOcaPfwMVOo58zsAdMt18BuoVDPxUJRacELbXv3hUIX2vYmOUvi8C8ydz/ThjXrqKqqLbDIAdsCKBd+Wo7GWa7o9qzOQHVVVXeAbs+yHHCH4aTsaCOQqunmUy1yBUAXkdMIfMlgF5EXLo2OpV/c/Up7jG4hhHcYLgWzAZXUc2b2ixsfvc/RmNNfOXD3Q/oeL9axJE1yT9IOoUu6MGUkAAAAAElFTkSuQmCC) no-repeat bottom left; }
+li.collapsed a.toggle { cursor: default; background-position: top left; }
+li { color: #666; cursor: pointer; }
+li.deprecated { text-decoration: line-through; font-style: italic; }
+li.odd { background: #f0f0f0; }
+li.even { background: #fafafa; }
+.item:hover { background: #ddd; }
+li small:before { content: "("; }
+li small:after { content: ")"; }
+li small.search_info { display: none; }
+a, a:visited { text-decoration: none; color: #05a; }
+li.clicked > .item { background: #05a; color: #ccc; }
+li.clicked > .item a, li.clicked > .item a:visited { color: #eee; }
+li.clicked > .item a.toggle { opacity: 0.5; background-position: bottom right; }
+li.collapsed.clicked a.toggle { background-position: top right; }
+#search input { border: 1px solid #bbb; border-radius: 3px; }
+#full_list_nav { margin-left: 10px; font-size: 0.9em; display: block; color: #aaa; }
+#full_list_nav a, #nav a:visited { color: #358; }
+#full_list_nav a:hover { background: transparent; color: #5af; }
+#full_list_nav span:after { content: ' | '; }
+#full_list_nav span:last-child:after { content: ''; }
+
+#content h1 { margin-top: 0; }
+li { white-space: nowrap; cursor: normal; }
+li small { display: block; font-size: 0.8em; }
+li small:before { content: ""; }
+li small:after { content: ""; }
+li small.search_info { display: none; }
+#search { width: 170px; position: static; margin: 3px; margin-left: 10px; font-size: 0.9em; color: #666; padding-left: 0; padding-right: 24px; }
+#content.insearch #search { background-position: center right; }
+#search input { width: 110px; }
+
+#full_list.insearch ul { display: block; }
+#full_list.insearch .item { display: none; }
+#full_list.insearch .found { display: block; padding-left: 11px !important; }
+#full_list.insearch li a.toggle { display: none; }
+#full_list.insearch li small.search_info { display: block; }
diff --git a/docs/css/style.css b/docs/css/style.css
new file mode 100644
index 00000000..f169a651
--- /dev/null
+++ b/docs/css/style.css
@@ -0,0 +1,503 @@
+html {
+  width: 100%;
+  height: 100%;
+}
+body {
+  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
+  font-size: 13px;
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  display: -webkit-flex;
+  display: -ms-flexbox;
+}
+
+#nav {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  border: 0;
+  border-right: 1px dotted #eee;
+  overflow: auto;
+}
+.nav_wrap {
+  margin: 0;
+  padding: 0;
+  width: 20%;
+  height: 100%;
+  position: relative;
+  display: flex;
+  display: -webkit-flex;
+  display: -ms-flexbox;
+  flex-shrink: 0;
+  -webkit-flex-shrink: 0;
+  -ms-flex: 1 0;
+}
+#resizer {
+  position: absolute;
+  right: -5px;
+  top: 0;
+  width: 10px;
+  height: 100%;
+  cursor: col-resize;
+  z-index: 9999;
+}
+#main {
+  flex: 5 1;
+  -webkit-flex: 5 1;
+  -ms-flex: 5 1;
+  outline: none;
+  position: relative;
+  background: #fff;
+  padding: 1.2em;
+  padding-top: 0.2em;
+  box-sizing: border-box;
+}
+
+@media (max-width: 920px) {
+  .nav_wrap { width: 100%; top: 0; right: 0; overflow: visible; position: absolute; }
+  #resizer { display: none; }
+  #nav {
+    z-index: 9999;
+    background: #fff;
+    display: none;
+    position: absolute;
+    top: 40px;
+    right: 12px;
+    width: 500px;
+    max-width: 80%;
+    height: 80%;
+    overflow-y: scroll;
+    border: 1px solid #999;
+    border-collapse: collapse;
+    box-shadow: -7px 5px 25px #aaa;
+    border-radius: 2px;
+  }
+}
+
+@media (min-width: 920px) {
+  body { height: 100%; overflow: hidden; }
+  #main { height: 100%; overflow: auto; }
+  #search { display: none; }
+}
+
+@media (max-width: 320px) {
+  body { height: 100%; overflow: hidden; overflow-wrap: break-word; }
+  #main { height: 100%; overflow: auto; }
+}
+
+#main img { max-width: 100%; }
+h1 { font-size: 25px; margin: 1em 0 0.5em; padding-top: 4px; border-top: 1px dotted #d5d5d5; }
+h1.noborder { border-top: 0px; margin-top: 0; padding-top: 4px; }
+h1.title { margin-bottom: 10px; }
+h1.alphaindex { margin-top: 0; font-size: 22px; }
+h2 {
+  padding: 0;
+  padding-bottom: 3px;
+  border-bottom: 1px #aaa solid;
+  font-size: 1.4em;
+  margin: 1.8em 0 0.5em;
+  position: relative;
+}
+h2 small { font-weight: normal; font-size: 0.7em; display: inline; position: absolute; right: 0; }
+h2 small a {
+  display: block;
+  height: 20px;
+  border: 1px solid #aaa;
+  border-bottom: 0;
+  border-top-left-radius: 5px;
+  background: #f8f8f8;
+  position: relative;
+  padding: 2px 7px;
+}
+a { font-weight: 550; }
+.clear { clear: both; }
+.inline { display: inline; }
+.inline p:first-child { display: inline; }
+.docstring, .tags, #filecontents { font-size: 15px; line-height: 1.5145em; }
+.docstring p > code, .docstring p > tt, .tags p > code, .tags p > tt {
+  color: #c7254e; background: #f9f2f4; padding: 2px 4px; font-size: 1em;
+  border-radius: 4px;
+}
+.docstring h1, .docstring h2, .docstring h3, .docstring h4 { padding: 0; border: 0; border-bottom: 1px dotted #bbb; }
+.docstring h1 { font-size: 1.2em; }
+.docstring h2 { font-size: 1.1em; }
+.docstring h3, .docstring h4 { font-size: 1em; border-bottom: 0; padding-top: 10px; }
+.summary_desc .object_link a, .docstring .object_link a {
+  font-family: monospace; font-size: 1.05em;
+  color: #05a; background: #EDF4FA; padding: 2px 4px; font-size: 1em;
+  border-radius: 4px;
+}
+.rdoc-term { padding-right: 25px; font-weight: bold; }
+.rdoc-list p { margin: 0; padding: 0; margin-bottom: 4px; }
+.summary_desc pre.code .object_link a, .docstring pre.code .object_link a {
+  padding: 0px; background: inherit; color: inherit; border-radius: inherit;
+}
+
+/* style for  */
+#filecontents table, .docstring table { border-collapse: collapse; }
+#filecontents table th, #filecontents table td,
+.docstring table th, .docstring table td { border: 1px solid #ccc; padding: 8px; padding-right: 17px; }
+#filecontents table tr:nth-child(odd),
+.docstring table tr:nth-child(odd) { background: #eee; }
+#filecontents table tr:nth-child(even),
+.docstring table tr:nth-child(even) { background: #fff; }
+#filecontents table th, .docstring table th { background: #fff; }
+
+/* style for 
       */
+#filecontents li > p, .docstring li > p { margin: 0px; }
+#filecontents ul, .docstring ul { padding-left: 20px; }
+/* style for 
       */
+#filecontents dl, .docstring dl { border: 1px solid #ccc; }
+#filecontents dt, .docstring dt { background: #ddd; font-weight: bold; padding: 3px 5px; }
+#filecontents dd, .docstring dd { padding: 5px 0px; margin-left: 18px; }
+#filecontents dd > p, .docstring dd > p { margin: 0px; }
+
+.note {
+  color: #222;
+  margin: 20px 0;
+  padding: 10px;
+  border: 1px solid #eee;
+  border-radius: 3px;
+  display: block;
+}
+.docstring .note {
+  border-left-color: #ccc;
+  border-left-width: 5px;
+}
+.note.todo { background: #ffffc5; border-color: #ececaa; }
+.note.returns_void { background: #efefef; }
+.note.deprecated { background: #ffe5e5; border-color: #e9dada; }
+.note.title.deprecated { background: #ffe5e5; border-color: #e9dada; }
+.note.private { background: #ffffc5; border-color: #ececaa; }
+.note.title { padding: 3px 6px; font-size: 0.9em; font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif; display: inline; }
+.summary_signature + .note.title { margin-left: 7px; }
+h1 .note.title { font-size: 0.5em; font-weight: normal; padding: 3px 5px; position: relative; top: -3px; text-transform: capitalize; }
+.note.title { background: #efefef; }
+.note.title.constructor { color: #fff; background: #6a98d6; border-color: #6689d6; }
+.note.title.writeonly { color: #fff; background: #45a638; border-color: #2da31d; }
+.note.title.readonly { color: #fff; background: #6a98d6; border-color: #6689d6; }
+.note.title.private { background: #d5d5d5; border-color: #c5c5c5; }
+.note.title.not_defined_here { background: transparent; border: none; font-style: italic; }
+.discussion .note { margin-top: 6px; }
+.discussion .note:first-child { margin-top: 0; }
+
+h3.inherited {
+  font-style: italic;
+  font-family: "Lucida Sans", "Lucida Grande", Verdana, Arial, sans-serif;
+  font-weight: normal;
+  padding: 0;
+  margin: 0;
+  margin-top: 12px;
+  margin-bottom: 3px;
+  font-size: 13px;
+}
+p.inherited {
+  padding: 0;
+  margin: 0;
+  margin-left: 25px;
+}
+
+.box_info dl {
+  margin: 0;
+  border: 0;
+  width: 100%;
+  font-size: 1em;
+  display: flex;
+  display: -webkit-flex;
+  display: -ms-flexbox;
+}
+.box_info dl dt {
+  flex-shrink: 0;
+  -webkit-flex-shrink: 1;
+  -ms-flex-shrink: 1;
+  width: 100px;
+  text-align: right;
+  font-weight: bold;
+  border: 1px solid #aaa;
+  border-width: 1px 0px 0px 1px;
+  padding: 6px 0;
+  padding-right: 10px;
+}
+.box_info dl dd {
+  flex-grow: 1;
+  -webkit-flex-grow: 1;
+  -ms-flex: 1;
+  max-width: 420px;
+  padding: 6px 0;
+  padding-right: 20px;
+  border: 1px solid #aaa;
+  border-width: 1px 1px 0 0;
+  overflow: hidden;
+  position: relative;
+}
+.box_info dl:last-child > * {
+  border-bottom: 1px solid #aaa;
+}
+.box_info dl:nth-child(odd) > * { background: #eee; }
+.box_info dl:nth-child(even) > * { background: #fff; }
+.box_info dl > * { margin: 0; }
+
+ul.toplevel { list-style: none; padding-left: 0; font-size: 1.1em; }
+.index_inline_list { padding-left: 0; font-size: 1.1em; }
+
+.index_inline_list li {
+  list-style: none;
+  display: inline-block;
+  padding: 0 12px;
+  line-height: 30px;
+  margin-bottom: 5px;
+}
+
+dl.constants { margin-left: 10px; }
+dl.constants dt { font-weight: bold; font-size: 1.1em; margin-bottom: 5px; }
+dl.constants.compact dt { display: inline-block; font-weight: normal }
+dl.constants dd { width: 75%; white-space: pre; font-family: monospace; margin-bottom: 18px; }
+dl.constants .docstring .note:first-child { margin-top: 5px; }
+
+.summary_desc {
+  margin-left: 32px;
+  display: block;
+  font-family: sans-serif;
+  font-size: 1.1em;
+  margin-top: 8px;
+  line-height: 1.5145em;
+  margin-bottom: 0.8em;
+}
+.summary_desc tt { font-size: 0.9em; }
+dl.constants .note { padding: 2px 6px; padding-right: 12px; margin-top: 6px; }
+dl.constants .docstring { margin-left: 32px; font-size: 0.9em; font-weight: normal; }
+dl.constants .tags { padding-left: 32px; font-size: 0.9em; line-height: 0.8em; }
+dl.constants .discussion *:first-child { margin-top: 0; }
+dl.constants .discussion *:last-child { margin-bottom: 0; }
+
+.method_details { border-top: 1px dotted #ccc; margin-top: 25px; padding-top: 0; }
+.method_details.first { border: 0; margin-top: 5px; }
+.method_details.first h3.signature { margin-top: 1em; }
+p.signature, h3.signature {
+  font-size: 1.1em; font-weight: normal; font-family: Monaco, Consolas, Courier, monospace;
+  padding: 6px 10px; margin-top: 1em;
+  background: #E8F4FF; border: 1px solid #d8d8e5; border-radius: 5px;
+}
+p.signature tt,
+h3.signature tt { font-family: Monaco, Consolas, Courier, monospace; }
+p.signature .overload,
+h3.signature .overload { display: block; }
+p.signature .extras,
+h3.signature .extras { font-weight: normal; font-family: sans-serif; color: #444; font-size: 1em; }
+p.signature .not_defined_here,
+h3.signature .not_defined_here,
+p.signature .aliases,
+h3.signature .aliases { display: block; font-weight: normal; font-size: 0.9em; font-family: sans-serif; margin-top: 0px; color: #555; }
+p.signature .aliases .names,
+h3.signature .aliases .names { font-family: Monaco, Consolas, Courier, monospace; font-weight: bold; color: #000; font-size: 1.2em; }
+
+.tags .tag_title { font-size: 1.05em; margin-bottom: 0; font-weight: bold; }
+.tags .tag_title tt { color: initial; padding: initial; background: initial; }
+.tags ul { margin-top: 5px; padding-left: 30px; list-style: square; }
+.tags ul li { margin-bottom: 3px; }
+.tags ul .name { font-family: monospace; font-weight: bold; }
+.tags ul .note { padding: 3px 6px; }
+.tags { margin-bottom: 12px; }
+
+.tags .examples .tag_title { margin-bottom: 10px; font-weight: bold; }
+.tags .examples .inline p { padding: 0; margin: 0; font-weight: bold; font-size: 1em; }
+.tags .examples .inline p:before { content: "▸"; font-size: 1em; margin-right: 5px; }
+
+.tags .overload .overload_item { list-style: none; margin-bottom: 25px; }
+.tags .overload .overload_item .signature {
+  padding: 2px 8px;
+  background: #F1F8FF; border: 1px solid #d8d8e5; border-radius: 3px;
+}
+.tags .overload .signature { margin-left: -15px; font-family: monospace; display: block; font-size: 1.1em; }
+.tags .overload .docstring { margin-top: 15px; }
+
+.defines { display: none; }
+
+#method_missing_details .notice.this { position: relative; top: -8px; color: #888; padding: 0; margin: 0; }
+
+.showSource { font-size: 0.9em; }
+.showSource a, .showSource a:visited { text-decoration: none; color: #666; }
+
+#content a, #content a:visited { text-decoration: none; color: #05a; }
+#content a:hover { background: #ffffa5; }
+
+ul.summary {
+  list-style: none;
+  font-family: monospace;
+  font-size: 1em;
+  line-height: 1.5em;
+  padding-left: 0px;
+}
+ul.summary a, ul.summary a:visited {
+  text-decoration: none; font-size: 1.1em;
+}
+ul.summary li { margin-bottom: 5px; }
+.summary_signature { padding: 4px 8px; background: #f8f8f8; border: 1px solid #f0f0f0; border-radius: 5px; }
+.summary_signature:hover { background: #CFEBFF; border-color: #A4CCDA; cursor: pointer; }
+.summary_signature.deprecated { background: #ffe5e5; border-color: #e9dada; }
+ul.summary.compact li { display: inline-block; margin: 0px 5px 0px 0px; line-height: 2.6em;}
+ul.summary.compact .summary_signature { padding: 5px 7px; padding-right: 4px; }
+#content .summary_signature:hover a,
+#content .summary_signature:hover a:visited {
+  background: transparent;
+  color: #049;
+}
+
+p.inherited a { font-family: monospace; font-size: 0.9em; }
+p.inherited { word-spacing: 5px; font-size: 1.2em; }
+
+p.children { font-size: 1.2em; }
+p.children a { font-size: 0.9em; }
+p.children strong { font-size: 0.8em; }
+p.children strong.modules { padding-left: 5px; }
+
+ul.fullTree { display: none; padding-left: 0; list-style: none; margin-left: 0; margin-bottom: 10px; }
+ul.fullTree ul { margin-left: 0; padding-left: 0; list-style: none; }
+ul.fullTree li { text-align: center; padding-top: 18px; padding-bottom: 12px; background: url(data:image/gif;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAACXBIWXMAAAsTAAALEwEAmpwYAAAKT2lDQ1BQaG90b3Nob3AgSUNDIHByb2ZpbGUAAHjanVNnVFPpFj333vRCS4iAlEtvUhUIIFJCi4AUkSYqIQkQSoghodkVUcERRUUEG8igiAOOjoCMFVEsDIoK2AfkIaKOg6OIisr74Xuja9a89+bN/rXXPues852zzwfACAyWSDNRNYAMqUIeEeCDx8TG4eQuQIEKJHAAEAizZCFz/SMBAPh+PDwrIsAHvgABeNMLCADATZvAMByH/w/qQplcAYCEAcB0kThLCIAUAEB6jkKmAEBGAYCdmCZTAKAEAGDLY2LjAFAtAGAnf+bTAICd+Jl7AQBblCEVAaCRACATZYhEAGg7AKzPVopFAFgwABRmS8Q5ANgtADBJV2ZIALC3AMDOEAuyAAgMADBRiIUpAAR7AGDIIyN4AISZABRG8lc88SuuEOcqAAB4mbI8uSQ5RYFbCC1xB1dXLh4ozkkXKxQ2YQJhmkAuwnmZGTKBNA/g88wAAKCRFRHgg/P9eM4Ors7ONo62Dl8t6r8G/yJiYuP+5c+rcEAAAOF0ftH+LC+zGoA7BoBt/qIl7gRoXgugdfeLZrIPQLUAoOnaV/Nw+H48PEWhkLnZ2eXk5NhKxEJbYcpXff5nwl/AV/1s+X48/Pf14L7iJIEyXYFHBPjgwsz0TKUcz5IJhGLc5o9H/LcL//wd0yLESWK5WCoU41EScY5EmozzMqUiiUKSKcUl0v9k4t8s+wM+3zUAsGo+AXuRLahdYwP2SycQWHTA4vcAAPK7b8HUKAgDgGiD4c93/+8//UegJQCAZkmScQAAXkQkLlTKsz/HCAAARKCBKrBBG/TBGCzABhzBBdzBC/xgNoRCJMTCQhBCCmSAHHJgKayCQiiGzbAdKmAv1EAdNMBRaIaTcA4uwlW4Dj1wD/phCJ7BKLyBCQRByAgTYSHaiAFiilgjjggXmYX4IcFIBBKLJCDJiBRRIkuRNUgxUopUIFVIHfI9cgI5h1xGupE7yAAygvyGvEcxlIGyUT3UDLVDuag3GoRGogvQZHQxmo8WoJvQcrQaPYw2oefQq2gP2o8+Q8cwwOgYBzPEbDAuxsNCsTgsCZNjy7EirAyrxhqwVqwDu4n1Y8+xdwQSgUXACTYEd0IgYR5BSFhMWE7YSKggHCQ0EdoJNwkDhFHCJyKTqEu0JroR+cQYYjIxh1hILCPWEo8TLxB7iEPENyQSiUMyJ7mQAkmxpFTSEtJG0m5SI+ksqZs0SBojk8naZGuyBzmULCAryIXkneTD5DPkG+Qh8lsKnWJAcaT4U+IoUspqShnlEOU05QZlmDJBVaOaUt2ooVQRNY9aQq2htlKvUYeoEzR1mjnNgxZJS6WtopXTGmgXaPdpr+h0uhHdlR5Ol9BX0svpR+iX6AP0dwwNhhWDx4hnKBmbGAcYZxl3GK+YTKYZ04sZx1QwNzHrmOeZD5lvVVgqtip8FZHKCpVKlSaVGyovVKmqpqreqgtV81XLVI+pXlN9rkZVM1PjqQnUlqtVqp1Q61MbU2epO6iHqmeob1Q/pH5Z/YkGWcNMw09DpFGgsV/jvMYgC2MZs3gsIWsNq4Z1gTXEJrHN2Xx2KruY/R27iz2qqaE5QzNKM1ezUvOUZj8H45hx+Jx0TgnnKKeX836K3hTvKeIpG6Y0TLkxZVxrqpaXllirSKtRq0frvTau7aedpr1Fu1n7gQ5Bx0onXCdHZ4/OBZ3nU9lT3acKpxZNPTr1ri6qa6UbobtEd79up+6Ynr5egJ5Mb6feeb3n+hx9L/1U/W36p/VHDFgGswwkBtsMzhg8xTVxbzwdL8fb8VFDXcNAQ6VhlWGX4YSRudE8o9VGjUYPjGnGXOMk423GbcajJgYmISZLTepN7ppSTbmmKaY7TDtMx83MzaLN1pk1mz0x1zLnm+eb15vft2BaeFostqi2uGVJsuRaplnutrxuhVo5WaVYVVpds0atna0l1rutu6cRp7lOk06rntZnw7Dxtsm2qbcZsOXYBtuutm22fWFnYhdnt8Wuw+6TvZN9un2N/T0HDYfZDqsdWh1+c7RyFDpWOt6azpzuP33F9JbpL2dYzxDP2DPjthPLKcRpnVOb00dnF2e5c4PziIuJS4LLLpc+Lpsbxt3IveRKdPVxXeF60vWdm7Obwu2o26/uNu5p7ofcn8w0nymeWTNz0MPIQ+BR5dE/C5+VMGvfrH5PQ0+BZ7XnIy9jL5FXrdewt6V3qvdh7xc+9j5yn+M+4zw33jLeWV/MN8C3yLfLT8Nvnl+F30N/I/9k/3r/0QCngCUBZwOJgUGBWwL7+Hp8Ib+OPzrbZfay2e1BjKC5QRVBj4KtguXBrSFoyOyQrSH355jOkc5pDoVQfujW0Adh5mGLw34MJ4WHhVeGP45wiFga0TGXNXfR3ENz30T6RJZE3ptnMU85ry1KNSo+qi5qPNo3ujS6P8YuZlnM1VidWElsSxw5LiquNm5svt/87fOH4p3iC+N7F5gvyF1weaHOwvSFpxapLhIsOpZATIhOOJTwQRAqqBaMJfITdyWOCnnCHcJnIi/RNtGI2ENcKh5O8kgqTXqS7JG8NXkkxTOlLOW5hCepkLxMDUzdmzqeFpp2IG0yPTq9MYOSkZBxQqohTZO2Z+pn5mZ2y6xlhbL+xW6Lty8elQfJa7OQrAVZLQq2QqboVFoo1yoHsmdlV2a/zYnKOZarnivN7cyzytuQN5zvn//tEsIS4ZK2pYZLVy0dWOa9rGo5sjxxedsK4xUFK4ZWBqw8uIq2Km3VT6vtV5eufr0mek1rgV7ByoLBtQFr6wtVCuWFfevc1+1dT1gvWd+1YfqGnRs+FYmKrhTbF5cVf9go3HjlG4dvyr+Z3JS0qavEuWTPZtJm6ebeLZ5bDpaql+aXDm4N2dq0Dd9WtO319kXbL5fNKNu7g7ZDuaO/PLi8ZafJzs07P1SkVPRU+lQ27tLdtWHX+G7R7ht7vPY07NXbW7z3/T7JvttVAVVN1WbVZftJ+7P3P66Jqun4lvttXa1ObXHtxwPSA/0HIw6217nU1R3SPVRSj9Yr60cOxx++/p3vdy0NNg1VjZzG4iNwRHnk6fcJ3/ceDTradox7rOEH0x92HWcdL2pCmvKaRptTmvtbYlu6T8w+0dbq3nr8R9sfD5w0PFl5SvNUyWna6YLTk2fyz4ydlZ19fi753GDborZ752PO32oPb++6EHTh0kX/i+c7vDvOXPK4dPKy2+UTV7hXmq86X23qdOo8/pPTT8e7nLuarrlca7nuer21e2b36RueN87d9L158Rb/1tWeOT3dvfN6b/fF9/XfFt1+cif9zsu72Xcn7q28T7xf9EDtQdlD3YfVP1v+3Njv3H9qwHeg89HcR/cGhYPP/pH1jw9DBY+Zj8uGDYbrnjg+OTniP3L96fynQ89kzyaeF/6i/suuFxYvfvjV69fO0ZjRoZfyl5O/bXyl/erA6xmv28bCxh6+yXgzMV70VvvtwXfcdx3vo98PT+R8IH8o/2j5sfVT0Kf7kxmTk/8EA5jz/GMzLdsAAAAgY0hSTQAAeiUAAICDAAD5/wAAgOkAAHUwAADqYAAAOpgAABdvkl/FRgAAAHtJREFUeNqMzrEJAkEURdGzuhgZbSoYWcAWoBVsB4JgZAGmphsZCZYzTQgWNCYrDN9RvMmHx+X916SUBFbo8CzD1idXrLErw1mQttgXtyrOcQ/Ny5p4Qh+2XqLYYazsPWNTiuMkRxa4vcV+evuNAUOLIx5+c2hyzv7hNQC67Q+/HHmlEwAAAABJRU5ErkJggg==) no-repeat top center; }
+ul.fullTree li:first-child { padding-top: 0; background: transparent; }
+ul.fullTree li:last-child { padding-bottom: 0; }
+.showAll ul.fullTree { display: block; }
+.showAll .inheritName { display: none; }
+
+#search { position: absolute; right: 12px; top: 0px; z-index: 9000; }
+#search a {
+  display: block; float: left;
+  padding: 4px 8px; text-decoration: none; color: #05a; fill: #05a;
+  border: 1px solid #d8d8e5;
+  border-bottom-left-radius: 3px; border-bottom-right-radius: 3px;
+  background: #F1F8FF;
+  box-shadow: -1px 1px 3px #ddd;
+}
+#search a:hover { background: #f5faff; color: #06b; fill: #06b; }
+#search a.active {
+  background: #568; padding-bottom: 20px; color: #fff; fill: #fff;
+  border: 1px solid #457;
+  border-top-left-radius: 5px; border-top-right-radius: 5px;
+}
+#search a.inactive { color: #999; fill: #999; }
+.inheritanceTree, .toggleDefines {
+  float: right;
+  border-left: 1px solid #aaa;
+  position: absolute; top: 0; right: 0;
+  height: 100%;
+  background: #f6f6f6;
+  padding: 5px;
+  min-width: 55px;
+  text-align: center;
+}
+
+#menu { font-size: 1.3em; color: #bbb; }
+#menu .title, #menu a { font-size: 0.7em; }
+#menu .title a { font-size: 1em; }
+#menu .title { color: #555; }
+#menu a, #menu a:visited { color: #333; text-decoration: none; border-bottom: 1px dotted #bbd; }
+#menu a:hover { color: #05a; }
+
+#footer { margin-top: 15px; border-top: 1px solid #ccc; text-align: center; padding: 7px 0; color: #999; }
+#footer a, #footer a:visited { color: #444; text-decoration: none; border-bottom: 1px dotted #bbd; }
+#footer a:hover { color: #05a; }
+
+#listing ul.alpha { font-size: 1.1em; }
+#listing ul.alpha { margin: 0; padding: 0; padding-bottom: 10px; list-style: none; }
+#listing ul.alpha li.letter { font-size: 1.4em; padding-bottom: 10px; }
+#listing ul.alpha ul { margin: 0; padding-left: 15px; }
+#listing ul small { color: #666; font-size: 0.7em; }
+
+li.r1 { background: #f0f0f0; }
+li.r2 { background: #fafafa; }
+
+#content ul.summary li.deprecated .summary_signature a,
+#content ul.summary li.deprecated .summary_signature a:visited { text-decoration: line-through; font-style: italic; }
+
+#toc {
+  position: relative;
+  float: right;
+  overflow-x: auto;
+  right: -3px;
+  margin-left: 20px;
+  margin-bottom: 20px;
+  padding: 20px; padding-right: 30px;
+  max-width: 300px;
+  z-index: 5000;
+  background: #fefefe;
+  border: 1px solid #ddd;
+  box-shadow: -2px 2px 6px #bbb;
+}
+#toc .title { margin: 0; }
+#toc ol { padding-left: 1.8em; }
+#toc li { font-size: 1.1em; line-height: 1.7em; }
+#toc > ol > li { font-size: 1.1em; font-weight: bold; }
+#toc ol > li > ol { font-size: 0.9em; }
+#toc ol ol > li > ol { padding-left: 2.3em; }
+#toc ol + li { margin-top: 0.3em; }
+#toc.hidden { padding: 10px; background: #fefefe; box-shadow: none; }
+#toc.hidden:hover { background: #fafafa; }
+#filecontents h1 + #toc.nofloat { margin-top: 0; }
+@media (max-width: 560px) {
+  #toc {
+    margin-left: 0;
+    margin-top: 16px;
+    float: none;
+    max-width: none;
+  }
+}
+
+/* syntax highlighting */
+.source_code { display: none; padding: 3px 8px; border-left: 8px solid #ddd; margin-top: 5px; }
+#filecontents pre.code, .docstring pre.code, .source_code pre { font-family: monospace; }
+#filecontents pre.code, .docstring pre.code { display: block; }
+.source_code .lines { padding-right: 12px; color: #555; text-align: right; }
+#filecontents pre.code, .docstring pre.code,
+.tags pre.example {
+  padding: 9px 14px;
+  margin-top: 4px;
+  border: 1px solid #e1e1e8;
+  background: #f7f7f9;
+  border-radius: 4px;
+  font-size: 1em;
+  overflow-x: auto;
+  line-height: 1.2em;
+}
+pre.code { color: #000; tab-size: 2; }
+pre.code .info.file { color: #555; }
+pre.code .val { color: #036A07; }
+pre.code .tstring_content,
+pre.code .heredoc_beg, pre.code .heredoc_end,
+pre.code .qwords_beg, pre.code .qwords_end, pre.code .qwords_sep,
+pre.code .words_beg, pre.code .words_end, pre.code .words_sep,
+pre.code .qsymbols_beg, pre.code .qsymbols_end, pre.code .qsymbols_sep,
+pre.code .symbols_beg, pre.code .symbols_end, pre.code .symbols_sep,
+pre.code .tstring, pre.code .dstring { color: #036A07; }
+pre.code .fid, pre.code .rubyid_new, pre.code .rubyid_to_s,
+pre.code .rubyid_to_sym, pre.code .rubyid_to_f,
+pre.code .dot + pre.code .id,
+pre.code .rubyid_to_i pre.code .rubyid_each { color: #0085FF; }
+pre.code .comment { color: #0066FF; }
+pre.code .const, pre.code .constant { color: #585CF6; }
+pre.code .label,
+pre.code .symbol { color: #C5060B; }
+pre.code .kw,
+pre.code .rubyid_require,
+pre.code .rubyid_extend,
+pre.code .rubyid_include { color: #0000FF; }
+pre.code .ivar { color: #318495; }
+pre.code .gvar,
+pre.code .rubyid_backref,
+pre.code .rubyid_nth_ref { color: #6D79DE; }
+pre.code .regexp, .dregexp { color: #036A07; }
+pre.code a { border-bottom: 1px dotted #bbf; }
+/* inline code */
+*:not(pre) > code {
+	padding: 1px 3px 1px 3px;
+	border: 1px solid #E1E1E8;
+	background: #F7F7F9;
+	border-radius: 4px;
+}
+
+/* Color fix for links */
+#content .summary_desc pre.code .id > .object_link a, /* identifier */
+#content .docstring pre.code .id > .object_link a { color: #0085FF; }
+#content .summary_desc pre.code .const > .object_link a, /* constant */
+#content .docstring pre.code .const > .object_link a { color: #585CF6; }
diff --git a/docs/file.CHANGELOG.html b/docs/file.CHANGELOG.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.CITATION.html b/docs/file.CITATION.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.CODE_OF_CONDUCT.html b/docs/file.CODE_OF_CONDUCT.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.CONTRIBUTING.html b/docs/file.CONTRIBUTING.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.FUNDING.html b/docs/file.FUNDING.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.IRP.html b/docs/file.IRP.html
new file mode 100644
index 00000000..34f4624b
--- /dev/null
+++ b/docs/file.IRP.html
@@ -0,0 +1,221 @@
+
+
+  
+    
+
+
+  File: IRP
+  
+    — Documentation by YARD 0.9.37
+  
+
+
+  
+
+  
+
+
+
+
+  
+
+  
+
+
+  
+  
+    
      
+      
+      
      
+    
      
+
+    
      
+      
+
+      
      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. 
+  
      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. 
+  
      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. 
+  
      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. 
+  
      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. 
+  
      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.
          • 
+    
        
+  
        7. 
+
      
+
+
      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. 
+  
      2. Reproduce the issue locally and add a regression spec in spec/.
        3. 
+  
      3. Implement the fix and run the test suite: bundle exec rspec (or the project’s preferred test command).
        4. 
+  
      4. Bump version in lib/oauth2/version.rb following semantic versioning.
        5. 
+  
      5. Update CHANGELOG.md with an entry describing the fix (avoid exploit details).
        6. 
+  
      6. Commit and push the branch, open a PR, and merge after approvals.
        7. 
+  
      7. Build and push the gem: gem build oauth2.gemspec && gem push pkg/... (coordinate with Tidelift before public push if disclosure is coordinated).
        8. 
+  
      8. Publish a release on GitHub and ensure the Tidelift advisory is posted.
        9. 
+
      
+
+
      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
        • 
+
      
+
      
+
+      
+
+    
      
+  
+
\ No newline at end of file
diff --git a/docs/file.LICENSE.html b/docs/file.LICENSE.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.OIDC.html b/docs/file.OIDC.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.README.html b/docs/file.README.html
new file mode 100644
index 00000000..b8856d16
--- /dev/null
+++ b/docs/file.README.html
@@ -0,0 +1,1646 @@
+
+
+  
+    
+
+
+  File: README
+  
+    — Documentation by YARD 0.9.37
+  
+
+
+  
+
+  
+
+
+
+
+  
+
+  
+
+
+  
+  
+    
      
+      
+      
      
+    
      
+
+    
      
+      
+
+      
    
+  
+    
+      
+    
+  
+  
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+  
+
    📍 NOTE
    RubyGems (the GitHub org, not the website) suffered a hostile takeover in September 2025.
    Ultimately 4 maintainers were hard removed and a reason has been given for only 1 of those, while 2 others resigned in protest.
    It is a complicated story which is difficult to parse quickly.
    I’m adding notes like this to gems because I don’t condone theft of repositories or gems from their rightful owners.
    If a similar theft happened with my repos/gems, I’d hope some would stand up for me.
    Disenfranchised former-maintainers have started gem.coop.
    Once available I will publish there exclusively; unless RubyCentral makes amends with the community.
    The “Technology for Humans: Joel Draper” podcast episode by reinteractive is the most cogent summary I’m aware of.
    See here, here and here for more info on what comes next.
    What I’m doing: A (WIP) proposal for bundler/gem scopes, and a (WIP) proposal for a federated gem server.
    
+
+
    Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0 ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5 oauth2 Logo by Chris Messina, CC BY-SA 3.0
    
+
+
    🔐 OAuth 2.0 Authorization Framework
    
+
+
    ⭐️ including OAuth 2.1 draft spec & OpenID Connect (OIDC)
    
+
+
    Version GitHub tag (latest SemVer) License: MIT Downloads Rank Open Source Helpers CodeCov Test Coverage Coveralls Test Coverage QLTY Test Coverage QLTY Maintainability CI Heads CI Runtime Dependencies @ HEAD CI Current CI JRuby Deps Locked Deps Unlocked CI Supported CI Legacy CI Unsupported CI Ancient CI Test Coverage CI Style CodeQL Apache SkyWalking Eyes License Compatibility Check
    
+
+
    if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know, as I may have missed the discord notification.
    
+
+
    
+
+
    if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.
    
+
+
    OpenCollective Backers OpenCollective Sponsors Sponsor Me on Github Liberapay Goal Progress Donate on PayPal Buy me a coffee Donate on Polar Donate at ko-fi.com
    
+
+
    🌻 Synopsis
    
+
+
    OAuth 2.0 is the industry-standard protocol for authorization.
    
+OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications,
    
+    desktop applications, mobile phones, and living room devices.
    
+This is a RubyGem for implementing OAuth 2.0 clients (not servers) in Ruby applications.
    
+
+
    Quick Examples
    
+
+
    
+  Convert the following `curl` command into a token request using this gem...
+
+  
    curl --request POST \
+  --url 'https://login.microsoftonline.com/REDMOND_REDACTED/oauth2/token' \
+  --header 'content-type: application/x-www-form-urlencoded' \
+  --data grant_type=client_credentials \
+  --data client_id=REDMOND_CLIENT_ID \
+  --data client_secret=REDMOND_CLIENT_SECRET \
+  --data resource=REDMOND_RESOURCE_UUID
+
    
+
+  
    NOTE: In the ruby version below, certain params are passed to the get_token call, instead of the client creation.
    
+
+  
    OAuth2::Client.new(
+  "REDMOND_CLIENT_ID", # client_id
+  "REDMOND_CLIENT_SECRET", # client_secret
+  auth_scheme: :request_body, # Other modes are supported: :basic_auth, :tls_client_auth, :private_key_jwt
+  token_url: "oauth2/token", # relative path, except with leading `/`, then absolute path
+  site: "https://login.microsoftonline.com/REDMOND_REDACTED",
+). # The base path for token_url when it is relative
+  client_credentials. # There are many other types to choose from!
+  get_token(resource: "REDMOND_RESOURCE_UUID")
+
    
+
+  
    NOTE: header - The content type specified in the curl is already the default!
    
+
+
    
+
+
    
+  Complete E2E single file script against mock-oauth2-server
+
+  
      
+    
    • E2E example uses navikt/mock-oauth2-server, which was added in v2.0.11
      • 
+    
    • E2E example does not ship with the released gem, so clone the source to play with it.
      • 
+  
    
+
+  
    docker compose -f docker-compose-ssl.yml up -d --wait
+ruby examples/e2e.rb
+# If your machine is slow or Docker pulls are cold, increase the wait:
+E2E_WAIT_TIMEOUT=120 ruby examples/e2e.rb
+# The mock server serves HTTP on 8080; the example points to http://localhost:8080 by default.
+
    
+
+  
    The output should be something like this:
    
+
+  
    ➜  ruby examples/e2e.rb
+Access token (truncated): eyJraWQiOiJkZWZhdWx0...
+userinfo status: 200
+userinfo body: {"sub" => "demo-sub", "aud" => ["demo-aud"], "nbf" => 1757816758000, "iss" => "http://localhost:8080/default", "exp" => 1757820358000, "iat" => 1757816758000, "jti" => "d63b97a7-ebe5-4dea-93e6-d542caba6104"}
+E2E complete
+
    
+
+  
    Make sure to shut down the mock server when you are done:
    
+
+  
    docker compose -f docker-compose-ssl.yml down
+
    
+
+  
    Troubleshooting: validate connectivity to the mock server
    
+
+  
      
+    
    • Check container status and port mapping:
+      
        
+        
      • docker compose -f docker-compose-ssl.yml ps
        • 
+      
      
+    
      • 
+    
    • From the host, try the discovery URL directly (this is what the example uses by default):
+      
        
+        
      • curl -v http://localhost:8080/default/.well-known/openid-configuration
        • 
+        
      • If that fails immediately, also try: curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration
+
        • 
+      
      
+    
      • 
+    
    • From inside the container (to distinguish container vs. host networking):
+      
        
+        
      • docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration
        • 
+      
      
+    
      • 
+    
    • Simple TCP probe from the host:
+      
        
+        
      • nc -vz localhost 8080  # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"'
        • 
+      
      
+    
      • 
+    
    • Inspect which host port 8080 is bound to (should be 8080):
+      
        
+        
      • docker inspect -f '{{ (index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }}' oauth2-mock-oauth2-server-1
        • 
+      
      
+    
      • 
+    
    • Look at server logs for readiness/errors:
+      
        
+        
      • docker logs -n 200 oauth2-mock-oauth2-server-1
        • 
+      
      
+    
      • 
+    
    • On Linux, ensure nothing else is bound to 8080 and that firewall/SELinux aren’t blocking:
+      
        
+        
      • ss -ltnp | grep :8080
        • 
+      
      
+    
      • 
+  
    
+
+  
    Notes
    
+
+  
      
+    
    • Discovery URL pattern is: http://localhost:8080/<realm>/.well-known/openid-configuration, where <realm> defaults to default.
      • 
+    
    • You can change these with env vars when running the example:
+      
        
+        
      • 
+E2E_ISSUER_BASE (default: http://localhost:8080)
        • 
+        
      • 
+E2E_REALM (default: default)
        • 
+      
      
+    
      • 
+  
    
+
+
    
+
+
    If it seems like you are in the wrong place, you might try one of these:
    
+
+
+
+
    💡 Info you can shake a stick at
    
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
    Tokens to Remember
+Gem name Gem namespace
+
    Works with JRuby
+JRuby 9.1 Compat JRuby 9.2 Compat JRuby 9.3 Compat 
     JRuby 9.4 Compat JRuby 10.0 Compat JRuby HEAD Compat
+
    Works with Truffle Ruby
+Truffle Ruby 22.3 Compat Truffle Ruby 23.0 Compat Truffle Ruby 23.1 Compat 
     Truffle Ruby 24.1 Compat
+
    Works with MRI Ruby 3
+Ruby 3.0 Compat Ruby 3.1 Compat Ruby 3.2 Compat Ruby 3.3 Compat Ruby 3.4 Compat Ruby HEAD Compat
+
    Works with MRI Ruby 2
+Ruby 2.2 Compat 
     Ruby 2.3 Compat Ruby 2.4 Compat Ruby 2.5 Compat Ruby 2.6 Compat Ruby 2.7 Compat
+
    Support & Community
+Join Me on Daily.dev's RubyFriends Live Chat on Discord Get help from me on Upwork Get help from me on Codementor
+
    Source
+Source on GitLab.com Source on CodeBerg.org Source on Github.com The best SHA: dQw4w9WgXcQ!
+
    Documentation
+Current release on RubyDoc.info YARD on Galtzo.com Maintainer Blog GitLab Wiki GitHub Wiki
+
    Compliance
+License: MIT Compatible with Apache Software Projects: Verified by SkyWalking Eyes 📄ilo-declaration-img Security Policy Contributor Covenant 2.1 SemVer 2.0.0
+
    Style
+Enforced Code Style Linter Keep-A-Changelog 1.0.0 Gitmoji Commits Compatibility appraised by: appraisal2
+
    Maintainer 🎖️
+Follow Me on LinkedIn Follow Me on Ruby.Social Follow Me on Bluesky Contact Maintainer My technical writing
+
    
+... 💖
+Find Me on WellFound: Find Me on CrunchBase My LinkTree More About Me 🧊 🐙  🛖 🧪
+
    
+
+
    Compatibility
    
+
+
    Compatible with MRI Ruby 2.2.0+, and concordant releases of JRuby, and TruffleRuby.
    
+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+  
+
    🚚 Amazing test matrix was brought to you by🔎 appraisal2 🔎 and the color 💚 green 💚
    👟 Check it out!✨ github.com/appraisal-rb/appraisal2 ✨
    
+
+
    Federated DVCS
    
+
+
    
+  Find this repo on federated forges (Coming soon!)
+
+  
+    
+      
+        
+        
+        
+        
+        
+        
+        
+      
+    
+    
+      
+        
+        
+        
+        
+        
+        
+        
+      
+      
+        
+        
+        
+        
+        
+        
+        
+      
+      
+        
+        
+        
+        
+        
+        
+        
+      
+      
+        
+        
+        
+        
+        
+        
+        
+      
+    
+  
    Federated DVCS RepositoryStatusIssuesPRsWikiCIDiscussions
    🧪 ruby-oauth/oauth2 on GitLab
+The Truth💚💚💚🐭 Tiny Matrix➖
    🧊 ruby-oauth/oauth2 on CodeBerg
+An Ethical Mirror (Donate)💚💚➖⭕️ No Matrix➖
    🐙 ruby-oauth/oauth2 on GitHub
+Another Mirror💚💚💚💯 Full Matrix💚
    🎮️ Discord Server
+Live Chat on DiscordLet’stalkaboutthislibrary!
    
+
+
    
+
+
    Enterprise Support Tidelift
+
    
+
+
    Available as part of the Tidelift Subscription.
    
+
+
    
+  Need enterprise-level guarantees?
+
+  
    The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.
    
+
+  
    Get help from me on Tidelift
    
+
+  
      
+    
    • 💡Subscribe for support guarantees covering all your FLOSS dependencies
      • 
+    
    • 💡Tidelift is part of Sonar
+
      • 
+    
    • 💡Tidelift pays maintainers to maintain the software you depend on!
      📊@Pointy Haired Boss: An enterprise support subscription is “never gonna let you down”, and supports open source maintainers
      • 
+  
    
+
+  
    Alternatively:
    
+
+  
      
+    
    • Live Chat on Discord
      • 
+    
    • Get help from me on Upwork
      • 
+    
    • Get help from me on Codementor
      • 
+  
    
+
+
    
+
+
    ✨ Installation
    
+
+
    Install the gem and add to the application’s Gemfile by executing:
    
+
+
    bundle add oauth2
+
    
+
+
    If bundler is not being used to manage dependencies, install the gem by executing:
    
+
+
    gem install oauth2
+
    
+
+
    🔒 Secure Installation
    
+
+
    
+  For Medium or High Security Installations
+
+  
    This gem is cryptographically signed, and has verifiable SHA-256 and SHA-512 checksums by
+stone_checksums. Be sure the gem you install hasn’t been tampered with
+by following the instructions below.
    
+
+  
    Add my public key (if you haven’t already, expires 2045-04-29) as a trusted certificate:
    
+
+  
    gem cert --add <(curl -Ls https://raw.github.com/galtzo-floss/certs/main/pboling.pem)
+
    
+
+  
    You only need to do that once.  Then proceed to install with:
    
+
+  
    gem install oauth2 -P MediumSecurity
+
    
+
+  
    The MediumSecurity trust profile will verify signed gems, but allow the installation of unsigned dependencies.
    
+
+  
    This is necessary because not all of oauth2’s dependencies are signed, so we cannot use HighSecurity.
    
+
+  
    If you want to up your security game full-time:
    
+
+  
    bundle config set --global trust-policy MediumSecurity
+
    
+
+  
    MediumSecurity instead of HighSecurity is necessary if not all the gems you use are signed.
    
+
+  
    NOTE: Be prepared to track down certs for signed gems and add them the same way you added mine.
    
+
+
    
+
+
    What is new for v2.0?
    
+
+
      
+  
    • Works with Ruby versions >= 2.2
      • 
+  
    • Drop support for the expired MAC Draft (all versions)
      • 
+  
    • Support IETF rfc7515 JSON Web Signature - JWS (since v2.0.12)
+    
        
+      
      • Support JWT kid for key discovery and management
        • 
+    
      
+  
      • 
+  
    • Support IETF rfc7523 JWT Bearer Tokens (since v2.0.0)
      • 
+  
    • Support IETF rfc7231 Relative Location in Redirect (since v2.0.0)
      • 
+  
    • Support IETF rfc6749 Don’t set oauth params when nil (since v2.0.0)
      • 
+  
    • Support IETF rfc7009 Token Revocation (since v2.0.10, updated in v2.0.13 to support revocation via URL-encoded parameters)
      • 
+  
    • Support OIDC 1.0 Private Key JWT; based on the OAuth JWT assertion specification (RFC 7523)
+
      • 
+  
    • Support new formats, including from jsonapi.org: application/vdn.api+json, application/vnd.collection+json, application/hal+json, application/problem+json
+
      • 
+  
    • Adds option to OAuth2::Client#get_token:
+    
        
+      
      • 
+:access_token_class (AccessToken); user specified class to use for all calls to get_token
+
        • 
+    
      
+  
      • 
+  
    • Adds option to OAuth2::AccessToken#initialize:
+    
        
+      
      • 
+:expires_latency (nil); number of seconds by which AccessToken validity will be reduced to offset latency
        • 
+    
      
+  
      • 
+  
    • By default, keys are transformed to snake case.
+    
        
+      
      • Original keys will still work as previously, in most scenarios, thanks to snaky_hash gem.
        • 
+      
      • However, this is a breaking change if you rely on response.parsed.to_h to retain the original case, and the original wasn’t snake case, as the keys in the result will be snake case.
        • 
+      
      • As of version 2.0.4 you can turn key transformation off with the snaky: false option.
        • 
+    
      
+  
      • 
+  
    • By default, the :auth_scheme is now :basic_auth (instead of :request_body)
+    
        
+      
      • Third-party strategies and gems may need to be updated if a provider was requiring client id/secret in the request body
        • 
+    
      
+  
      • 
+  
    • … A lot more
      • 
+
    
+
+
    Compatibility
    
+
+
    Targeted ruby compatibility is non-EOL versions of Ruby, currently 3.2, 3.3, and 3.4.
    
+Compatibility is further distinguished as “Best Effort Support” or “Incidental Support” for older versions of Ruby.
    
+This gem will install on Ruby versions >= v2.2 for 2.x releases.
    
+See 1-4-stable branch for older rubies.
    
+
+
    
+  Ruby Engine Compatibility Policy
+
+  
    This gem is tested against MRI, JRuby, and Truffleruby.
+Each of those has varying versions that target a specific version of MRI Ruby.
+This gem should work in the just-listed Ruby engines according to the targeted MRI compatibility in the table below.
+If you would like to add support for additional engines,
+see gemfiles/README.md, then submit a PR to the correct maintenance branch as according to the table below.
    
+
+
    
+
+
    
+  Ruby Version Compatibility Policy
+
+  
    If something doesn’t work on one of these interpreters, it’s a bug.
    
+
+  
    This library may inadvertently work (or seem to work) on other Ruby
+implementations; however, support will only be provided for the versions listed
+above.
    
+
+  
    If you would like this library to support another Ruby version, you may
+volunteer to be a maintainer. Being a maintainer entails making sure all tests
+run and pass on that implementation. When something breaks on your
+implementation, you will be responsible for providing patches in a timely
+fashion. If critical issues for a particular implementation exist at the time
+of a major release, support for that Ruby version may be dropped.
    
+
+
    
+
+
+  
+    
+      
+      
+      
+      
+      
+      
+    
+  
+  
+    
+      
+      
+      
+      
+      
+      
+    
+    
+      
+      
+      
+      
+      
+      
+    
+    
+      
+      
+      
+      
+      
+      
+    
+  
+
     Ruby OAuth2 VersionMaintenance BranchTargeted SupportBest Effort SupportIncidental Support
    1️⃣2.0.xmain3.2, 3.3, 3.42.5, 2.6, 2.7, 3.0, 3.12.2, 2.3, 2.4
    2️⃣1.4.x1-4-stable3.2, 3.3, 3.42.5, 2.6, 2.7, 3.0, 3.11.9, 2.0, 2.1, 2.2, 2.3, 2.4
    3️⃣olderN/ABest of luck to you!Please upgrade! 
    
+
+
    NOTE: The 1.4 series will only receive critical security updates.
    
+See SECURITY.md and IRP.md.
    
+
+
    ⚙️ Configuration
    
+
+
    You can turn on additional warnings.
    
+
+
    OAuth2.configure do |config|
+  # Turn on a warning like:
+  #   OAuth2::AccessToken.from_hash: `hash` contained more than one 'token' key
+  config.silence_extra_tokens_warning = false # default: true
+  # Set to true if you want to also show warnings about no tokens
+  config.silence_no_tokens_warning = false # default: true,
+end
+
    
+
+
    The “extra tokens” problem comes from ambiguity in the spec about which token is the right token.
    
+Some OAuth 2.0 standards legitimately have multiple tokens.
    
+You may need to subclass OAuth2::AccessToken, or write your own custom alternative to it, and pass it in.
    
+Specify your custom class with the access_token_class option.
    
+
+
    If you only need one token, you can, as of v2.0.10,
    
+specify the exact token name you want to extract via the OAuth2::AccessToken using
    
+the token_name option.
    
+
+
    You’ll likely need to do some source diving.
    
+This gem has 100% test coverage for lines and branches, so the specs are a great place to look for ideas.
    
+If you have time and energy, please contribute to the documentation!
    
+
+
    🔧 Basic Usage
    
+
+
    
+authorize_url and token_url are on site root (Just Works!)
    
+
+
    require "oauth2"
+client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org")
+# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
+client.auth_code.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth2/callback")
+# => "https://example.org/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
+
+access = client.auth_code.get_token("authorization_code_value", redirect_uri: "http://localhost:8080/oauth2/callback", headers: {"Authorization" => "Basic some_password"})
+response = access.get("/api/resource", params: {"query_foo" => "bar"})
+response.class.name
+# => OAuth2::Response
+
    
+
+
    Relative authorize_url and token_url (Not on site root, Just Works!)
    
+
+
    In the above example, the default Authorization URL is oauth/authorize and default Access Token URL is oauth/token, and, as they are missing a leading /, both are relative.
    
+
+
    client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/nested/directory/on/your/server")
+# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
+client.auth_code.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth2/callback")
+# => "https://example.org/nested/directory/on/your/server/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
+
    
+
+
    Customize authorize_url and token_url
+
    
+
+
    You can specify custom URLs for authorization and access token, and when using a leading / they will not be relative, as shown below:
    
+
+
    client = OAuth2::Client.new(
+  "client_id",
+  "client_secret",
+  site: "https://example.org/nested/directory/on/your/server",
+  authorize_url: "/jaunty/authorize/",
+  token_url: "/stirrups/access_token",
+)
+# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
+client.auth_code.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth2/callback")
+# => "https://example.org/jaunty/authorize/?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
+client.class.name
+# => OAuth2::Client
+
    
+
+
    snake_case and indifferent access in Response#parsed
    
+
+
    response = access.get("/api/resource", params: {"query_foo" => "bar"})
+# Even if the actual response is CamelCase. it will be made available as snaky:
+JSON.parse(response.body)         # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
+response.parsed                   # => {"access_token"=>"aaaaaaaa", "additional_data"=>"additional"}
+response.parsed.access_token      # => "aaaaaaaa"
+response.parsed[:access_token]    # => "aaaaaaaa"
+response.parsed.additional_data   # => "additional"
+response.parsed[:additional_data] # => "additional"
+response.parsed.class.name        # => SnakyHash::StringKeyed (from snaky_hash gem)
+
    
+
+
    Serialization
    
+
+
    As of v2.0.11, if you need to serialize the parsed result, you can!
    
+
+
    There are two ways to do this, globally, or discretely.  The discrete way is recommended.
    
+
+
    Global Serialization Config
    
+
+
    Globally configure SnakyHash::StringKeyed to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails).
    
+
+
    SnakyHash::StringKeyed.class_eval do
+  extend SnakyHash::Serializer
+end
+
    
+
+
    Discrete Serialization Config
    
+
+
    Discretely configure a custom Snaky Hash class to use the serializer.
    
+
+
    class MySnakyHash < SnakyHash::StringKeyed
+  # Give this hash class `dump` and `load` abilities!
+  extend SnakyHash::Serializer
+end
+
+# And tell your client to use the custom class in each call:
+client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/oauth2")
+token = client.get_token({snaky_hash_klass: MySnakyHash})
+
    
+
+
    Serialization Extensions
    
+
+
    These extensions work regardless of whether you used the global or discrete config above.
    
+
+
    There are a few hacks you may need in your class to support Ruby < 2.4.2 or < 2.6.
    
+They are likely not needed if you are on a newer Ruby.
    
+Expand the examples below, or the ruby-oauth/snaky_hash gem,
    
+or response_spec.rb, for more ideas, especially if you need to study the hacks for older Rubies.
    
+
+
    
+  See Examples
+
+  
    class MySnakyHash < SnakyHash::StringKeyed
+  # Give this hash class `dump` and `load` abilities!
+  extend SnakyHash::Serializer
+
+  #### Serialization Extentions
+  #
+  # Act on the non-hash values (including the values of hashes) as they are dumped to JSON
+  # In other words, this retains nested hashes, and only the deepest leaf nodes become bananas.
+  # WARNING: This is a silly example!
+  dump_value_extensions.add(:to_fruit) do |value|
+    "banana" # => Make values "banana" on dump
+  end
+
+  # Act on the non-hash values (including the values of hashes) as they are loaded from the JSON dump
+  # In other words, this retains nested hashes, and only the deepest leaf nodes become ***.
+  # WARNING: This is a silly example!
+  load_value_extensions.add(:to_stars) do |value|
+    "***" # Turn dumped bananas into *** when they are loaded
+  end
+
+  # Act on the entire hash as it is prepared for dumping to JSON
+  # WARNING: This is a silly example!
+  dump_hash_extensions.add(:to_cheese) do |value|
+    if value.is_a?(Hash)
+      value.transform_keys do |key|
+        split = key.split("_")
+        first_word = split[0]
+        key.sub(first_word, "cheese")
+      end
+    else
+      value
+    end
+  end
+
+  # Act on the entire hash as it is loaded from the JSON dump
+  # WARNING: This is a silly example!
+  load_hash_extensions.add(:to_pizza) do |value|
+    if value.is_a?(Hash)
+      res = klass.new
+      value.keys.each_with_object(res) do |key, result|
+        split = key.split("_")
+        last_word = split[-1]
+        new_key = key.sub(last_word, "pizza")
+        result[new_key] = value[key]
+      end
+      res
+    else
+      value
+    end
+  end
+end
+
    
+
+
    
+
+
    Prefer camelCase over snake_case? => snaky: false
    
+
+
    response = access.get("/api/resource", params: {"query_foo" => "bar"}, snaky: false)
+JSON.parse(response.body)         # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
+response.parsed                   # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
+response.parsed["accessToken"]    # => "aaaaaaaa"
+response.parsed["additionalData"] # => "additional"
+response.parsed.class.name        # => Hash (just, regular old Hash)
+
    
+
+
    
+  Debugging & Logging
+
+  
    Set an environment variable as per usual (e.g. with dotenv).
    
+
+  
    # will log both request and response, including bodies
+ENV["OAUTH_DEBUG"] = "true"
+
    
+
+  
    By default, debug output will go to $stdout. This can be overridden when
+initializing your OAuth2::Client.
    
+
+  
    require "oauth2"
+client = OAuth2::Client.new(
+  "client_id",
+  "client_secret",
+  site: "https://example.org",
+  logger: Logger.new("example.log", "weekly"),
+)
+
    
+
+
    
+
+
    OAuth2::Response
    
+
+
    The AccessToken methods #get, #post, #put and #delete and the generic #request
    
+will return an instance of the #OAuth2::Response class.
    
+
+
    This instance contains a #parsed method that will parse the response body and
    
+return a Hash-like SnakyHash::StringKeyed if the Content-Type is application/x-www-form-urlencoded or if
    
+the body is a JSON object.  It will return an Array if the body is a JSON
    
+array.  Otherwise, it will return the original body string.
    
+
+
    The original response body, headers, and status can be accessed via their
    
+respective methods.
    
+
+
    OAuth2::AccessToken
    
+
+
    If you have an existing Access Token for a user, you can initialize an instance
    
+using various class methods including the standard new, from_hash (if you have
    
+a hash of the values), or from_kvform (if you have an
    
+application/x-www-form-urlencoded encoded string of the values).
    
+
+
    Options (since v2.0.x unless noted):
    
+
+
      
+  
    • 
+    
+      
+        
+          
+          
+        
+      
+    
      
+expires_latency (Integernil): Seconds to subtract from expires_in when computing #expired? to offset latency.
      
+  
      • 
+  
    • 
+    
+      
+        
+          
+          
+          
+        
+      
+    
      
+token_name (StringSymbolnil): When multiple token-like fields exist in responses, select the field name to use as the access token (since v2.0.10).
      
+  
      • 
+  
    • 
+    
+      
+        
+          
+          
+          
+        
+      
+    
      
+mode (SymbolProcHash): Controls how the token is transmitted on requests made via this AccessToken instance.
      
+    
        
+      
      • 
+:header — Send as Authorization: Bearer  header (default and preferred by OAuth 2.1 draft guidance).
+
        • 
+      
      • 
+:query — Send as access_token query parameter (discouraged in general, but required by some providers).
        • 
+      
      • Verb-dependent (since v2.0.15): Provide either:
+        
          
+          
        • a Proc taking |verb| and returning :header or :query, or
          • 
+          
        • a Hash with verb symbols as keys, for example {get: :query, post: :header, delete: :header}.
          • 
+        
        
+      
        • 
+    
      
+  
      • 
+
    
+
+
    Note: Verb-dependent mode supports providers like Instagram that require query mode for GET and header mode for POST/DELETE
    
+
+
      
+  
    • Verb-dependent mode via Proc was added in v2.0.15
      • 
+  
    • Verb-dependent mode via Hash was added in v2.0.16
      • 
+
    
+
+
    OAuth2::Error
    
+
+
    On 400+ status code responses, an OAuth2::Error will be raised.  If it is a
    
+standard OAuth2 error response, the body will be parsed and #code and #description will contain the values provided from the error and
    
+error_description parameters.  The #response property of OAuth2::Error will
    
+always contain the OAuth2::Response instance.
    
+
+
    If you do not want an error to be raised, you may use :raise_errors => false
    
+option on initialization of the client.  In this case the OAuth2::Response
    
+instance will be returned as usual and on 400+ status code responses, the
    
+Response instance will contain the OAuth2::Error instance.
    
+
+
    Authorization Grants
    
+
+
    Note on OAuth 2.1 (draft):
    
+
+
      
+  
    • PKCE is required for all OAuth clients using the authorization code flow (especially public clients). Implement PKCE in your app when required by your provider. See RFC 7636 and RFC 8252.
      • 
+  
    • Redirect URIs must be compared using exact string matching by the Authorization Server.
      • 
+  
    • The Implicit grant (response_type=token) and the Resource Owner Password Credentials grant are omitted from OAuth 2.1; they remain here for OAuth 2.0 compatibility but should be avoided for new apps.
      • 
+  
    • Bearer tokens in the query string are omitted due to security risks; prefer Authorization header usage.
      • 
+  
    • Refresh tokens for public clients must either be sender-constrained (e.g., DPoP/MTLS) or one-time use.
      • 
+  
    • The definitions of public and confidential clients are simplified to refer only to whether the client has credentials.
      • 
+
    
+
+
    References:
    
+
+
      
+  
    • OAuth 2.1 draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13
      • 
+  
    • Aaron Parecki: https://aaronparecki.com/2019/12/12/21/its-time-for-oauth-2-dot-1
      • 
+  
    • FusionAuth: https://fusionauth.io/blog/2020/04/15/whats-new-in-oauth-2-1
      • 
+  
    • Okta: https://developer.okta.com/blog/2019/12/13/oauth-2-1-how-many-rfcs
      • 
+  
    • Video: https://www.youtube.com/watch?v=g_aVPdwBTfw
      • 
+  
    • Differences overview: https://fusionauth.io/learn/expert-advice/oauth/differences-between-oauth-2-oauth-2-1/
      • 
+
    
+
+
    Currently, the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion
    
+authentication grant types have helper strategy classes that simplify client
    
+use. They are available via the #auth_code,
    
+#implicit,
    
+#password,
    
+#client_credentials, and
    
+#assertion methods respectively.
    
+
+
    These aren’t full examples, but demonstrative of the differences between usage for each strategy.
    
+
+
    auth_url = client.auth_code.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth/callback")
+access = client.auth_code.get_token("code_value", redirect_uri: "http://localhost:8080/oauth/callback")
+
+auth_url = client.implicit.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth/callback")
+# get the token params in the callback and
+access = OAuth2::AccessToken.from_kvform(client, query_string)
+
+access = client.password.get_token("username", "password")
+
+access = client.client_credentials.get_token
+
+# Client Assertion Strategy
+# see: https://tools.ietf.org/html/rfc7523
+claimset = {
+  iss: "http://localhost:3001",
+  aud: "http://localhost:8080/oauth2/token",
+  sub: "me@example.com",
+  exp: Time.now.utc.to_i + 3600,
+}
+assertion_params = [claimset, "HS256", "secret_key"]
+access = client.assertion.get_token(assertion_params)
+
+# The `access` (i.e. access token) is then used like so:
+access.token # actual access_token string, if you need it somewhere
+access.get("/api/stuff") # making api calls with access token
+
    
+
+
    If you want to specify additional headers to be sent out with the
    
+request, add a ‘headers’ hash under ‘params’:
    
+
+
    access = client.auth_code.get_token("code_value", redirect_uri: "http://localhost:8080/oauth/callback", headers: {"Some" => "Header"})
+
    
+
+
    You can always use the #request method on the OAuth2::Client instance to make
    
+requests for tokens for any Authentication grant type.
    
+
+
    📘 Comprehensive Usage
    
+
+
    Common Flows (end-to-end)
    
+
+
      
+  
    • Authorization Code (server-side web app):
      • 
+
    
+
+
    require "oauth2"
+client = OAuth2::Client.new(
+  ENV["CLIENT_ID"],
+  ENV["CLIENT_SECRET"],
+  site: "https://provider.example.com",
+  redirect_uri: "https://my.app.example.com/oauth/callback",
+)
+
+# Step 1: redirect user to consent
+state = SecureRandom.hex(16)
+auth_url = client.auth_code.authorize_url(/service/scope: "openid profile email", state: state)
+# redirect_to auth_url
+
+# Step 2: handle the callback
+# params[:code], params[:state]
+raise "state mismatch" unless params[:state] == state
+access = client.auth_code.get_token(params[:code])
+
+# Step 3: call APIs
+profile = access.get("/api/v1/me").parsed
+
    
+
+
      
+  
    • Client Credentials (machine-to-machine):
      • 
+
    
+
+
    client = OAuth2::Client.new(ENV["CLIENT_ID"], ENV["CLIENT_SECRET"], site: "https://provider.example.com")
+access = client.client_credentials.get_token(audience: "https://api.example.com")
+resp = access.get("/v1/things")
+
    
+
+
      
+  
    • Resource Owner Password (legacy; avoid when possible):
      • 
+
    
+
+
    access = client.password.get_token("jdoe", "s3cret", scope: "read")
+
    
+
+
    Examples
    
+
+
    
+  JHipster UAA (Spring Cloud) password grant example (legacy; avoid when possible)
+
+  
    # This converts a Postman/Net::HTTP multipart token request to oauth2 gem usage.
+# JHipster UAA typically exposes the token endpoint at /uaa/oauth/token.
+# The original snippet included:
+# - Basic Authorization header for the client (web_app:changeit)
+# - X-XSRF-TOKEN header from a cookie (some deployments require it)
+# - grant_type=password with username/password and client_id
+# Using oauth2 gem, you don't need to build multipart bodies; the gem sends
+# application/x-www-form-urlencoded as required by RFC 6749.
+
+require "oauth2"
+
+client = OAuth2::Client.new(
+  "web_app",            # client_id
+  "changeit",           # client_secret
+  site: "http://localhost:8080/uaa",
+  token_url: "/oauth/token",      # absolute under site (or "oauth/token" relative)
+  auth_scheme: :basic_auth,         # sends HTTP Basic Authorization header
+)
+
+# If your UAA requires an XSRF header for the token call, provide it as a header.
+# Often this is not required for token endpoints, but if your gateway enforces it,
+# obtain the value from the XSRF-TOKEN cookie and pass it here.
+xsrf_token = ENV["X_XSRF_TOKEN"] # e.g., pulled from a prior set-cookie value
+
+access = client.password.get_token(
+  "admin",                 # username
+  "admin",                 # password
+  headers: xsrf_token ? {"X-XSRF-TOKEN" => xsrf_token} : {},
+  # JHipster commonly also accepts/needs the client_id in the body; include if required:
+  # client_id: "web_app",
+)
+
+puts access.token
+puts access.to_hash # full token response
+
    
+
+  
    Notes:
    
+
+  
      
+    
    • Resource Owner Password Credentials (ROPC) is deprecated in OAuth 2.1 and discouraged. Prefer Authorization Code + PKCE.
      • 
+    
    • If your deployment strictly demands the X-XSRF-TOKEN header, first fetch it from an endpoint that sets the XSRF-TOKEN cookie (often “/” or a login page) and pass it to headers.
      • 
+    
    • For Basic auth, auth_scheme: :basic_auth handles the Authorization header; you do not need to base64-encode manually.
      • 
+  
    
+
+
    
+
+
    Instagram API (verb‑dependent token mode)
    
+
+
    Providers like Instagram require the access token to be sent differently depending on the HTTP verb:
    
+
+
      
+  
    • GET requests: token must be in the query string (?access_token=…)
      • 
+  
    • POST/DELETE requests: token must be in the Authorization header (Bearer …)
      • 
+
    
+
+
    Since v2.0.15, you can configure an AccessToken with a verb‑dependent mode. The gem will choose how to send the token based on the request method.
    
+
+
    Example: exchanging and refreshing long‑lived Instagram tokens, and making API calls
    
+
+
    require "oauth2"
+
+# NOTE: Users authenticate via Facebook Login to obtain a short‑lived user token (not shown here).
+# See Facebook Login docs for obtaining the initial short‑lived token.
+
+client = OAuth2::Client.new(nil, nil, site: "https://graph.instagram.com")
+
+# Start with a short‑lived token you already obtained via Facebook Login
+short_lived = OAuth2::AccessToken.new(
+  client,
+  ENV["IG_SHORT_LIVED_TOKEN"],
+  # Key part: verb‑dependent mode
+  mode: {get: :query, post: :header, delete: :header},
+)
+
+# 1) Exchange for a long‑lived token (Instagram requires GET with access_token in query)
+#    Endpoint: GET https://graph.instagram.com/access_token
+#    Params: grant_type=ig_exchange_token, client_secret=APP_SECRET
+exchange = short_lived.get(
+  "/access_token",
+  params: {
+    grant_type: "ig_exchange_token",
+    client_secret: ENV["IG_APP_SECRET"],
+    # access_token param will be added automatically by the AccessToken (mode => :query for GET)
+  },
+)
+long_lived_token_value = exchange.parsed["access_token"]
+
+long_lived = OAuth2::AccessToken.new(
+  client,
+  long_lived_token_value,
+  mode: {get: :query, post: :header, delete: :header},
+)
+
+# 2) Refresh the long‑lived token (Instagram uses GET with token in query)
+#    Endpoint: GET https://graph.instagram.com/refresh_access_token
+refresh_resp = long_lived.get(
+  "/refresh_access_token",
+  params: {grant_type: "ig_refresh_token"},
+)
+long_lived = OAuth2::AccessToken.new(
+  client,
+  refresh_resp.parsed["access_token"],
+  mode: {get: :query, post: :header, delete: :header},
+)
+
+# 3) Typical API GET request (token in query automatically)
+me = long_lived.get("/me", params: {fields: "id,username"}).parsed
+
+# 4) Example POST (token sent via Bearer header automatically)
+# Note: Replace the path/params with a real Instagram Graph API POST you need,
+# such as publishing media via the Graph API endpoints.
+# long_lived.post("/me/media", body: {image_url: "https://...", caption: "hello"})
+
    
+
+
    Tips:
    
+
+
      
+  
    • Avoid query‑string bearer tokens unless required by your provider. Instagram explicitly requires it for GET requests.
      • 
+  
    • If you need a custom rule, you can pass a Proc for mode, e.g. mode: ->(verb) { verb == :get ? :query : :header }.
      • 
+
    
+
+
    Refresh Tokens
    
+
+
    When the server issues a refresh_token, you can refresh manually or implement an auto-refresh wrapper.
    
+
+
      
+  
    • Manual refresh:
      • 
+
    
+
+
    if access.expired?
+  access = access.refresh
+end
+
    
+
+
      
+  
    • Auto-refresh wrapper pattern:
      • 
+
    
+
+
    class AutoRefreshingToken
+  def initialize(token_provider, store: nil)
+    @token = token_provider
+    @store = store # e.g., something that responds to read/write for token data
+  end
+
+  def with(&blk)
+    tok = ensure_fresh!
+    blk ? blk.call(tok) : tok
+  rescue OAuth2::Error => e
+    # If a 401 suggests token invalidation, try one refresh and retry once
+    if e.response && e.response.status == 401 && @token.refresh_token
+      @token = @token.refresh
+      @store.write(@token.to_hash) if @store
+      retry
+    end
+    raise
+  end
+
+private
+
+  def ensure_fresh!
+    if @token.expired? && @token.refresh_token
+      @token = @token.refresh
+      @store.write(@token.to_hash) if @store
+    end
+    @token
+  end
+end
+
+# usage
+keeper = AutoRefreshingToken.new(access)
+keeper.with { |tok| tok.get("/v1/protected") }
+
    
+
+
    Persist the token across processes using AccessToken#to_hash and AccessToken.from_hash(client, hash).
    
+
+
    Token Revocation (RFC 7009)
    
+
+
    You can revoke either the access token or the refresh token.
    
+
+
    # Revoke the current access token
+access.revoke(token_type_hint: :access_token)
+
+# Or explicitly revoke the refresh token (often also invalidates associated access tokens)
+access.revoke(token_type_hint: :refresh_token)
+
    
+
+
    Client Configuration Tips
    
+
+
    Mutual TLS (mTLS) client authentication
    
+
+
    Some providers require OAuth requests (including the token request and subsequent API calls) to be sender‑constrained using mutual TLS (mTLS). With this gem, you enable mTLS by providing a client certificate/private key to Faraday via connection_opts.ssl and, if your provider requires it for client authentication, selecting the tls_client_auth auth_scheme.
    
+
+
    Example using PEM files (certificate and key):
    
+
+
    require "oauth2"
+require "openssl"
+
+client = OAuth2::Client.new(
+  ENV.fetch("CLIENT_ID"),
+  ENV.fetch("CLIENT_SECRET"),
+  site: "https://example.com",
+  authorize_url: "/oauth/authorize/",
+  token_url: "/oauth/token/",
+  auth_scheme: :tls_client_auth, # if your AS requires mTLS-based client authentication
+  connection_opts: {
+    ssl: {
+      client_cert: OpenSSL::X509::Certificate.new(File.read("localhost.pem")),
+      client_key: OpenSSL::PKey::RSA.new(File.read("localhost-key.pem")),
+      # Optional extras, uncomment as needed:
+      # ca_file: "/path/to/ca-bundle.pem",   # custom CA(s)
+      # verify: true                           # enable server cert verification (recommended)
+    },
+  },
+)
+
+# Example token request (any grant type can be used). The mTLS handshake
+# will occur automatically on HTTPS calls using the configured cert/key.
+access = client.client_credentials.get_token
+
+# Subsequent resource requests will also use mTLS on HTTPS endpoints of `site`:
+resp = access.get("/v1/protected")
+
    
+
+
    Notes:
    
+
+
      
+  
    • Files must contain the appropriate PEMs. The private key may be encrypted; if so, pass a password to OpenSSL::PKey::RSA.new(File.read(path), ENV["KEY_PASSWORD"]).
      • 
+  
    • If your certificate and key are in a PKCS#12/PFX bundle, you can load them like:
+    
        
+      
      • p12 = OpenSSL::PKCS12.new(File.read("client.p12"), ENV["P12_PASSWORD"])
        • 
+      
      • client_cert = p12.certificate; client_key = p12.key
        • 
+    
      
+  
      • 
+  
    • Server trust:
+    
        
+      
      • If your environment does not have system CAs, specify ca_file or ca_path inside the ssl: hash.
        • 
+      
      • Keep verify: true in production. Set verify: false only for local testing.
        • 
+    
      
+  
      • 
+  
    • Faraday adapter: Any adapter that supports Ruby’s OpenSSL should work. net_http (default) and net_http_persistent are common choices.
      • 
+  
    • Scope of mTLS: The SSL client cert is applied to any HTTPS request made by this client (token and resource requests) to the configured site base URL (and absolute URLs you call with the same client).
      • 
+  
    • OIDC tie-in: Some OPs require tls_client_auth at the token endpoint per OIDC/OAuth specifications. That is enabled via auth_scheme: :tls_client_auth as shown above.
      • 
+
    
+
+
    Authentication schemes for the token request
    
+
+
    OAuth2::Client.new(
+  id,
+  secret,
+  site: "https://provider.example.com",
+  auth_scheme: :basic_auth, # default. Alternatives: :request_body, :tls_client_auth, :private_key_jwt
+)
+
    
+
+
    Faraday connection, timeouts, proxy, custom adapter/middleware:
    
+
+
    client = OAuth2::Client.new(
+  id,
+  secret,
+  site: "https://provider.example.com",
+  connection_opts: {
+    request: {open_timeout: 5, timeout: 15},
+    proxy: ENV["HTTPS_PROXY"],
+    ssl: {verify: true},
+  },
+) do |faraday|
+  faraday.request(:url_encoded)
+  # faraday.response :logger, Logger.new($stdout) # see OAUTH_DEBUG below
+  faraday.adapter(:net_http_persistent) # or any Faraday adapter you need
+end
+
    
+
+
    Using flat query params (Faraday::FlatParamsEncoder)
    
+
+
    Some APIs expect repeated key parameters to be sent as flat params rather than arrays. Faraday provides FlatParamsEncoder for this purpose. You can configure the oauth2 client to use it when building requests.
    
+
+
    require "faraday"
+
+client = OAuth2::Client.new(
+  id,
+  secret,
+  site: "https://api.example.com",
+  # Pass Faraday connection options to make FlatParamsEncoder the default
+  connection_opts: {
+    request: {params_encoder: Faraday::FlatParamsEncoder},
+  },
+) do |faraday|
+  faraday.request(:url_encoded)
+  faraday.adapter(:net_http)
+end
+
+access = client.client_credentials.get_token
+
+# Example of a GET with two flat filter params (not an array):
+# Results in: ?filter=order.clientCreatedTime%3E1445006997000&filter=order.clientCreatedTime%3C1445611797000
+resp = access.get(
+  "/v1/orders",
+  params: {
+    # Provide the values as an array; FlatParamsEncoder expands them as repeated keys
+    filter: [
+      "order.clientCreatedTime>1445006997000",
+      "order.clientCreatedTime<1445611797000",
+    ],
+  },
+)
+
    
+
+
    If you instead need to build a raw Faraday connection yourself, the equivalent configuration is:
    
+
+
    conn = Faraday.new("https://api.example.com", request: {params_encoder: Faraday::FlatParamsEncoder})
+
    
+
+
    Redirection
    
+
+
    The library follows up to max_redirects (default 5).
    
+You can override per-client via options[:max_redirects].
    
+
+
    Handling Responses and Errors
    
+
+
      
+  
    • Parsing:
      • 
+
    
+
+
    resp = access.get("/v1/thing")
+resp.status     # Integer
+resp.headers    # Hash
+resp.body       # String
+resp.parsed     # SnakyHash::StringKeyed or Array when JSON array
+
    
+
+
      
+  
    • Error handling:
      • 
+
    
+
+
    begin
+  access.get("/v1/forbidden")
+rescue OAuth2::Error => e
+  e.code         # OAuth2 error code (when present)
+  e.description  # OAuth2 error description (when present)
+  e.response     # OAuth2::Response (full access to status/headers/body)
+end
+
    
+
+
      
+  
    • Disable raising on 4xx/5xx to inspect the response yourself:
      • 
+
    
+
+
    client = OAuth2::Client.new(id, secret, site: site, raise_errors: false)
+res = client.request(:get, "/v1/maybe-errors")
+if res.status == 429
+  sleep res.headers["retry-after"].to_i
+end
+
    
+
+
    Making Raw Token Requests
    
+
+
    If a provider requires non-standard parameters or headers, you can call client.get_token directly:
    
+
+
    access = client.get_token({
+  grant_type: "client_credentials",
+  audience: "https://api.example.com",
+  headers: {"X-Custom" => "value"},
+  parse: :json, # override parsing
+})
+
    
+
+
    OpenID Connect (OIDC) Notes
    
+
+
      
+  
    • If the token response includes an id_token (a JWT), this gem surfaces it but does not validate the signature. Use a JWT library and your provider’s JWKs to verify it.
      • 
+  
    • For private_key_jwt client authentication, provide auth_scheme: :private_key_jwt and ensure your key configuration matches the provider requirements.
      • 
+  
    • See OIDC.md for a more complete OIDC overview, example, and links to the relevant specifications.
      • 
+
    
+
+
    Debugging
    
+
+
      
+  
    • Set environment variable OAUTH_DEBUG=true to enable verbose Faraday logging (uses the client-provided logger).
      • 
+  
    • To mirror a working curl request, ensure you set the same auth scheme, params, and content type. The Quick Example at the top shows a curl-to-ruby translation.
      • 
+
    
+
+
    
+
+
    🦷 FLOSS Funding
    
+
+
    While ruby-oauth tools are free software and will always be, the project would benefit immensely from some funding.
    
+Raising a monthly budget of… “dollars” would make the project more sustainable.
    
+
+
    We welcome both individual and corporate sponsors! We also offer a
    
+wide array of funding channels to account for your preferences
    
+(although currently Open Collective is our preferred funding platform).
    
+
+
    If you’re working in a company that’s making significant use of ruby-oauth tools we’d
    
+appreciate it if you suggest to your company to become a ruby-oauth sponsor.
    
+
+
    You can support the development of ruby-oauth tools via
    
+GitHub Sponsors,
    
+Liberapay,
    
+PayPal,
    
+Open Collective
    
+and Tidelift.
    
+
+
+  
+    
+      
+    
+  
+  
+    
+      
+    
+  
+
    📍 NOTE
    If doing a sponsorship in the form of donation is problematic for your company 
     from an accounting standpoint, we’d recommend the use of Tidelift, 
     where you can get a support-like subscription instead.
    
+
+
    Open Collective for Individuals
    
+
+
    Support us with a monthly donation and help us continue our activities. [Become a backer]
    
+
+
    NOTE: kettle-readme-backers updates this list every day, automatically.
    
+
+
+
    No backers yet. Be the first!
    
+
    
+
+
    Open Collective for Organizations
    
+
+
    Become a sponsor and get your logo on our README on GitHub with a link to your site. [Become a sponsor]
    
+
+
    NOTE: kettle-readme-backers updates this list every day, automatically.
    
+
+
+
    No sponsors yet. Be the first!
    
+
    
+
+
    Another way to support open-source
    
+
+
    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.
    
+
+
    I’m developing a new library, floss_funding, designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look.
    
+
+
    Floss-Funding.dev: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags
    
+
+
    OpenCollective Backers OpenCollective Sponsors Sponsor Me on Github Liberapay Goal Progress Donate on PayPal Buy me a coffee Donate on Polar Donate to my FLOSS efforts at ko-fi.com Donate to my FLOSS efforts using Patreon
    
+
+
    🔐 Security
    
+
+
    To report a security vulnerability, please use the Tidelift security contact.
    
+Tidelift will coordinate the fix and disclosure.
    
+
+
    For more see SECURITY.md, THREAT_MODEL.md, and IRP.md.
    
+
+
    🤝 Contributing
    
+
+
    If you need some ideas of where to help, you could work on adding more code coverage,
    
+or if it is already 💯 (see below) check reek, issues, or PRs,
    
+or use the gem and think about how it could be better.
    
+
+
    We Keep A Changelog so if you make changes, remember to update it.
    
+
+
    See CONTRIBUTING.md for more detailed instructions.
    
+
+
    🚀 Release Instructions
    
+
+
    See CONTRIBUTING.md.
    
+
+
    Code Coverage
    
+
+
    Coverage Graph
    
+
+
    Coveralls Test Coverage
    
+
+
    QLTY Test Coverage
    
+
+
    🪇 Code of Conduct
    
+
+
    Everyone interacting with this project’s codebases, issue trackers,
    
+chat rooms and mailing lists agrees to follow the Contributor Covenant 2.1.
    
+
+
    🌈 Contributors
    
+
+
    Contributors
    
+
+
    Made with contributors-img.
    
+
+
    Also see GitLab Contributors: https://gitlab.com/ruby-oauth/oauth2/-/graphs/main
    
+
+
    
+    ⭐️ Star History
+
+
+ 
+   
+   
+   Star History Chart
+ 
+
+
+
    
+
+
    📌 Versioning
    
+
+
    This Library adheres to Semantic Versioning 2.0.0.
    
+Violations of this scheme should be reported as bugs.
    
+Specifically, if a minor or patch version is released that breaks backward compatibility,
    
+a new version should be immediately released that restores compatibility.
    
+Breaking changes to the public API will only be introduced with new major versions.
    
+
+
    
+  
    dropping support for a platform is both obviously and objectively a breaking change 

    
+—Jordan Harband (@ljharb, maintainer of SemVer) in SemVer issue 716
    
+
    
+
+
    I understand that policy doesn’t work universally (“exceptions to every rule!”),
    
+but it is the policy here.
    
+As such, in many cases it is good to specify a dependency on this library using
    
+the Pessimistic Version Constraint with two digits of precision.
    
+
+
    For example:
    
+
+
    spec.add_dependency("oauth2", "~> 2.0")
+
    
+
+
    
+  📌 Is "Platform Support" part of the public API? More details inside.
+
+  
    SemVer should, IMO, but doesn’t explicitly, say that dropping support for specific Platforms
+is a breaking change to an API, and for that reason the bike shedding is endless.
    
+
+  
    To get a better understanding of how SemVer is intended to work over a project’s lifetime,
+read this article from the creator of SemVer:
    
+
+  
+
+
    
+
+
    See CHANGELOG.md for a list of releases.
    
+
+
    📄 License
    
+
+
    The gem is available as open source under the terms of
    
+the MIT License License: MIT.
    
+See LICENSE.txt for the official Copyright Notice.
    
+
+
    © Copyright
    
+
+
      
+    
    • 
+        Copyright (c) 2017 – 2025 Peter H. Boling, of
+        
+            Galtzo.com
+            
+              Galtzo.com Logo (Wordless) by Aboling0, CC BY-SA 4.0
+            
+        , and oauth2 contributors.
+    
      • 
+    
    • 
+        Copyright (c) 2011 - 2013 Michael Bleigh and Intridea, Inc.
+    
      • 
+
    
+
+
    🤑 A request for help
    
+
+
    Maintainers have teeth and need to pay their dentists.
    
+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.
    
+
+
    To join the community or get help 👇️ Join the Discord.
    
+
+
    Live Chat on Discord
    
+
+
    To say “thanks!” ☝️ Join the Discord or 👇️ send money.
    
+
+
    Sponsor ruby-oauth/oauth2 on Open Source Collective 💌 Sponsor me on GitHub Sponsors 💌 Sponsor me on Liberapay 💌 Donate on PayPal
    
+
+
    Please give the project a star ⭐ ♥.
    
+
+
    Thanks for RTFM. ☺️
    
+
+
    
+  
+    rel="me" Social Proofs
+  
+
+
+
+
+
    
+

+
+      
+
+    
+  
+
\ No newline at end of file
diff --git a/docs/file.REEK.html b/docs/file.REEK.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.RUBOCOP.html b/docs/file.RUBOCOP.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.SECURITY.html b/docs/file.SECURITY.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.THREAT_MODEL.html b/docs/file.THREAT_MODEL.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.access_token.html b/docs/file.access_token.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.authenticator.html b/docs/file.authenticator.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.client.html b/docs/file.client.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.error.html b/docs/file.error.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.filtered_attributes.html b/docs/file.filtered_attributes.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.oauth2-2.0.10.gem.html b/docs/file.oauth2-2.0.10.gem.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.oauth2-2.0.11.gem.html b/docs/file.oauth2-2.0.11.gem.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.oauth2-2.0.12.gem.html b/docs/file.oauth2-2.0.12.gem.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.oauth2-2.0.13.gem.html b/docs/file.oauth2-2.0.13.gem.html
new file mode 100644
index 00000000..8068efe3
--- /dev/null
+++ b/docs/file.oauth2-2.0.13.gem.html
@@ -0,0 +1,71 @@
+
+
+  
+    
+
+
+  File: oauth2-2.0.13.gem
+  
+    — Documentation by YARD 0.9.37
+  
+
+
+  
+
+  
+
+
+
+
+  
+
+  
+
+
+  
+  
+    

+      
+      

+    

+
+    

+      
+
+      
3bfe481d98f859f37f3b90ced2b8856a843eef0f2e0263163cccc14430047bc3cd03d28597f48daa3d623b52d692c3b3e7c2dc26df5eb588dd82d28608fba639

+

+
+      
+
+    

+  
+
\ No newline at end of file
diff --git a/docs/file.oauth2-2.0.14.gem.html b/docs/file.oauth2-2.0.14.gem.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.oauth2-2.0.15.gem.html b/docs/file.oauth2-2.0.15.gem.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.oauth2-2.0.16.gem.html b/docs/file.oauth2-2.0.16.gem.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.oauth2-2.0.17.gem.html b/docs/file.oauth2-2.0.17.gem.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.oauth2.html b/docs/file.oauth2.html
new file mode 100644
index 00000000..d68c15d5
--- /dev/null
+++ b/docs/file.oauth2.html
@@ -0,0 +1,79 @@
+
+
+  
+    
+
+
+  File: oauth2
+  
+    — Documentation by YARD 0.9.37
+  
+
+
+  
+
+  
+
+
+
+
+  
+
+  
+
+
+  
+  
+    

+      
+      

+    

+
+    

+      
+
+      
module OAuth2

+  OAUTH_DEBUG: bool

+
+
DEFAULT_CONFIG: untyped

+  @config: untyped

+
+
def self.config: () -> untyped

+  def self.configure: () { (untyped) -> void } -> void

+end

+

+
+      
+
+    

+  
+
\ No newline at end of file
diff --git a/docs/file.response.html b/docs/file.response.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.strategy.html b/docs/file.strategy.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file.version.html b/docs/file.version.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/file_list.html b/docs/file_list.html
new file mode 100644
index 00000000..b342b1fa
--- /dev/null
+++ b/docs/file_list.html
@@ -0,0 +1,299 @@
+
+
+  
+    
+    
+    
+      
+    
+      
+    
+
+    
+      
+    
+      
+    
+
+    File List
+    
+  
+  
+    

+      

+        
File List

+        
+
+        
+      

+
+      
+    

+  
+
diff --git a/docs/frames.html b/docs/frames.html
new file mode 100644
index 00000000..e69de29b
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 00000000..d41b748e
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,1646 @@
+
+
+  
+    
+
+
+  File: README
+  
+    — Documentation by YARD 0.9.37
+  
+
+
+  
+
+  
+
+
+
+
+  
+
+  
+
+
+  
+  
+    

+      
+      

+    

+
+    

+      
+
+      

+  
+    
+      
+    
+  
+  
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+    
+      
+    
+  
+
📍 NOTE
RubyGems (the GitHub org, not the website) suffered a hostile takeover in September 2025.
Ultimately 4 maintainers were hard removed and a reason has been given for only 1 of those, while 2 others resigned in protest.
It is a complicated story which is difficult to parse quickly.
I’m adding notes like this to gems because I don’t condone theft of repositories or gems from their rightful owners.
If a similar theft happened with my repos/gems, I’d hope some would stand up for me.
Disenfranchised former-maintainers have started gem.coop.
Once available I will publish there exclusively; unless RubyCentral makes amends with the community.
The “Technology for Humans: Joel Draper” podcast episode by reinteractive is the most cogent summary I’m aware of.
See here, here and here for more info on what comes next.
What I’m doing: A (WIP) proposal for bundler/gem scopes, and a (WIP) proposal for a federated gem server.

+
+
Galtzo FLOSS Logo by Aboling0, CC BY-SA 4.0 ruby-lang Logo, Yukihiro Matsumoto, Ruby Visual Identity Team, CC BY-SA 2.5 oauth2 Logo by Chris Messina, CC BY-SA 3.0

+
+
🔐 OAuth 2.0 Authorization Framework

+
+
⭐️ including OAuth 2.1 draft spec & OpenID Connect (OIDC)

+
+
Version GitHub tag (latest SemVer) License: MIT Downloads Rank Open Source Helpers CodeCov Test Coverage Coveralls Test Coverage QLTY Test Coverage QLTY Maintainability CI Heads CI Runtime Dependencies @ HEAD CI Current CI JRuby Deps Locked Deps Unlocked CI Supported CI Legacy CI Unsupported CI Ancient CI Test Coverage CI Style CodeQL Apache SkyWalking Eyes License Compatibility Check

+
+
if ci_badges.map(&:color).detect { it != "green"} ☝️ let me know, as I may have missed the discord notification.

+
+

+
+
if ci_badges.map(&:color).all? { it == "green"} 👇️ send money so I can do more of this. FLOSS maintenance is now my full-time job.

+
+
OpenCollective Backers OpenCollective Sponsors Sponsor Me on Github Liberapay Goal Progress Donate on PayPal Buy me a coffee Donate on Polar Donate at ko-fi.com

+
+
🌻 Synopsis

+
+
OAuth 2.0 is the industry-standard protocol for authorization.

+OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications,

+    desktop applications, mobile phones, and living room devices.

+This is a RubyGem for implementing OAuth 2.0 clients (not servers) in Ruby applications.

+
+
Quick Examples

+
+

+  Convert the following `curl` command into a token request using this gem...
+
+  
curl --request POST \
+  --url 'https://login.microsoftonline.com/REDMOND_REDACTED/oauth2/token' \
+  --header 'content-type: application/x-www-form-urlencoded' \
+  --data grant_type=client_credentials \
+  --data client_id=REDMOND_CLIENT_ID \
+  --data client_secret=REDMOND_CLIENT_SECRET \
+  --data resource=REDMOND_RESOURCE_UUID
+

+
+  
NOTE: In the ruby version below, certain params are passed to the get_token call, instead of the client creation.

+
+  
OAuth2::Client.new(
+  "REDMOND_CLIENT_ID", # client_id
+  "REDMOND_CLIENT_SECRET", # client_secret
+  auth_scheme: :request_body, # Other modes are supported: :basic_auth, :tls_client_auth, :private_key_jwt
+  token_url: "oauth2/token", # relative path, except with leading `/`, then absolute path
+  site: "https://login.microsoftonline.com/REDMOND_REDACTED",
+). # The base path for token_url when it is relative
+  client_credentials. # There are many other types to choose from!
+  get_token(resource: "REDMOND_RESOURCE_UUID")
+

+
+  
NOTE: header - The content type specified in the curl is already the default!

+
+

+
+

+  Complete E2E single file script against mock-oauth2-server
+
+  
    
+    
  • E2E example uses navikt/mock-oauth2-server, which was added in v2.0.11
    • 
+    
  • E2E example does not ship with the released gem, so clone the source to play with it.
    • 
+  

+
+  
docker compose -f docker-compose-ssl.yml up -d --wait
+ruby examples/e2e.rb
+# If your machine is slow or Docker pulls are cold, increase the wait:
+E2E_WAIT_TIMEOUT=120 ruby examples/e2e.rb
+# The mock server serves HTTP on 8080; the example points to http://localhost:8080 by default.
+

+
+  
The output should be something like this:

+
+  
➜  ruby examples/e2e.rb
+Access token (truncated): eyJraWQiOiJkZWZhdWx0...
+userinfo status: 200
+userinfo body: {"sub" => "demo-sub", "aud" => ["demo-aud"], "nbf" => 1757816758000, "iss" => "http://localhost:8080/default", "exp" => 1757820358000, "iat" => 1757816758000, "jti" => "d63b97a7-ebe5-4dea-93e6-d542caba6104"}
+E2E complete
+

+
+  
Make sure to shut down the mock server when you are done:

+
+  
docker compose -f docker-compose-ssl.yml down
+

+
+  
Troubleshooting: validate connectivity to the mock server

+
+  
    
+    
  • Check container status and port mapping:
+      
      
+        
    • docker compose -f docker-compose-ssl.yml ps
      • 
+      
    
+    
    • 
+    
  • From the host, try the discovery URL directly (this is what the example uses by default):
+      
      
+        
    • curl -v http://localhost:8080/default/.well-known/openid-configuration
      • 
+        
    • If that fails immediately, also try: curl -v --connect-timeout 2 http://127.0.0.1:8080/default/.well-known/openid-configuration
+
      • 
+      
    
+    
    • 
+    
  • From inside the container (to distinguish container vs. host networking):
+      
      
+        
    • docker exec -it oauth2-mock-oauth2-server-1 curl -v http://127.0.0.1:8080/default/.well-known/openid-configuration
      • 
+      
    
+    
    • 
+    
  • Simple TCP probe from the host:
+      
      
+        
    • nc -vz localhost 8080  # or: ruby -rsocket -e 'TCPSocket.new("localhost",8080).close; puts "tcp ok"'
      • 
+      
    
+    
    • 
+    
  • Inspect which host port 8080 is bound to (should be 8080):
+      
      
+        
    • docker inspect -f '{{ (index (index .NetworkSettings.Ports "8080/tcp") 0).HostPort }}' oauth2-mock-oauth2-server-1
      • 
+      
    
+    
    • 
+    
  • Look at server logs for readiness/errors:
+      
      
+        
    • docker logs -n 200 oauth2-mock-oauth2-server-1
      • 
+      
    
+    
    • 
+    
  • On Linux, ensure nothing else is bound to 8080 and that firewall/SELinux aren’t blocking:
+      
      
+        
    • ss -ltnp | grep :8080
      • 
+      
    
+    
    • 
+  

+
+  
Notes

+
+  
    
+    
  • Discovery URL pattern is: http://localhost:8080/<realm>/.well-known/openid-configuration, where <realm> defaults to default.
    • 
+    
  • You can change these with env vars when running the example:
+      
      
+        
    • 
+E2E_ISSUER_BASE (default: http://localhost:8080)
      • 
+        
    • 
+E2E_REALM (default: default)
      • 
+      
    
+    
    • 
+  

+
+

+
+
If it seems like you are in the wrong place, you might try one of these:

+
+
+
+
💡 Info you can shake a stick at

+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+    
+      
+      
+    
+  
+
Tokens to Remember
+Gem name Gem namespace
+
Works with JRuby
+JRuby 9.1 Compat JRuby 9.2 Compat JRuby 9.3 Compat 
 JRuby 9.4 Compat JRuby 10.0 Compat JRuby HEAD Compat
+
Works with Truffle Ruby
+Truffle Ruby 22.3 Compat Truffle Ruby 23.0 Compat Truffle Ruby 23.1 Compat 
 Truffle Ruby 24.1 Compat
+
Works with MRI Ruby 3
+Ruby 3.0 Compat Ruby 3.1 Compat Ruby 3.2 Compat Ruby 3.3 Compat Ruby 3.4 Compat Ruby HEAD Compat
+
Works with MRI Ruby 2
+Ruby 2.2 Compat 
 Ruby 2.3 Compat Ruby 2.4 Compat Ruby 2.5 Compat Ruby 2.6 Compat Ruby 2.7 Compat
+
Support & Community
+Join Me on Daily.dev's RubyFriends Live Chat on Discord Get help from me on Upwork Get help from me on Codementor
+
Source
+Source on GitLab.com Source on CodeBerg.org Source on Github.com The best SHA: dQw4w9WgXcQ!
+
Documentation
+Current release on RubyDoc.info YARD on Galtzo.com Maintainer Blog GitLab Wiki GitHub Wiki
+
Compliance
+License: MIT Compatible with Apache Software Projects: Verified by SkyWalking Eyes 📄ilo-declaration-img Security Policy Contributor Covenant 2.1 SemVer 2.0.0
+
Style
+Enforced Code Style Linter Keep-A-Changelog 1.0.0 Gitmoji Commits Compatibility appraised by: appraisal2
+
Maintainer 🎖️
+Follow Me on LinkedIn Follow Me on Ruby.Social Follow Me on Bluesky Contact Maintainer My technical writing
+

+... 💖
+Find Me on WellFound: Find Me on CrunchBase My LinkTree More About Me 🧊 🐙  🛖 🧪
+

+
+
Compatibility

+
+
Compatible with MRI Ruby 2.2.0+, and concordant releases of JRuby, and TruffleRuby.

+
+
+  
+    
+      
+      
+    
+  
+  
+    
+      
+      
+    
+  
+
🚚 Amazing test matrix was brought to you by🔎 appraisal2 🔎 and the color 💚 green 💚
👟 Check it out!✨ github.com/appraisal-rb/appraisal2 ✨

+
+
Federated DVCS

+
+

+  Find this repo on federated forges (Coming soon!)
+
+  
+    
+      
+        
+        
+        
+        
+        
+        
+        
+      
+    
+    
+      
+        
+        
+        
+        
+        
+        
+        
+      
+      
+        
+        
+        
+        
+        
+        
+        
+      
+      
+        
+        
+        
+        
+        
+        
+        
+      
+      
+        
+        
+        
+        
+        
+        
+        
+      
+    
+  
Federated DVCS RepositoryStatusIssuesPRsWikiCIDiscussions
🧪 ruby-oauth/oauth2 on GitLab
+The Truth💚💚💚🐭 Tiny Matrix➖
🧊 ruby-oauth/oauth2 on CodeBerg
+An Ethical Mirror (Donate)💚💚➖⭕️ No Matrix➖
🐙 ruby-oauth/oauth2 on GitHub
+Another Mirror💚💚💚💯 Full Matrix💚
🎮️ Discord Server
+Live Chat on DiscordLet’stalkaboutthislibrary!

+
+

+
+
Enterprise Support Tidelift
+

+
+
Available as part of the Tidelift Subscription.

+
+

+  Need enterprise-level guarantees?
+
+  
The maintainers of this and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use.

+
+  
Get help from me on Tidelift

+
+  
    
+    
  • 💡Subscribe for support guarantees covering all your FLOSS dependencies
    • 
+    
  • 💡Tidelift is part of Sonar
+
    • 
+    
  • 💡Tidelift pays maintainers to maintain the software you depend on!
    📊@Pointy Haired Boss: An enterprise support subscription is “never gonna let you down”, and supports open source maintainers
    • 
+  

+
+  
Alternatively:

+
+  
    
+    
  • Live Chat on Discord
    • 
+    
  • Get help from me on Upwork
    • 
+    
  • Get help from me on Codementor
    • 
+  

+
+

+
+
✨ Installation

+
+
Install the gem and add to the application’s Gemfile by executing:

+
+
bundle add oauth2
+

+
+
If bundler is not being used to manage dependencies, install the gem by executing:

+
+
gem install oauth2
+

+
+
🔒 Secure Installation

+
+

+  For Medium or High Security Installations
+
+  
This gem is cryptographically signed, and has verifiable SHA-256 and SHA-512 checksums by
+stone_checksums. Be sure the gem you install hasn’t been tampered with
+by following the instructions below.

+
+  
Add my public key (if you haven’t already, expires 2045-04-29) as a trusted certificate:

+
+  
gem cert --add <(curl -Ls https://raw.github.com/galtzo-floss/certs/main/pboling.pem)
+

+
+  
You only need to do that once.  Then proceed to install with:

+
+  
gem install oauth2 -P MediumSecurity
+

+
+  
The MediumSecurity trust profile will verify signed gems, but allow the installation of unsigned dependencies.

+
+  
This is necessary because not all of oauth2’s dependencies are signed, so we cannot use HighSecurity.

+
+  
If you want to up your security game full-time:

+
+  
bundle config set --global trust-policy MediumSecurity
+

+
+  
MediumSecurity instead of HighSecurity is necessary if not all the gems you use are signed.

+
+  
NOTE: Be prepared to track down certs for signed gems and add them the same way you added mine.

+
+

+
+
What is new for v2.0?

+
+
    
+  
  • Works with Ruby versions >= 2.2
    • 
+  
  • Drop support for the expired MAC Draft (all versions)
    • 
+  
  • Support IETF rfc7515 JSON Web Signature - JWS (since v2.0.12)
+    
      
+      
    • Support JWT kid for key discovery and management
      • 
+    
    
+  
    • 
+  
  • Support IETF rfc7523 JWT Bearer Tokens (since v2.0.0)
    • 
+  
  • Support IETF rfc7231 Relative Location in Redirect (since v2.0.0)
    • 
+  
  • Support IETF rfc6749 Don’t set oauth params when nil (since v2.0.0)
    • 
+  
  • Support IETF rfc7009 Token Revocation (since v2.0.10, updated in v2.0.13 to support revocation via URL-encoded parameters)
    • 
+  
  • Support OIDC 1.0 Private Key JWT; based on the OAuth JWT assertion specification (RFC 7523)
+
    • 
+  
  • Support new formats, including from jsonapi.org: application/vdn.api+json, application/vnd.collection+json, application/hal+json, application/problem+json
+
    • 
+  
  • Adds option to OAuth2::Client#get_token:
+    
      
+      
    • 
+:access_token_class (AccessToken); user specified class to use for all calls to get_token
+
      • 
+    
    
+  
    • 
+  
  • Adds option to OAuth2::AccessToken#initialize:
+    
      
+      
    • 
+:expires_latency (nil); number of seconds by which AccessToken validity will be reduced to offset latency
      • 
+    
    
+  
    • 
+  
  • By default, keys are transformed to snake case.
+    
      
+      
    • Original keys will still work as previously, in most scenarios, thanks to snaky_hash gem.
      • 
+      
    • However, this is a breaking change if you rely on response.parsed.to_h to retain the original case, and the original wasn’t snake case, as the keys in the result will be snake case.
      • 
+      
    • As of version 2.0.4 you can turn key transformation off with the snaky: false option.
      • 
+    
    
+  
    • 
+  
  • By default, the :auth_scheme is now :basic_auth (instead of :request_body)
+    
      
+      
    • Third-party strategies and gems may need to be updated if a provider was requiring client id/secret in the request body
      • 
+    
    
+  
    • 
+  
  • … A lot more
    • 
+

+
+
Compatibility

+
+
Targeted ruby compatibility is non-EOL versions of Ruby, currently 3.2, 3.3, and 3.4.

+Compatibility is further distinguished as “Best Effort Support” or “Incidental Support” for older versions of Ruby.

+This gem will install on Ruby versions >= v2.2 for 2.x releases.

+See 1-4-stable branch for older rubies.

+
+

+  Ruby Engine Compatibility Policy
+
+  
This gem is tested against MRI, JRuby, and Truffleruby.
+Each of those has varying versions that target a specific version of MRI Ruby.
+This gem should work in the just-listed Ruby engines according to the targeted MRI compatibility in the table below.
+If you would like to add support for additional engines,
+see gemfiles/README.md, then submit a PR to the correct maintenance branch as according to the table below.

+
+

+
+

+  Ruby Version Compatibility Policy
+
+  
If something doesn’t work on one of these interpreters, it’s a bug.

+
+  
This library may inadvertently work (or seem to work) on other Ruby
+implementations; however, support will only be provided for the versions listed
+above.

+
+  
If you would like this library to support another Ruby version, you may
+volunteer to be a maintainer. Being a maintainer entails making sure all tests
+run and pass on that implementation. When something breaks on your
+implementation, you will be responsible for providing patches in a timely
+fashion. If critical issues for a particular implementation exist at the time
+of a major release, support for that Ruby version may be dropped.

+
+

+
+
+  
+    
+      
+      
+      
+      
+      
+      
+    
+  
+  
+    
+      
+      
+      
+      
+      
+      
+    
+    
+      
+      
+      
+      
+      
+      
+    
+    
+      
+      
+      
+      
+      
+      
+    
+  
+
 Ruby OAuth2 VersionMaintenance BranchTargeted SupportBest Effort SupportIncidental Support
1️⃣2.0.xmain3.2, 3.3, 3.42.5, 2.6, 2.7, 3.0, 3.12.2, 2.3, 2.4
2️⃣1.4.x1-4-stable3.2, 3.3, 3.42.5, 2.6, 2.7, 3.0, 3.11.9, 2.0, 2.1, 2.2, 2.3, 2.4
3️⃣olderN/ABest of luck to you!Please upgrade! 

+
+
NOTE: The 1.4 series will only receive critical security updates.

+See SECURITY.md and IRP.md.

+
+
⚙️ Configuration

+
+
You can turn on additional warnings.

+
+
OAuth2.configure do |config|
+  # Turn on a warning like:
+  #   OAuth2::AccessToken.from_hash: `hash` contained more than one 'token' key
+  config.silence_extra_tokens_warning = false # default: true
+  # Set to true if you want to also show warnings about no tokens
+  config.silence_no_tokens_warning = false # default: true,
+end
+

+
+
The “extra tokens” problem comes from ambiguity in the spec about which token is the right token.

+Some OAuth 2.0 standards legitimately have multiple tokens.

+You may need to subclass OAuth2::AccessToken, or write your own custom alternative to it, and pass it in.

+Specify your custom class with the access_token_class option.

+
+
If you only need one token, you can, as of v2.0.10,

+specify the exact token name you want to extract via the OAuth2::AccessToken using

+the token_name option.

+
+
You’ll likely need to do some source diving.

+This gem has 100% test coverage for lines and branches, so the specs are a great place to look for ideas.

+If you have time and energy, please contribute to the documentation!

+
+
🔧 Basic Usage

+
+

+authorize_url and token_url are on site root (Just Works!)

+
+
require "oauth2"
+client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org")
+# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
+client.auth_code.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth2/callback")
+# => "https://example.org/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
+
+access = client.auth_code.get_token("authorization_code_value", redirect_uri: "http://localhost:8080/oauth2/callback", headers: {"Authorization" => "Basic some_password"})
+response = access.get("/api/resource", params: {"query_foo" => "bar"})
+response.class.name
+# => OAuth2::Response
+

+
+
Relative authorize_url and token_url (Not on site root, Just Works!)

+
+
In the above example, the default Authorization URL is oauth/authorize and default Access Token URL is oauth/token, and, as they are missing a leading /, both are relative.

+
+
client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/nested/directory/on/your/server")
+# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
+client.auth_code.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth2/callback")
+# => "https://example.org/nested/directory/on/your/server/oauth/authorize?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
+

+
+
Customize authorize_url and token_url
+

+
+
You can specify custom URLs for authorization and access token, and when using a leading / they will not be relative, as shown below:

+
+
client = OAuth2::Client.new(
+  "client_id",
+  "client_secret",
+  site: "https://example.org/nested/directory/on/your/server",
+  authorize_url: "/jaunty/authorize/",
+  token_url: "/stirrups/access_token",
+)
+# => #<OAuth2::Client:0x00000001204c8288 @id="client_id", @secret="client_sec...
+client.auth_code.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth2/callback")
+# => "https://example.org/jaunty/authorize/?client_id=client_id&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Foauth2%2Fcallback&response_type=code"
+client.class.name
+# => OAuth2::Client
+

+
+
snake_case and indifferent access in Response#parsed

+
+
response = access.get("/api/resource", params: {"query_foo" => "bar"})
+# Even if the actual response is CamelCase. it will be made available as snaky:
+JSON.parse(response.body)         # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
+response.parsed                   # => {"access_token"=>"aaaaaaaa", "additional_data"=>"additional"}
+response.parsed.access_token      # => "aaaaaaaa"
+response.parsed[:access_token]    # => "aaaaaaaa"
+response.parsed.additional_data   # => "additional"
+response.parsed[:additional_data] # => "additional"
+response.parsed.class.name        # => SnakyHash::StringKeyed (from snaky_hash gem)
+

+
+
Serialization

+
+
As of v2.0.11, if you need to serialize the parsed result, you can!

+
+
There are two ways to do this, globally, or discretely.  The discrete way is recommended.

+
+
Global Serialization Config

+
+
Globally configure SnakyHash::StringKeyed to use the serializer. Put this in your code somewhere reasonable (like an initializer for Rails).

+
+
SnakyHash::StringKeyed.class_eval do
+  extend SnakyHash::Serializer
+end
+

+
+
Discrete Serialization Config

+
+
Discretely configure a custom Snaky Hash class to use the serializer.

+
+
class MySnakyHash < SnakyHash::StringKeyed
+  # Give this hash class `dump` and `load` abilities!
+  extend SnakyHash::Serializer
+end
+
+# And tell your client to use the custom class in each call:
+client = OAuth2::Client.new("client_id", "client_secret", site: "https://example.org/oauth2")
+token = client.get_token({snaky_hash_klass: MySnakyHash})
+

+
+
Serialization Extensions

+
+
These extensions work regardless of whether you used the global or discrete config above.

+
+
There are a few hacks you may need in your class to support Ruby < 2.4.2 or < 2.6.

+They are likely not needed if you are on a newer Ruby.

+Expand the examples below, or the ruby-oauth/snaky_hash gem,

+or response_spec.rb, for more ideas, especially if you need to study the hacks for older Rubies.

+
+

+  See Examples
+
+  
class MySnakyHash < SnakyHash::StringKeyed
+  # Give this hash class `dump` and `load` abilities!
+  extend SnakyHash::Serializer
+
+  #### Serialization Extentions
+  #
+  # Act on the non-hash values (including the values of hashes) as they are dumped to JSON
+  # In other words, this retains nested hashes, and only the deepest leaf nodes become bananas.
+  # WARNING: This is a silly example!
+  dump_value_extensions.add(:to_fruit) do |value|
+    "banana" # => Make values "banana" on dump
+  end
+
+  # Act on the non-hash values (including the values of hashes) as they are loaded from the JSON dump
+  # In other words, this retains nested hashes, and only the deepest leaf nodes become ***.
+  # WARNING: This is a silly example!
+  load_value_extensions.add(:to_stars) do |value|
+    "***" # Turn dumped bananas into *** when they are loaded
+  end
+
+  # Act on the entire hash as it is prepared for dumping to JSON
+  # WARNING: This is a silly example!
+  dump_hash_extensions.add(:to_cheese) do |value|
+    if value.is_a?(Hash)
+      value.transform_keys do |key|
+        split = key.split("_")
+        first_word = split[0]
+        key.sub(first_word, "cheese")
+      end
+    else
+      value
+    end
+  end
+
+  # Act on the entire hash as it is loaded from the JSON dump
+  # WARNING: This is a silly example!
+  load_hash_extensions.add(:to_pizza) do |value|
+    if value.is_a?(Hash)
+      res = klass.new
+      value.keys.each_with_object(res) do |key, result|
+        split = key.split("_")
+        last_word = split[-1]
+        new_key = key.sub(last_word, "pizza")
+        result[new_key] = value[key]
+      end
+      res
+    else
+      value
+    end
+  end
+end
+

+
+

+
+
Prefer camelCase over snake_case? => snaky: false

+
+
response = access.get("/api/resource", params: {"query_foo" => "bar"}, snaky: false)
+JSON.parse(response.body)         # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
+response.parsed                   # => {"accessToken"=>"aaaaaaaa", "additionalData"=>"additional"}
+response.parsed["accessToken"]    # => "aaaaaaaa"
+response.parsed["additionalData"] # => "additional"
+response.parsed.class.name        # => Hash (just, regular old Hash)
+

+
+

+  Debugging & Logging
+
+  
Set an environment variable as per usual (e.g. with dotenv).

+
+  
# will log both request and response, including bodies
+ENV["OAUTH_DEBUG"] = "true"
+

+
+  
By default, debug output will go to $stdout. This can be overridden when
+initializing your OAuth2::Client.

+
+  
require "oauth2"
+client = OAuth2::Client.new(
+  "client_id",
+  "client_secret",
+  site: "https://example.org",
+  logger: Logger.new("example.log", "weekly"),
+)
+

+
+

+
+
OAuth2::Response

+
+
The AccessToken methods #get, #post, #put and #delete and the generic #request

+will return an instance of the #OAuth2::Response class.

+
+
This instance contains a #parsed method that will parse the response body and

+return a Hash-like SnakyHash::StringKeyed if the Content-Type is application/x-www-form-urlencoded or if

+the body is a JSON object.  It will return an Array if the body is a JSON

+array.  Otherwise, it will return the original body string.

+
+
The original response body, headers, and status can be accessed via their

+respective methods.

+
+
OAuth2::AccessToken

+
+
If you have an existing Access Token for a user, you can initialize an instance

+using various class methods including the standard new, from_hash (if you have

+a hash of the values), or from_kvform (if you have an

+application/x-www-form-urlencoded encoded string of the values).

+
+
Options (since v2.0.x unless noted):

+
+
    
+  
  • 
+    
+      
+        
+          
+          
+        
+      
+    
    
+expires_latency (Integernil): Seconds to subtract from expires_in when computing #expired? to offset latency.
    
+  
    • 
+  
  • 
+    
+      
+        
+          
+          
+          
+        
+      
+    
    
+token_name (StringSymbolnil): When multiple token-like fields exist in responses, select the field name to use as the access token (since v2.0.10).
    
+  
    • 
+  
  • 
+    
+      
+        
+          
+          
+          
+        
+      
+    
    
+mode (SymbolProcHash): Controls how the token is transmitted on requests made via this AccessToken instance.
    
+    
      
+      
    • 
+:header — Send as Authorization: Bearer  header (default and preferred by OAuth 2.1 draft guidance).
+
      • 
+      
    • 
+:query — Send as access_token query parameter (discouraged in general, but required by some providers).
      • 
+      
    • Verb-dependent (since v2.0.15): Provide either:
+        
        
+          
      • a Proc taking |verb| and returning :header or :query, or
        • 
+          
      • a Hash with verb symbols as keys, for example {get: :query, post: :header, delete: :header}.
        • 
+        
      
+      
      • 
+    
    
+  
    • 
+

+
+
Note: Verb-dependent mode supports providers like Instagram that require query mode for GET and header mode for POST/DELETE

+
+
    
+  
  • Verb-dependent mode via Proc was added in v2.0.15
    • 
+  
  • Verb-dependent mode via Hash was added in v2.0.16
    • 
+

+
+
OAuth2::Error

+
+
On 400+ status code responses, an OAuth2::Error will be raised.  If it is a

+standard OAuth2 error response, the body will be parsed and #code and #description will contain the values provided from the error and

+error_description parameters.  The #response property of OAuth2::Error will

+always contain the OAuth2::Response instance.

+
+
If you do not want an error to be raised, you may use :raise_errors => false

+option on initialization of the client.  In this case the OAuth2::Response

+instance will be returned as usual and on 400+ status code responses, the

+Response instance will contain the OAuth2::Error instance.

+
+
Authorization Grants

+
+
Note on OAuth 2.1 (draft):

+
+
    
+  
  • PKCE is required for all OAuth clients using the authorization code flow (especially public clients). Implement PKCE in your app when required by your provider. See RFC 7636 and RFC 8252.
    • 
+  
  • Redirect URIs must be compared using exact string matching by the Authorization Server.
    • 
+  
  • The Implicit grant (response_type=token) and the Resource Owner Password Credentials grant are omitted from OAuth 2.1; they remain here for OAuth 2.0 compatibility but should be avoided for new apps.
    • 
+  
  • Bearer tokens in the query string are omitted due to security risks; prefer Authorization header usage.
    • 
+  
  • Refresh tokens for public clients must either be sender-constrained (e.g., DPoP/MTLS) or one-time use.
    • 
+  
  • The definitions of public and confidential clients are simplified to refer only to whether the client has credentials.
    • 
+

+
+
References:

+
+
    
+  
  • OAuth 2.1 draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13
    • 
+  
  • Aaron Parecki: https://aaronparecki.com/2019/12/12/21/its-time-for-oauth-2-dot-1
    • 
+  
  • FusionAuth: https://fusionauth.io/blog/2020/04/15/whats-new-in-oauth-2-1
    • 
+  
  • Okta: https://developer.okta.com/blog/2019/12/13/oauth-2-1-how-many-rfcs
    • 
+  
  • Video: https://www.youtube.com/watch?v=g_aVPdwBTfw
    • 
+  
  • Differences overview: https://fusionauth.io/learn/expert-advice/oauth/differences-between-oauth-2-oauth-2-1/
    • 
+

+
+
Currently, the Authorization Code, Implicit, Resource Owner Password Credentials, Client Credentials, and Assertion

+authentication grant types have helper strategy classes that simplify client

+use. They are available via the #auth_code,

+#implicit,

+#password,

+#client_credentials, and

+#assertion methods respectively.

+
+
These aren’t full examples, but demonstrative of the differences between usage for each strategy.

+
+
auth_url = client.auth_code.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth/callback")
+access = client.auth_code.get_token("code_value", redirect_uri: "http://localhost:8080/oauth/callback")
+
+auth_url = client.implicit.authorize_url(https://github.com/redirect_uri:%20"http://localhost:8080/oauth/callback")
+# get the token params in the callback and
+access = OAuth2::AccessToken.from_kvform(client, query_string)
+
+access = client.password.get_token("username", "password")
+
+access = client.client_credentials.get_token
+
+# Client Assertion Strategy
+# see: https://tools.ietf.org/html/rfc7523
+claimset = {
+  iss: "http://localhost:3001",
+  aud: "http://localhost:8080/oauth2/token",
+  sub: "me@example.com",
+  exp: Time.now.utc.to_i + 3600,
+}
+assertion_params = [claimset, "HS256", "secret_key"]
+access = client.assertion.get_token(assertion_params)
+
+# The `access` (i.e. access token) is then used like so:
+access.token # actual access_token string, if you need it somewhere
+access.get("/api/stuff") # making api calls with access token
+

+
+
If you want to specify additional headers to be sent out with the

+request, add a ‘headers’ hash under ‘params’:

+
+
access = client.auth_code.get_token("code_value", redirect_uri: "http://localhost:8080/oauth/callback", headers: {"Some" => "Header"})
+

+
+
You can always use the #request method on the OAuth2::Client instance to make

+requests for tokens for any Authentication grant type.

+
+
📘 Comprehensive Usage

+
+
Common Flows (end-to-end)

+
+
    
+  
  • Authorization Code (server-side web app):
    • 
+

+
+
require "oauth2"
+client = OAuth2::Client.new(
+  ENV["CLIENT_ID"],
+  ENV["CLIENT_SECRET"],
+  site: "https://provider.example.com",
+  redirect_uri: "https://my.app.example.com/oauth/callback",
+)
+
+# Step 1: redirect user to consent
+state = SecureRandom.hex(16)
+auth_url = client.auth_code.authorize_url(/service/scope: "openid profile email", state: state)
+# redirect_to auth_url
+
+# Step 2: handle the callback
+# params[:code], params[:state]
+raise "state mismatch" unless params[:state] == state
+access = client.auth_code.get_token(params[:code])
+
+# Step 3: call APIs
+profile = access.get("/api/v1/me").parsed
+

+
+
    
+  
  • Client Credentials (machine-to-machine):
    • 
+

+
+
client = OAuth2::Client.new(ENV["CLIENT_ID"], ENV["CLIENT_SECRET"], site: "https://provider.example.com")
+access = client.client_credentials.get_token(audience: "https://api.example.com")
+resp = access.get("/v1/things")
+

+
+
    
+  
  • Resource Owner Password (legacy; avoid when possible):
    • 
+

+
+
access = client.password.get_token("jdoe", "s3cret", scope: "read")
+

+
+
Examples

+
+

+  JHipster UAA (Spring Cloud) password grant example (legacy; avoid when possible)
+
+  
# This converts a Postman/Net::HTTP multipart token request to oauth2 gem usage.
+# JHipster UAA typically exposes the token endpoint at /uaa/oauth/token.
+# The original snippet included:
+# - Basic Authorization header for the client (web_app:changeit)
+# - X-XSRF-TOKEN header from a cookie (some deployments require it)
+# - grant_type=password with username/password and client_id
+# Using oauth2 gem, you don't need to build multipart bodies; the gem sends
+# application/x-www-form-urlencoded as required by RFC 6749.
+
+require "oauth2"
+
+client = OAuth2::Client.new(
+  "web_app",            # client_id
+  "changeit",           # client_secret
+  site: "http://localhost:8080/uaa",
+  token_url: "/oauth/token",      # absolute under site (or "oauth/token" relative)
+  auth_scheme: :basic_auth,         # sends HTTP Basic Authorization header
+)
+
+# If your UAA requires an XSRF header for the token call, provide it as a header.
+# Often this is not required for token endpoints, but if your gateway enforces it,
+# obtain the value from the XSRF-TOKEN cookie and pass it here.
+xsrf_token = ENV["X_XSRF_TOKEN"] # e.g., pulled from a prior set-cookie value
+
+access = client.password.get_token(
+  "admin",                 # username
+  "admin",                 # password
+  headers: xsrf_token ? {"X-XSRF-TOKEN" => xsrf_token} : {},
+  # JHipster commonly also accepts/needs the client_id in the body; include if required:
+  # client_id: "web_app",
+)
+
+puts access.token
+puts access.to_hash # full token response
+

+
+  
Notes:

+
+  
    
+    
  • Resource Owner Password Credentials (ROPC) is deprecated in OAuth 2.1 and discouraged. Prefer Authorization Code + PKCE.
    • 
+    
  • If your deployment strictly demands the X-XSRF-TOKEN header, first fetch it from an endpoint that sets the XSRF-TOKEN cookie (often “/” or a login page) and pass it to headers.
    • 
+    
  • For Basic auth, auth_scheme: :basic_auth handles the Authorization header; you do not need to base64-encode manually.
    • 
+  

+
+

+
+
Instagram API (verb‑dependent token mode)

+
+
Providers like Instagram require the access token to be sent differently depending on the HTTP verb:

+
+
    
+  
  • GET requests: token must be in the query string (?access_token=…)
    • 
+  
  • POST/DELETE requests: token must be in the Authorization header (Bearer …)
    • 
+

+
+
Since v2.0.15, you can configure an AccessToken with a verb‑dependent mode. The gem will choose how to send the token based on the request method.

+
+
Example: exchanging and refreshing long‑lived Instagram tokens, and making API calls

+
+
require "oauth2"
+
+# NOTE: Users authenticate via Facebook Login to obtain a short‑lived user token (not shown here).
+# See Facebook Login docs for obtaining the initial short‑lived token.
+
+client = OAuth2::Client.new(nil, nil, site: "https://graph.instagram.com")
+
+# Start with a short‑lived token you already obtained via Facebook Login
+short_lived = OAuth2::AccessToken.new(
+  client,
+  ENV["IG_SHORT_LIVED_TOKEN"],
+  # Key part: verb‑dependent mode
+  mode: {get: :query, post: :header, delete: :header},
+)
+
+# 1) Exchange for a long‑lived token (Instagram requires GET with access_token in query)
+#    Endpoint: GET https://graph.instagram.com/access_token
+#    Params: grant_type=ig_exchange_token, client_secret=APP_SECRET
+exchange = short_lived.get(
+  "/access_token",
+  params: {
+    grant_type: "ig_exchange_token",
+    client_secret: ENV["IG_APP_SECRET"],
+    # access_token param will be added automatically by the AccessToken (mode => :query for GET)
+  },
+)
+long_lived_token_value = exchange.parsed["access_token"]
+
+long_lived = OAuth2::AccessToken.new(
+  client,
+  long_lived_token_value,
+  mode: {get: :query, post: :header, delete: :header},
+)
+
+# 2) Refresh the long‑lived token (Instagram uses GET with token in query)
+#    Endpoint: GET https://graph.instagram.com/refresh_access_token
+refresh_resp = long_lived.get(
+  "/refresh_access_token",
+  params: {grant_type: "ig_refresh_token"},
+)
+long_lived = OAuth2::AccessToken.new(
+  client,
+  refresh_resp.parsed["access_token"],
+  mode: {get: :query, post: :header, delete: :header},
+)
+
+# 3) Typical API GET request (token in query automatically)
+me = long_lived.get("/me", params: {fields: "id,username"}).parsed
+
+# 4) Example POST (token sent via Bearer header automatically)
+# Note: Replace the path/params with a real Instagram Graph API POST you need,
+# such as publishing media via the Graph API endpoints.
+# long_lived.post("/me/media", body: {image_url: "https://...", caption: "hello"})
+

+
+
Tips:

+
+
    
+  
  • Avoid query‑string bearer tokens unless required by your provider. Instagram explicitly requires it for GET requests.
    • 
+  
  • If you need a custom rule, you can pass a Proc for mode, e.g. mode: ->(verb) { verb == :get ? :query : :header }.
    • 
+

+
+
Refresh Tokens

+
+
When the server issues a refresh_token, you can refresh manually or implement an auto-refresh wrapper.

+
+
    
+  
  • Manual refresh:
    • 
+

+
+
if access.expired?
+  access = access.refresh
+end
+

+
+
    
+  
  • Auto-refresh wrapper pattern:
    • 
+

+
+
class AutoRefreshingToken
+  def initialize(token_provider, store: nil)
+    @token = token_provider
+    @store = store # e.g., something that responds to read/write for token data
+  end
+
+  def with(&blk)
+    tok = ensure_fresh!
+    blk ? blk.call(tok) : tok
+  rescue OAuth2::Error => e
+    # If a 401 suggests token invalidation, try one refresh and retry once
+    if e.response && e.response.status == 401 && @token.refresh_token
+      @token = @token.refresh
+      @store.write(@token.to_hash) if @store
+      retry
+    end
+    raise
+  end
+
+private
+
+  def ensure_fresh!
+    if @token.expired? && @token.refresh_token
+      @token = @token.refresh
+      @store.write(@token.to_hash) if @store
+    end
+    @token
+  end
+end
+
+# usage
+keeper = AutoRefreshingToken.new(access)
+keeper.with { |tok| tok.get("/v1/protected") }
+

+
+
Persist the token across processes using AccessToken#to_hash and AccessToken.from_hash(client, hash).

+
+
Token Revocation (RFC 7009)

+
+
You can revoke either the access token or the refresh token.

+
+
# Revoke the current access token
+access.revoke(token_type_hint: :access_token)
+
+# Or explicitly revoke the refresh token (often also invalidates associated access tokens)
+access.revoke(token_type_hint: :refresh_token)
+

+
+
Client Configuration Tips

+
+
Mutual TLS (mTLS) client authentication

+
+
Some providers require OAuth requests (including the token request and subsequent API calls) to be sender‑constrained using mutual TLS (mTLS). With this gem, you enable mTLS by providing a client certificate/private key to Faraday via connection_opts.ssl and, if your provider requires it for client authentication, selecting the tls_client_auth auth_scheme.

+
+
Example using PEM files (certificate and key):

+
+
require "oauth2"
+require "openssl"
+
+client = OAuth2::Client.new(
+  ENV.fetch("CLIENT_ID"),
+  ENV.fetch("CLIENT_SECRET"),
+  site: "https://example.com",
+  authorize_url: "/oauth/authorize/",
+  token_url: "/oauth/token/",
+  auth_scheme: :tls_client_auth, # if your AS requires mTLS-based client authentication
+  connection_opts: {
+    ssl: {
+      client_cert: OpenSSL::X509::Certificate.new(File.read("localhost.pem")),
+      client_key: OpenSSL::PKey::RSA.new(File.read("localhost-key.pem")),
+      # Optional extras, uncomment as needed:
+      # ca_file: "/path/to/ca-bundle.pem",   # custom CA(s)
+      # verify: true                           # enable server cert verification (recommended)
+    },
+  },
+)
+
+# Example token request (any grant type can be used). The mTLS handshake
+# will occur automatically on HTTPS calls using the configured cert/key.
+access = client.client_credentials.get_token
+
+# Subsequent resource requests will also use mTLS on HTTPS endpoints of `site`:
+resp = access.get("/v1/protected")
+

+
+
Notes:

+
+
    
+  
  • Files must contain the appropriate PEMs. The private key may be encrypted; if so, pass a password to OpenSSL::PKey::RSA.new(File.read(path), ENV["KEY_PASSWORD"]).
    • 
+  
  • If your certificate and key are in a PKCS#12/PFX bundle, you can load them like:
+    
      
+      
    • p12 = OpenSSL::PKCS12.new(File.read("client.p12"), ENV["P12_PASSWORD"])
      • 
+      
    • client_cert = p12.certificate; client_key = p12.key
      • 
+    
    
+  
    • 
+  
  • Server trust:
+    
      
+      
    • If your environment does not have system CAs, specify ca_file or ca_path inside the ssl: hash.
      • 
+      
    • Keep verify: true in production. Set verify: false only for local testing.
      • 
+    
    
+  
    • 
+  
  • Faraday adapter: Any adapter that supports Ruby’s OpenSSL should work. net_http (default) and net_http_persistent are common choices.
    • 
+  
  • Scope of mTLS: The SSL client cert is applied to any HTTPS request made by this client (token and resource requests) to the configured site base URL (and absolute URLs you call with the same client).
    • 
+  
  • OIDC tie-in: Some OPs require tls_client_auth at the token endpoint per OIDC/OAuth specifications. That is enabled via auth_scheme: :tls_client_auth as shown above.
    • 
+

+
+
Authentication schemes for the token request

+
+
OAuth2::Client.new(
+  id,
+  secret,
+  site: "https://provider.example.com",
+  auth_scheme: :basic_auth, # default. Alternatives: :request_body, :tls_client_auth, :private_key_jwt
+)
+

+
+
Faraday connection, timeouts, proxy, custom adapter/middleware:

+
+
client = OAuth2::Client.new(
+  id,
+  secret,
+  site: "https://provider.example.com",
+  connection_opts: {
+    request: {open_timeout: 5, timeout: 15},
+    proxy: ENV["HTTPS_PROXY"],
+    ssl: {verify: true},
+  },
+) do |faraday|
+  faraday.request(:url_encoded)
+  # faraday.response :logger, Logger.new($stdout) # see OAUTH_DEBUG below
+  faraday.adapter(:net_http_persistent) # or any Faraday adapter you need
+end
+

+
+
Using flat query params (Faraday::FlatParamsEncoder)

+
+
Some APIs expect repeated key parameters to be sent as flat params rather than arrays. Faraday provides FlatParamsEncoder for this purpose. You can configure the oauth2 client to use it when building requests.

+
+
require "faraday"
+
+client = OAuth2::Client.new(
+  id,
+  secret,
+  site: "https://api.example.com",
+  # Pass Faraday connection options to make FlatParamsEncoder the default
+  connection_opts: {
+    request: {params_encoder: Faraday::FlatParamsEncoder},
+  },
+) do |faraday|
+  faraday.request(:url_encoded)
+  faraday.adapter(:net_http)
+end
+
+access = client.client_credentials.get_token
+
+# Example of a GET with two flat filter params (not an array):
+# Results in: ?filter=order.clientCreatedTime%3E1445006997000&filter=order.clientCreatedTime%3C1445611797000
+resp = access.get(
+  "/v1/orders",
+  params: {
+    # Provide the values as an array; FlatParamsEncoder expands them as repeated keys
+    filter: [
+      "order.clientCreatedTime>1445006997000",
+      "order.clientCreatedTime<1445611797000",
+    ],
+  },
+)
+

+
+
If you instead need to build a raw Faraday connection yourself, the equivalent configuration is:

+
+
conn = Faraday.new("https://api.example.com", request: {params_encoder: Faraday::FlatParamsEncoder})
+

+
+
Redirection

+
+
The library follows up to max_redirects (default 5).

+You can override per-client via options[:max_redirects].

+
+
Handling Responses and Errors

+
+
    
+  
  • Parsing:
    • 
+

+
+
resp = access.get("/v1/thing")
+resp.status     # Integer
+resp.headers    # Hash
+resp.body       # String
+resp.parsed     # SnakyHash::StringKeyed or Array when JSON array
+

+
+
    
+  
  • Error handling:
    • 
+

+
+
begin
+  access.get("/v1/forbidden")
+rescue OAuth2::Error => e
+  e.code         # OAuth2 error code (when present)
+  e.description  # OAuth2 error description (when present)
+  e.response     # OAuth2::Response (full access to status/headers/body)
+end
+

+
+
    
+  
  • Disable raising on 4xx/5xx to inspect the response yourself:
    • 
+

+
+
client = OAuth2::Client.new(id, secret, site: site, raise_errors: false)
+res = client.request(:get, "/v1/maybe-errors")
+if res.status == 429
+  sleep res.headers["retry-after"].to_i
+end
+

+
+
Making Raw Token Requests

+
+
If a provider requires non-standard parameters or headers, you can call client.get_token directly:

+
+
access = client.get_token({
+  grant_type: "client_credentials",
+  audience: "https://api.example.com",
+  headers: {"X-Custom" => "value"},
+  parse: :json, # override parsing
+})
+

+
+
OpenID Connect (OIDC) Notes

+
+
    
+  
  • If the token response includes an id_token (a JWT), this gem surfaces it but does not validate the signature. Use a JWT library and your provider’s JWKs to verify it.
    • 
+  
  • For private_key_jwt client authentication, provide auth_scheme: :private_key_jwt and ensure your key configuration matches the provider requirements.
    • 
+  
  • See OIDC.md for a more complete OIDC overview, example, and links to the relevant specifications.
    • 
+

+
+
Debugging

+
+
    
+  
  • Set environment variable OAUTH_DEBUG=true to enable verbose Faraday logging (uses the client-provided logger).
    • 
+  
  • To mirror a working curl request, ensure you set the same auth scheme, params, and content type. The Quick Example at the top shows a curl-to-ruby translation.
    • 
+

+
+

+
+
🦷 FLOSS Funding

+
+
While ruby-oauth tools are free software and will always be, the project would benefit immensely from some funding.

+Raising a monthly budget of… “dollars” would make the project more sustainable.

+
+
We welcome both individual and corporate sponsors! We also offer a

+wide array of funding channels to account for your preferences

+(although currently Open Collective is our preferred funding platform).

+
+
If you’re working in a company that’s making significant use of ruby-oauth tools we’d

+appreciate it if you suggest to your company to become a ruby-oauth sponsor.

+
+
You can support the development of ruby-oauth tools via

+GitHub Sponsors,

+Liberapay,

+PayPal,

+Open Collective

+and Tidelift.

+
+
+  
+    
+      
+    
+  
+  
+    
+      
+    
+  
+
📍 NOTE
If doing a sponsorship in the form of donation is problematic for your company 
 from an accounting standpoint, we’d recommend the use of Tidelift, 
 where you can get a support-like subscription instead.

+
+
Open Collective for Individuals

+
+
Support us with a monthly donation and help us continue our activities. [Become a backer]

+
+
NOTE: kettle-readme-backers updates this list every day, automatically.

+
+
+
No backers yet. Be the first!

+

+
+
Open Collective for Organizations

+
+
Become a sponsor and get your logo on our README on GitHub with a link to your site. [Become a sponsor]

+
+
NOTE: kettle-readme-backers updates this list every day, automatically.

+
+
+
No sponsors yet. Be the first!

+

+
+
Another way to support open-source

+
+
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.

+
+
I’m developing a new library, floss_funding, designed to empower open-source developers like myself to get paid for the work we do, in a sustainable way. Please give it a look.

+
+
Floss-Funding.dev: 👉️ No network calls. 👉️ No tracking. 👉️ No oversight. 👉️ Minimal crypto hashing. 💡 Easily disabled nags

+
+
OpenCollective Backers OpenCollective Sponsors Sponsor Me on Github Liberapay Goal Progress Donate on PayPal Buy me a coffee Donate on Polar Donate to my FLOSS efforts at ko-fi.com Donate to my FLOSS efforts using Patreon

+
+
🔐 Security

+
+
To report a security vulnerability, please use the Tidelift security contact.

+Tidelift will coordinate the fix and disclosure.

+
+
For more see SECURITY.md, THREAT_MODEL.md, and IRP.md.

+
+
🤝 Contributing

+
+
If you need some ideas of where to help, you could work on adding more code coverage,

+or if it is already 💯 (see below) check reek, issues, or PRs,

+or use the gem and think about how it could be better.

+
+
We Keep A Changelog so if you make changes, remember to update it.

+
+
See CONTRIBUTING.md for more detailed instructions.

+
+
🚀 Release Instructions

+
+
See CONTRIBUTING.md.

+
+
Code Coverage

+
+
Coverage Graph

+
+
Coveralls Test Coverage

+
+
QLTY Test Coverage

+
+
🪇 Code of Conduct

+
+
Everyone interacting with this project’s codebases, issue trackers,

+chat rooms and mailing lists agrees to follow the Contributor Covenant 2.1.

+
+
🌈 Contributors

+
+
Contributors

+
+
Made with contributors-img.

+
+
Also see GitLab Contributors: https://gitlab.com/ruby-oauth/oauth2/-/graphs/main

+
+

+    ⭐️ Star History
+
+
+ 
+   
+   
+   Star History Chart
+ 
+
+
+

+
+
📌 Versioning

+
+
This Library adheres to Semantic Versioning 2.0.0.

+Violations of this scheme should be reported as bugs.

+Specifically, if a minor or patch version is released that breaks backward compatibility,

+a new version should be immediately released that restores compatibility.

+Breaking changes to the public API will only be introduced with new major versions.

+
+

+  
dropping support for a platform is both obviously and objectively a breaking change 


+—Jordan Harband (@ljharb, maintainer of SemVer) in SemVer issue 716

+

+
+
I understand that policy doesn’t work universally (“exceptions to every rule!”),

+but it is the policy here.

+As such, in many cases it is good to specify a dependency on this library using

+the Pessimistic Version Constraint with two digits of precision.

+
+
For example:

+
+
spec.add_dependency("oauth2", "~> 2.0")
+

+
+

+  📌 Is "Platform Support" part of the public API? More details inside.
+
+  
SemVer should, IMO, but doesn’t explicitly, say that dropping support for specific Platforms
+is a breaking change to an API, and for that reason the bike shedding is endless.

+
+  
To get a better understanding of how SemVer is intended to work over a project’s lifetime,
+read this article from the creator of SemVer:

+
+  
+
+

+
+
See CHANGELOG.md for a list of releases.

+
+
📄 License

+
+
The gem is available as open source under the terms of

+the MIT License License: MIT.

+See LICENSE.txt for the official Copyright Notice.

+
+
© Copyright

+
+
    
+    
  • 
+        Copyright (c) 2017 – 2025 Peter H. Boling, of
+        
+            Galtzo.com
+            
+              Galtzo.com Logo (Wordless) by Aboling0, CC BY-SA 4.0
+            
+        , and oauth2 contributors.
+    
    • 
+    
  • 
+        Copyright (c) 2011 - 2013 Michael Bleigh and Intridea, Inc.
+    
    • 
+

+
+
🤑 A request for help

+
+
Maintainers have teeth and need to pay their dentists.

+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.

+
+
To join the community or get help 👇️ Join the Discord.

+
+
Live Chat on Discord

+
+
To say “thanks!” ☝️ Join the Discord or 👇️ send money.

+
+
Sponsor ruby-oauth/oauth2 on Open Source Collective 💌 Sponsor me on GitHub Sponsors 💌 Sponsor me on Liberapay 💌 Donate on PayPal

+
+
Please give the project a star ⭐ ♥.

+
+
Thanks for RTFM. ☺️

+
+

+  
+    rel="me" Social Proofs
+  
+
+
+
+
+

+

+
+      
+
+    

+  
+
\ No newline at end of file
diff --git a/docs/js/app.js b/docs/js/app.js
new file mode 100644
index 00000000..b5610eff
--- /dev/null
+++ b/docs/js/app.js
@@ -0,0 +1,344 @@
+(function () {
+  var localStorage = {},
+    sessionStorage = {};
+  try {
+    localStorage = window.localStorage;
+  } catch (e) {}
+  try {
+    sessionStorage = window.sessionStorage;
+  } catch (e) {}
+
+  function createSourceLinks() {
+    $(".method_details_list .source_code").before(
+      "[View source]"
+    );
+    $(".toggleSource").toggle(
+      function () {
+        $(this).parent().nextAll(".source_code").slideDown(100);
+        $(this).text("Hide source");
+      },
+      function () {
+        $(this).parent().nextAll(".source_code").slideUp(100);
+        $(this).text("View source");
+      }
+    );
+  }
+
+  function createDefineLinks() {
+    var tHeight = 0;
+    $(".defines").after(" more...");
+    $(".toggleDefines").toggle(
+      function () {
+        tHeight = $(this).parent().prev().height();
+        $(this).prev().css("display", "inline");
+        $(this).parent().prev().height($(this).parent().height());
+        $(this).text("(less)");
+      },
+      function () {
+        $(this).prev().hide();
+        $(this).parent().prev().height(tHeight);
+        $(this).text("more...");
+      }
+    );
+  }
+
+  function createFullTreeLinks() {
+    var tHeight = 0;
+    $(".inheritanceTree").toggle(
+      function () {
+        tHeight = $(this).parent().prev().height();
+        $(this).parent().toggleClass("showAll");
+        $(this).text("(hide)");
+        $(this).parent().prev().height($(this).parent().height());
+      },
+      function () {
+        $(this).parent().toggleClass("showAll");
+        $(this).parent().prev().height(tHeight);
+        $(this).text("show all");
+      }
+    );
+  }
+
+  function searchFrameButtons() {
+    $(".full_list_link").click(function () {
+      toggleSearchFrame(this, $(this).attr("href"));
+      return false;
+    });
+    window.addEventListener("message", function (e) {
+      if (e.data === "navEscape") {
+        $("#nav").slideUp(100);
+        $("#search a").removeClass("active inactive");
+        $(window).focus();
+      }
+    });
+
+    $(window).resize(function () {
+      if ($("#search:visible").length === 0) {
+        $("#nav").removeAttr("style");
+        $("#search a").removeClass("active inactive");
+        $(window).focus();
+      }
+    });
+  }
+
+  function toggleSearchFrame(id, link) {
+    var frame = $("#nav");
+    $("#search a").removeClass("active").addClass("inactive");
+    if (frame.attr("src") === link && frame.css("display") !== "none") {
+      frame.slideUp(100);
+      $("#search a").removeClass("active inactive");
+    } else {
+      $(id).addClass("active").removeClass("inactive");
+      if (frame.attr("src") !== link) frame.attr("src", link);
+      frame.slideDown(100);
+    }
+  }
+
+  function linkSummaries() {
+    $(".summary_signature").click(function () {
+      document.location = $(this).find("a").attr("href");
+    });
+  }
+
+  function summaryToggle() {
+    $(".summary_toggle").click(function (e) {
+      e.preventDefault();
+      localStorage.summaryCollapsed = $(this).text();
+      $(".summary_toggle").each(function () {
+        $(this).text($(this).text() == "collapse" ? "expand" : "collapse");
+        var next = $(this).parent().parent().nextAll("ul.summary").first();
+        if (next.hasClass("compact")) {
+          next.toggle();
+          next.nextAll("ul.summary").first().toggle();
+        } else if (next.hasClass("summary")) {
+          var list = $('
    ');
+          list.html(next.html());
+          list.find(".summary_desc, .note").remove();
+          list.find("a").each(function () {
+            $(this).html($(this).find("strong").html());
+            $(this).parent().html($(this)[0].outerHTML);
+          });
+          next.before(list);
+          next.toggle();
+        }
+      });
+      return false;
+    });
+    if (localStorage.summaryCollapsed == "collapse") {
+      $(".summary_toggle").first().click();
+    } else {
+      localStorage.summaryCollapsed = "expand";
+    }
+  }
+
+  function constantSummaryToggle() {
+    $(".constants_summary_toggle").click(function (e) {
+      e.preventDefault();
+      localStorage.summaryCollapsed = $(this).text();
+      $(".constants_summary_toggle").each(function () {
+        $(this).text($(this).text() == "collapse" ? "expand" : "collapse");
+        var next = $(this).parent().parent().nextAll("dl.constants").first();
+        if (next.hasClass("compact")) {
+          next.toggle();
+          next.nextAll("dl.constants").first().toggle();
+        } else if (next.hasClass("constants")) {
+          var list = $('
    ');
+          list.html(next.html());
+          list.find("dt").each(function () {
+            $(this).addClass("summary_signature");
+            $(this).text($(this).text().split("=")[0]);
+            if ($(this).has(".deprecated").length) {
+              $(this).addClass("deprecated");
+            }
+          });
+          // Add the value of the constant as "Tooltip" to the summary object
+          list.find("pre.code").each(function () {
+            console.log($(this).parent());
+            var dt_element = $(this).parent().prev();
+            var tooltip = $(this).text();
+            if (dt_element.hasClass("deprecated")) {
+              tooltip = "Deprecated. " + tooltip;
+            }
+            dt_element.attr("title", tooltip);
+          });
+          list.find(".docstring, .tags, dd").remove();
+          next.before(list);
+          next.toggle();
+        }
+      });
+      return false;
+    });
+    if (localStorage.summaryCollapsed == "collapse") {
+      $(".constants_summary_toggle").first().click();
+    } else {
+      localStorage.summaryCollapsed = "expand";
+    }
+  }
+
+  function generateTOC() {
+    if ($("#filecontents").length === 0) return;
+    var _toc = $('
      ');
+    var show = false;
+    var toc = _toc;
+    var counter = 0;
+    var tags = ["h2", "h3", "h4", "h5", "h6"];
+    var i;
+    var curli;
+    if ($("#filecontents h1").length > 1) tags.unshift("h1");
+    for (i = 0; i < tags.length; i++) {
+      tags[i] = "#filecontents " + tags[i];
+    }
+    var lastTag = parseInt(tags[0][1], 10);
+    $(tags.join(", ")).each(function () {
+      if ($(this).parents(".method_details .docstring").length != 0) return;
+      if (this.id == "filecontents") return;
+      show = true;
+      var thisTag = parseInt(this.tagName[1], 10);
+      if (this.id.length === 0) {
+        var proposedId = $(this).attr("toc-id");
+        if (typeof proposedId != "undefined") this.id = proposedId;
+        else {
+          var proposedId = $(this)
+            .text()
+            .replace(/[^a-z0-9-]/gi, "_");
+          if ($("#" + proposedId).length > 0) {
+            proposedId += counter;
+            counter++;
+          }
+          this.id = proposedId;
+        }
+      }
+      if (thisTag > lastTag) {
+        for (i = 0; i < thisTag - lastTag; i++) {
+          if (typeof curli == "undefined") {
+            curli = $("
    1. ");
+            toc.append(curli);
+          }
+          toc = $("
        ");
+          curli.append(toc);
+          curli = undefined;
+        }
+      }
+      if (thisTag < lastTag) {
+        for (i = 0; i < lastTag - thisTag; i++) {
+          toc = toc.parent();
+          toc = toc.parent();
+        }
+      }
+      var title = $(this).attr("toc-title");
+      if (typeof title == "undefined") title = $(this).text();
+      curli = $('
      1. ' + title + "
        2. ");
+      toc.append(curli);
+      lastTag = thisTag;
+    });
+    if (!show) return;
+    html =
+      '';
+    $("#content").prepend(html);
+    $("#toc").append(_toc);
+    $("#toc .hide_toc").toggle(
+      function () {
+        $("#toc .top").slideUp("fast");
+        $("#toc").toggleClass("hidden");
+        $("#toc .title small").toggle();
+      },
+      function () {
+        $("#toc .top").slideDown("fast");
+        $("#toc").toggleClass("hidden");
+        $("#toc .title small").toggle();
+      }
+    );
+  }
+
+  function navResizeFn(e) {
+    if (e.which !== 1) {
+      navResizeFnStop();
+      return;
+    }
+
+    sessionStorage.navWidth = e.pageX.toString();
+    $(".nav_wrap").css("width", e.pageX);
+    $(".nav_wrap").css("-ms-flex", "inherit");
+  }
+
+  function navResizeFnStop() {
+    $(window).unbind("mousemove", navResizeFn);
+    window.removeEventListener("message", navMessageFn, false);
+  }
+
+  function navMessageFn(e) {
+    if (e.data.action === "mousemove") navResizeFn(e.data.event);
+    if (e.data.action === "mouseup") navResizeFnStop();
+  }
+
+  function navResizer() {
+    $("#resizer").mousedown(function (e) {
+      e.preventDefault();
+      $(window).mousemove(navResizeFn);
+      window.addEventListener("message", navMessageFn, false);
+    });
+    $(window).mouseup(navResizeFnStop);
+
+    if (sessionStorage.navWidth) {
+      navResizeFn({ which: 1, pageX: parseInt(sessionStorage.navWidth, 10) });
+    }
+  }
+
+  function navExpander() {
+    if (typeof pathId === "undefined") return;
+    var done = false,
+      timer = setTimeout(postMessage, 500);
+    function postMessage() {
+      if (done) return;
+      clearTimeout(timer);
+      var opts = { action: "expand", path: pathId };
+      document.getElementById("nav").contentWindow.postMessage(opts, "*");
+      done = true;
+    }
+
+    window.addEventListener(
+      "message",
+      function (event) {
+        if (event.data === "navReady") postMessage();
+        return false;
+      },
+      false
+    );
+  }
+
+  function mainFocus() {
+    var hash = window.location.hash;
+    if (hash !== "" && $(hash)[0]) {
+      $(hash)[0].scrollIntoView();
+    }
+
+    setTimeout(function () {
+      $("#main").focus();
+    }, 10);
+  }
+
+  function navigationChange() {
+    // This works around the broken anchor navigation with the YARD template.
+    window.onpopstate = function () {
+      var hash = window.location.hash;
+      if (hash !== "" && $(hash)[0]) {
+        $(hash)[0].scrollIntoView();
+      }
+    };
+  }
+
+  $(document).ready(function () {
+    navResizer();
+    navExpander();
+    createSourceLinks();
+    createDefineLinks();
+    createFullTreeLinks();
+    searchFrameButtons();
+    linkSummaries();
+    summaryToggle();
+    constantSummaryToggle();
+    generateTOC();
+    mainFocus();
+    navigationChange();
+  });
+})();
diff --git a/docs/js/full_list.js b/docs/js/full_list.js
new file mode 100644
index 00000000..12bba48d
--- /dev/null
+++ b/docs/js/full_list.js
@@ -0,0 +1,242 @@
+(function() {
+
+var $clicked = $(null);
+var searchTimeout = null;
+var searchCache = [];
+var caseSensitiveMatch = false;
+var ignoreKeyCodeMin = 8;
+var ignoreKeyCodeMax = 46;
+var commandKey = 91;
+
+RegExp.escape = function(text) {
+    return text.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&");
+}
+
+function escapeShortcut() {
+  $(document).keydown(function(evt) {
+    if (evt.which == 27) {
+      window.parent.postMessage('navEscape', '*');
+    }
+  });
+}
+
+function navResizer() {
+  $(window).mousemove(function(e) {
+    window.parent.postMessage({
+      action: 'mousemove', event: {pageX: e.pageX, which: e.which}
+    }, '*');
+  }).mouseup(function(e) {
+    window.parent.postMessage({action: 'mouseup'}, '*');
+  });
+  window.parent.postMessage("navReady", "*");
+}
+
+function clearSearchTimeout() {
+  clearTimeout(searchTimeout);
+  searchTimeout = null;
+}
+
+function enableLinks() {
+  // load the target page in the parent window
+  $('#full_list li').on('click', function(evt) {
+    $('#full_list li').removeClass('clicked');
+    $clicked = $(this);
+    $clicked.addClass('clicked');
+    evt.stopPropagation();
+
+    if (evt.target.tagName === 'A') return true;
+
+    var elem = $clicked.find('> .item .object_link a')[0];
+    var e = evt.originalEvent;
+    var newEvent = new MouseEvent(evt.originalEvent.type);
+    newEvent.initMouseEvent(e.type, e.canBubble, e.cancelable, e.view, e.detail, e.screenX, e.screenY, e.clientX, e.clientY, e.ctrlKey, e.altKey, e.shiftKey, e.metaKey, e.button, e.relatedTarget);
+    elem.dispatchEvent(newEvent);
+    evt.preventDefault();
+    return false;
+  });
+}
+
+function enableToggles() {
+  // show/hide nested classes on toggle click
+  $('#full_list a.toggle').on('click', function(evt) {
+    evt.stopPropagation();
+    evt.preventDefault();
+    $(this).parent().parent().toggleClass('collapsed');
+    $(this).attr('aria-expanded', function (i, attr) {
+        return attr == 'true' ? 'false' : 'true'
+    });
+    highlight();
+  });
+
+  // navigation of nested classes using keyboard
+  $('#full_list a.toggle').on('keypress',function(evt) {
+    // enter key is pressed
+    if (evt.which == 13) {
+      evt.stopPropagation();
+      evt.preventDefault();
+      $(this).parent().parent().toggleClass('collapsed');
+      $(this).attr('aria-expanded', function (i, attr) {
+          return attr == 'true' ? 'false' : 'true'
+      });
+      highlight();
+    }
+  });
+}
+
+function populateSearchCache() {
+  $('#full_list li .item').each(function() {
+    var $node = $(this);
+    var $link = $node.find('.object_link a');
+    if ($link.length > 0) {
+      searchCache.push({
+        node: $node,
+        link: $link,
+        name: $link.text(),
+        fullName: $link.attr('title').split(' ')[0]
+      });
+    }
+  });
+}
+
+function enableSearch() {
+  $('#search input').keyup(function(event) {
+    if (ignoredKeyPress(event)) return;
+    if (this.value === "") {
+      clearSearch();
+    } else {
+      performSearch(this.value);
+    }
+  });
+
+  $('#full_list').after("");
+}
+
+function ignoredKeyPress(event) {
+  if (
+    (event.keyCode > ignoreKeyCodeMin && event.keyCode < ignoreKeyCodeMax) ||
+    (event.keyCode == commandKey)
+  ) {
+    return true;
+  } else {
+    return false;
+  }
+}
+
+function clearSearch() {
+  clearSearchTimeout();
+  $('#full_list .found').removeClass('found').each(function() {
+    var $link = $(this).find('.object_link a');
+    $link.text($link.text());
+  });
+  $('#full_list, #content').removeClass('insearch');
+  $clicked.parents().removeClass('collapsed');
+  highlight();
+}
+
+function performSearch(searchString) {
+  clearSearchTimeout();
+  $('#full_list, #content').addClass('insearch');
+  $('#noresults').text('').hide();
+  partialSearch(searchString, 0);
+}
+
+function partialSearch(searchString, offset) {
+  var lastRowClass = '';
+  var i = null;
+  for (i = offset; i < Math.min(offset + 50, searchCache.length); i++) {
+    var item = searchCache[i];
+    var searchName = (searchString.indexOf('::') != -1 ? item.fullName : item.name);
+    var matchString = buildMatchString(searchString);
+    var matchRegexp = new RegExp(matchString, caseSensitiveMatch ? "" : "i");
+    if (searchName.match(matchRegexp) == null) {
+      item.node.removeClass('found');
+      item.link.text(item.link.text());
+    }
+    else {
+      item.node.addClass('found');
+      item.node.removeClass(lastRowClass).addClass(lastRowClass == 'r1' ? 'r2' : 'r1');
+      lastRowClass = item.node.hasClass('r1') ? 'r1' : 'r2';
+      item.link.html(item.name.replace(matchRegexp, "$&"));
+    }
+  }
+  if(i == searchCache.length) {
+    searchDone();
+  } else {
+    searchTimeout = setTimeout(function() {
+      partialSearch(searchString, i);
+    }, 0);
+  }
+}
+
+function searchDone() {
+  searchTimeout = null;
+  highlight();
+  var found = $('#full_list li:visible').size();
+  if (found === 0) {
+    $('#noresults').text('No results were found.');
+  } else {
+    // This is read out to screen readers
+    $('#noresults').text('There are ' + found + ' results.');
+  }
+  $('#noresults').show();
+  $('#content').removeClass('insearch');
+}
+
+function buildMatchString(searchString, event) {
+  caseSensitiveMatch = searchString.match(/[A-Z]/) != null;
+  var regexSearchString = RegExp.escape(searchString);
+  if (caseSensitiveMatch) {
+    regexSearchString += "|" +
+      $.map(searchString.split(''), function(e) { return RegExp.escape(e); }).
+      join('.+?');
+  }
+  return regexSearchString;
+}
+
+function highlight() {
+  $('#full_list li:visible').each(function(n) {
+    $(this).removeClass('even odd').addClass(n % 2 == 0 ? 'odd' : 'even');
+  });
+}
+
+/**
+ * Expands the tree to the target element and its immediate
+ * children.
+ */
+function expandTo(path) {
+  var $target = $(document.getElementById('object_' + path));
+  $target.addClass('clicked');
+  $target.removeClass('collapsed');
+  $target.parentsUntil('#full_list', 'li').removeClass('collapsed');
+
+  $target.find('a.toggle').attr('aria-expanded', 'true')
+  $target.parentsUntil('#full_list', 'li').each(function(i, el) {
+    $(el).find('> div > a.toggle').attr('aria-expanded', 'true');
+  });
+
+  if($target[0]) {
+    window.scrollTo(window.scrollX, $target.offset().top - 250);
+    highlight();
+  }
+}
+
+function windowEvents(event) {
+  var msg = event.data;
+  if (msg.action === "expand") {
+    expandTo(msg.path);
+  }
+  return false;
+}
+
+window.addEventListener("message", windowEvents, false);
+
+$(document).ready(function() {
+  escapeShortcut();
+  navResizer();
+  enableLinks();
+  enableToggles();
+  populateSearchCache();
+  enableSearch();
+});
+
+})();
diff --git a/docs/js/jquery.js b/docs/js/jquery.js
new file mode 100644
index 00000000..198b3ff0
--- /dev/null
+++ b/docs/js/jquery.js
@@ -0,0 +1,4 @@
+/*! jQuery v1.7.1 jquery.com | jquery.org/license */
+(function(a,b){function cy(a){return f.isWindow(a)?a:a.nodeType===9?a.defaultView||a.parentWindow:!1}function cv(a){if(!ck[a]){var b=c.body,d=f("<"+a+">").appendTo(b),e=d.css("display");d.remove();if(e==="none"||e===""){cl||(cl=c.createElement("iframe"),cl.frameBorder=cl.width=cl.height=0),b.appendChild(cl);if(!cm||!cl.createElement)cm=(cl.contentWindow||cl.contentDocument).document,cm.write((c.compatMode==="CSS1Compat"?"":"")+""),cm.close();d=cm.createElement(a),cm.body.appendChild(d),e=f.css(d,"display"),b.removeChild(cl)}ck[a]=e}return ck[a]}function cu(a,b){var c={};f.each(cq.concat.apply([],cq.slice(0,b)),function(){c[this]=a});return c}function ct(){cr=b}function cs(){setTimeout(ct,0);return cr=f.now()}function cj(){try{return new a.ActiveXObject("Microsoft.XMLHTTP")}catch(b){}}function ci(){try{return new a.XMLHttpRequest}catch(b){}}function cc(a,c){a.dataFilter&&(c=a.dataFilter(c,a.dataType));var d=a.dataTypes,e={},g,h,i=d.length,j,k=d[0],l,m,n,o,p;for(g=1;g0){if(c!=="border")for(;g=0===c})}function S(a){return!a||!a.parentNode||a.parentNode.nodeType===11}function K(){return!0}function J(){return!1}function n(a,b,c){var d=b+"defer",e=b+"queue",g=b+"mark",h=f._data(a,d);h&&(c==="queue"||!f._data(a,e))&&(c==="mark"||!f._data(a,g))&&setTimeout(function(){!f._data(a,e)&&!f._data(a,g)&&(f.removeData(a,d,!0),h.fire())},0)}function m(a){for(var b in a){if(b==="data"&&f.isEmptyObject(a[b]))continue;if(b!=="toJSON")return!1}return!0}function l(a,c,d){if(d===b&&a.nodeType===1){var e="data-"+c.replace(k,"-$1").toLowerCase();d=a.getAttribute(e);if(typeof d=="string"){try{d=d==="true"?!0:d==="false"?!1:d==="null"?null:f.isNumeric(d)?parseFloat(d):j.test(d)?f.parseJSON(d):d}catch(g){}f.data(a,c,d)}else d=b}return d}function h(a){var b=g[a]={},c,d;a=a.split(/\s+/);for(c=0,d=a.length;c)[^>]*$|#([\w\-]*)$)/,j=/\S/,k=/^\s+/,l=/\s+$/,m=/^<(\w+)\s*\/?>(?:<\/\1>)?$/,n=/^[\],:{}\s]*$/,o=/\\(?:["\\\/bfnrt]|u[0-9a-fA-F]{4})/g,p=/"[^"\\\n\r]*"|true|false|null|-?\d+(?:\.\d*)?(?:[eE][+\-]?\d+)?/g,q=/(?:^|:|,)(?:\s*\[)+/g,r=/(webkit)[ \/]([\w.]+)/,s=/(opera)(?:.*version)?[ \/]([\w.]+)/,t=/(msie) ([\w.]+)/,u=/(mozilla)(?:.*? rv:([\w.]+))?/,v=/-([a-z]|[0-9])/ig,w=/^-ms-/,x=function(a,b){return(b+"").toUpperCase()},y=d.userAgent,z,A,B,C=Object.prototype.toString,D=Object.prototype.hasOwnProperty,E=Array.prototype.push,F=Array.prototype.slice,G=String.prototype.trim,H=Array.prototype.indexOf,I={};e.fn=e.prototype={constructor:e,init:function(a,d,f){var g,h,j,k;if(!a)return this;if(a.nodeType){this.context=this[0]=a,this.length=1;return this}if(a==="body"&&!d&&c.body){this.context=c,this[0]=c.body,this.selector=a,this.length=1;return this}if(typeof a=="string"){a.charAt(0)!=="<"||a.charAt(a.length-1)!==">"||a.length<3?g=i.exec(a):g=[null,a,null];if(g&&(g[1]||!d)){if(g[1]){d=d instanceof e?d[0]:d,k=d?d.ownerDocument||d:c,j=m.exec(a),j?e.isPlainObject(d)?(a=[c.createElement(j[1])],e.fn.attr.call(a,d,!0)):a=[k.createElement(j[1])]:(j=e.buildFragment([g[1]],[k]),a=(j.cacheable?e.clone(j.fragment):j.fragment).childNodes);return e.merge(this,a)}h=c.getElementById(g[2]);if(h&&h.parentNode){if(h.id!==g[2])return f.find(a);this.length=1,this[0]=h}this.context=c,this.selector=a;return this}return!d||d.jquery?(d||f).find(a):this.constructor(d).find(a)}if(e.isFunction(a))return f.ready(a);a.selector!==b&&(this.selector=a.selector,this.context=a.context);return e.makeArray(a,this)},selector:"",jquery:"1.7.1",length:0,size:function(){return this.length},toArray:function(){return F.call(this,0)},get:function(a){return a==null?this.toArray():a<0?this[this.length+a]:this[a]},pushStack:function(a,b,c){var d=this.constructor();e.isArray(a)?E.apply(d,a):e.merge(d,a),d.prevObject=this,d.context=this.context,b==="find"?d.selector=this.selector+(this.selector?" ":"")+c:b&&(d.selector=this.selector+"."+b+"("+c+")");return d},each:function(a,b){return e.each(this,a,b)},ready:function(a){e.bindReady(),A.add(a);return this},eq:function(a){a=+a;return a===-1?this.slice(a):this.slice(a,a+1)},first:function(){return this.eq(0)},last:function(){return this.eq(-1)},slice:function(){return this.pushStack(F.apply(this,arguments),"slice",F.call(arguments).join(","))},map:function(a){return this.pushStack(e.map(this,function(b,c){return a.call(b,c,b)}))},end:function(){return this.prevObject||this.constructor(null)},push:E,sort:[].sort,splice:[].splice},e.fn.init.prototype=e.fn,e.extend=e.fn.extend=function(){var a,c,d,f,g,h,i=arguments[0]||{},j=1,k=arguments.length,l=!1;typeof i=="boolean"&&(l=i,i=arguments[1]||{},j=2),typeof i!="object"&&!e.isFunction(i)&&(i={}),k===j&&(i=this,--j);for(;j0)return;A.fireWith(c,[e]),e.fn.trigger&&e(c).trigger("ready").off("ready")}},bindReady:function(){if(!A){A=e.Callbacks("once memory");if(c.readyState==="complete")return setTimeout(e.ready,1);if(c.addEventListener)c.addEventListener("DOMContentLoaded",B,!1),a.addEventListener("load",e.ready,!1);else if(c.attachEvent){c.attachEvent("onreadystatechange",B),a.attachEvent("onload",e.ready);var b=!1;try{b=a.frameElement==null}catch(d){}c.documentElement.doScroll&&b&&J()}}},isFunction:function(a){return e.type(a)==="function"},isArray:Array.isArray||function(a){return e.type(a)==="array"},isWindow:function(a){return a&&typeof a=="object"&&"setInterval"in a},isNumeric:function(a){return!isNaN(parseFloat(a))&&isFinite(a)},type:function(a){return a==null?String(a):I[C.call(a)]||"object"},isPlainObject:function(a){if(!a||e.type(a)!=="object"||a.nodeType||e.isWindow(a))return!1;try{if(a.constructor&&!D.call(a,"constructor")&&!D.call(a.constructor.prototype,"isPrototypeOf"))return!1}catch(c){return!1}var d;for(d in a);return d===b||D.call(a,d)},isEmptyObject:function(a){for(var b in a)return!1;return!0},error:function(a){throw new Error(a)},parseJSON:function(b){if(typeof b!="string"||!b)return null;b=e.trim(b);if(a.JSON&&a.JSON.parse)return a.JSON.parse(b);if(n.test(b.replace(o,"@").replace(p,"]").replace(q,"")))return(new Function("return "+b))();e.error("Invalid JSON: "+b)},parseXML:function(c){var d,f;try{a.DOMParser?(f=new DOMParser,d=f.parseFromString(c,"text/xml")):(d=new ActiveXObject("Microsoft.XMLDOM"),d.async="false",d.loadXML(c))}catch(g){d=b}(!d||!d.documentElement||d.getElementsByTagName("parsererror").length)&&e.error("Invalid XML: "+c);return d},noop:function(){},globalEval:function(b){b&&j.test(b)&&(a.execScript||function(b){a.eval.call(a,b)})(b)},camelCase:function(a){return a.replace(w,"ms-").replace(v,x)},nodeName:function(a,b){return a.nodeName&&a.nodeName.toUpperCase()===b.toUpperCase()},each:function(a,c,d){var f,g=0,h=a.length,i=h===b||e.isFunction(a);if(d){if(i){for(f in a)if(c.apply(a[f],d)===!1)break}else for(;g0&&a[0]&&a[j-1]||j===0||e.isArray(a));if(k)for(;i1?i.call(arguments,0):b,j.notifyWith(k,e)}}function l(a){return function(c){b[a]=arguments.length>1?i.call(arguments,0):c,--g||j.resolveWith(j,b)}}var b=i.call(arguments,0),c=0,d=b.length,e=Array(d),g=d,h=d,j=d<=1&&a&&f.isFunction(a.promise)?a:f.Deferred(),k=j.promise();if(d>1){for(;c
        a",d=q.getElementsByTagName("*"),e=q.getElementsByTagName("a")[0];if(!d||!d.length||!e)return{};g=c.createElement("select"),h=g.appendChild(c.createElement("option")),i=q.getElementsByTagName("input")[0],b={leadingWhitespace:q.firstChild.nodeType===3,tbody:!q.getElementsByTagName("tbody").length,htmlSerialize:!!q.getElementsByTagName("link").length,style:/top/.test(e.getAttribute("style")),hrefNormalized:e.getAttribute("href")==="/a",opacity:/^0.55/.test(e.style.opacity),cssFloat:!!e.style.cssFloat,checkOn:i.value==="on",optSelected:h.selected,getSetAttribute:q.className!=="t",enctype:!!c.createElement("form").enctype,html5Clone:c.createElement("nav").cloneNode(!0).outerHTML!=="<:nav>",submitBubbles:!0,changeBubbles:!0,focusinBubbles:!1,deleteExpando:!0,noCloneEvent:!0,inlineBlockNeedsLayout:!1,shrinkWrapBlocks:!1,reliableMarginRight:!0},i.checked=!0,b.noCloneChecked=i.cloneNode(!0).checked,g.disabled=!0,b.optDisabled=!h.disabled;try{delete q.test}catch(s){b.deleteExpando=!1}!q.addEventListener&&q.attachEvent&&q.fireEvent&&(q.attachEvent("onclick",function(){b.noCloneEvent=!1}),q.cloneNode(!0).fireEvent("onclick")),i=c.createElement("input"),i.value="t",i.setAttribute("type","radio"),b.radioValue=i.value==="t",i.setAttribute("checked","checked"),q.appendChild(i),k=c.createDocumentFragment(),k.appendChild(q.lastChild),b.checkClone=k.cloneNode(!0).cloneNode(!0).lastChild.checked,b.appendChecked=i.checked,k.removeChild(i),k.appendChild(q),q.innerHTML="",a.getComputedStyle&&(j=c.createElement("div"),j.style.width="0",j.style.marginRight="0",q.style.width="2px",q.appendChild(j),b.reliableMarginRight=(parseInt((a.getComputedStyle(j,null)||{marginRight:0}).marginRight,10)||0)===0);if(q.attachEvent)for(o in{submit:1,change:1,focusin:1})n="on"+o,p=n in q,p||(q.setAttribute(n,"return;"),p=typeof q[n]=="function"),b[o+"Bubbles"]=p;k.removeChild(q),k=g=h=j=q=i=null,f(function(){var a,d,e,g,h,i,j,k,m,n,o,r=c.getElementsByTagName("body")[0];!r||(j=1,k="position:absolute;top:0;left:0;width:1px;height:1px;margin:0;",m="visibility:hidden;border:0;",n="style='"+k+"border:5px solid #000;padding:0;'",o="
        "+""+"
        ",a=c.createElement("div"),a.style.cssText=m+"width:0;height:0;position:static;top:0;margin-top:"+j+"px",r.insertBefore(a,r.firstChild),q=c.createElement("div"),a.appendChild(q),q.innerHTML="
        t
        ",l=q.getElementsByTagName("td"),p=l[0].offsetHeight===0,l[0].style.display="",l[1].style.display="none",b.reliableHiddenOffsets=p&&l[0].offsetHeight===0,q.innerHTML="",q.style.width=q.style.paddingLeft="1px",f.boxModel=b.boxModel=q.offsetWidth===2,typeof q.style.zoom!="undefined"&&(q.style.display="inline",q.style.zoom=1,b.inlineBlockNeedsLayout=q.offsetWidth===2,q.style.display="",q.innerHTML="
        ",b.shrinkWrapBlocks=q.offsetWidth!==2),q.style.cssText=k+m,q.innerHTML=o,d=q.firstChild,e=d.firstChild,h=d.nextSibling.firstChild.firstChild,i={doesNotAddBorder:e.offsetTop!==5,doesAddBorderForTableAndCells:h.offsetTop===5},e.style.position="fixed",e.style.top="20px",i.fixedPosition=e.offsetTop===20||e.offsetTop===15,e.style.position=e.style.top="",d.style.overflow="hidden",d.style.position="relative",i.subtractsBorderForOverflowNotVisible=e.offsetTop===-5,i.doesNotIncludeMarginInBodyOffset=r.offsetTop!==j,r.removeChild(a),q=a=null,f.extend(b,i))});return b}();var j=/^(?:\{.*\}|\[.*\])$/,k=/([A-Z])/g;f.extend({cache:{},uuid:0,expando:"jQuery"+(f.fn.jquery+Math.random()).replace(/\D/g,""),noData:{embed:!0,object:"clsid:D27CDB6E-AE6D-11cf-96B8-444553540000",applet:!0},hasData:function(a){a=a.nodeType?f.cache[a[f.expando]]:a[f.expando];return!!a&&!m(a)},data:function(a,c,d,e){if(!!f.acceptData(a)){var g,h,i,j=f.expando,k=typeof c=="string",l=a.nodeType,m=l?f.cache:a,n=l?a[j]:a[j]&&j,o=c==="events";if((!n||!m[n]||!o&&!e&&!m[n].data)&&k&&d===b)return;n||(l?a[j]=n=++f.uuid:n=j),m[n]||(m[n]={},l||(m[n].toJSON=f.noop));if(typeof c=="object"||typeof c=="function")e?m[n]=f.extend(m[n],c):m[n].data=f.extend(m[n].data,c);g=h=m[n],e||(h.data||(h.data={}),h=h.data),d!==b&&(h[f.camelCase(c)]=d);if(o&&!h[c])return g.events;k?(i=h[c],i==null&&(i=h[f.camelCase(c)])):i=h;return i}},removeData:function(a,b,c){if(!!f.acceptData(a)){var d,e,g,h=f.expando,i=a.nodeType,j=i?f.cache:a,k=i?a[h]:h;if(!j[k])return;if(b){d=c?j[k]:j[k].data;if(d){f.isArray(b)||(b in d?b=[b]:(b=f.camelCase(b),b in d?b=[b]:b=b.split(" ")));for(e=0,g=b.length;e-1)return!0;return!1},val:function(a){var c,d,e,g=this[0];{if(!!arguments.length){e=f.isFunction(a);return this.each(function(d){var g=f(this),h;if(this.nodeType===1){e?h=a.call(this,d,g.val()):h=a,h==null?h="":typeof h=="number"?h+="":f.isArray(h)&&(h=f.map(h,function(a){return a==null?"":a+""})),c=f.valHooks[this.nodeName.toLowerCase()]||f.valHooks[this.type];if(!c||!("set"in c)||c.set(this,h,"value")===b)this.value=h}})}if(g){c=f.valHooks[g.nodeName.toLowerCase()]||f.valHooks[g.type];if(c&&"get"in c&&(d=c.get(g,"value"))!==b)return d;d=g.value;return typeof d=="string"?d.replace(q,""):d==null?"":d}}}}),f.extend({valHooks:{option:{get:function(a){var b=a.attributes.value;return!b||b.specified?a.value:a.text}},select:{get:function(a){var b,c,d,e,g=a.selectedIndex,h=[],i=a.options,j=a.type==="select-one";if(g<0)return null;c=j?g:0,d=j?g+1:i.length;for(;c=0}),c.length||(a.selectedIndex=-1);return c}}},attrFn:{val:!0,css:!0,html:!0,text:!0,data:!0,width:!0,height:!0,offset:!0},attr:function(a,c,d,e){var g,h,i,j=a.nodeType;if(!!a&&j!==3&&j!==8&&j!==2){if(e&&c in f.attrFn)return f(a)[c](d);if(typeof a.getAttribute=="undefined")return f.prop(a,c,d);i=j!==1||!f.isXMLDoc(a),i&&(c=c.toLowerCase(),h=f.attrHooks[c]||(u.test(c)?x:w));if(d!==b){if(d===null){f.removeAttr(a,c);return}if(h&&"set"in h&&i&&(g=h.set(a,d,c))!==b)return g;a.setAttribute(c,""+d);return d}if(h&&"get"in h&&i&&(g=h.get(a,c))!==null)return g;g=a.getAttribute(c);return g===null?b:g}},removeAttr:function(a,b){var c,d,e,g,h=0;if(b&&a.nodeType===1){d=b.toLowerCase().split(p),g=d.length;for(;h=0}})});var z=/^(?:textarea|input|select)$/i,A=/^([^\.]*)?(?:\.(.+))?$/,B=/\bhover(\.\S+)?\b/,C=/^key/,D=/^(?:mouse|contextmenu)|click/,E=/^(?:focusinfocus|focusoutblur)$/,F=/^(\w*)(?:#([\w\-]+))?(?:\.([\w\-]+))?$/,G=function(a){var b=F.exec(a);b&&(b[1]=(b[1]||"").toLowerCase(),b[3]=b[3]&&new RegExp("(?:^|\\s)"+b[3]+"(?:\\s|$)"));return b},H=function(a,b){var c=a.attributes||{};return(!b[1]||a.nodeName.toLowerCase()===b[1])&&(!b[2]||(c.id||{}).value===b[2])&&(!b[3]||b[3].test((c["class"]||{}).value))},I=function(a){return f.event.special.hover?a:a.replace(B,"mouseenter$1 mouseleave$1")};
+f.event={add:function(a,c,d,e,g){var h,i,j,k,l,m,n,o,p,q,r,s;if(!(a.nodeType===3||a.nodeType===8||!c||!d||!(h=f._data(a)))){d.handler&&(p=d,d=p.handler),d.guid||(d.guid=f.guid++),j=h.events,j||(h.events=j={}),i=h.handle,i||(h.handle=i=function(a){return typeof f!="undefined"&&(!a||f.event.triggered!==a.type)?f.event.dispatch.apply(i.elem,arguments):b},i.elem=a),c=f.trim(I(c)).split(" ");for(k=0;k=0&&(h=h.slice(0,-1),k=!0),h.indexOf(".")>=0&&(i=h.split("."),h=i.shift(),i.sort());if((!e||f.event.customEvent[h])&&!f.event.global[h])return;c=typeof c=="object"?c[f.expando]?c:new f.Event(h,c):new f.Event(h),c.type=h,c.isTrigger=!0,c.exclusive=k,c.namespace=i.join("."),c.namespace_re=c.namespace?new RegExp("(^|\\.)"+i.join("\\.(?:.*\\.)?")+"(\\.|$)"):null,o=h.indexOf(":")<0?"on"+h:"";if(!e){j=f.cache;for(l in j)j[l].events&&j[l].events[h]&&f.event.trigger(c,d,j[l].handle.elem,!0);return}c.result=b,c.target||(c.target=e),d=d!=null?f.makeArray(d):[],d.unshift(c),p=f.event.special[h]||{};if(p.trigger&&p.trigger.apply(e,d)===!1)return;r=[[e,p.bindType||h]];if(!g&&!p.noBubble&&!f.isWindow(e)){s=p.delegateType||h,m=E.test(s+h)?e:e.parentNode,n=null;for(;m;m=m.parentNode)r.push([m,s]),n=m;n&&n===e.ownerDocument&&r.push([n.defaultView||n.parentWindow||a,s])}for(l=0;le&&i.push({elem:this,matches:d.slice(e)});for(j=0;j0?this.on(b,null,a,c):this.trigger(b)},f.attrFn&&(f.attrFn[b]=!0),C.test(b)&&(f.event.fixHooks[b]=f.event.keyHooks),D.test(b)&&(f.event.fixHooks[b]=f.event.mouseHooks)}),function(){function x(a,b,c,e,f,g){for(var h=0,i=e.length;h0){k=j;break}}j=j[a]}e[h]=k}}}function w(a,b,c,e,f,g){for(var h=0,i=e.length;h+~,(\[\\]+)+|[>+~])(\s*,\s*)?((?:.|\r|\n)*)/g,d="sizcache"+(Math.random()+"").replace(".",""),e=0,g=Object.prototype.toString,h=!1,i=!0,j=/\\/g,k=/\r\n/g,l=/\W/;[0,0].sort(function(){i=!1;return 0});var m=function(b,d,e,f){e=e||[],d=d||c;var h=d;if(d.nodeType!==1&&d.nodeType!==9)return[];if(!b||typeof b!="string")return e;var i,j,k,l,n,q,r,t,u=!0,v=m.isXML(d),w=[],x=b;do{a.exec(""),i=a.exec(x);if(i){x=i[3],w.push(i[1]);if(i[2]){l=i[3];break}}}while(i);if(w.length>1&&p.exec(b))if(w.length===2&&o.relative[w[0]])j=y(w[0]+w[1],d,f);else{j=o.relative[w[0]]?[d]:m(w.shift(),d);while(w.length)b=w.shift(),o.relative[b]&&(b+=w.shift()),j=y(b,j,f)}else{!f&&w.length>1&&d.nodeType===9&&!v&&o.match.ID.test(w[0])&&!o.match.ID.test(w[w.length-1])&&(n=m.find(w.shift(),d,v),d=n.expr?m.filter(n.expr,n.set)[0]:n.set[0]);if(d){n=f?{expr:w.pop(),set:s(f)}:m.find(w.pop(),w.length===1&&(w[0]==="~"||w[0]==="+")&&d.parentNode?d.parentNode:d,v),j=n.expr?m.filter(n.expr,n.set):n.set,w.length>0?k=s(j):u=!1;while(w.length)q=w.pop(),r=q,o.relative[q]?r=w.pop():q="",r==null&&(r=d),o.relative[q](k,r,v)}else k=w=[]}k||(k=j),k||m.error(q||b);if(g.call(k)==="[object Array]")if(!u)e.push.apply(e,k);else if(d&&d.nodeType===1)for(t=0;k[t]!=null;t++)k[t]&&(k[t]===!0||k[t].nodeType===1&&m.contains(d,k[t]))&&e.push(j[t]);else for(t=0;k[t]!=null;t++)k[t]&&k[t].nodeType===1&&e.push(j[t]);else s(k,e);l&&(m(l,h,e,f),m.uniqueSort(e));return e};m.uniqueSort=function(a){if(u){h=i,a.sort(u);if(h)for(var b=1;b0},m.find=function(a,b,c){var d,e,f,g,h,i;if(!a)return[];for(e=0,f=o.order.length;e":function(a,b){var c,d=typeof b=="string",e=0,f=a.length;if(d&&!l.test(b)){b=b.toLowerCase();for(;e=0)?c||d.push(h):c&&(b[g]=!1));return!1},ID:function(a){return a[1].replace(j,"")},TAG:function(a,b){return a[1].replace(j,"").toLowerCase()},CHILD:function(a){if(a[1]==="nth"){a[2]||m.error(a[0]),a[2]=a[2].replace(/^\+|\s*/g,"");var b=/(-?)(\d*)(?:n([+\-]?\d*))?/.exec(a[2]==="even"&&"2n"||a[2]==="odd"&&"2n+1"||!/\D/.test(a[2])&&"0n+"+a[2]||a[2]);a[2]=b[1]+(b[2]||1)-0,a[3]=b[3]-0}else a[2]&&m.error(a[0]);a[0]=e++;return a},ATTR:function(a,b,c,d,e,f){var g=a[1]=a[1].replace(j,"");!f&&o.attrMap[g]&&(a[1]=o.attrMap[g]),a[4]=(a[4]||a[5]||"").replace(j,""),a[2]==="~="&&(a[4]=" "+a[4]+" ");return a},PSEUDO:function(b,c,d,e,f){if(b[1]==="not")if((a.exec(b[3])||"").length>1||/^\w/.test(b[3]))b[3]=m(b[3],null,null,c);else{var g=m.filter(b[3],c,d,!0^f);d||e.push.apply(e,g);return!1}else if(o.match.POS.test(b[0])||o.match.CHILD.test(b[0]))return!0;return b},POS:function(a){a.unshift(!0);return a}},filters:{enabled:function(a){return a.disabled===!1&&a.type!=="hidden"},disabled:function(a){return a.disabled===!0},checked:function(a){return a.checked===!0},selected:function(a){a.parentNode&&a.parentNode.selectedIndex;return a.selected===!0},parent:function(a){return!!a.firstChild},empty:function(a){return!a.firstChild},has:function(a,b,c){return!!m(c[3],a).length},header:function(a){return/h\d/i.test(a.nodeName)},text:function(a){var b=a.getAttribute("type"),c=a.type;return a.nodeName.toLowerCase()==="input"&&"text"===c&&(b===c||b===null)},radio:function(a){return a.nodeName.toLowerCase()==="input"&&"radio"===a.type},checkbox:function(a){return a.nodeName.toLowerCase()==="input"&&"checkbox"===a.type},file:function(a){return a.nodeName.toLowerCase()==="input"&&"file"===a.type},password:function(a){return a.nodeName.toLowerCase()==="input"&&"password"===a.type},submit:function(a){var b=a.nodeName.toLowerCase();return(b==="input"||b==="button")&&"submit"===a.type},image:function(a){return a.nodeName.toLowerCase()==="input"&&"image"===a.type},reset:function(a){var b=a.nodeName.toLowerCase();return(b==="input"||b==="button")&&"reset"===a.type},button:function(a){var b=a.nodeName.toLowerCase();return b==="input"&&"button"===a.type||b==="button"},input:function(a){return/input|select|textarea|button/i.test(a.nodeName)},focus:function(a){return a===a.ownerDocument.activeElement}},setFilters:{first:function(a,b){return b===0},last:function(a,b,c,d){return b===d.length-1},even:function(a,b){return b%2===0},odd:function(a,b){return b%2===1},lt:function(a,b,c){return bc[3]-0},nth:function(a,b,c){return c[3]-0===b},eq:function(a,b,c){return c[3]-0===b}},filter:{PSEUDO:function(a,b,c,d){var e=b[1],f=o.filters[e];if(f)return f(a,c,b,d);if(e==="contains")return(a.textContent||a.innerText||n([a])||"").indexOf(b[3])>=0;if(e==="not"){var g=b[3];for(var h=0,i=g.length;h=0}},ID:function(a,b){return a.nodeType===1&&a.getAttribute("id")===b},TAG:function(a,b){return b==="*"&&a.nodeType===1||!!a.nodeName&&a.nodeName.toLowerCase()===b},CLASS:function(a,b){return(" "+(a.className||a.getAttribute("class"))+" ").indexOf(b)>-1},ATTR:function(a,b){var c=b[1],d=m.attr?m.attr(a,c):o.attrHandle[c]?o.attrHandle[c](a):a[c]!=null?a[c]:a.getAttribute(c),e=d+"",f=b[2],g=b[4];return d==null?f==="!=":!f&&m.attr?d!=null:f==="="?e===g:f==="*="?e.indexOf(g)>=0:f==="~="?(" "+e+" ").indexOf(g)>=0:g?f==="!="?e!==g:f==="^="?e.indexOf(g)===0:f==="$="?e.substr(e.length-g.length)===g:f==="|="?e===g||e.substr(0,g.length+1)===g+"-":!1:e&&d!==!1},POS:function(a,b,c,d){var e=b[2],f=o.setFilters[e];if(f)return f(a,c,b,d)}}},p=o.match.POS,q=function(a,b){return"\\"+(b-0+1)};for(var r in o.match)o.match[r]=new RegExp(o.match[r].source+/(?![^\[]*\])(?![^\(]*\))/.source),o.leftMatch[r]=new RegExp(/(^(?:.|\r|\n)*?)/.source+o.match[r].source.replace(/\\(\d+)/g,q));var s=function(a,b){a=Array.prototype.slice.call(a,0);if(b){b.push.apply(b,a);return b}return a};try{Array.prototype.slice.call(c.documentElement.childNodes,0)[0].nodeType}catch(t){s=function(a,b){var c=0,d=b||[];if(g.call(a)==="[object Array]")Array.prototype.push.apply(d,a);else if(typeof a.length=="number")for(var e=a.length;c",e.insertBefore(a,e.firstChild),c.getElementById(d)&&(o.find.ID=function(a,c,d){if(typeof c.getElementById!="undefined"&&!d){var e=c.getElementById(a[1]);return e?e.id===a[1]||typeof e.getAttributeNode!="undefined"&&e.getAttributeNode("id").nodeValue===a[1]?[e]:b:[]}},o.filter.ID=function(a,b){var c=typeof a.getAttributeNode!="undefined"&&a.getAttributeNode("id");return a.nodeType===1&&c&&c.nodeValue===b}),e.removeChild(a),e=a=null}(),function(){var a=c.createElement("div");a.appendChild(c.createComment("")),a.getElementsByTagName("*").length>0&&(o.find.TAG=function(a,b){var c=b.getElementsByTagName(a[1]);if(a[1]==="*"){var d=[];for(var e=0;c[e];e++)c[e].nodeType===1&&d.push(c[e]);c=d}return c}),a.innerHTML="",a.firstChild&&typeof a.firstChild.getAttribute!="undefined"&&a.firstChild.getAttribute("href")!=="#"&&(o.attrHandle.href=function(a){return a.getAttribute("href",2)}),a=null}(),c.querySelectorAll&&function(){var a=m,b=c.createElement("div"),d="__sizzle__";b.innerHTML="
        ";if(!b.querySelectorAll||b.querySelectorAll(".TEST").length!==0){m=function(b,e,f,g){e=e||c;if(!g&&!m.isXML(e)){var h=/^(\w+$)|^\.([\w\-]+$)|^#([\w\-]+$)/.exec(b);if(h&&(e.nodeType===1||e.nodeType===9)){if(h[1])return s(e.getElementsByTagName(b),f);if(h[2]&&o.find.CLASS&&e.getElementsByClassName)return s(e.getElementsByClassName(h[2]),f)}if(e.nodeType===9){if(b==="body"&&e.body)return s([e.body],f);if(h&&h[3]){var i=e.getElementById(h[3]);if(!i||!i.parentNode)return s([],f);if(i.id===h[3])return s([i],f)}try{return s(e.querySelectorAll(b),f)}catch(j){}}else if(e.nodeType===1&&e.nodeName.toLowerCase()!=="object"){var k=e,l=e.getAttribute("id"),n=l||d,p=e.parentNode,q=/^\s*[+~]/.test(b);l?n=n.replace(/'/g,"\\$&"):e.setAttribute("id",n),q&&p&&(e=e.parentNode);try{if(!q||p)return s(e.querySelectorAll("[id='"+n+"'] "+b),f)}catch(r){}finally{l||k.removeAttribute("id")}}}return a(b,e,f,g)};for(var e in a)m[e]=a[e];b=null}}(),function(){var a=c.documentElement,b=a.matchesSelector||a.mozMatchesSelector||a.webkitMatchesSelector||a.msMatchesSelector;if(b){var d=!b.call(c.createElement("div"),"div"),e=!1;try{b.call(c.documentElement,"[test!='']:sizzle")}catch(f){e=!0}m.matchesSelector=function(a,c){c=c.replace(/\=\s*([^'"\]]*)\s*\]/g,"='$1']");if(!m.isXML(a))try{if(e||!o.match.PSEUDO.test(c)&&!/!=/.test(c)){var f=b.call(a,c);if(f||!d||a.document&&a.document.nodeType!==11)return f}}catch(g){}return m(c,null,null,[a]).length>0}}}(),function(){var a=c.createElement("div");a.innerHTML="
        ";if(!!a.getElementsByClassName&&a.getElementsByClassName("e").length!==0){a.lastChild.className="e";if(a.getElementsByClassName("e").length===1)return;o.order.splice(1,0,"CLASS"),o.find.CLASS=function(a,b,c){if(typeof b.getElementsByClassName!="undefined"&&!c)return b.getElementsByClassName(a[1])},a=null}}(),c.documentElement.contains?m.contains=function(a,b){return a!==b&&(a.contains?a.contains(b):!0)}:c.documentElement.compareDocumentPosition?m.contains=function(a,b){return!!(a.compareDocumentPosition(b)&16)}:m.contains=function(){return!1},m.isXML=function(a){var b=(a?a.ownerDocument||a:0).documentElement;return b?b.nodeName!=="HTML":!1};var y=function(a,b,c){var d,e=[],f="",g=b.nodeType?[b]:b;while(d=o.match.PSEUDO.exec(a))f+=d[0],a=a.replace(o.match.PSEUDO,"");a=o.relative[a]?a+"*":a;for(var h=0,i=g.length;h0)for(h=g;h=0:f.filter(a,this).length>0:this.filter(a).length>0)},closest:function(a,b){var c=[],d,e,g=this[0];if(f.isArray(a)){var h=1;while(g&&g.ownerDocument&&g!==b){for(d=0;d-1:f.find.matchesSelector(g,a)){c.push(g);break}g=g.parentNode;if(!g||!g.ownerDocument||g===b||g.nodeType===11)break}}c=c.length>1?f.unique(c):c;return this.pushStack(c,"closest",a)},index:function(a){if(!a)return this[0]&&this[0].parentNode?this.prevAll().length:-1;if(typeof a=="string")return f.inArray(this[0],f(a));return f.inArray(a.jquery?a[0]:a,this)},add:function(a,b){var c=typeof a=="string"?f(a,b):f.makeArray(a&&a.nodeType?[a]:a),d=f.merge(this.get(),c);return this.pushStack(S(c[0])||S(d[0])?d:f.unique(d))},andSelf:function(){return this.add(this.prevObject)}}),f.each({parent:function(a){var b=a.parentNode;return b&&b.nodeType!==11?b:null},parents:function(a){return f.dir(a,"parentNode")},parentsUntil:function(a,b,c){return f.dir(a,"parentNode",c)},next:function(a){return f.nth(a,2,"nextSibling")},prev:function(a){return f.nth(a,2,"previousSibling")},nextAll:function(a){return f.dir(a,"nextSibling")},prevAll:function(a){return f.dir(a,"previousSibling")},nextUntil:function(a,b,c){return f.dir(a,"nextSibling",c)},prevUntil:function(a,b,c){return f.dir(a,"previousSibling",c)},siblings:function(a){return f.sibling(a.parentNode.firstChild,a)},children:function(a){return f.sibling(a.firstChild)},contents:function(a){return f.nodeName(a,"iframe")?a.contentDocument||a.contentWindow.document:f.makeArray(a.childNodes)}},function(a,b){f.fn[a]=function(c,d){var e=f.map(this,b,c);L.test(a)||(d=c),d&&typeof d=="string"&&(e=f.filter(d,e)),e=this.length>1&&!R[a]?f.unique(e):e,(this.length>1||N.test(d))&&M.test(a)&&(e=e.reverse());return this.pushStack(e,a,P.call(arguments).join(","))}}),f.extend({filter:function(a,b,c){c&&(a=":not("+a+")");return b.length===1?f.find.matchesSelector(b[0],a)?[b[0]]:[]:f.find.matches(a,b)},dir:function(a,c,d){var e=[],g=a[c];while(g&&g.nodeType!==9&&(d===b||g.nodeType!==1||!f(g).is(d)))g.nodeType===1&&e.push(g),g=g[c];return e},nth:function(a,b,c,d){b=b||1;var e=0;for(;a;a=a[c])if(a.nodeType===1&&++e===b)break;return a},sibling:function(a,b){var c=[];for(;a;a=a.nextSibling)a.nodeType===1&&a!==b&&c.push(a);return c}});var V="abbr|article|aside|audio|canvas|datalist|details|figcaption|figure|footer|header|hgroup|mark|meter|nav|output|progress|section|summary|time|video",W=/ jQuery\d+="(?:\d+|null)"/g,X=/^\s+/,Y=/<(?!area|br|col|embed|hr|img|input|link|meta|param)(([\w:]+)[^>]*)\/>/ig,Z=/<([\w:]+)/,$=/
    ","
    "],tr:[2,"","
    "],td:[3,"","
    "],col:[2,"","
    "],area:[1,"",""],_default:[0,"",""]},bh=U(c);bg.optgroup=bg.option,bg.tbody=bg.tfoot=bg.colgroup=bg.caption=bg.thead,bg.th=bg.td,f.support.htmlSerialize||(bg._default=[1,"div
    ","
    "]),f.fn.extend({text:function(a){if(f.isFunction(a))return this.each(function(b){var c=f(this);c.text(a.call(this,b,c.text()))});if(typeof a!="object"&&a!==b)return this.empty().append((this[0]&&this[0].ownerDocument||c).createTextNode(a));return f.text(this)},wrapAll:function(a){if(f.isFunction(a))return this.each(function(b){f(this).wrapAll(a.call(this,b))});if(this[0]){var b=f(a,this[0].ownerDocument).eq(0).clone(!0);this[0].parentNode&&b.insertBefore(this[0]),b.map(function(){var a=this;while(a.firstChild&&a.firstChild.nodeType===1)a=a.firstChild;return a}).append(this)}return this},wrapInner:function(a){if(f.isFunction(a))return this.each(function(b){f(this).wrapInner(a.call(this,b))});return this.each(function(){var b=f(this),c=b.contents();c.length?c.wrapAll(a):b.append(a)})},wrap:function(a){var b=f.isFunction(a);return this.each(function(c){f(this).wrapAll(b?a.call(this,c):a)})},unwrap:function(){return this.parent().each(function(){f.nodeName(this,"body")||f(this).replaceWith(this.childNodes)}).end()},append:function(){return this.domManip(arguments,!0,function(a){this.nodeType===1&&this.appendChild(a)})},prepend:function(){return this.domManip(arguments,!0,function(a){this.nodeType===1&&this.insertBefore(a,this.firstChild)})},before:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this)});if(arguments.length){var a=f.clean(arguments);a.push.apply(a,this.toArray());return this.pushStack(a,"before",arguments)}},after:function(){if(this[0]&&this[0].parentNode)return this.domManip(arguments,!1,function(a){this.parentNode.insertBefore(a,this.nextSibling)});if(arguments.length){var a=this.pushStack(this,"after",arguments);a.push.apply(a,f.clean(arguments));return a}},remove:function(a,b){for(var c=0,d;(d=this[c])!=null;c++)if(!a||f.filter(a,[d]).length)!b&&d.nodeType===1&&(f.cleanData(d.getElementsByTagName("*")),f.cleanData([d])),d.parentNode&&d.parentNode.removeChild(d);return this},empty:function() +{for(var a=0,b;(b=this[a])!=null;a++){b.nodeType===1&&f.cleanData(b.getElementsByTagName("*"));while(b.firstChild)b.removeChild(b.firstChild)}return this},clone:function(a,b){a=a==null?!1:a,b=b==null?a:b;return this.map(function(){return f.clone(this,a,b)})},html:function(a){if(a===b)return this[0]&&this[0].nodeType===1?this[0].innerHTML.replace(W,""):null;if(typeof a=="string"&&!ba.test(a)&&(f.support.leadingWhitespace||!X.test(a))&&!bg[(Z.exec(a)||["",""])[1].toLowerCase()]){a=a.replace(Y,"<$1>");try{for(var c=0,d=this.length;c1&&l0?this.clone(!0):this).get();f(e[h])[b](j),d=d.concat(j)}return this.pushStack(d,a,e.selector)}}),f.extend({clone:function(a,b,c){var d,e,g,h=f.support.html5Clone||!bc.test("<"+a.nodeName)?a.cloneNode(!0):bo(a);if((!f.support.noCloneEvent||!f.support.noCloneChecked)&&(a.nodeType===1||a.nodeType===11)&&!f.isXMLDoc(a)){bk(a,h),d=bl(a),e=bl(h);for(g=0;d[g];++g)e[g]&&bk(d[g],e[g])}if(b){bj(a,h);if(c){d=bl(a),e=bl(h);for(g=0;d[g];++g)bj(d[g],e[g])}}d=e=null;return h},clean:function(a,b,d,e){var g;b=b||c,typeof b.createElement=="undefined"&&(b=b.ownerDocument||b[0]&&b[0].ownerDocument||c);var h=[],i;for(var j=0,k;(k=a[j])!=null;j++){typeof k=="number"&&(k+="");if(!k)continue;if(typeof k=="string")if(!_.test(k))k=b.createTextNode(k);else{k=k.replace(Y,"<$1>");var l=(Z.exec(k)||["",""])[1].toLowerCase(),m=bg[l]||bg._default,n=m[0],o=b.createElement("div");b===c?bh.appendChild(o):U(b).appendChild(o),o.innerHTML=m[1]+k+m[2];while(n--)o=o.lastChild;if(!f.support.tbody){var p=$.test(k),q=l==="table"&&!p?o.firstChild&&o.firstChild.childNodes:m[1]===""&&!p?o.childNodes:[];for(i=q.length-1;i>=0;--i)f.nodeName(q[i],"tbody")&&!q[i].childNodes.length&&q[i].parentNode.removeChild(q[i])}!f.support.leadingWhitespace&&X.test(k)&&o.insertBefore(b.createTextNode(X.exec(k)[0]),o.firstChild),k=o.childNodes}var r;if(!f.support.appendChecked)if(k[0]&&typeof (r=k.length)=="number")for(i=0;i=0)return b+"px"}}}),f.support.opacity||(f.cssHooks.opacity={get:function(a,b){return br.test((b&&a.currentStyle?a.currentStyle.filter:a.style.filter)||"")?parseFloat(RegExp.$1)/100+"":b?"1":""},set:function(a,b){var c=a.style,d=a.currentStyle,e=f.isNumeric(b)?"alpha(opacity="+b*100+")":"",g=d&&d.filter||c.filter||"";c.zoom=1;if(b>=1&&f.trim(g.replace(bq,""))===""){c.removeAttribute("filter");if(d&&!d.filter)return}c.filter=bq.test(g)?g.replace(bq,e):g+" "+e}}),f(function(){f.support.reliableMarginRight||(f.cssHooks.marginRight={get:function(a,b){var c;f.swap(a,{display:"inline-block"},function(){b?c=bz(a,"margin-right","marginRight"):c=a.style.marginRight});return c}})}),c.defaultView&&c.defaultView.getComputedStyle&&(bA=function(a,b){var c,d,e;b=b.replace(bs,"-$1").toLowerCase(),(d=a.ownerDocument.defaultView)&&(e=d.getComputedStyle(a,null))&&(c=e.getPropertyValue(b),c===""&&!f.contains(a.ownerDocument.documentElement,a)&&(c=f.style(a,b)));return c}),c.documentElement.currentStyle&&(bB=function(a,b){var c,d,e,f=a.currentStyle&&a.currentStyle[b],g=a.style;f===null&&g&&(e=g[b])&&(f=e),!bt.test(f)&&bu.test(f)&&(c=g.left,d=a.runtimeStyle&&a.runtimeStyle.left,d&&(a.runtimeStyle.left=a.currentStyle.left),g.left=b==="fontSize"?"1em":f||0,f=g.pixelLeft+"px",g.left=c,d&&(a.runtimeStyle.left=d));return f===""?"auto":f}),bz=bA||bB,f.expr&&f.expr.filters&&(f.expr.filters.hidden=function(a){var b=a.offsetWidth,c=a.offsetHeight;return b===0&&c===0||!f.support.reliableHiddenOffsets&&(a.style&&a.style.display||f.css(a,"display"))==="none"},f.expr.filters.visible=function(a){return!f.expr.filters.hidden(a)});var bD=/%20/g,bE=/\[\]$/,bF=/\r?\n/g,bG=/#.*$/,bH=/^(.*?):[ \t]*([^\r\n]*)\r?$/mg,bI=/^(?:color|date|datetime|datetime-local|email|hidden|month|number|password|range|search|tel|text|time|url|week)$/i,bJ=/^(?:about|app|app\-storage|.+\-extension|file|res|widget):$/,bK=/^(?:GET|HEAD)$/,bL=/^\/\//,bM=/\?/,bN=/)<[^<]*)*<\/script>/gi,bO=/^(?:select|textarea)/i,bP=/\s+/,bQ=/([?&])_=[^&]*/,bR=/^([\w\+\.\-]+:)(?:\/\/([^\/?#:]*)(?::(\d+))?)?/,bS=f.fn.load,bT={},bU={},bV,bW,bX=["*/"]+["*"];try{bV=e.href}catch(bY){bV=c.createElement("a"),bV.href="",bV=bV.href}bW=bR.exec(bV.toLowerCase())||[],f.fn.extend({load:function(a,c,d){if(typeof a!="string"&&bS)return bS.apply(this,arguments);if(!this.length)return this;var e=a.indexOf(" ");if(e>=0){var g=a.slice(e,a.length);a=a.slice(0,e)}var h="GET";c&&(f.isFunction(c)?(d=c,c=b):typeof c=="object"&&(c=f.param(c,f.ajaxSettings.traditional),h="POST"));var i=this;f.ajax({url:a,type:h,dataType:"html",data:c,complete:function(a,b,c){c=a.responseText,a.isResolved()&&(a.done(function(a){c=a}),i.html(g?f("
    ").append(c.replace(bN,"")).find(g):c)),d&&i.each(d,[c,b,a])}});return this},serialize:function(){return f.param(this.serializeArray())},serializeArray:function(){return this.map(function(){return this.elements?f.makeArray(this.elements):this}).filter(function(){return this.name&&!this.disabled&&(this.checked||bO.test(this.nodeName)||bI.test(this.type))}).map(function(a,b){var c=f(this).val();return c==null?null:f.isArray(c)?f.map(c,function(a,c){return{name:b.name,value:a.replace(bF,"\r\n")}}):{name:b.name,value:c.replace(bF,"\r\n")}}).get()}}),f.each("ajaxStart ajaxStop ajaxComplete ajaxError ajaxSuccess ajaxSend".split(" "),function(a,b){f.fn[b]=function(a){return this.on(b,a)}}),f.each(["get","post"],function(a,c){f[c]=function(a,d,e,g){f.isFunction(d)&&(g=g||e,e=d,d=b);return f.ajax({type:c,url:a,data:d,success:e,dataType:g})}}),f.extend({getScript:function(a,c){return f.get(a,b,c,"script")},getJSON:function(a,b,c){return f.get(a,b,c,"json")},ajaxSetup:function(a,b){b?b_(a,f.ajaxSettings):(b=a,a=f.ajaxSettings),b_(a,b);return a},ajaxSettings:{url:bV,isLocal:bJ.test(bW[1]),global:!0,type:"GET",contentType:"application/x-www-form-urlencoded",processData:!0,async:!0,accepts:{xml:"application/xml, text/xml",html:"text/html",text:"text/plain",json:"application/json, text/javascript","*":bX},contents:{xml:/xml/,html:/html/,json:/json/},responseFields:{xml:"responseXML",text:"responseText"},converters:{"* text":a.String,"text html":!0,"text json":f.parseJSON,"text xml":f.parseXML},flatOptions:{context:!0,url:!0}},ajaxPrefilter:bZ(bT),ajaxTransport:bZ(bU),ajax:function(a,c){function w(a,c,l,m){if(s!==2){s=2,q&&clearTimeout(q),p=b,n=m||"",v.readyState=a>0?4:0;var o,r,u,w=c,x=l?cb(d,v,l):b,y,z;if(a>=200&&a<300||a===304){if(d.ifModified){if(y=v.getResponseHeader("Last-Modified"))f.lastModified[k]=y;if(z=v.getResponseHeader("Etag"))f.etag[k]=z}if(a===304)w="notmodified",o=!0;else try{r=cc(d,x),w="success",o=!0}catch(A){w="parsererror",u=A}}else{u=w;if(!w||a)w="error",a<0&&(a=0)}v.status=a,v.statusText=""+(c||w),o?h.resolveWith(e,[r,w,v]):h.rejectWith(e,[v,w,u]),v.statusCode(j),j=b,t&&g.trigger("ajax"+(o?"Success":"Error"),[v,d,o?r:u]),i.fireWith(e,[v,w]),t&&(g.trigger("ajaxComplete",[v,d]),--f.active||f.event.trigger("ajaxStop"))}}typeof a=="object"&&(c=a,a=b),c=c||{};var d=f.ajaxSetup({},c),e=d.context||d,g=e!==d&&(e.nodeType||e instanceof f)?f(e):f.event,h=f.Deferred(),i=f.Callbacks("once memory"),j=d.statusCode||{},k,l={},m={},n,o,p,q,r,s=0,t,u,v={readyState:0,setRequestHeader:function(a,b){if(!s){var c=a.toLowerCase();a=m[c]=m[c]||a,l[a]=b}return this},getAllResponseHeaders:function(){return s===2?n:null},getResponseHeader:function(a){var c;if(s===2){if(!o){o={};while(c=bH.exec(n))o[c[1].toLowerCase()]=c[2]}c=o[a.toLowerCase()]}return c===b?null:c},overrideMimeType:function(a){s||(d.mimeType=a);return this},abort:function(a){a=a||"abort",p&&p.abort(a),w(0,a);return this}};h.promise(v),v.success=v.done,v.error=v.fail,v.complete=i.add,v.statusCode=function(a){if(a){var b;if(s<2)for(b in a)j[b]=[j[b],a[b]];else b=a[v.status],v.then(b,b)}return this},d.url=((a||d.url)+"").replace(bG,"").replace(bL,bW[1]+"//"),d.dataTypes=f.trim(d.dataType||"*").toLowerCase().split(bP),d.crossDomain==null&&(r=bR.exec(d.url.toLowerCase()),d.crossDomain=!(!r||r[1]==bW[1]&&r[2]==bW[2]&&(r[3]||(r[1]==="http:"?80:443))==(bW[3]||(bW[1]==="http:"?80:443)))),d.data&&d.processData&&typeof d.data!="string"&&(d.data=f.param(d.data,d.traditional)),b$(bT,d,c,v);if(s===2)return!1;t=d.global,d.type=d.type.toUpperCase(),d.hasContent=!bK.test(d.type),t&&f.active++===0&&f.event.trigger("ajaxStart");if(!d.hasContent){d.data&&(d.url+=(bM.test(d.url)?"&":"?")+d.data,delete d.data),k=d.url;if(d.cache===!1){var x=f.now(),y=d.url.replace(bQ,"$1_="+x);d.url=y+(y===d.url?(bM.test(d.url)?"&":"?")+"_="+x:"")}}(d.data&&d.hasContent&&d.contentType!==!1||c.contentType)&&v.setRequestHeader("Content-Type",d.contentType),d.ifModified&&(k=k||d.url,f.lastModified[k]&&v.setRequestHeader("If-Modified-Since",f.lastModified[k]),f.etag[k]&&v.setRequestHeader("If-None-Match",f.etag[k])),v.setRequestHeader("Accept",d.dataTypes[0]&&d.accepts[d.dataTypes[0]]?d.accepts[d.dataTypes[0]]+(d.dataTypes[0]!=="*"?", "+bX+"; q=0.01":""):d.accepts["*"]);for(u in d.headers)v.setRequestHeader(u,d.headers[u]);if(d.beforeSend&&(d.beforeSend.call(e,v,d)===!1||s===2)){v.abort();return!1}for(u in{success:1,error:1,complete:1})v[u](d[u]);p=b$(bU,d,c,v);if(!p)w(-1,"No Transport");else{v.readyState=1,t&&g.trigger("ajaxSend",[v,d]),d.async&&d.timeout>0&&(q=setTimeout(function(){v.abort("timeout")},d.timeout));try{s=1,p.send(l,w)}catch(z){if(s<2)w(-1,z);else throw z}}return v},param:function(a,c){var d=[],e=function(a,b){b=f.isFunction(b)?b():b,d[d.length]=encodeURIComponent(a)+"="+encodeURIComponent(b)};c===b&&(c=f.ajaxSettings.traditional);if(f.isArray(a)||a.jquery&&!f.isPlainObject(a))f.each(a,function(){e(this.name,this.value)});else for(var g in a)ca(g,a[g],c,e);return d.join("&").replace(bD,"+")}}),f.extend({active:0,lastModified:{},etag:{}});var cd=f.now(),ce=/(\=)\?(&|$)|\?\?/i;f.ajaxSetup({jsonp:"callback",jsonpCallback:function(){return f.expando+"_"+cd++}}),f.ajaxPrefilter("json jsonp",function(b,c,d){var e=b.contentType==="application/x-www-form-urlencoded"&&typeof b.data=="string";if(b.dataTypes[0]==="jsonp"||b.jsonp!==!1&&(ce.test(b.url)||e&&ce.test(b.data))){var g,h=b.jsonpCallback=f.isFunction(b.jsonpCallback)?b.jsonpCallback():b.jsonpCallback,i=a[h],j=b.url,k=b.data,l="$1"+h+"$2";b.jsonp!==!1&&(j=j.replace(ce,l),b.url===j&&(e&&(k=k.replace(ce,l)),b.data===k&&(j+=(/\?/.test(j)?"&":"?")+b.jsonp+"="+h))),b.url=j,b.data=k,a[h]=function(a){g=[a]},d.always(function(){a[h]=i,g&&f.isFunction(i)&&a[h](g[0])}),b.converters["script json"]=function(){g||f.error(h+" was not called");return g[0]},b.dataTypes[0]="json";return"script"}}),f.ajaxSetup({accepts:{script:"text/javascript, application/javascript, application/ecmascript, application/x-ecmascript"},contents:{script:/javascript|ecmascript/},converters:{"text script":function(a){f.globalEval(a);return a}}}),f.ajaxPrefilter("script",function(a){a.cache===b&&(a.cache=!1),a.crossDomain&&(a.type="GET",a.global=!1)}),f.ajaxTransport("script",function(a){if(a.crossDomain){var d,e=c.head||c.getElementsByTagName("head")[0]||c.documentElement;return{send:function(f,g){d=c.createElement("script"),d.async="async",a.scriptCharset&&(d.charset=a.scriptCharset),d.src=a.url,d.onload=d.onreadystatechange=function(a,c){if(c||!d.readyState||/loaded|complete/.test(d.readyState))d.onload=d.onreadystatechange=null,e&&d.parentNode&&e.removeChild(d),d=b,c||g(200,"success")},e.insertBefore(d,e.firstChild)},abort:function(){d&&d.onload(0,1)}}}});var cf=a.ActiveXObject?function(){for(var a in ch)ch[a](0,1)}:!1,cg=0,ch;f.ajaxSettings.xhr=a.ActiveXObject?function(){return!this.isLocal&&ci()||cj()}:ci,function(a){f.extend(f.support,{ajax:!!a,cors:!!a&&"withCredentials"in a})}(f.ajaxSettings.xhr()),f.support.ajax&&f.ajaxTransport(function(c){if(!c.crossDomain||f.support.cors){var d;return{send:function(e,g){var h=c.xhr(),i,j;c.username?h.open(c.type,c.url,c.async,c.username,c.password):h.open(c.type,c.url,c.async);if(c.xhrFields)for(j in c.xhrFields)h[j]=c.xhrFields[j];c.mimeType&&h.overrideMimeType&&h.overrideMimeType(c.mimeType),!c.crossDomain&&!e["X-Requested-With"]&&(e["X-Requested-With"]="XMLHttpRequest");try{for(j in e)h.setRequestHeader(j,e[j])}catch(k){}h.send(c.hasContent&&c.data||null),d=function(a,e){var j,k,l,m,n;try{if(d&&(e||h.readyState===4)){d=b,i&&(h.onreadystatechange=f.noop,cf&&delete ch[i]);if(e)h.readyState!==4&&h.abort();else{j=h.status,l=h.getAllResponseHeaders(),m={},n=h.responseXML,n&&n.documentElement&&(m.xml=n),m.text=h.responseText;try{k=h.statusText}catch(o){k=""}!j&&c.isLocal&&!c.crossDomain?j=m.text?200:404:j===1223&&(j=204)}}}catch(p){e||g(-1,p)}m&&g(j,k,m,l)},!c.async||h.readyState===4?d():(i=++cg,cf&&(ch||(ch={},f(a).unload(cf)),ch[i]=d),h.onreadystatechange=d)},abort:function(){d&&d(0,1)}}}});var ck={},cl,cm,cn=/^(?:toggle|show|hide)$/,co=/^([+\-]=)?([\d+.\-]+)([a-z%]*)$/i,cp,cq=[["height","marginTop","marginBottom","paddingTop","paddingBottom"],["width","marginLeft","marginRight","paddingLeft","paddingRight"],["opacity"]],cr;f.fn.extend({show:function(a,b,c){var d,e;if(a||a===0)return this.animate(cu("show",3),a,b,c);for(var g=0,h=this.length;g=i.duration+this.startTime){this.now=this.end,this.pos=this.state=1,this.update(),i.animatedProperties[this.prop]=!0;for(b in i.animatedProperties)i.animatedProperties[b]!==!0&&(g=!1);if(g){i.overflow!=null&&!f.support.shrinkWrapBlocks&&f.each(["","X","Y"],function(a,b){h.style["overflow"+b]=i.overflow[a]}),i.hide&&f(h).hide();if(i.hide||i.show)for(b in i.animatedProperties)f.style(h,b,i.orig[b]),f.removeData(h,"fxshow"+b,!0),f.removeData(h,"toggle"+b,!0);d=i.complete,d&&(i.complete=!1,d.call(h))}return!1}i.duration==Infinity?this.now=e:(c=e-this.startTime,this.state=c/i.duration,this.pos=f.easing[i.animatedProperties[this.prop]](this.state,c,0,1,i.duration),this.now=this.start+(this.end-this.start)*this.pos),this.update();return!0}},f.extend(f.fx,{tick:function(){var a,b=f.timers,c=0;for(;c-1,k={},l={},m,n;j?(l=e.position(),m=l.top,n=l.left):(m=parseFloat(h)||0,n=parseFloat(i)||0),f.isFunction(b)&&(b=b.call(a,c,g)),b.top!=null&&(k.top=b.top-g.top+m),b.left!=null&&(k.left=b.left-g.left+n),"using"in b?b.using.call(a,k):e.css(k)}},f.fn.extend({position:function(){if(!this[0])return null;var a=this[0],b=this.offsetParent(),c=this.offset(),d=cx.test(b[0].nodeName)?{top:0,left:0}:b.offset();c.top-=parseFloat(f.css(a,"marginTop"))||0,c.left-=parseFloat(f.css(a,"marginLeft"))||0,d.top+=parseFloat(f.css(b[0],"borderTopWidth"))||0,d.left+=parseFloat(f.css(b[0],"borderLeftWidth"))||0;return{top:c.top-d.top,left:c.left-d.left}},offsetParent:function(){return this.map(function(){var a=this.offsetParent||c.body;while(a&&!cx.test(a.nodeName)&&f.css(a,"position")==="static")a=a.offsetParent;return a})}}),f.each(["Left","Top"],function(a,c){var d="scroll"+c;f.fn[d]=function(c){var e,g;if(c===b){e=this[0];if(!e)return null;g=cy(e);return g?"pageXOffset"in g?g[a?"pageYOffset":"pageXOffset"]:f.support.boxModel&&g.document.documentElement[d]||g.document.body[d]:e[d]}return this.each(function(){g=cy(this),g?g.scrollTo(a?f(g).scrollLeft():c,a?c:f(g).scrollTop()):this[d]=c})}}),f.each(["Height","Width"],function(a,c){var d=c.toLowerCase();f.fn["inner"+c]=function(){var a=this[0];return a?a.style?parseFloat(f.css(a,d,"padding")):this[d]():null},f.fn["outer"+c]=function(a){var b=this[0];return b?b.style?parseFloat(f.css(b,d,a?"margin":"border")):this[d]():null},f.fn[d]=function(a){var e=this[0];if(!e)return a==null?null:this;if(f.isFunction(a))return this.each(function(b){var c=f(this);c[d](a.call(this,b,c[d]()))});if(f.isWindow(e)){var g=e.document.documentElement["client"+c],h=e.document.body;return e.document.compatMode==="CSS1Compat"&&g||h&&h["client"+c]||g}if(e.nodeType===9)return Math.max(e.documentElement["client"+c],e.body["scroll"+c],e.documentElement["scroll"+c],e.body["offset"+c],e.documentElement["offset"+c]);if(a===b){var i=f.css(e,d),j=parseFloat(i);return f.isNumeric(j)?j:i}return this.css(d,typeof a=="string"?a:a+"px")}}),a.jQuery=a.$=f,typeof define=="function"&&define.amd&&define.amd.jQuery&&define("jquery",[],function(){return f})})(window); \ No newline at end of file diff --git a/docs/method_list.html b/docs/method_list.html new file mode 100644 index 00000000..e69de29b diff --git a/docs/top-level-namespace.html b/docs/top-level-namespace.html new file mode 100644 index 00000000..e69de29b diff --git a/examples/e2e.rb b/examples/e2e.rb new file mode 100644 index 00000000..22329c1a --- /dev/null +++ b/examples/e2e.rb @@ -0,0 +1,138 @@ +# frozen_string_literal: true + +# End-to-end example using oauth2 gem against a local mock-oauth2-server. +# Prerequisites: +# 1) Start the mock server (HTTP on 8080): +# docker compose -f docker-compose-ssl.yml up -d --wait +# 2) Run this script: +# ruby examples/e2e.rb +# 3) Stop the server when you're done: +# docker compose -f docker-compose-ssl.yml down +# Notes: +# - The mock server uses a self-signed certificate. SSL verification is disabled in this example. +# - Tested down to Ruby 2.4 (avoid newer syntax). + +require "oauth2" +require "json" +require "net/http" +require "uri" + +module E2E + class ClientCredentialsDemo + attr_reader :client_id, :client_secret, :issuer_base, :realm + + # issuer_base: e.g., https://localhost:8080 + # realm: mock-oauth2-server issuer id ("default" by default) + def initialize(client_id, client_secret, issuer_base, realm) + @client_id = client_id + @client_secret = client_secret + @issuer_base = issuer_base + @realm = realm + end + + def run + wait_for_server_ready + well_known = discover + token = fetch_token(well_known) + puts "Access token (truncated): #{token.token[0, 20]}..." + call_userinfo(well_known, token) + puts "E2E complete" + end + + private + + def discovery_url + File.join(@issuer_base, @realm, "/.well-known/openid-configuration") + end + + def wait_for_server_ready(timeout = nil) + timeout = (timeout || ENV["E2E_WAIT_TIMEOUT"] || 90).to_i + uri = URI(discovery_url) + deadline = Time.now + timeout + announced = false + loop do + begin + http = Net::HTTP.new(uri.host, uri.port) + http.use_ssl = uri.scheme == "https" + http.verify_mode = OpenSSL::SSL::VERIFY_NONE + req = Net::HTTP::Get.new(uri.request_uri) + res = http.request(req) + return if res.code.to_i == 200 + rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ECONNRESET, SocketError, EOFError, OpenSSL::SSL::SSLError + # ignore and retry until timeout + end + unless announced + puts "Waiting for mock OAuth2 server at #{uri} ..." + announced = true + end + break if Time.now >= deadline + sleep(0.5) + end + raise "Server not reachable at #{uri} within #{timeout}s. Ensure it's running: docker compose -f docker-compose-ssl.yml up -d --wait. You can increase the wait by setting E2E_WAIT_TIMEOUT (seconds)." + end + + def discover + uri = URI(discovery_url) + http = Net::HTTP.new(uri.host, uri.port) + http.use_ssl = uri.scheme == "https" + http.verify_mode = OpenSSL::SSL::VERIFY_NONE + req = Net::HTTP::Get.new(uri.request_uri) + res = http.request(req) + unless res.code.to_i == 200 + raise "Discovery failed: #{res.code} #{res.message} - #{res.body}" + end + data = JSON.parse(res.body) + # Expect token_endpoint and possibly userinfo_endpoint + data + end + + def fetch_token(well_known) + client = OAuth2::Client.new( + @client_id, + @client_secret, + site: @issuer_base, + token_url: URI.parse(well_known["token_endpoint"]).request_uri, + ssl: {verify: false}, + auth_scheme: :request_body, # send client creds in request body (compatible default for mock servers) + ) + # Use client_credentials grant + client.client_credentials.get_token + end + + def call_userinfo(well_known, token) + userinfo = well_known["userinfo_endpoint"] + unless userinfo + puts "No userinfo_endpoint advertised by server; skipping userinfo call." + return + end + uri = URI(userinfo) + http = Net::HTTP.new(uri.host, uri.port) + http.use_ssl = uri.scheme == "https" + http.verify_mode = OpenSSL::SSL::VERIFY_NONE + req = Net::HTTP::Get.new(uri.request_uri) + req["Authorization"] = "Bearer #{token.token}" + res = http.request(req) + puts "userinfo status: #{res.code} #{res.message}" + if res.code.to_i == 200 + begin + body = JSON.parse(res.body) + rescue StandardError + body = res.body + end + puts "userinfo body: #{body.inspect}" + else + puts "userinfo error body: #{res.body}" + end + end + end +end + +if __FILE__ == $PROGRAM_NAME + # These must match the mock server configuration (see config-ssl.json) + client_id = ENV["E2E_CLIENT_ID"] || "demo-client" + client_secret = ENV["E2E_CLIENT_SECRET"] || "demo-secret" + issuer_base = ENV["E2E_ISSUER_BASE"] || "http://localhost:8080/" + realm = ENV["E2E_REALM"] || "default" + + E2E::ClientCredentialsDemo.new(client_id, client_secret, issuer_base, realm).run +end diff --git a/gemfiles/README.md b/gemfiles/README.md new file mode 100644 index 00000000..cd99cdab --- /dev/null +++ b/gemfiles/README.md @@ -0,0 +1,110 @@ +# History + +This document will become out-of-date quickly, but remains historically relevant until +such time as this gem is released with support for non-EOL Ruby only. + +`faraday` v0.17.3 is the first version that stops using `&Proc.new` for block forwarding, + and thus is the oldest version oauth2 is compatible with. + +```ruby +gem "faraday", [">= 0.17.3", "< 3.0"] +``` + +# Ruby + +We use the Github Action `ruby/setup-ruby@master` to install Ruby, and it has a matrix of +[supported versions](https://github.com/ruby/setup-ruby/blob/master/README.md#supported-versions) (copied below). + +| Interpreter | Versions | +|-----------------------|------------------------------------------------------------------------------------------| +| `ruby` | 1.9.3, 2.0.0, 2.1.9, 2.2, all versions from 2.3.0 until 3.1.1, head, debug, mingw, mswin | +| `jruby` | 9.1.17.0 - 9.3.3.0, head | +| `truffleruby` | 19.3.0 - 22.0.0, head | +| `truffleruby+graalvm` | 21.2.0 - 22.0.0, head | + +In the naming of gemfiles, we will use the below shorthand for interpreter, +and version. Platforms will be represented without modification. + +| Interpreter | Shorthand | +|-----------------------|-----------| +| `ruby` | r | +| `jruby` | jr | +| `truffleruby` | tr | +| `truffleruby+graalvm` | trg | + +Building onto that, we can add the MRI target spec, +since that's what all Rubygems use for minimum version compatibility. + +| Interpreter + Version | MRI spec | Shorthand | +|----------------------------|----------|------------| +| ruby-1.9.3 | 1.9 | r1_9 | +| ruby-2.0.0 | 2.0 | r2_0 | +| ruby-2.1.9 | 2.1 | r2_1 | +| ruby-2.2.x | 2.2 | r2_2 | +| ruby-2.3.x | 2.3 | r2_3 | +| ruby-2.4.x | 2.4 | r2_4 | +| ruby-2.5.x | 2.5 | r2_5 | +| ruby-2.6.x | 2.6 | r2_6 | +| ruby-2.7.x | 2.7 | r2_7 | +| ruby-3.0.x | 3.0 | r3_0 | +| ruby-3.1.x | 3.1 | r3_1 | +| ruby-head | 3.2 | rH3_2 | +| ruby-mingw | (?) | rmin | +| ruby-mswin | (?) | rMS | +| jruby-9.1.x.x | 2.3 | jr9_1-r2_3 | +| jruby-9.2.x.x | 2.5 | jr9_2-r2_5 | +| jruby-9.3.x.x | 2.6 | jr9_3-r2_6 | +| jruby-head | 2.7 | jrH-r2_7 | +| truffleruby-19.3.x | 2.5(?) | tr19-r2_5 | +| truffleruby-20.x.x | 2.6.5 | tr20-r2_6 | +| truffleruby-21.x.x | 2.7.4 | tr21-r2_7 | +| truffleruby-22.x.x | 3.0.2 | tr22-r3_0 | +| truffleruby-head | 3.1(?) | trH-r3_1 | +| truffleruby+graalvm-21.2.x | 2.7.4 | trg21-r2_7 | +| truffleruby+graalvm-22.x.x | 3.0.2 | trg22-r3_0 | +| truffleruby+graalvm-head | 3.1(?) | trgH-r3_1 | + +We will run tests on as many of these as possible, in a matrix with each supported major version of `faraday`, +which means 0.17.3+ (as `f0`), 1.10.x (as `f1`), 2.2.x (as `f2`). + +Discrete versions of `faraday` to test against, as of 2025.05.14, with minimum version of Ruby for each: + +* 2.9.0, Ruby >= 3.0 +* 2.2.0, Ruby >= 2.6 +* 1.10.0, Ruby >= 2.4 +* 0.17.4, Ruby >= 1.9 + +❌ - Incompatible +✅ - Official Support +🚧 - Unofficial Support +🤡 - Incidental Compatibility +🙈 - Unknown Compatibility + +| Shorthand | f0 - 0.17.3+ | f1 - 1.10.x | f2 - 2.2.x | +|------------|------------------|------------------|-----------------| +| r1_9 | 🤡 f0-r1_9 | ❌ | ❌ | +| r2_0 | 🤡 f0-r2_0 | ❌ | ❌ | +| r2_1 | 🤡 f0-r2_1 | ❌ | ❌ | +| r2_2 | 🤡 f0-r2_2 | ❌ | ❌ | +| r2_3 | 🚧 f0-r2_3 | ❌ | ❌ | +| r2_4 | 🚧 f0-r2_4 | 🚧 f1-r2_4 | ❌ | +| r2_5 | 🚧 f0-r2_5 | 🚧 f1-r2_5 | ❌ | +| r2_6 | 🚧 f0-r2_6 | 🚧 f1-r2_6 | 🚧 f2-r2_6 | +| r2_7 | ✅ f0-r2_7 | ✅ f1-r2_7 | ✅ f2-r2_7 | +| r3_0 | ✅ f0-r3_0 | ✅ f1-r3_0 | ✅ f2-r3_0 | +| r3_1 | ✅ f0-r3_1 | ✅ f1-r3_1 | ✅ f2-r3_1 | +| rH3_2 | 🚧 f0-rH3_2 | 🚧 f1-rH3_2 | 🚧 f2-rH3_2 | +| rmin | 🙈 f0-rmin | 🙈 f1-rmin | 🙈 f2-rmin | +| rMS | 🙈 f0-rMS | 🙈 f1-rMS | 🙈 f2-rMS | +| jr9_1-r2_3 | 🚧 f0-jr9_1-r2_3 | ❌ | ❌ | +| jr9_2-r2_5 | 🚧 f0-jr9_2-r2_5 | 🚧 f1-jr9_2-r2_5 | ❌ | +| jr9_3-r2_6 | ✅ f0-jr9_3-r2_6 | ✅ f1-jr9_3-r2_6 | ✅ f2-jr9_3-r2_6 | +| jrH-r2_7 | 🚧 f0-jrH-r2_7 | 🚧 f1-jrH-r2_7 | 🚧 f2-jrH-r2_7 | +| tr19-r2_5 | 🚧 f0-tr19-r2_5 | 🚧 f1-tr19-r2_5 | ❌ | +| tr20-r2_6 | 🚧 f0-tr20-r2_6 | 🚧 f1-tr20-r2_6 | 🚧 f2-tr20-r2_6 | +| tr21-r2_7 | ✅ f0-tr21-r2_7 | ✅ f1-tr21-r2_7 | ✅ f2-tr21-r2_7 | +| tr22-r3_0 | ✅ f0-tr22-r3_0 | ✅ f1-tr22-r3_0 | ✅ f2-tr22-r3_0 | +| trH-r3_1 | 🚧 f0-trH-r3_1 | 🚧 f1-trH-r3_1 | 🚧 f2-trH-r3_1 | +| trg21-r2_7 | ✅ f0-trg21-r2_7 | ✅ f1-trg21-r2_7 | ✅ f2-trg21-r2_7 | +| trg22-r3_0 | ✅ f0-trg22-r3_0 | ✅ f1-trg22-r3_0 | ✅ f2-trg22-r3_0 | +| trgH-r3_1 | 🚧 f0-trgH-r3_1 | 🚧 f1-trgH-r3_1 | 🚧 f2-trgH-r3_1 | diff --git a/gemfiles/audit.gemfile b/gemfiles/audit.gemfile new file mode 100644 index 00000000..46af23c5 --- /dev/null +++ b/gemfiles/audit.gemfile @@ -0,0 +1,21 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/audit.gemfile") + +eval_gemfile("modular/faraday_v2.gemfile") + +eval_gemfile("modular/hashie_v5.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_7.gemfile") + +eval_gemfile("modular/multi_xml_v0_7.gemfile") + +eval_gemfile("modular/rack_v3.gemfile") + +eval_gemfile("modular/x_std_libs.gemfile") diff --git a/gemfiles/coverage.gemfile b/gemfiles/coverage.gemfile new file mode 100644 index 00000000..ea228fb0 --- /dev/null +++ b/gemfiles/coverage.gemfile @@ -0,0 +1,23 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/coverage.gemfile") + +eval_gemfile("modular/faraday_v2.gemfile") + +eval_gemfile("modular/hashie_v5.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_7.gemfile") + +eval_gemfile("modular/multi_xml_v0_7.gemfile") + +eval_gemfile("modular/optional.gemfile") + +eval_gemfile("modular/rack_v3.gemfile") + +eval_gemfile("modular/x_std_libs.gemfile") diff --git a/gemfiles/current.gemfile b/gemfiles/current.gemfile new file mode 100644 index 00000000..8880702e --- /dev/null +++ b/gemfiles/current.gemfile @@ -0,0 +1,7 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/x_std_libs.gemfile") diff --git a/gemfiles/current_runtime_heads.gemfile b/gemfiles/current_runtime_heads.gemfile new file mode 100644 index 00000000..d76bab3f --- /dev/null +++ b/gemfiles/current_runtime_heads.gemfile @@ -0,0 +1,10 @@ +# This file was generated by Appraisal2 + +source "https://rubygems.org/" + +gem "mutex_m", ">= 0.2" +gem "stringio", ">= 3.0" + +gemspec path: "../" + +eval_gemfile("modular/runtime_heads.gemfile") diff --git a/gemfiles/dep_heads.gemfile b/gemfiles/dep_heads.gemfile new file mode 100644 index 00000000..ceecfc2b --- /dev/null +++ b/gemfiles/dep_heads.gemfile @@ -0,0 +1,7 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/runtime_heads.gemfile") diff --git a/gemfiles/head.gemfile b/gemfiles/head.gemfile new file mode 100644 index 00000000..f22db7f3 --- /dev/null +++ b/gemfiles/head.gemfile @@ -0,0 +1,10 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gem "cgi", ">= 0.5" +gem "benchmark", "~> 0.4", ">= 0.4.1" + +gemspec path: "../" + +eval_gemfile("modular/runtime_heads.gemfile") diff --git a/gemfiles/jruby_1.7.gemfile b/gemfiles/jruby_1.7.gemfile deleted file mode 100644 index 3acfed07..00000000 --- a/gemfiles/jruby_1.7.gemfile +++ /dev/null @@ -1,7 +0,0 @@ -source 'https://rubygems.org/' - -group :test do - gem 'rake', [">= 10.0", "< 12"] -end - -gemspec :path => '../' diff --git a/gemfiles/jruby_9.0.gemfile b/gemfiles/jruby_9.0.gemfile deleted file mode 100644 index 13fd08d3..00000000 --- a/gemfiles/jruby_9.0.gemfile +++ /dev/null @@ -1,7 +0,0 @@ -source 'https://rubygems.org/' - -gem 'faraday', '~> 0.15.4' - -gem 'rake', [">= 10.0", "< 12"] - -gemspec :path => '../' diff --git a/gemfiles/jruby_9.1.gemfile b/gemfiles/jruby_9.1.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/jruby_9.1.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/jruby_9.2.gemfile b/gemfiles/jruby_9.2.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/jruby_9.2.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/jruby_head.gemfile b/gemfiles/jruby_head.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/jruby_head.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/modular/audit.gemfile b/gemfiles/modular/audit.gemfile new file mode 100644 index 00000000..e5cc9199 --- /dev/null +++ b/gemfiles/modular/audit.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Many gems are dropping support for Ruby < 3, +# so we only want to run our security audit in CI on Ruby 3+ +gem "bundler-audit", "~> 0.9.2" diff --git a/gemfiles/modular/coverage.gemfile b/gemfiles/modular/coverage.gemfile new file mode 100644 index 00000000..ee32b0a1 --- /dev/null +++ b/gemfiles/modular/coverage.gemfile @@ -0,0 +1,6 @@ +# frozen_string_literal: true + +# We run code coverage on the latest version of Ruby only. + +# Coverage +gem "kettle-soup-cover", "~> 1.0", ">= 1.0.10", require: false diff --git a/gemfiles/modular/debug.gemfile b/gemfiles/modular/debug.gemfile new file mode 100644 index 00000000..3e86091c --- /dev/null +++ b/gemfiles/modular/debug.gemfile @@ -0,0 +1,13 @@ +# Ex-Standard Library gems +gem "irb", "~> 1.15", ">= 1.15.2" # removed from stdlib in 3.5 + +platform :mri do + # Debugging - Ensure ENV["DEBUG"] == "true" to use debuggers within spec suite + # Use binding.break, binding.b, or debugger in code + gem "debug", ">= 1.1" # ruby >= 2.7 + + # Dev Console - Binding.pry - Irb replacement + # gem "pry", "~> 0.14" # ruby >= 2.0 +end + +gem "gem_bench", "~> 2.0", ">= 2.0.5" diff --git a/gemfiles/modular/documentation.gemfile b/gemfiles/modular/documentation.gemfile new file mode 100644 index 00000000..47f1a9d3 --- /dev/null +++ b/gemfiles/modular/documentation.gemfile @@ -0,0 +1,12 @@ +# frozen_string_literal: true + +# Documentation +gem "kramdown", "~> 2.5", ">= 2.5.1" # Ruby >= 2.5 +gem "kramdown-parser-gfm", "~> 1.1" # Ruby >= 2.3 +gem "yard", "~> 0.9", ">= 0.9.37", require: false +gem "yard-junk", "~> 0.0", ">= 0.0.10", github: "pboling/yard-junk", branch: "next", require: false +gem "yard-relative_markdown_links", "~> 0.5.0" + +# Std Lib extractions +gem "rdoc", "~> 6.11" +gem "yard-fence", "~> 0.4", require: false # Ruby >= 3.2 diff --git a/gemfiles/modular/erb/r2.3/default.gemfile b/gemfiles/modular/erb/r2.3/default.gemfile new file mode 100644 index 00000000..ca868e84 --- /dev/null +++ b/gemfiles/modular/erb/r2.3/default.gemfile @@ -0,0 +1,6 @@ +# The cake is a lie. +# erb v2.2, the oldest release, was never compatible with Ruby 2.3. +# In addition, erb does not follow SemVer, and old rubies get dropped in a patch. +# This means we have no choice but to use the erb that shipped with Ruby 2.3 +# /opt/hostedtoolcache/Ruby/2.3.8/x64/lib/ruby/gems/2.3.0/gems/erb-2.2.2/lib/erb.rb:670:in `prepare_trim_mode': undefined method `match?' for "-":String (NoMethodError) +# gem "erb", ">= 2.2" # ruby >= 2.3.0 diff --git a/gemfiles/modular/erb/r2.4/v2.2.gemfile b/gemfiles/modular/erb/r2.4/v2.2.gemfile new file mode 100644 index 00000000..5777e7e3 --- /dev/null +++ b/gemfiles/modular/erb/r2.4/v2.2.gemfile @@ -0,0 +1,6 @@ +# Ruby >= 2.3.0 (claimed, but not true, minimum support is Ruby 2.4) +# Last version supporting Ruby <= 2.6 +gem "erb", "~> 2.2.2" + +# Pin CGI to a version compatible with Ruby 2.4. +gem "cgi", "~> 0.1.1" diff --git a/gemfiles/modular/erb/r2.6/v2.2.gemfile b/gemfiles/modular/erb/r2.6/v2.2.gemfile new file mode 100644 index 00000000..7cd85745 --- /dev/null +++ b/gemfiles/modular/erb/r2.6/v2.2.gemfile @@ -0,0 +1,3 @@ +# Ruby >= 2.3.0 (claimed, but not true, minimum support is Ruby 2.4) +# Last version supporting Ruby <= 2.6 +gem "erb", "~> 2.2.2" diff --git a/gemfiles/modular/erb/r2/v3.0.gemfile b/gemfiles/modular/erb/r2/v3.0.gemfile new file mode 100644 index 00000000..c03bd8d8 --- /dev/null +++ b/gemfiles/modular/erb/r2/v3.0.gemfile @@ -0,0 +1 @@ +gem "erb", "~> 3.0" # ruby >= 2.7.0 diff --git a/gemfiles/modular/erb/r3.1/v4.0.gemfile b/gemfiles/modular/erb/r3.1/v4.0.gemfile new file mode 100644 index 00000000..2e9046d8 --- /dev/null +++ b/gemfiles/modular/erb/r3.1/v4.0.gemfile @@ -0,0 +1,2 @@ +# last version compatible with Ruby 3.1 +gem "erb", "~> 4.0" # ruby >= 2.7.0 diff --git a/gemfiles/modular/erb/r3/v5.0.gemfile b/gemfiles/modular/erb/r3/v5.0.gemfile new file mode 100644 index 00000000..97033fa7 --- /dev/null +++ b/gemfiles/modular/erb/r3/v5.0.gemfile @@ -0,0 +1 @@ +gem "erb", "~> 5.0" # ruby >= 3.2.0 diff --git a/gemfiles/modular/erb/vHEAD.gemfile b/gemfiles/modular/erb/vHEAD.gemfile new file mode 100644 index 00000000..65f8433e --- /dev/null +++ b/gemfiles/modular/erb/vHEAD.gemfile @@ -0,0 +1,2 @@ +# Ruby >= 3.2 (dependency of kettle-dev) +gem "erb", github: "ruby/erb", branch: "master" diff --git a/gemfiles/modular/faraday_v0.gemfile b/gemfiles/modular/faraday_v0.gemfile new file mode 100644 index 00000000..caa833b9 --- /dev/null +++ b/gemfiles/modular/faraday_v0.gemfile @@ -0,0 +1,7 @@ +# frozen_string_literal: true + +# Ruby >= 1.9 +# 0.17.3 is the first version to not use &Proc.new when forwarding blocks. +# Thus, it is the oldest version oauth2 is compatible with. +# This version of faraday is the last compatible with Ruby 1.9, 2.0, 2.1, 2.2, and 2.3: +gem "faraday", "~> 0.17.6" diff --git a/gemfiles/modular/faraday_v1.gemfile b/gemfiles/modular/faraday_v1.gemfile new file mode 100644 index 00000000..49bd282a --- /dev/null +++ b/gemfiles/modular/faraday_v1.gemfile @@ -0,0 +1,4 @@ +# frozen_string_literal: true + +# Last version compatible with Ruby 2.4, and 2.5 +gem "faraday", "~> 1.10", ">= 1.10.4" diff --git a/gemfiles/modular/faraday_v2.gemfile b/gemfiles/modular/faraday_v2.gemfile new file mode 100644 index 00000000..45130ada --- /dev/null +++ b/gemfiles/modular/faraday_v2.gemfile @@ -0,0 +1,4 @@ +# frozen_string_literal: true + +# last version that will install on Ruby 2.6 & 2.7 +gem "faraday", "~> 2.8", ">=2.8.1" diff --git a/gemfiles/modular/hashie_v0.gemfile b/gemfiles/modular/hashie_v0.gemfile new file mode 100644 index 00000000..78a4bef5 --- /dev/null +++ b/gemfiles/modular/hashie_v0.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# We will test it against Ruby 2.3. +gem "hashie", "~> 0.4", ">= 0.4.0" diff --git a/gemfiles/modular/hashie_v1.gemfile b/gemfiles/modular/hashie_v1.gemfile new file mode 100644 index 00000000..6cd97b2e --- /dev/null +++ b/gemfiles/modular/hashie_v1.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# We will test it against Ruby 2.4. +gem "hashie", "~> 1.2", ">= 1.2.0" diff --git a/gemfiles/modular/hashie_v2.gemfile b/gemfiles/modular/hashie_v2.gemfile new file mode 100644 index 00000000..ca62311c --- /dev/null +++ b/gemfiles/modular/hashie_v2.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# We will test it against Ruby 2.5. +gem "hashie", "~> 2.1", ">= 2.1.2" diff --git a/gemfiles/modular/hashie_v3.gemfile b/gemfiles/modular/hashie_v3.gemfile new file mode 100644 index 00000000..aeff95b3 --- /dev/null +++ b/gemfiles/modular/hashie_v3.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# We will test it against Ruby 2.6. +gem "hashie", "~> 3.6", ">= 3.6.0" diff --git a/gemfiles/modular/hashie_v4.gemfile b/gemfiles/modular/hashie_v4.gemfile new file mode 100644 index 00000000..c18d3cb9 --- /dev/null +++ b/gemfiles/modular/hashie_v4.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# We will test it against Ruby 2.7. +gem "hashie", "~> 4.1", ">= 4.1.0" diff --git a/gemfiles/modular/hashie_v5.gemfile b/gemfiles/modular/hashie_v5.gemfile new file mode 100644 index 00000000..0c6cd403 --- /dev/null +++ b/gemfiles/modular/hashie_v5.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# We will test it against Ruby 3.0+. +gem "hashie", "~> 5.0", ">= 5.0.0" diff --git a/gemfiles/modular/injected.gemfile b/gemfiles/modular/injected.gemfile new file mode 100644 index 00000000..175b724a --- /dev/null +++ b/gemfiles/modular/injected.gemfile @@ -0,0 +1,60 @@ +# NOTE: It is preferable to list development dependencies in the gemspec due to increased +# visibility and discoverability on RubyGems.org. +# However, this gem sits underneath all my other gems, and also "depends on" many of them. +# So instead of depending on them directly it injects them into the other gem's gemspec on install. +# This gem, and its injected dev dependencies, will install on Ruby down to 2.3.x. +# This gem does not inject runtime dependencies. +# Thus, dev dependencies injected into gemspecs must have +# +# required_ruby_version ">= 2.3" (or lower) +# +# Development dependencies that require strictly newer Ruby versions should be in a "gemfile", +# and preferably a modular one (see gemfiles/modular/*.gemfile). + +# Security +gem "bundler-audit", "~> 0.9.2" # ruby >= 2.0.0 + +# Tasks +gem "rake", "~> 13.0" # ruby >= 2.2.0 + +# Debugging +gem "require_bench", "~> 1.0", ">= 1.0.4" # ruby >= 2.2.0 + +# Testing +gem "appraisal2", "~> 3.0" # ruby >= 1.8.7, for testing against multiple versions of dependencies +gem "kettle-test", "~> 1.0" # ruby >= 2.3 +gem "rspec-pending_for" # ruby >= 2.3, used to skip specs on incompatible Rubies + +# Releasing +gem "ruby-progressbar", "~> 1.13" # ruby >= 0 +gem "stone_checksums", "~> 1.0", ">= 1.0.2" # ruby >= 2.2.0 + +# Git integration (optional) +# The 'git' gem is optional; kettle-dev falls back to shelling out to `git` if it is not present. +# The current release of the git gem depends on activesupport, which makes it too heavy to depend on directly +# Compatibility with the git gem is tested via appraisals instead. +# gem("git", ">= 1.19.1") # ruby >= 2.3 + +# Development tasks +gem "gitmoji-regex", "~> 1.0", ">= 1.0.3" # ruby >= 2.3.0 + +# The cake is a lie. erb v2.2, the oldest release on RubyGems.org, was never compatible with Ruby 2.3. +# This means we have no choice but to use the erb that shipped with Ruby 2.3 +# /opt/hostedtoolcache/Ruby/2.3.8/x64/lib/ruby/gems/2.3.0/gems/erb-2.2.2/lib/erb.rb:670:in `prepare_trim_mode': undefined method `match?' for "-":String (NoMethodError) +# gem "erb", ">= 2.2" # ruby >= 2.3.0, not SemVer, old rubies get dropped in a patch. + +# HTTP recording for deterministic specs +# It seems that somehow just having a newer version of appraisal installed breaks +# Ruby 2.3 and 2.4 even if their bundle specifies an older version, +# and as a result it can only be a dependency in the appraisals. +# | An error occurred while loading spec_helper. +# | Failure/Error: require "vcr" +# | +# | NoMethodError: +# | undefined method `delete_prefix' for "CONTENT_LENGTH":String +# | # ./spec/config/vcr.rb:3:in `require' +# | # ./spec/config/vcr.rb:3:in `' +# | # ./spec/spec_helper.rb:8:in `require_relative' +# | # ./spec/spec_helper.rb:8:in `' +# gem "vcr", ">= 4" # 6.0 claims to support ruby >= 2.3, but fails on ruby 2.4 +# gem "webmock", ">= 3" # Last version to support ruby >= 2.3 diff --git a/gemfiles/modular/jwt_v1.gemfile b/gemfiles/modular/jwt_v1.gemfile new file mode 100644 index 00000000..a48aa406 --- /dev/null +++ b/gemfiles/modular/jwt_v1.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# This version of jwt is the last compatible with Ruby 1.9, 2.0, 2.1, 2.2, 2.3, 2.4: +gem "jwt", "~> 1.5", ">= 1.5.6" diff --git a/gemfiles/modular/jwt_v2.gemfile b/gemfiles/modular/jwt_v2.gemfile new file mode 100644 index 00000000..589888ed --- /dev/null +++ b/gemfiles/modular/jwt_v2.gemfile @@ -0,0 +1,4 @@ +# frozen_string_literal: true + +# Ruby >= 2.5 +gem "jwt", "~> 2.10", ">= 2.10.1" diff --git a/gemfiles/modular/jwt_v3.gemfile b/gemfiles/modular/jwt_v3.gemfile new file mode 100644 index 00000000..0ff1d8b0 --- /dev/null +++ b/gemfiles/modular/jwt_v3.gemfile @@ -0,0 +1,4 @@ +# frozen_string_literal: true + +# Ruby >= 2.5 +gem "jwt", ">= 3.0.0.beta1", "< 4" diff --git a/gemfiles/modular/latest.gemfile b/gemfiles/modular/latest.gemfile new file mode 100644 index 00000000..1a592057 --- /dev/null +++ b/gemfiles/modular/latest.gemfile @@ -0,0 +1,8 @@ +gem "mutex_m", ">= 0.2" +gem "stringio", ">= 3.0" +eval_gemfile "faraday_v2.gemfile" +eval_gemfile "hashie_v5.gemfile" +eval_gemfile "jwt_v3.gemfile" +eval_gemfile "logger_v1_7.gemfile" +eval_gemfile "multi_xml_v0_7.gemfile" +eval_gemfile "rack_v3.gemfile" diff --git a/gemfiles/modular/logger_v1_2.gemfile b/gemfiles/modular/logger_v1_2.gemfile new file mode 100644 index 00000000..7c56847a --- /dev/null +++ b/gemfiles/modular/logger_v1_2.gemfile @@ -0,0 +1,6 @@ +# frozen_string_literal: true + +# Ruby >= 2.3 +# This version of logger is the last compatible with Ruby 1.8. 1.9, 2.0, 2.1, 2.2: +# We will test it against 2.3, and 2.4. +gem "logger", "~> 1.2.8", ">= 1.2.8.1" diff --git a/gemfiles/modular/logger_v1_5.gemfile b/gemfiles/modular/logger_v1_5.gemfile new file mode 100644 index 00000000..9986fcc9 --- /dev/null +++ b/gemfiles/modular/logger_v1_5.gemfile @@ -0,0 +1,6 @@ +# frozen_string_literal: true + +# Ruby >= 2.3 +# This version of logger is the last compatible with Ruby 2.3, 2.4: +# We will test it against 2.5, and 2.6. +gem "logger", "~> 1.5.3" diff --git a/gemfiles/modular/logger_v1_7.gemfile b/gemfiles/modular/logger_v1_7.gemfile new file mode 100644 index 00000000..3ac3e049 --- /dev/null +++ b/gemfiles/modular/logger_v1_7.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 2.5 +# We will test it against Ruby 2.7, 3.0, 3.1, 3.2, 3.3, 3.4. +gem "logger", "~> 1.7", ">= 1.7.0" diff --git a/gemfiles/modular/multi_xml_v0_5.gemfile b/gemfiles/modular/multi_xml_v0_5.gemfile new file mode 100644 index 00000000..3f4c0eac --- /dev/null +++ b/gemfiles/modular/multi_xml_v0_5.gemfile @@ -0,0 +1,6 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# We will test it against Ruby 2.3, 2.4 +# This minor version of multi_xml is the oldest compatible with this gem: +gem "multi_xml", "~> 0.5", ">= 0.5.5" diff --git a/gemfiles/modular/multi_xml_v0_6.gemfile b/gemfiles/modular/multi_xml_v0_6.gemfile new file mode 100644 index 00000000..6db93997 --- /dev/null +++ b/gemfiles/modular/multi_xml_v0_6.gemfile @@ -0,0 +1,6 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# We will test it against Ruby 2.5, 2.6, 2.7, 3.0, 3.1. +# This version of multi_xml is the last compatible with Ruby 1.8, 1.9, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 3.0: +gem "multi_xml", "~> 0.6", ">= 0.6.0" diff --git a/gemfiles/modular/multi_xml_v0_7.gemfile b/gemfiles/modular/multi_xml_v0_7.gemfile new file mode 100644 index 00000000..87dac9b8 --- /dev/null +++ b/gemfiles/modular/multi_xml_v0_7.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 2.5 +# We will test it against Ruby 2.5, 2.6, 2.7, 3.0, 3.1, 3.2, 3.3, 3.4. +gem "multi_xml", "~> 0.7", ">= 0.7.2" diff --git a/gemfiles/modular/mutex_m/r2.4/v0.1.gemfile b/gemfiles/modular/mutex_m/r2.4/v0.1.gemfile new file mode 100644 index 00000000..cabf9806 --- /dev/null +++ b/gemfiles/modular/mutex_m/r2.4/v0.1.gemfile @@ -0,0 +1,3 @@ +# Ruby >= 0 +# Last version supporting Ruby <= 2.4 +gem "mutex_m", "~> 0.1" diff --git a/gemfiles/modular/mutex_m/r2/v0.3.gemfile b/gemfiles/modular/mutex_m/r2/v0.3.gemfile new file mode 100644 index 00000000..42e9d9bd --- /dev/null +++ b/gemfiles/modular/mutex_m/r2/v0.3.gemfile @@ -0,0 +1,2 @@ +# Ruby >= 2.5 +gem "mutex_m", "~> 0.2" diff --git a/gemfiles/modular/mutex_m/r3/v0.3.gemfile b/gemfiles/modular/mutex_m/r3/v0.3.gemfile new file mode 100644 index 00000000..42e9d9bd --- /dev/null +++ b/gemfiles/modular/mutex_m/r3/v0.3.gemfile @@ -0,0 +1,2 @@ +# Ruby >= 2.5 +gem "mutex_m", "~> 0.2" diff --git a/gemfiles/modular/mutex_m/vHEAD.gemfile b/gemfiles/modular/mutex_m/vHEAD.gemfile new file mode 100644 index 00000000..8af3b6fc --- /dev/null +++ b/gemfiles/modular/mutex_m/vHEAD.gemfile @@ -0,0 +1,2 @@ +# Ruby >= 2.5 (dependency of omniauth) +gem "mutex_m", github: "ruby/mutex_m", branch: "master" diff --git a/gemfiles/modular/optional.gemfile b/gemfiles/modular/optional.gemfile new file mode 100644 index 00000000..2eda51c6 --- /dev/null +++ b/gemfiles/modular/optional.gemfile @@ -0,0 +1,2 @@ +# Optional dependencies are not depended on directly, but may be used if present. +gem "addressable", ">= 2.8", "< 3" # ruby >= 2.2 diff --git a/gemfiles/modular/rack_v1_2.gemfile b/gemfiles/modular/rack_v1_2.gemfile new file mode 100644 index 00000000..3456b97f --- /dev/null +++ b/gemfiles/modular/rack_v1_2.gemfile @@ -0,0 +1,6 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# We will test it against Ruby 2.3. +# This minor version of rack is the oldest compatible with this gem: +gem "rack", "~> 1.2", ">= 1.2.8" diff --git a/gemfiles/modular/rack_v1_6.gemfile b/gemfiles/modular/rack_v1_6.gemfile new file mode 100644 index 00000000..728aa09b --- /dev/null +++ b/gemfiles/modular/rack_v1_6.gemfile @@ -0,0 +1,6 @@ +# frozen_string_literal: true + +# Ruby >= 0 +# This is the newest version of rack that installs on Ruby < 2.2.2. +# We will test it against Ruby 2.4. +gem "rack", "~> 1.6", ">= 1.6.13" diff --git a/gemfiles/modular/rack_v2.gemfile b/gemfiles/modular/rack_v2.gemfile new file mode 100644 index 00000000..f93b415c --- /dev/null +++ b/gemfiles/modular/rack_v2.gemfile @@ -0,0 +1,6 @@ +# frozen_string_literal: true + +# Ruby >= 2.3 +# This version of rack is the last compatible with Ruby 2.3. +# We will test it against Ruby 2.5. +gem "rack", "~> 2.2", ">= 2.2.14" diff --git a/gemfiles/modular/rack_v3.gemfile b/gemfiles/modular/rack_v3.gemfile new file mode 100644 index 00000000..02678e3a --- /dev/null +++ b/gemfiles/modular/rack_v3.gemfile @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +# Ruby >= 2.4 +# We will test it against Ruby 2.6+. +gem "rack", "~> 3.1", ">= 3.1.14" diff --git a/gemfiles/modular/runtime_heads.gemfile b/gemfiles/modular/runtime_heads.gemfile new file mode 100644 index 00000000..7d74c143 --- /dev/null +++ b/gemfiles/modular/runtime_heads.gemfile @@ -0,0 +1,29 @@ +# frozen_string_literal: true + +# Test against HEAD of runtime dependencies so we can proactively file bugs + +# Ruby >= 3.0 +gem "faraday", github: "lostisland/faraday", branch: "main" + +# Ruby >= 0 +gem "hashie", github: "hashie/hashie", branch: "master" + +# Ruby >= 2.5 +gem "jwt", github: "jwt/ruby-jwt", branch: "main" + +# Ruby >= 2.5 +gem "logger", github: "ruby/logger", branch: "master" + +# Ruby >= 3.2 +gem "multi_xml", github: "sferik/multi_xml", branch: "master" + +# Ruby >= 2.4 +gem "rack", github: "rack/rack", branch: "main" + +# Ruby >= 2.2 +gem "version_gem", github: "ruby-oauth/version_gem", branch: "main" + +# Ruby >= 2.2 +gem "snaky_hash", github: "ruby-oauth/snaky_hash", branch: "main" + +eval_gemfile("x_std_libs/vHEAD.gemfile") diff --git a/gemfiles/modular/stringio/r2.4/v0.0.2.gemfile b/gemfiles/modular/stringio/r2.4/v0.0.2.gemfile new file mode 100644 index 00000000..94021cf3 --- /dev/null +++ b/gemfiles/modular/stringio/r2.4/v0.0.2.gemfile @@ -0,0 +1,4 @@ +# !!WARNING!! +# NOT SEMVER +# Last version to support Ruby <= 2.5 +gem "stringio", ">= 0.0.2" diff --git a/gemfiles/modular/stringio/r2/v3.0.gemfile b/gemfiles/modular/stringio/r2/v3.0.gemfile new file mode 100644 index 00000000..e85bb18e --- /dev/null +++ b/gemfiles/modular/stringio/r2/v3.0.gemfile @@ -0,0 +1,5 @@ +# !!WARNING!! +# NOT SEMVER +# Version 3.0.7 dropped support for Ruby <= 2.7 +# Version 3.0.0 dropped support for Ruby <= 2.4 +gem "stringio", ">= 3.0" diff --git a/gemfiles/modular/stringio/r3/v3.0.gemfile b/gemfiles/modular/stringio/r3/v3.0.gemfile new file mode 100644 index 00000000..e85bb18e --- /dev/null +++ b/gemfiles/modular/stringio/r3/v3.0.gemfile @@ -0,0 +1,5 @@ +# !!WARNING!! +# NOT SEMVER +# Version 3.0.7 dropped support for Ruby <= 2.7 +# Version 3.0.0 dropped support for Ruby <= 2.4 +gem "stringio", ">= 3.0" diff --git a/gemfiles/modular/stringio/vHEAD.gemfile b/gemfiles/modular/stringio/vHEAD.gemfile new file mode 100644 index 00000000..5f2a7412 --- /dev/null +++ b/gemfiles/modular/stringio/vHEAD.gemfile @@ -0,0 +1,2 @@ +# Ruby >= 2.5 (dependency of omniauth) +gem "stringio", github: "ruby/stringio", branch: "master" diff --git a/gemfiles/modular/style.gemfile b/gemfiles/modular/style.gemfile new file mode 100644 index 00000000..b4c80c98 --- /dev/null +++ b/gemfiles/modular/style.gemfile @@ -0,0 +1,25 @@ +# frozen_string_literal: true + +# We run rubocop on the latest version of Ruby, +# but in support of the oldest supported version of Ruby + +gem "reek", "~> 6.5" +# gem "rubocop", "~> 1.73", ">= 1.73.2" # constrained by standard +gem "rubocop-packaging", "~> 0.6", ">= 0.6.0" +gem "standard", ">= 1.50" +gem "rubocop-on-rbs", "~> 1.8" # ruby >= 3.1.0 + +# Std Lib extractions +gem "benchmark", "~> 0.4", ">= 0.4.1" # Removed from Std Lib in Ruby 3.5 + +if ENV.fetch("https://github.com/RUBOCOP_LTS_LOCAL", "false").casecmp("true").zero? + home = ENV["HOME"] + gem "rubocop-lts", path: "#{home}/src/rubocop-lts/rubocop-lts" + gem "rubocop-lts-rspec", path: "#{home}/src/rubocop-lts/rubocop-lts-rspec" + gem "rubocop-ruby2_2", path: "#{home}/src/rubocop-lts/rubocop-ruby2_2" + gem "standard-rubocop-lts", path: "#{home}/src/rubocop-lts/standard-rubocop-lts" +else + gem "rubocop-lts", "~> 8.0" + gem "rubocop-ruby2_2" + gem "rubocop-rspec", "~> 3.6" +end diff --git a/gemfiles/modular/x_std_libs.gemfile b/gemfiles/modular/x_std_libs.gemfile new file mode 100644 index 00000000..cb677752 --- /dev/null +++ b/gemfiles/modular/x_std_libs.gemfile @@ -0,0 +1,2 @@ +### Std Lib Extracted Gems +eval_gemfile "x_std_libs/r3/libs.gemfile" diff --git a/gemfiles/modular/x_std_libs/r2.3/libs.gemfile b/gemfiles/modular/x_std_libs/r2.3/libs.gemfile new file mode 100644 index 00000000..2fee8b60 --- /dev/null +++ b/gemfiles/modular/x_std_libs/r2.3/libs.gemfile @@ -0,0 +1,3 @@ +eval_gemfile "../../erb/r2.3/default.gemfile" +eval_gemfile "../../mutex_m/r2.4/v0.1.gemfile" +eval_gemfile "../../stringio/r2.4/v0.0.2.gemfile" diff --git a/gemfiles/modular/x_std_libs/r2.4/libs.gemfile b/gemfiles/modular/x_std_libs/r2.4/libs.gemfile new file mode 100644 index 00000000..5a3c5b6c --- /dev/null +++ b/gemfiles/modular/x_std_libs/r2.4/libs.gemfile @@ -0,0 +1,3 @@ +eval_gemfile "../../erb/r2.4/v2.2.gemfile" +eval_gemfile "../../mutex_m/r2.4/v0.1.gemfile" +eval_gemfile "../../stringio/r2.4/v0.0.2.gemfile" diff --git a/gemfiles/modular/x_std_libs/r2.6/libs.gemfile b/gemfiles/modular/x_std_libs/r2.6/libs.gemfile new file mode 100644 index 00000000..beac38c9 --- /dev/null +++ b/gemfiles/modular/x_std_libs/r2.6/libs.gemfile @@ -0,0 +1,3 @@ +eval_gemfile "../../erb/r2.6/v2.2.gemfile" +eval_gemfile "../../mutex_m/r2/v0.3.gemfile" +eval_gemfile "../../stringio/r2/v3.0.gemfile" diff --git a/gemfiles/modular/x_std_libs/r2/libs.gemfile b/gemfiles/modular/x_std_libs/r2/libs.gemfile new file mode 100644 index 00000000..441c4f03 --- /dev/null +++ b/gemfiles/modular/x_std_libs/r2/libs.gemfile @@ -0,0 +1,3 @@ +eval_gemfile "../../erb/r2/v3.0.gemfile" +eval_gemfile "../../mutex_m/r2/v0.3.gemfile" +eval_gemfile "../../stringio/r2/v3.0.gemfile" diff --git a/gemfiles/modular/x_std_libs/r3.1/libs.gemfile b/gemfiles/modular/x_std_libs/r3.1/libs.gemfile new file mode 100644 index 00000000..bdab5bde --- /dev/null +++ b/gemfiles/modular/x_std_libs/r3.1/libs.gemfile @@ -0,0 +1,3 @@ +eval_gemfile "../../erb/r3.1/v4.0.gemfile" +eval_gemfile "../../mutex_m/r3/v0.3.gemfile" +eval_gemfile "../../stringio/r3/v3.0.gemfile" diff --git a/gemfiles/modular/x_std_libs/r3/libs.gemfile b/gemfiles/modular/x_std_libs/r3/libs.gemfile new file mode 100644 index 00000000..c293a3dd --- /dev/null +++ b/gemfiles/modular/x_std_libs/r3/libs.gemfile @@ -0,0 +1,3 @@ +eval_gemfile "../../erb/r3/v5.0.gemfile" +eval_gemfile "../../mutex_m/r3/v0.3.gemfile" +eval_gemfile "../../stringio/r3/v3.0.gemfile" diff --git a/gemfiles/modular/x_std_libs/vHEAD.gemfile b/gemfiles/modular/x_std_libs/vHEAD.gemfile new file mode 100644 index 00000000..acc5ccbf --- /dev/null +++ b/gemfiles/modular/x_std_libs/vHEAD.gemfile @@ -0,0 +1,3 @@ +eval_gemfile "../erb/vHEAD.gemfile" +eval_gemfile "../mutex_m/vHEAD.gemfile" +eval_gemfile "../stringio/vHEAD.gemfile" diff --git a/gemfiles/omnibus.gemfile b/gemfiles/omnibus.gemfile new file mode 100644 index 00000000..a900a8ed --- /dev/null +++ b/gemfiles/omnibus.gemfile @@ -0,0 +1,25 @@ +# This file was generated by Appraisal2 + +source "https://rubygems.org/" + +gemspec path: "../" + +eval_gemfile("modular/audit.gemfile") + +eval_gemfile("modular/coverage.gemfile") + +eval_gemfile("modular/documentation.gemfile") + +eval_gemfile("modular/faraday_v2.gemfile") + +eval_gemfile("modular/hashie_v5.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_7.gemfile") + +eval_gemfile("modular/multi_xml_v0_7.gemfile") + +eval_gemfile("modular/rack_v3.gemfile") + +eval_gemfile("modular/style.gemfile") diff --git a/gemfiles/ruby_1.9.gemfile b/gemfiles/ruby_1.9.gemfile deleted file mode 100644 index bbef7523..00000000 --- a/gemfiles/ruby_1.9.gemfile +++ /dev/null @@ -1,11 +0,0 @@ -source 'https://rubygems.org/' - -gem 'faraday', '~> 0.15.4' - -gem 'json', '< 2.0' -gem 'rack', '~> 1.2' -gem 'rake', [">= 10.0", "< 12"] -gem 'term-ansicolor', '< 1.4.0' -gem 'tins', '< 1.7' - -gemspec :path => '../' diff --git a/gemfiles/ruby_2.0.gemfile b/gemfiles/ruby_2.0.gemfile deleted file mode 100644 index 87a679f6..00000000 --- a/gemfiles/ruby_2.0.gemfile +++ /dev/null @@ -1,6 +0,0 @@ -source 'https://rubygems.org/' - -gem 'faraday', '~> 0.15.4' -gem 'rack', '~> 1.2' - -gemspec :path => '../' diff --git a/gemfiles/ruby_2.1.gemfile b/gemfiles/ruby_2.1.gemfile deleted file mode 100644 index 87a679f6..00000000 --- a/gemfiles/ruby_2.1.gemfile +++ /dev/null @@ -1,6 +0,0 @@ -source 'https://rubygems.org/' - -gem 'faraday', '~> 0.15.4' -gem 'rack', '~> 1.2' - -gemspec :path => '../' diff --git a/gemfiles/ruby_2.2.gemfile b/gemfiles/ruby_2.2.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/ruby_2.2.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/ruby_2.3.gemfile b/gemfiles/ruby_2.3.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/ruby_2.3.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/ruby_2.4.gemfile b/gemfiles/ruby_2.4.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/ruby_2.4.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/ruby_2.5.gemfile b/gemfiles/ruby_2.5.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/ruby_2.5.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/ruby_2.6.gemfile b/gemfiles/ruby_2.6.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/ruby_2.6.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/ruby_2.7.gemfile b/gemfiles/ruby_2.7.gemfile deleted file mode 100644 index 822e2f2c..00000000 --- a/gemfiles/ruby_2.7.gemfile +++ /dev/null @@ -1,9 +0,0 @@ -source 'https://rubygems.org/' - -group :development do - gem 'pry' - gem 'byebug' - gem 'pry-byebug' -end - -gemspec :path => '../' diff --git a/gemfiles/ruby_2_3_hashie_v0.gemfile b/gemfiles/ruby_2_3_hashie_v0.gemfile new file mode 100644 index 00000000..e05db00c --- /dev/null +++ b/gemfiles/ruby_2_3_hashie_v0.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v0.gemfile") + +eval_gemfile("modular/hashie_v0.gemfile") + +eval_gemfile("modular/jwt_v1.gemfile") + +eval_gemfile("modular/logger_v1_2.gemfile") + +eval_gemfile("modular/multi_xml_v0_5.gemfile") + +eval_gemfile("modular/rack_v1_2.gemfile") + +eval_gemfile("modular/x_std_libs/r2.3/libs.gemfile") diff --git a/gemfiles/ruby_2_3_hashie_v1.gemfile b/gemfiles/ruby_2_3_hashie_v1.gemfile new file mode 100644 index 00000000..4c75f106 --- /dev/null +++ b/gemfiles/ruby_2_3_hashie_v1.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v0.gemfile") + +eval_gemfile("modular/hashie_v1.gemfile") + +eval_gemfile("modular/jwt_v1.gemfile") + +eval_gemfile("modular/logger_v1_2.gemfile") + +eval_gemfile("modular/multi_xml_v0_5.gemfile") + +eval_gemfile("modular/rack_v1_2.gemfile") + +eval_gemfile("modular/x_std_libs/r2.3/libs.gemfile") diff --git a/gemfiles/ruby_2_3_hashie_v2.gemfile b/gemfiles/ruby_2_3_hashie_v2.gemfile new file mode 100644 index 00000000..d4c88a94 --- /dev/null +++ b/gemfiles/ruby_2_3_hashie_v2.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v0.gemfile") + +eval_gemfile("modular/hashie_v2.gemfile") + +eval_gemfile("modular/jwt_v1.gemfile") + +eval_gemfile("modular/logger_v1_2.gemfile") + +eval_gemfile("modular/multi_xml_v0_5.gemfile") + +eval_gemfile("modular/rack_v1_2.gemfile") + +eval_gemfile("modular/x_std_libs/r2.3/libs.gemfile") diff --git a/gemfiles/ruby_2_3_hashie_v3.gemfile b/gemfiles/ruby_2_3_hashie_v3.gemfile new file mode 100644 index 00000000..d9707c54 --- /dev/null +++ b/gemfiles/ruby_2_3_hashie_v3.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v0.gemfile") + +eval_gemfile("modular/hashie_v3.gemfile") + +eval_gemfile("modular/jwt_v1.gemfile") + +eval_gemfile("modular/logger_v1_2.gemfile") + +eval_gemfile("modular/multi_xml_v0_5.gemfile") + +eval_gemfile("modular/rack_v1_2.gemfile") + +eval_gemfile("modular/x_std_libs/r2.3/libs.gemfile") diff --git a/gemfiles/ruby_2_3_hashie_v4.gemfile b/gemfiles/ruby_2_3_hashie_v4.gemfile new file mode 100644 index 00000000..fe6aa629 --- /dev/null +++ b/gemfiles/ruby_2_3_hashie_v4.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v0.gemfile") + +eval_gemfile("modular/hashie_v4.gemfile") + +eval_gemfile("modular/jwt_v1.gemfile") + +eval_gemfile("modular/logger_v1_2.gemfile") + +eval_gemfile("modular/multi_xml_v0_5.gemfile") + +eval_gemfile("modular/rack_v1_2.gemfile") + +eval_gemfile("modular/x_std_libs/r2.3/libs.gemfile") diff --git a/gemfiles/ruby_2_3_hashie_v5.gemfile b/gemfiles/ruby_2_3_hashie_v5.gemfile new file mode 100644 index 00000000..80c73ee7 --- /dev/null +++ b/gemfiles/ruby_2_3_hashie_v5.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v0.gemfile") + +eval_gemfile("modular/hashie_v5.gemfile") + +eval_gemfile("modular/jwt_v1.gemfile") + +eval_gemfile("modular/logger_v1_2.gemfile") + +eval_gemfile("modular/multi_xml_v0_5.gemfile") + +eval_gemfile("modular/rack_v1_2.gemfile") + +eval_gemfile("modular/x_std_libs/r2.3/libs.gemfile") diff --git a/gemfiles/ruby_2_4.gemfile b/gemfiles/ruby_2_4.gemfile new file mode 100644 index 00000000..040a5e7a --- /dev/null +++ b/gemfiles/ruby_2_4.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v1.gemfile") + +eval_gemfile("modular/hashie_v1.gemfile") + +eval_gemfile("modular/jwt_v1.gemfile") + +eval_gemfile("modular/logger_v1_2.gemfile") + +eval_gemfile("modular/multi_xml_v0_5.gemfile") + +eval_gemfile("modular/rack_v1_6.gemfile") + +eval_gemfile("modular/x_std_libs/r2.4/libs.gemfile") diff --git a/gemfiles/ruby_2_5.gemfile b/gemfiles/ruby_2_5.gemfile new file mode 100644 index 00000000..ebc8793a --- /dev/null +++ b/gemfiles/ruby_2_5.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v1.gemfile") + +eval_gemfile("modular/hashie_v2.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_5.gemfile") + +eval_gemfile("modular/multi_xml_v0_6.gemfile") + +eval_gemfile("modular/rack_v2.gemfile") + +eval_gemfile("modular/x_std_libs/r2.6/libs.gemfile") diff --git a/gemfiles/ruby_2_6.gemfile b/gemfiles/ruby_2_6.gemfile new file mode 100644 index 00000000..cda9b771 --- /dev/null +++ b/gemfiles/ruby_2_6.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v2.gemfile") + +eval_gemfile("modular/hashie_v3.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_5.gemfile") + +eval_gemfile("modular/multi_xml_v0_6.gemfile") + +eval_gemfile("modular/rack_v3.gemfile") + +eval_gemfile("modular/x_std_libs/r2.6/libs.gemfile") diff --git a/gemfiles/ruby_2_7.gemfile b/gemfiles/ruby_2_7.gemfile new file mode 100644 index 00000000..2a1c3f9f --- /dev/null +++ b/gemfiles/ruby_2_7.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v2.gemfile") + +eval_gemfile("modular/hashie_v4.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_7.gemfile") + +eval_gemfile("modular/multi_xml_v0_6.gemfile") + +eval_gemfile("modular/rack_v3.gemfile") + +eval_gemfile("modular/x_std_libs/r2/libs.gemfile") diff --git a/gemfiles/ruby_3_0.gemfile b/gemfiles/ruby_3_0.gemfile new file mode 100644 index 00000000..64aecbb9 --- /dev/null +++ b/gemfiles/ruby_3_0.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v2.gemfile") + +eval_gemfile("modular/hashie_v5.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_7.gemfile") + +eval_gemfile("modular/multi_xml_v0_6.gemfile") + +eval_gemfile("modular/rack_v3.gemfile") + +eval_gemfile("modular/x_std_libs/r3.1/libs.gemfile") diff --git a/gemfiles/ruby_3_1.gemfile b/gemfiles/ruby_3_1.gemfile new file mode 100644 index 00000000..64aecbb9 --- /dev/null +++ b/gemfiles/ruby_3_1.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v2.gemfile") + +eval_gemfile("modular/hashie_v5.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_7.gemfile") + +eval_gemfile("modular/multi_xml_v0_6.gemfile") + +eval_gemfile("modular/rack_v3.gemfile") + +eval_gemfile("modular/x_std_libs/r3.1/libs.gemfile") diff --git a/gemfiles/ruby_3_2.gemfile b/gemfiles/ruby_3_2.gemfile new file mode 100644 index 00000000..74a84749 --- /dev/null +++ b/gemfiles/ruby_3_2.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v2.gemfile") + +eval_gemfile("modular/hashie_v5.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_7.gemfile") + +eval_gemfile("modular/multi_xml_v0_7.gemfile") + +eval_gemfile("modular/rack_v3.gemfile") + +eval_gemfile("modular/x_std_libs/r3/libs.gemfile") diff --git a/gemfiles/ruby_3_3.gemfile b/gemfiles/ruby_3_3.gemfile new file mode 100644 index 00000000..74a84749 --- /dev/null +++ b/gemfiles/ruby_3_3.gemfile @@ -0,0 +1,19 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/faraday_v2.gemfile") + +eval_gemfile("modular/hashie_v5.gemfile") + +eval_gemfile("modular/jwt_v2.gemfile") + +eval_gemfile("modular/logger_v1_7.gemfile") + +eval_gemfile("modular/multi_xml_v0_7.gemfile") + +eval_gemfile("modular/rack_v3.gemfile") + +eval_gemfile("modular/x_std_libs/r3/libs.gemfile") diff --git a/gemfiles/ruby_head.gemfile b/gemfiles/ruby_head.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/ruby_head.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/style.gemfile b/gemfiles/style.gemfile new file mode 100644 index 00000000..f1d77e54 --- /dev/null +++ b/gemfiles/style.gemfile @@ -0,0 +1,9 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/style.gemfile") + +eval_gemfile("modular/x_std_libs.gemfile") diff --git a/gemfiles/truffleruby.gemfile b/gemfiles/truffleruby.gemfile deleted file mode 100644 index a02c547f..00000000 --- a/gemfiles/truffleruby.gemfile +++ /dev/null @@ -1,3 +0,0 @@ -source 'https://rubygems.org/' - -gemspec :path => '../' diff --git a/gemfiles/unlocked_deps.gemfile b/gemfiles/unlocked_deps.gemfile new file mode 100644 index 00000000..50f8c85c --- /dev/null +++ b/gemfiles/unlocked_deps.gemfile @@ -0,0 +1,15 @@ +# This file was generated by Appraisal2 + +source "https://gem.coop/" + +gemspec path: "../" + +eval_gemfile("modular/coverage.gemfile") + +eval_gemfile("modular/documentation.gemfile") + +eval_gemfile("modular/style.gemfile") + +eval_gemfile("modular/optional.gemfile") + +eval_gemfile("modular/x_std_libs.gemfile") diff --git a/gemfiles/vanilla.gemfile b/gemfiles/vanilla.gemfile new file mode 100644 index 00000000..0ac28b98 --- /dev/null +++ b/gemfiles/vanilla.gemfile @@ -0,0 +1,5 @@ +# This file was generated by Appraisal2 + +source "https://rubygems.org/" + +gemspec path: "../" diff --git a/lib/oauth2.rb b/lib/oauth2.rb index 61a97927..f0fd7f8b 100644 --- a/lib/oauth2.rb +++ b/lib/oauth2.rb @@ -1,22 +1,81 @@ +# frozen_string_literal: true + # includes modules from stdlib -require 'cgi' -require 'time' +require "cgi" +require "time" + +# third party gems +require "snaky_hash" +require "version_gem" # includes gem files -require 'oauth2/error' -require 'oauth2/snaky_hash' -require 'oauth2/authenticator' -require 'oauth2/client' -require 'oauth2/strategy/base' -require 'oauth2/strategy/auth_code' -require 'oauth2/strategy/implicit' -require 'oauth2/strategy/password' -require 'oauth2/strategy/client_credentials' -require 'oauth2/strategy/assertion' -require 'oauth2/access_token' -require 'oauth2/mac_token' -require 'oauth2/response' +require_relative "oauth2/version" +require_relative "oauth2/filtered_attributes" +require_relative "oauth2/error" +require_relative "oauth2/authenticator" +require_relative "oauth2/client" +require_relative "oauth2/strategy/base" +require_relative "oauth2/strategy/auth_code" +require_relative "oauth2/strategy/implicit" +require_relative "oauth2/strategy/password" +require_relative "oauth2/strategy/client_credentials" +require_relative "oauth2/strategy/assertion" +require_relative "oauth2/access_token" +require_relative "oauth2/response" # The namespace of this library +# +# This module is the entry point and top-level namespace for the oauth2 gem. +# It exposes configuration, constants, and requires the primary public classes. module OAuth2 + # When true, enables verbose HTTP logging via Faraday's logger middleware. + # Controlled by the OAUTH_DEBUG environment variable. Any case-insensitive + # value equal to "true" will enable debugging. + # + # @return [Boolean] + OAUTH_DEBUG = ENV.fetch("https://github.com/OAUTH_DEBUG", "false").casecmp("true").zero? + + # Default configuration values for the oauth2 library. + # + # @example Toggle warnings + # OAuth2.configure do |config| + # config[:silence_extra_tokens_warning] = false + # config[:silence_no_tokens_warning] = false + # end + # + # @return [SnakyHash::SymbolKeyed] A mutable Hash-like config with symbol keys + DEFAULT_CONFIG = SnakyHash::SymbolKeyed.new( + silence_extra_tokens_warning: true, + silence_no_tokens_warning: true, + ) + + # The current runtime configuration for the library. + # + # @return [SnakyHash::SymbolKeyed] + @config = DEFAULT_CONFIG.dup + + class << self + # Access the current configuration. + # + # Prefer using {OAuth2.configure} to mutate configuration. + # + # @return [SnakyHash::SymbolKeyed] + attr_reader :config + end + + # Configure global library behavior. + # + # Yields the mutable configuration object so callers can update settings. + # + # @yieldparam [SnakyHash::SymbolKeyed] config the configuration object + # @return [void] + def configure + yield @config + end + module_function :configure +end + +# Extend OAuth2::Version with VersionGem helpers to provide semantic version helpers. +OAuth2::Version.class_eval do + extend VersionGem::Basic end diff --git a/lib/oauth2/access_token.rb b/lib/oauth2/access_token.rb index 274a6250..8c68e321 100644 --- a/lib/oauth2/access_token.rb +++ b/lib/oauth2/access_token.rb @@ -1,59 +1,182 @@ +# frozen_string_literal: true + +# :nocov: +begin + # The first version of hashie that has a version file was 1.1.0 + # The first version of hashie that required the version file at runtime was 3.2.0 + # If it has already been loaded then this is very low cost, as Kernel.require uses maintains a cache + # If this it hasn't this will work to get it loaded, and then we will be able to use + # defined?(Hashie::Version) + # as a test. + # TODO: get rid this mess when we drop Hashie < 3.2, as Hashie will self-load its version then + require "hashie/version" +rescue LoadError + nil +end +# :nocov: + module OAuth2 - class AccessToken + class AccessToken # rubocop:disable Metrics/ClassLength + TOKEN_KEYS_STR = %w[access_token id_token token accessToken idToken].freeze + TOKEN_KEYS_SYM = %i[access_token id_token token accessToken idToken].freeze + TOKEN_KEY_LOOKUP = TOKEN_KEYS_STR + TOKEN_KEYS_SYM + + include FilteredAttributes + attr_reader :client, :token, :expires_in, :expires_at, :expires_latency, :params attr_accessor :options, :refresh_token, :response + filtered_attributes :token, :refresh_token class << self # Initializes an AccessToken from a Hash # - # @param client [Client] the OAuth2::Client instance - # @param hash [Hash] a hash of AccessToken property values - # @return [AccessToken] the initalized AccessToken + # @param [OAuth2::Client] client the OAuth2::Client instance + # @param [Hash] hash a hash containing the token and other properties + # @option hash [String] 'access_token' the access token value + # @option hash [String] 'id_token' alternative key for the access token value + # @option hash [String] 'token' alternative key for the access token value + # @option hash [String] 'refresh_token' (optional) the refresh token value + # @option hash [Integer, String] 'expires_in' (optional) number of seconds until token expires + # @option hash [Integer, String] 'expires_at' (optional) epoch time in seconds when token expires + # @option hash [Integer, String] 'expires_latency' (optional) seconds to reduce token validity by + # + # @return [OAuth2::AccessToken] the initialized AccessToken + # + # @note The method will use the first found token key in the following order: + # 'access_token', 'id_token', 'token' (or their symbolic versions) + # @note If multiple token keys are present, a warning will be issued unless + # OAuth2.config.silence_extra_tokens_warning is true + # @note If no token keys are present, a warning will be issued unless + # OAuth2.config.silence_no_tokens_warning is true + # @note For "soon-to-expire"/"clock-skew" functionality see the `:expires_latency` option. + # @note If snaky key conversion is being used, token_name needs to match the converted key. + # + # @example + # hash = { 'access_token' => 'token_value', 'refresh_token' => 'refresh_value' } + # access_token = OAuth2::AccessToken.from_hash(client, hash) def from_hash(client, hash) - hash = hash.dup - new(client, hash.delete('access_token') || hash.delete(:access_token), hash) + fresh = hash.dup + # If token_name is present, then use that key name + key = + if fresh.key?(:token_name) + t_key = fresh[:token_name] + no_tokens_warning(fresh, t_key) + t_key + else + # Otherwise, if one of the supported default keys is present, use whichever has precedence + supported_keys = TOKEN_KEY_LOOKUP & fresh.keys + t_key = supported_keys[0] + extra_tokens_warning(supported_keys, t_key) + t_key + end + # :nocov: + # TODO: Get rid of this branching logic when dropping Hashie < v3.2 + token = if !defined?(Hashie::VERSION) # i.e. <= "1.1.0"; the first Hashie to ship with a VERSION constant + warn("snaky_hash and oauth2 will drop support for Hashie v0 in the next major version. Please upgrade to a modern Hashie.") + # There is a bug in Hashie v0, which is accounts for. + fresh.delete(key) || fresh[key] || "" + else + fresh.delete(key) || "" + end + # :nocov: + new(client, token, fresh) end # Initializes an AccessToken from a key/value application/x-www-form-urlencoded string # # @param [Client] client the OAuth2::Client instance # @param [String] kvform the application/x-www-form-urlencoded string - # @return [AccessToken] the initalized AccessToken + # @return [AccessToken] the initialized AccessToken def from_kvform(client, kvform) from_hash(client, Rack::Utils.parse_query(kvform)) end + + private + + # Having too many is sus, and may lead to bugs. Having none is fine (e.g. refresh flow doesn't need a token). + def extra_tokens_warning(supported_keys, key) + return if OAuth2.config.silence_extra_tokens_warning + return if supported_keys.length <= 1 + + warn("OAuth2::AccessToken.from_hash: `hash` contained more than one 'token' key (#{supported_keys}); using #{key.inspect}.") + end + + def no_tokens_warning(hash, key) + return if OAuth2.config.silence_no_tokens_warning + return if key && hash.key?(key) + + warn(%[ +OAuth2::AccessToken#from_hash key mismatch. +Custom token_name (#{key}) is not found in (#{hash.keys}) +You may need to set `snaky: false`. See inline documentation for more info. + ]) + end end - # Initalize an AccessToken + # Initialize an AccessToken + # + # @note For "soon-to-expire"/"clock-skew" functionality see the `:expires_latency` option. + # @note If no token is provided, the AccessToken will be considered invalid. + # This is to prevent the possibility of a token being accidentally + # created with no token value. + # If you want to create an AccessToken with no token value, + # you can pass in an empty string or nil for the token value. + # If you want to create an AccessToken with no token value and + # no refresh token, you can pass in an empty string or nil for the + # token value and nil for the refresh token, and `raise_errors: false`. # # @param [Client] client the OAuth2::Client instance - # @param [String] token the Access Token value + # @param [String] token the Access Token value (optional, may not be used in refresh flows) # @param [Hash] opts the options to create the Access Token with # @option opts [String] :refresh_token (nil) the refresh_token value # @option opts [FixNum, String] :expires_in (nil) the number of seconds in which the AccessToken will expire # @option opts [FixNum, String] :expires_at (nil) the epoch time in seconds in which AccessToken will expire - # @option opts [FixNum, String] :expires_latency (nil) the number of seconds by which AccessToken validity will be reduced to offset latency - # @option opts [Symbol] :mode (:header) the transmission mode of the Access Token parameter value - # one of :header, :body or :query + # @option opts [FixNum, String] :expires_latency (nil) the number of seconds by which AccessToken validity will be reduced to offset latency, @version 2.0+ + # @option opts [Symbol, Hash, or callable] :mode (:header) the transmission mode of the Access Token parameter value: + # either one of :header, :body or :query; or a Hash with verb symbols as keys mapping to one of these symbols + # (e.g., `{get: :query, post: :header, delete: :header}`); or a callable that accepts a request-verb parameter + # and returns one of these three symbols. # @option opts [String] :header_format ('Bearer %s') the string format to use for the Authorization header + # + # @example Verb-dependent Hash mode + # # Send token in query for GET, in header for POST/DELETE, in body for PUT/PATCH + # OAuth2::AccessToken.new(client, token, mode: {get: :query, post: :header, delete: :header, put: :body, patch: :body}) # @option opts [String] :param_name ('access_token') the parameter name to use for transmission of the # Access Token value in :body or :query transmission mode - def initialize(client, token, opts = {}) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength, Metrics/CyclomaticComplexity + # @option opts [String] :token_name (nil) the name of the response parameter that identifies the access token + # When nil one of TOKEN_KEY_LOOKUP will be used + def initialize(client, token, opts = {}) @client = client @token = token.to_s opts = opts.dup - [:refresh_token, :expires_in, :expires_at, :expires_latency].each do |arg| + %i[refresh_token expires_in expires_at expires_latency].each do |arg| instance_variable_set("@#{arg}", opts.delete(arg) || opts.delete(arg.to_s)) end - @expires_in ||= opts.delete('expires') + no_tokens = (@token.nil? || @token.empty?) && (@refresh_token.nil? || @refresh_token.empty?) + if no_tokens + if @client.options[:raise_errors] + raise Error.new({ + error: "OAuth2::AccessToken has no token", + error_description: "Options are: #{opts.inspect}", + }) + elsif !OAuth2.config.silence_no_tokens_warning + warn("OAuth2::AccessToken has no token") + end + end + # @option opts [Fixnum, String] :expires is deprecated + @expires_in ||= opts.delete("expires") @expires_in &&= @expires_in.to_i @expires_at &&= convert_expires_at(@expires_at) @expires_latency &&= @expires_latency.to_i - @expires_at ||= Time.now.to_i + @expires_in if @expires_in + @expires_at ||= Time.now.to_i + @expires_in if @expires_in && !@expires_in.zero? @expires_at -= @expires_latency if @expires_latency - @options = {:mode => opts.delete(:mode) || :header, - :header_format => opts.delete(:header_format) || 'Bearer %s', - :param_name => opts.delete(:param_name) || 'access_token'} + @options = { + mode: opts.delete(:mode) || :header, + header_format: opts.delete(:header_format) || "Bearer %s", + param_name: opts.delete(:param_name) || "access_token", + } + @options[:token_name] = opts.delete(:token_name) if opts.key?(:token_name) + @params = opts end @@ -64,42 +187,131 @@ def [](key) @params[key] end - # Whether or not the token expires + # Whether the token expires # # @return [Boolean] def expires? !!@expires_at end - # Whether or not the token is expired + # Check if token is expired # - # @return [Boolean] + # @return [Boolean] true if the token is expired, false otherwise def expired? expires? && (expires_at <= Time.now.to_i) end # Refreshes the current Access Token # - # @return [AccessToken] a new AccessToken - # @note options should be carried over to the new AccessToken - def refresh(params = {}, access_token_opts = {}, access_token_class = self.class) - raise('A refresh_token is not available') unless refresh_token - params[:grant_type] = 'refresh_token' + # @param [Hash] params additional params to pass to the refresh token request + # @param [Hash] access_token_opts options that will be passed to the AccessToken initialization + # + # @yield [opts] The block to modify the refresh token request options + # @yieldparam [Hash] opts The options hash that can be modified + # + # @return [OAuth2::AccessToken] a new AccessToken instance + # + # @note current token's options are carried over to the new AccessToken + def refresh(params = {}, access_token_opts = {}, &block) + raise OAuth2::Error.new({error: "A refresh_token is not available"}) unless refresh_token + + params[:grant_type] = "refresh_token" params[:refresh_token] = refresh_token - new_token = @client.get_token(params, access_token_opts, access_token_class) + new_token = @client.get_token(params, access_token_opts, &block) new_token.options = options - new_token.refresh_token = refresh_token unless new_token.refresh_token + if new_token.refresh_token + # Keep it if there is one + else + new_token.refresh_token = refresh_token + end new_token end # A compatibility alias # @note does not modify the receiver, so bang is not the default method - alias refresh! refresh + alias_method :refresh!, :refresh + + # Revokes the token at the authorization server + # + # @param [Hash] params additional parameters to be sent during revocation + # @option params [String, Symbol, nil] :token_type_hint ('access_token' or 'refresh_token') hint about which token to revoke + # @option params [Symbol] :token_method (:post_with_query_string) overrides OAuth2::Client#options[:token_method] + # + # @yield [req] The block is passed the request being made, allowing customization + # @yieldparam [Faraday::Request] req The request object that can be modified + # + # @return [OAuth2::Response] OAuth2::Response instance + # + # @api public + # + # @raise [OAuth2::Error] if token_type_hint is invalid or the specified token is not available + # + # @note If the token passed to the request + # is an access token, the server MAY revoke the respective refresh + # token as well. + # @note If the token passed to the request + # is a refresh token and the authorization server supports the + # revocation of access tokens, then the authorization server SHOULD + # also invalidate all access tokens based on the same authorization + # grant + # @note If the server responds with HTTP status code 503, your code must + # assume the token still exists and may retry after a reasonable delay. + # The server may include a "Retry-After" header in the response to + # indicate how long the service is expected to be unavailable to the + # requesting client. + # + # @see https://datatracker.ietf.org/doc/html/rfc7009 + # @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.1 + def revoke(params = {}, &block) + token_type_hint_orig = params.delete(:token_type_hint) + token_type_hint = nil + revoke_token = case token_type_hint_orig + when "access_token", :access_token + token_type_hint = "access_token" + token + when "refresh_token", :refresh_token + token_type_hint = "refresh_token" + refresh_token + when nil + if token + token_type_hint = "access_token" + token + elsif refresh_token + token_type_hint = "refresh_token" + refresh_token + end + else + raise OAuth2::Error.new({error: "token_type_hint must be one of [nil, :refresh_token, :access_token], so if you need something else consider using a subclass or entirely custom AccessToken class."}) + end + raise OAuth2::Error.new({error: "#{token_type_hint || "unknown token type"} is not available for revoking"}) unless revoke_token && !revoke_token.empty? + + @client.revoke_token(revoke_token, token_type_hint, params, &block) + end + # A compatibility alias + # @note does not modify the receiver, so bang is not the default method + alias_method :revoke!, :revoke # Convert AccessToken to a hash which can be used to rebuild itself with AccessToken.from_hash # + # @note Don't return expires_latency because it has already been deducted from expires_at + # # @return [Hash] a hash of AccessToken property values def to_hash - params.merge(:access_token => token, :refresh_token => refresh_token, :expires_at => expires_at) + hsh = { + access_token: token, + refresh_token: refresh_token, + expires_at: expires_at, + mode: options[:mode], + header_format: options[:header_format], + param_name: options[:param_name], + } + hsh[:token_name] = options[:token_name] if options.key?(:token_name) + # TODO: Switch when dropping Ruby < 2.5 support + # params.transform_keys(&:to_sym) # Ruby 2.5 only + # Old Ruby transform_keys alternative: + sheesh = @params.each_with_object({}) { |(k, v), memo| + memo[k.to_sym] = v + } + sheesh.merge(hsh) end # Make a request with the Access Token @@ -107,9 +319,18 @@ def to_hash # @param [Symbol] verb the HTTP request method # @param [String] path the HTTP URL path of the request # @param [Hash] opts the options to make the request with - # @see Client#request + # @option opts [Hash] :params additional URL parameters + # @option opts [Hash, String] :body the request body + # @option opts [Hash] :headers request headers + # + # @yield [req] The block to modify the request + # @yieldparam [Faraday::Request] req The request object that can be modified + # + # @return [OAuth2::Response] the response from the request + # + # @see OAuth2::Client#request def request(verb, path, opts = {}, &block) - configure_authentication!(opts) + configure_authentication!(opts, verb) @client.request(verb, path, opts, &block) end @@ -150,17 +371,31 @@ def delete(path, opts = {}, &block) # Get the headers hash (includes Authorization token) def headers - {'Authorization' => options[:header_format] % token} + {"Authorization" => options[:header_format] % token} end private - def configure_authentication!(opts) # rubocop:disable MethodLength, Metrics/AbcSize - case options[:mode] + def configure_authentication!(opts, verb) + mode_opt = options[:mode] + mode = + if mode_opt.respond_to?(:call) + mode_opt.call(verb) + elsif mode_opt.is_a?(Hash) + key = verb.to_sym + # Try symbol key first, then string key; default to :header when missing + mode_opt[key] || mode_opt[key.to_s] || :header + else + mode_opt + end + + case mode when :header opts[:headers] ||= {} opts[:headers].merge!(headers) when :query + # OAuth 2.1 note: Bearer tokens in the query string are omitted from the spec due to security risks. + # Prefer the default :header mode whenever possible. opts[:params] ||= {} opts[:params][options[:param_name]] = token when :body @@ -168,19 +403,18 @@ def configure_authentication!(opts) # rubocop:disable MethodLength, Metrics/AbcS if opts[:body].is_a?(Hash) opts[:body][options[:param_name]] = token else - opts[:body] << "&#{options[:param_name]}=#{token}" + opts[:body] += "&#{options[:param_name]}=#{token}" end # @todo support for multi-part (file uploads) else - raise("invalid :mode option of #{options[:mode]}") + raise("invalid :mode option of #{mode}") end end def convert_expires_at(expires_at) - expires_at_i = expires_at.to_i - return expires_at_i if expires_at_i > Time.now.utc.to_i - return Time.parse(expires_at).to_i if expires_at.is_a?(String) - expires_at_i + Time.iso8601(expires_at.to_s).to_i + rescue ArgumentError + expires_at.to_i end end end diff --git a/lib/oauth2/authenticator.rb b/lib/oauth2/authenticator.rb index d21660db..5fbdc758 100644 --- a/lib/oauth2/authenticator.rb +++ b/lib/oauth2/authenticator.rb @@ -1,9 +1,26 @@ -require 'base64' +# frozen_string_literal: true + +require "base64" module OAuth2 + # Builds and applies client authentication to token and revoke requests. + # + # Depending on the selected mode, credentials are applied as Basic Auth + # headers, request body parameters, or only the client_id is sent (TLS). class Authenticator + include FilteredAttributes + + # @return [Symbol, String] Authentication mode (e.g., :basic_auth, :request_body, :tls_client_auth, :private_key_jwt) + # @return [String, nil] Client identifier + # @return [String, nil] Client secret (filtered in inspected output) attr_reader :mode, :id, :secret + filtered_attributes :secret + # Create a new Authenticator + # + # @param [String, nil] id Client identifier + # @param [String, nil] secret Client secret + # @param [Symbol, String] mode Authentication mode def initialize(id, secret, mode) @id = id @secret = secret @@ -12,7 +29,7 @@ def initialize(id, secret, mode) # Apply the request credentials used to authenticate to the Authorization Server # - # Depending on configuration, this might be as request params or as an + # Depending on the configuration, this might be as request params or as an # Authorization header. # # User-provided params and header take precedence. @@ -34,35 +51,57 @@ def apply(params) end end + # Encodes a Basic Authorization header value for the provided credentials. + # + # @param [String] user The client identifier + # @param [String] password The client secret + # @return [String] The value to use for the Authorization header def self.encode_basic_auth(user, password) - 'Basic ' + Base64.strict_encode64(user + ':' + password) + "Basic #{Base64.strict_encode64("#{user}:#{password}")}" end private # Adds client_id and client_secret request parameters if they are not # already set. + # + # @param [Hash] params Request parameters + # @return [Hash] Updated parameters including client_id and client_secret def apply_params_auth(params) - {'client_id' => id, 'client_secret' => secret}.merge(params) + result = {} + result["client_id"] = id unless id.nil? + result["client_secret"] = secret unless secret.nil? + result.merge(params) end - # When using schemes that don't require the client_secret to be passed i.e TLS Client Auth, + # When using schemes that don't require the client_secret to be passed (e.g., TLS Client Auth), # we don't want to send the secret + # + # @param [Hash] params Request parameters + # @return [Hash] Updated parameters including only client_id def apply_client_id(params) - { 'client_id' => id }.merge(params) + result = {} + result["client_id"] = id unless id.nil? + result.merge(params) end # Adds an `Authorization` header with Basic Auth credentials if and only if # it is not already set in the params. + # + # @param [Hash] params Request parameters (may include :headers) + # @return [Hash] Updated parameters with Authorization header def apply_basic_auth(params) headers = params.fetch(:headers, {}) headers = basic_auth_header.merge(headers) - params.merge(:headers => headers) + params.merge(headers: headers) end - # @see https://tools.ietf.org/html/rfc2617#section-2 + # Build the Basic Authorization header. + # + # @see https://datatracker.ietf.org/doc/html/rfc2617#section-2 + # @return [Hash] Header hash containing the Authorization entry def basic_auth_header - {'Authorization' => self.class.encode_basic_auth(id, secret)} + {"Authorization" => self.class.encode_basic_auth(id, secret)} end end end diff --git a/lib/oauth2/client.rb b/lib/oauth2/client.rb index 020bd654..7c64c3c1 100644 --- a/lib/oauth2/client.rb +++ b/lib/oauth2/client.rb @@ -1,33 +1,51 @@ -require 'faraday' -require 'logger' +# frozen_string_literal: true + +require "faraday" +require "logger" + +# :nocov: since coverage tracking only runs on the builds with Faraday v2 +# We do run builds on Faraday v0 (and v1!), so this code is actually covered! +# This is the only nocov in the whole project! +if Faraday::Utils.respond_to?(:default_space_encoding) + # This setting doesn't exist in faraday 0.x + Faraday::Utils.default_space_encoding = "%20" +end +# :nocov: module OAuth2 + ConnectionError = Class.new(Faraday::ConnectionFailed) + TimeoutError = Class.new(Faraday::TimeoutError) + # The OAuth2::Client class class Client # rubocop:disable Metrics/ClassLength - RESERVED_PARAM_KEYS = ['headers', 'parse'].freeze + RESERVED_REQ_KEYS = %w[body headers params redirect_count].freeze + RESERVED_PARAM_KEYS = (RESERVED_REQ_KEYS + %w[parse snaky snaky_hash_klass token_method]).freeze + + include FilteredAttributes attr_reader :id, :secret, :site attr_accessor :options attr_writer :connection + filtered_attributes :secret - # Instantiate a new OAuth 2.0 client using the - # Client ID and Client Secret registered to your - # application. + # Initializes a new OAuth2::Client instance using the Client ID and Client Secret registered to your application. # # @param [String] client_id the client_id value # @param [String] client_secret the client_secret value - # @param [Hash] options the options to create the client with + # @param [Hash] options the options to configure the client # @option options [String] :site the OAuth2 provider site host - # @option options [String] :redirect_uri the absolute URI to the Redirection Endpoint for use in authorization grants and token exchange # @option options [String] :authorize_url ('/oauth/authorize') absolute or relative URL path to the Authorization endpoint + # @option options [String] :revoke_url ('/oauth/revoke') absolute or relative URL path to the Revoke endpoint # @option options [String] :token_url ('/oauth/token') absolute or relative URL path to the Token endpoint - # @option options [Symbol] :token_method (:post) HTTP method to use to request token (:get or :post) - # @option options [Symbol] :auth_scheme (:basic_auth) HTTP method to use to authorize request (:basic_auth or :request_body) - # @option options [Hash] :connection_opts ({}) Hash of connection options to pass to initialize Faraday with - # @option options [FixNum] :max_redirects (5) maximum number of redirects to follow - # @option options [Boolean] :raise_errors (true) whether or not to raise an OAuth2::Error - # @option options [Logger] :logger (::Logger.new($stdout)) which logger to use when OAUTH_DEBUG is enabled - # on responses with 400+ status codes + # @option options [Symbol] :token_method (:post) HTTP method to use to request token (:get, :post, :post_with_query_string) + # @option options [Symbol] :auth_scheme (:basic_auth) the authentication scheme (:basic_auth, :request_body, :tls_client_auth, :private_key_jwt) + # @option options [Hash] :connection_opts ({}) Hash of connection options to pass to initialize Faraday + # @option options [Boolean] :raise_errors (true) whether to raise an OAuth2::Error on responses with 400+ status codes + # @option options [Integer] :max_redirects (5) maximum number of redirects to follow + # @option options [Logger] :logger (::Logger.new($stdout)) Logger instance for HTTP request/response output; requires OAUTH_DEBUG to be true + # @option options [Class] :access_token_class (AccessToken) class to use for access tokens; you can subclass OAuth2::AccessToken, @version 2.0+ + # @option options [Hash] :ssl SSL options for Faraday + # # @yield [builder] The Faraday connection builder def initialize(client_id, client_secret, options = {}, &block) opts = options.dup @@ -35,27 +53,35 @@ def initialize(client_id, client_secret, options = {}, &block) @secret = client_secret @site = opts.delete(:site) ssl = opts.delete(:ssl) - @options = {:authorize_url => 'oauth/authorize', - :token_url => 'oauth/token', - :token_method => :post, - :auth_scheme => :basic_auth, - :connection_opts => {}, - :connection_build => block, - :max_redirects => 5, - :raise_errors => true, - :logger => ::Logger.new($stdout)}.merge!(opts) + warn("OAuth2::Client#initialize argument `extract_access_token` will be removed in oauth2 v3. Refactor to use `access_token_class`.") if opts[:extract_access_token] + @options = { + authorize_url: "oauth/authorize", + revoke_url: "oauth/revoke", + token_url: "oauth/token", + token_method: :post, + auth_scheme: :basic_auth, + connection_opts: {}, + connection_build: block, + max_redirects: 5, + raise_errors: true, + logger: ::Logger.new($stdout), + access_token_class: AccessToken, + }.merge(opts) @options[:connection_opts][:ssl] = ssl if ssl end # Set the site host # - # @param value [String] the OAuth2 provider site host + # @param [String] value the OAuth2 provider site host + # @return [String] the site host value def site=(value) @connection = nil @site = value end # The Faraday connection object + # + # @return [Faraday::Connection] the initialized Faraday connection def connection @connection ||= Faraday.new(site, options[:connection_opts]) do |builder| @@ -63,8 +89,8 @@ def connection if options[:connection_build] options[:connection_build].call(builder) else - builder.request :url_encoded # form-encode POST params - builder.adapter Faraday.default_adapter # make requests with Net::HTTP + builder.request(:url_encoded) # form-encode POST params + builder.adapter(Faraday.default_adapter) # make requests with Net::HTTP end end end @@ -72,6 +98,7 @@ def connection # The authorize endpoint URL of the OAuth2 provider # # @param [Hash] params additional query parameters + # @return [String] the constructed authorize URL def authorize_url(https://github.com/params%20=%20%7B%7D) params = (params || {}).merge(redirection_params) connection.build_url(https://github.com/options[:authorize_url],%20params).to_s @@ -79,126 +106,211 @@ def authorize_url(https://github.com/params%20=%20%7B%7D) # The token endpoint URL of the OAuth2 provider # - # @param [Hash] params additional query parameters + # @param [Hash, nil] params additional query parameters + # @return [String] the constructed token URL def token_url(https://github.com/params%20=%20nil) connection.build_url(https://github.com/options[:token_url],%20params).to_s end + # The revoke endpoint URL of the OAuth2 provider + # + # @param [Hash, nil] params additional query parameters + # @return [String] the constructed revoke URL + def revoke_url(https://github.com/params%20=%20nil) + connection.build_url(https://github.com/options[:revoke_url],%20params).to_s + end + # Makes a request relative to the specified site root. # - # @param [Symbol] verb one of :get, :post, :put, :delete + # Updated HTTP 1.1 specification (IETF RFC 7231) relaxed the original constraint (IETF RFC 2616), + # allowing the use of relative URLs in Location headers. + # + # @see https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.2 + # + # @param [Symbol] verb one of [:get, :post, :put, :delete] # @param [String] url URL path of request - # @param [Hash] opts the options to make the request with - # @option opts [Hash] :params additional query parameters for the URL of the request - # @option opts [Hash, String] :body the body of the request - # @option opts [Hash] :headers http request headers - # @option opts [Boolean] :raise_errors whether or not to raise an OAuth2::Error on 400+ status - # code response for this request. Will default to client option - # @option opts [Symbol] :parse @see Response::initialize - # @yield [req] The Faraday request - def request(verb, url, opts = {}) # rubocop:disable CyclomaticComplexity, MethodLength, Metrics/AbcSize - url = connection.build_https://github.com/url(url).to_s - response = connection.run_request(verb, url, opts[:body], opts[:headers]) do |req| - req.params.update(opts[:params]) if opts[:params] - yield(req) if block_given? - end - response = Response.new(response, :parse => opts[:parse]) + # @param [Hash] req_opts the options to make the request with + # @option req_opts [Hash] :params additional query parameters for the URL of the request + # @option req_opts [Hash, String] :body the body of the request + # @option req_opts [Hash] :headers http request headers + # @option req_opts [Boolean] :raise_errors whether to raise an OAuth2::Error on 400+ status + # code response for this request. Overrides the client instance setting. + # @option req_opts [Symbol] :parse @see Response::initialize + # @option req_opts [Boolean] :snaky (true) @see Response::initialize + # + # @yield [req] The block is passed the request being made, allowing customization + # @yieldparam [Faraday::Request] req The request object that can be modified + # @see Faraday::Connection#run_request + # + # @return [OAuth2::Response] the response from the request + def request(verb, url, req_opts = {}, &block) + response = execute_request(verb, url, req_opts, &block) + status = response.status - case response.status + case status when 301, 302, 303, 307 - opts[:redirect_count] ||= 0 - opts[:redirect_count] += 1 - return response if opts[:redirect_count] > options[:max_redirects] - if response.status == 303 + req_opts[:redirect_count] ||= 0 + req_opts[:redirect_count] += 1 + return response if req_opts[:redirect_count] > options[:max_redirects] + + if status == 303 verb = :get - opts.delete(:body) + req_opts.delete(:body) + end + location = response.headers["location"] + if location + full_location = response.response.env.url.merge(location) + request(verb, full_location, req_opts) + else + error = Error.new(response) + raise(error, "Got #{status} status code, but no Location header was present") end - request(verb, response.headers['location'], opts) when 200..299, 300..399 - # on non-redirecting 3xx statuses, just return the response + # on non-redirecting 3xx statuses, return the response response when 400..599 - error = Error.new(response) - raise(error) if opts.fetch(:raise_errors, options[:raise_errors]) + if req_opts.fetch(:raise_errors, options[:raise_errors]) + error = Error.new(response) + raise(error) + end + response else error = Error.new(response) - raise(error, "Unhandled status code value of #{response.status}") + raise(error, "Unhandled status code value of #{status}") end end - # Initializes an AccessToken by making a request to the token endpoint + # Retrieves an access token from the token endpoint using the specified parameters # - # @param params [Hash] a Hash of params for the token endpoint - # @param access_token_opts [Hash] access token options, to pass to the AccessToken object - # @param access_token_class [Class] class of access token for easier subclassing OAuth2::AccessToken - # @return [AccessToken] the initialized AccessToken - def get_token(params, access_token_opts = {}, access_token_class = AccessToken) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity - # if ruby version >= 2.4 - # params.transform_keys! do |key| - # RESERVED_PARAM_KEYS.include?(key) ? key.to_sym : key - # end - params = params.map do |key, value| - if RESERVED_PARAM_KEYS.include?(key) - [key.to_sym, value] - else - [key, value] - end - end.to_h + # @param [Hash] params a Hash of params for the token endpoint + # * params can include a 'headers' key with a Hash of request headers + # * params can include a 'parse' key with the Symbol name of response parsing strategy (default: :automatic) + # * params can include a 'snaky' key to control snake_case conversion (default: false) + # @param [Hash] access_token_opts options that will be passed to the AccessToken initialization + # @param [Proc] extract_access_token (deprecated) a proc that can extract the access token from the response + # + # @yield [opts] The block is passed the options being used to make the request + # @yieldparam [Hash] opts options being passed to the http library + # + # @return [AccessToken, nil] the initialized AccessToken instance, or nil if token extraction fails + # and raise_errors is false + # + # @note The extract_access_token parameter is deprecated and will be removed in oauth2 v3. + # Use access_token_class on initialization instead. + # + # @example + # client.get_token( + # 'grant_type' => 'authorization_code', + # 'code' => 'auth_code_value', + # 'headers' => {'Authorization' => 'Basic ...'} + # ) + def get_token(params, access_token_opts = {}, extract_access_token = nil, &block) + warn("OAuth2::Client#get_token argument `extract_access_token` will be removed in oauth2 v3. Refactor to use `access_token_class` on #initialize.") if extract_access_token + extract_access_token ||= options[:extract_access_token] + req_opts = params_to_req_opts(params) + response = request(http_method, token_url, req_opts, &block) - params = authenticator.apply(params) - opts = {:raise_errors => options[:raise_errors], :parse => params.delete(:parse)} - headers = params.delete(:headers) || {} - if options[:token_method] == :post - opts[:body] = params - opts[:headers] = {'Content-Type' => 'application/x-www-form-urlencoded'} + # In v1.4.x, the deprecated extract_access_token option retrieves the token from the response. + # We preserve this behavior here, but a custom access_token_class that implements #from_hash + # should be used instead. + if extract_access_token + parse_response_legacy(response, access_token_opts, extract_access_token) else - opts[:params] = params - opts[:headers] = {} + parse_response(response, access_token_opts) end - opts[:headers].merge!(headers) - response = request(options[:token_method], token_url, opts) - response_contains_token = response.parsed.is_a?(Hash) && - (response.parsed['access_token'] || response.parsed['id_token']) + end - if options[:raise_errors] && !response_contains_token - error = Error.new(response) - raise(error) - elsif !response_contains_token - return nil - end + # Makes a request to revoke a token at the authorization server + # + # @param [String] token The token to be revoked + # @param [String, nil] token_type_hint A hint about the type of the token being revoked (e.g., 'access_token' or 'refresh_token') + # @param [Hash] params additional parameters for the token revocation + # @option params [Symbol] :parse (:automatic) parsing strategy for the response + # @option params [Boolean] :snaky (true) whether to convert response keys to snake_case + # @option params [Symbol] :token_method (:post_with_query_string) overrides OAuth2::Client#options[:token_method] + # @option params [Hash] :headers Additional request headers + # + # @yield [req] The block is passed the request being made, allowing customization + # @yieldparam [Faraday::Request] req The request object that can be modified + # + # @return [OAuth2::Response] OAuth2::Response instance + # + # @api public + # + # @note If the token passed to the request + # is an access token, the server MAY revoke the respective refresh + # token as well. + # @note If the token passed to the request + # is a refresh token and the authorization server supports the + # revocation of access tokens, then the authorization server SHOULD + # also invalidate all access tokens based on the same authorization + # grant + # @note If the server responds with HTTP status code 503, your code must + # assume the token still exists and may retry after a reasonable delay. + # The server may include a "Retry-After" header in the response to + # indicate how long the service is expected to be unavailable to the + # requesting client. + # + # @see https://datatracker.ietf.org/doc/html/rfc7009 + # @see https://datatracker.ietf.org/doc/html/rfc7009#section-2.1 + def revoke_token(token, token_type_hint = nil, params = {}, &block) + params[:token_method] ||= :post_with_query_string + params[:token] = token + params[:token_type_hint] = token_type_hint if token_type_hint - build_access_token(response, access_token_opts, access_token_class) + req_opts = params_to_req_opts(params) + + request(http_method, revoke_url, req_opts, &block) + end + + # The HTTP Method of the request + # + # @return [Symbol] HTTP verb, one of [:get, :post, :put, :delete] + def http_method + http_meth = options[:token_method].to_sym + return :post if http_meth == :post_with_query_string + + http_meth end # The Authorization Code strategy # - # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.1 + # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.1 def auth_code @auth_code ||= OAuth2::Strategy::AuthCode.new(self) end # The Implicit strategy # - # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-26#section-4.2 + # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-26#section-4.2 def implicit @implicit ||= OAuth2::Strategy::Implicit.new(self) end # The Resource Owner Password Credentials strategy # - # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.3 + # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.3 def password @password ||= OAuth2::Strategy::Password.new(self) end # The Client Credentials strategy # - # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.4 + # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.4 def client_credentials @client_credentials ||= OAuth2::Strategy::ClientCredentials.new(self) end + # The Assertion strategy + # + # This allows for assertion-based authentication where an identity provider + # asserts the identity of the user or client application seeking access. + # + # @see http://datatracker.ietf.org/doc/html/rfc7521 + # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-assertions-01#section-4.1 + # + # @return [OAuth2::Strategy::Assertion] the initialized Assertion strategy def assertion @assertion ||= OAuth2::Strategy::Assertion.new(self) end @@ -209,19 +321,24 @@ def assertion # requesting authorization. If it is provided at authorization time it MUST # also be provided with the token exchange request. # - # Providing the :redirect_uri to the OAuth2::Client instantiation will take + # OAuth 2.1 note: Authorization Servers must compare redirect URIs using exact string matching. + # This client simply forwards the configured redirect_uri; the exact-match validation happens server-side. + # + # Providing :redirect_uri to the OAuth2::Client instantiation will take # care of managing this. # # @api semipublic # - # @see https://tools.ietf.org/html/rfc6749#section-4.1 - # @see https://tools.ietf.org/html/rfc6749#section-4.1.3 - # @see https://tools.ietf.org/html/rfc6749#section-4.2.1 - # @see https://tools.ietf.org/html/rfc6749#section-10.6 + # @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1 + # @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3 + # @see https://datatracker.ietf.org/doc/html/rfc6749#section-4.2.1 + # @see https://datatracker.ietf.org/doc/html/rfc6749#section-10.6 + # @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13 + # # @return [Hash] the params to add to a request or URL def redirection_params if options[:redirect_uri] - {'redirect_uri' => options[:redirect_uri]} + {"redirect_uri" => options[:redirect_uri]} else {} end @@ -229,6 +346,125 @@ def redirection_params private + # Processes request parameters and transforms them into request options + # + # @param [Hash] params the request parameters to process + # @option params [Symbol] :parse (:automatic) parsing strategy for the response + # @option params [Boolean] :snaky (true) whether to convert response keys to snake_case + # @option params [Class] :snaky_hash_klass (SnakyHash::StringKeyed) class to use for snake_case hash conversion + # @option params [Symbol] :token_method (:post) HTTP method to use for token request + # @option params [Hash] :headers Additional HTTP headers for the request + # + # @return [Hash] the processed request options + # + # @api private + def params_to_req_opts(params) + parse, snaky, snaky_hash_klass, token_method, params, headers = parse_snaky_params_headers(params) + req_opts = { + raise_errors: options[:raise_errors], + token_method: token_method || options[:token_method], + parse: parse, + snaky: snaky, + snaky_hash_klass: snaky_hash_klass, + } + if req_opts[:token_method] == :post + # NOTE: If proliferation of request types continues, we should implement a parser solution for Request, + # just like we have with Response. + req_opts[:body] = if headers["Content-Type"] == "application/json" + params.to_json + else + params + end + + req_opts[:headers] = {"Content-Type" => "application/x-www-form-urlencoded"} + else + req_opts[:params] = params + req_opts[:headers] = {} + end + req_opts[:headers].merge!(headers) + req_opts + end + + # Processes and transforms parameters for OAuth requests + # + # @param [Hash] params the input parameters to process + # @option params [Symbol] :parse (:automatic) parsing strategy for the response + # @option params [Boolean] :snaky (true) whether to convert response keys to snake_case + # @option params [Class] :snaky_hash_klass (SnakyHash::StringKeyed) class to use for snake_case hash conversion + # @option params [Symbol] :token_method overrides the default token method for this request + # @option params [Hash] :headers HTTP headers for the request + # + # @return [Array<(Symbol, Boolean, Class, Symbol, Hash, Hash)>] Returns an array containing: + # - parse strategy (Symbol) + # - snaky flag for response key transformation (Boolean) + # - hash class for snake_case conversion (Class) + # - token method override (Symbol, nil) + # - processed parameters (Hash) + # - HTTP headers (Hash) + # + # @api private + def parse_snaky_params_headers(params) + params = params.map do |key, value| + if RESERVED_PARAM_KEYS.include?(key) + [key.to_sym, value] + else + [key, value] + end + end.to_h + parse = params.key?(:parse) ? params.delete(:parse) : Response::DEFAULT_OPTIONS[:parse] + snaky = params.key?(:snaky) ? params.delete(:snaky) : Response::DEFAULT_OPTIONS[:snaky] + snaky_hash_klass = params.key?(:snaky_hash_klass) ? params.delete(:snaky_hash_klass) : Response::DEFAULT_OPTIONS[:snaky_hash_klass] + token_method = params.delete(:token_method) if params.key?(:token_method) + params = authenticator.apply(params) + # authenticator may add :headers, and we separate them from params here + headers = params.delete(:headers) || {} + [parse, snaky, snaky_hash_klass, token_method, params, headers] + end + + # Executes an HTTP request with error handling and response processing + # + # @param [Symbol] verb the HTTP method to use (:get, :post, :put, :delete) + # @param [String] url the URL for the request + # @param [Hash] opts the request options + # @option opts [Hash] :body the request body + # @option opts [Hash] :headers the request headers + # @option opts [Hash] :params the query parameters to append to the URL + # @option opts [Symbol, nil] :parse (:automatic) parsing strategy for the response + # @option opts [Boolean] :snaky (true) whether to convert response keys to snake_case + # + # @yield [req] gives access to the request object before sending + # @yieldparam [Faraday::Request] req the request object that can be modified + # + # @return [OAuth2::Response] the response wrapped in an OAuth2::Response object + # + # @raise [OAuth2::ConnectionError] when there's a network error + # @raise [OAuth2::TimeoutError] when the request times out + # + # @api private + def execute_request(verb, url, opts = {}) + url = connection.build_https://github.com/url(url).to_s + # See: Hash#partition https://bugs.ruby-lang.org/issues/16252 + req_opts, oauth_opts = opts. + partition { |k, _v| RESERVED_REQ_KEYS.include?(k.to_s) }. + map { |p| Hash[p] } + + begin + response = connection.run_request(verb, url, req_opts[:body], req_opts[:headers]) do |req| + req.params.update(req_opts[:params]) if req_opts[:params] + yield(req) if block_given? + end + rescue Faraday::ConnectionFailed => e + raise ConnectionError, e + rescue Faraday::TimeoutError => e + raise TimeoutError, e + end + + parse = oauth_opts.key?(:parse) ? oauth_opts.delete(:parse) : Response::DEFAULT_OPTIONS[:parse] + snaky = oauth_opts.key?(:snaky) ? oauth_opts.delete(:snaky) : Response::DEFAULT_OPTIONS[:snaky] + + Response.new(response, parse: parse, snaky: snaky) + end + # Returns the authenticator object # # @return [Authenticator] the initialized Authenticator @@ -236,17 +472,98 @@ def authenticator Authenticator.new(id, secret, options[:auth_scheme]) end - # Builds the access token from the response of the HTTP call + # Parses the OAuth response and builds an access token using legacy extraction method + # + # @deprecated Use {#parse_response} instead + # + # @param [OAuth2::Response] response the OAuth2::Response from the token endpoint + # @param [Hash] access_token_opts options to pass to the AccessToken initialization + # @param [Proc] extract_access_token proc to extract the access token from response + # + # @return [AccessToken, nil] the initialized AccessToken if successful, nil if extraction fails + # and raise_errors option is false + # + # @raise [OAuth2::Error] if response indicates an error and raise_errors option is true + # + # @api private + def parse_response_legacy(response, access_token_opts, extract_access_token) + access_token = build_access_token_legacy(response, access_token_opts, extract_access_token) + + return access_token if access_token + + if options[:raise_errors] + error = Error.new(response) + raise(error) + end + + nil + end + + # Parses the OAuth response and builds an access token using the configured access token class + # + # @param [OAuth2::Response] response the OAuth2::Response from the token endpoint + # @param [Hash] access_token_opts options to pass to the AccessToken initialization + # + # @return [AccessToken] the initialized AccessToken instance + # + # @raise [OAuth2::Error] if the response is empty/invalid and the raise_errors option is true + # + # @api private + def parse_response(response, access_token_opts) + access_token_class = options[:access_token_class] + data = response.parsed + + unless data.is_a?(Hash) && !data.empty? + return unless options[:raise_errors] + + error = Error.new(response) + raise(error) + end + + build_access_token(response, access_token_opts, access_token_class) + end + + # Creates an access token instance from response data using the specified token class + # + # @param [OAuth2::Response] response the OAuth2::Response from the token endpoint + # @param [Hash] access_token_opts additional options to pass to the AccessToken initialization + # @param [Class] access_token_class the class that should be used to create access token instances # - # @return [AccessToken] the initialized AccessToken + # @return [AccessToken] an initialized AccessToken instance with response data + # + # @note If the access token class responds to response=, the full response object will be set + # + # @api private def build_access_token(response, access_token_opts, access_token_class) access_token_class.from_hash(self, response.parsed.merge(access_token_opts)).tap do |access_token| access_token.response = response if access_token.respond_to?(:response=) end end + # Builds an access token using a legacy extraction proc + # + # @deprecated Use {#build_access_token} instead + # + # @param [OAuth2::Response] response the OAuth2::Response from the token endpoint + # @param [Hash] access_token_opts additional options to pass to the access token extraction + # @param [Proc] extract_access_token a proc that takes client and token hash as arguments + # and returns an access token instance + # + # @return [AccessToken, nil] the access token instance if extraction succeeds, + # nil if any error occurs during extraction + # + # @api private + def build_access_token_legacy(response, access_token_opts, extract_access_token) + extract_access_token.call(self, response.parsed.merge(access_token_opts)) + rescue + # An error will be raised by the called if nil is returned and options[:raise_errors] is truthy, so this rescue is but temporary. + # Unfortunately, it does hide the real error, but this is deprecated legacy code, + # and this was effectively the long-standing pre-existing behavior, so there is little point in changing it. + nil + end + def oauth_debug_logging(builder) - builder.response :logger, options[:logger], :bodies => true if ENV['OAUTH_DEBUG'] == 'true' + builder.response(:logger, options[:logger], bodies: true) if OAuth2::OAUTH_DEBUG end end end diff --git a/lib/oauth2/error.rb b/lib/oauth2/error.rb index 335084c4..bccbe193 100644 --- a/lib/oauth2/error.rb +++ b/lib/oauth2/error.rb @@ -1,49 +1,77 @@ +# frozen_string_literal: true + module OAuth2 + # Represents an OAuth2 error condition. + # + # Wraps details from an OAuth2::Response or Hash payload returned by an + # authorization server, exposing error code and description per RFC 6749. class Error < StandardError - attr_reader :response, :code, :description + # @return [OAuth2::Response, Hash, Object] Original response or payload used to build the error + # @return [String] Raw body content (if available) + # @return [String, nil] Error code (e.g., 'invalid_grant') + # @return [String, nil] Human-readable description for the error + attr_reader :response, :body, :code, :description - # standard error codes include: - # 'invalid_request', 'invalid_client', 'invalid_token', 'invalid_grant', 'unsupported_grant_type', 'invalid_scope' + # Create a new OAuth2::Error + # + # @param [OAuth2::Response, Hash, Object] response A Response or error payload def initialize(response) @response = response - message_opts = {} - - if response.parsed.is_a?(Hash) - @code = response.parsed['error'] - @description = response.parsed['error_description'] - message_opts = parse_error_description(@code, @description) + if response.respond_to?(:parsed) + if response.parsed.is_a?(Hash) + @code = response.parsed["error"] + @description = response.parsed["error_description"] + end + elsif response.is_a?(Hash) + @code = response["error"] + @description = response["error_description"] end - - super(error_message(response.body, message_opts)) + @body = if response.respond_to?(:body) + response.body + else + @response + end + message_opts = parse_error_description(@code, @description) + super(error_message(@body, message_opts)) end private + # Builds a multi-line error message including description and raw body. + # + # @param [String, #encode] response_body Response body content + # @param [Hash] opts Options including :error_description + # @return [String] Message suitable for StandardError def error_message(response_body, opts = {}) lines = [] lines << opts[:error_description] if opts[:error_description] error_string = if response_body.respond_to?(:encode) && opts[:error_description].respond_to?(:encoding) - script_encoding = opts[:error_description].encoding - response_body.encode(script_encoding, :invalid => :replace, :undef => :replace) - else - response_body - end + script_encoding = opts[:error_description].encoding + response_body.encode(script_encoding, invalid: :replace, undef: :replace) + else + response_body + end lines << error_string lines.join("\n") end + # Formats the OAuth2 error code and description into a single string. + # + # @param [String, nil] code OAuth2 error code + # @param [String, nil] description OAuth2 error description + # @return [Hash] Options hash containing :error_description when present def parse_error_description(code, description) return {} unless code || description - error_description = '' - error_description << "#{code}: " if code - error_description << description if description + error_description = "" + error_description += "#{code}: " if code + error_description += description if description - {:error_description => error_description} + {error_description: error_description} end end end diff --git a/lib/oauth2/filtered_attributes.rb b/lib/oauth2/filtered_attributes.rb new file mode 100644 index 00000000..c1da8247 --- /dev/null +++ b/lib/oauth2/filtered_attributes.rb @@ -0,0 +1,52 @@ +module OAuth2 + # Mixin that redacts sensitive instance variables in #inspect output. + # + # Classes include this module and declare which attributes should be filtered + # using {.filtered_attributes}. Any instance variable name that includes one of + # those attribute names will be shown as [FILTERED] in the object's inspect. + module FilteredAttributes + # Hook invoked when the module is included. Extends the including class with + # class-level helpers. + # + # @param [Class] base The including class + # @return [void] + def self.included(base) + base.extend(ClassMethods) + end + + # Class-level helpers for configuring filtered attributes. + module ClassMethods + # Declare attributes that should be redacted in inspect output. + # + # @param [Array] attributes One or more attribute names + # @return [void] + def filtered_attributes(*attributes) + @filtered_attribute_names = attributes.map(&:to_sym) + end + + # The configured attribute names to filter. + # + # @return [Array] + def filtered_attribute_names + @filtered_attribute_names || [] + end + end + + # Custom inspect that redacts configured attributes. + # + # @return [String] + def inspect + filtered_attribute_names = self.class.filtered_attribute_names + return super if filtered_attribute_names.empty? + + inspected_vars = instance_variables.map do |var| + if filtered_attribute_names.any? { |filtered_var| var.to_s.include?(filtered_var.to_s) } + "#{var}=[FILTERED]" + else + "#{var}=#{instance_variable_get(var).inspect}" + end + end + "#<#{self.class}:#{object_id} #{inspected_vars.join(", ")}>" + end + end +end diff --git a/lib/oauth2/mac_token.rb b/lib/oauth2/mac_token.rb deleted file mode 100644 index df060742..00000000 --- a/lib/oauth2/mac_token.rb +++ /dev/null @@ -1,117 +0,0 @@ -require 'base64' -require 'digest' -require 'openssl' -require 'securerandom' - -module OAuth2 - class MACToken < AccessToken - # Generates a MACToken from an AccessToken and secret - # - # @param [AccessToken] token the OAuth2::Token instance - # @option [String] secret the secret key value - # @param [Hash] options the options to create the Access Token with - # @see MACToken#initialize - def self.from_access_token(token, secret, options = {}) - new(token.client, token.token, secret, token.params.merge(:refresh_token => token.refresh_token, :expires_in => token.expires_in, :expires_at => token.expires_at).merge(options)) - end - - attr_reader :secret, :algorithm - - # Initalize a MACToken - # - # @param [Client] client the OAuth2::Client instance - # @param [String] token the Access Token value - # @option [String] secret the secret key value - # @param [Hash] opts the options to create the Access Token with - # @option opts [String] :refresh_token (nil) the refresh_token value - # @option opts [FixNum, String] :expires_in (nil) the number of seconds in which the AccessToken will expire - # @option opts [FixNum, String] :expires_at (nil) the epoch time in seconds in which AccessToken will expire - # @option opts [FixNum, String] :algorithm (hmac-sha-256) the algorithm to use for the HMAC digest (one of 'hmac-sha-256', 'hmac-sha-1') - def initialize(client, token, secret, opts = {}) - @secret = secret - self.algorithm = opts.delete(:algorithm) || 'hmac-sha-256' - - super(client, token, opts) - end - - # Make a request with the MAC Token - # - # @param [Symbol] verb the HTTP request method - # @param [String] path the HTTP URL path of the request - # @param [Hash] opts the options to make the request with - # @see Client#request - def request(verb, path, opts = {}, &block) - url = client.connection.build_url(https://github.com/path,%20opts[:params]).to_s - - opts[:headers] ||= {} - opts[:headers]['Authorization'] = header(verb, url) - - @client.request(verb, path, opts, &block) - end - - # Get the headers hash (always an empty hash) - def headers - {} - end - - # Generate the MAC header - # - # @param [Symbol] verb the HTTP request method - # @param [String] url the HTTP URL path of the request - def header(verb, url) - timestamp = Time.now.utc.to_i - nonce = Digest::MD5.hexdigest([timestamp, SecureRandom.hex].join(':')) - - uri = URI.parse(url) - - raise(ArgumentError, "could not parse \"#{url}\" into URI") unless uri.is_a?(URI::HTTP) - - mac = signature(timestamp, nonce, verb, uri) - - "MAC id=\"#{token}\", ts=\"#{timestamp}\", nonce=\"#{nonce}\", mac=\"#{mac}\"" - end - - # Generate the Base64-encoded HMAC digest signature - # - # @param [Fixnum] timestamp the timestamp of the request in seconds since epoch - # @param [String] nonce the MAC header nonce - # @param [Symbol] verb the HTTP request method - # @param [String] uri the HTTP URL path of the request - def signature(timestamp, nonce, verb, uri) - signature = [ - timestamp, - nonce, - verb.to_s.upcase, - uri.request_uri, - uri.host, - uri.port, - '', nil - ].join("\n") - - Base64.strict_encode64(OpenSSL::HMAC.digest(@algorithm, secret, signature)) - end - - # Set the HMAC algorithm - # - # @param [String] alg the algorithm to use (one of 'hmac-sha-1', 'hmac-sha-256') - def algorithm=(alg) - @algorithm = begin - case alg.to_s - when 'hmac-sha-1' - OpenSSL::Digest::SHA1.new - when 'hmac-sha-256' - OpenSSL::Digest::SHA256.new - else - raise(ArgumentError, 'Unsupported algorithm') - end - end - end - - private - - # No-op since we need the verb and path - # and the MAC always goes in a header - def token=(_noop) - end - end -end diff --git a/lib/oauth2/response.rb b/lib/oauth2/response.rb index dd2ae93f..fb47c381 100644 --- a/lib/oauth2/response.rb +++ b/lib/oauth2/response.rb @@ -1,31 +1,55 @@ -require 'multi_json' -require 'multi_xml' -require 'rack' +# frozen_string_literal: true + +require "json" +require "multi_xml" +require "rack" module OAuth2 - # OAuth2::Response class + # The Response class handles HTTP responses in the OAuth2 gem, providing methods + # to access and parse response data in various formats. + # + # @since 1.0.0 class Response + # Default configuration options for Response instances + # + # @return [Hash] The default options hash + DEFAULT_OPTIONS = { + parse: :automatic, + snaky: true, + snaky_hash_klass: SnakyHash::StringKeyed, + }.freeze + + # @return [Faraday::Response] The raw Faraday response object attr_reader :response + + # @return [Hash] The options hash for this instance attr_accessor :options - # Procs that, when called, will parse a response body according - # to the specified format. + # @private + # Storage for response body parser procedures + # + # @return [Hash] Hash of parser procs keyed by format symbol @@parsers = { - :query => lambda { |body| Rack::Utils.parse_query(body) }, - :text => lambda { |body| body }, + query: ->(body) { Rack::Utils.parse_query(body) }, + text: ->(body) { body }, } - # Content type assignments for various potential HTTP content types. + # @private + # Maps content types to parser symbols + # + # @return [Hash] Hash of content types mapped to parser symbols @@content_types = { - 'application/x-www-form-urlencoded' => :query, - 'text/plain' => :text, + "application/x-www-form-urlencoded" => :query, + "text/plain" => :text, } # Adds a new content type parser. # - # @param [Symbol] key A descriptive symbol key such as :json or :query. - # @param [Array] mime_types One or more mime types to which this parser applies. - # @yield [String] A block returning parsed content. + # @param [Symbol] key A descriptive symbol key such as :json or :query + # @param [Array, String] mime_types One or more mime types to which this parser applies + # @yield [String] Block that will be called to parse the response body + # @yieldparam [String] body The response body to parse + # @return [void] def self.register_parser(key, mime_types, &block) key = key.to_sym @@parsers[key] = block @@ -37,33 +61,48 @@ def self.register_parser(key, mime_types, &block) # Initializes a Response instance # # @param [Faraday::Response] response The Faraday response instance - # @param [Hash] opts options in which to initialize the instance - # @option opts [Symbol] :parse (:automatic) how to parse the response body. one of :query (for x-www-form-urlencoded), - # :json, or :automatic (determined by Content-Type response header) - def initialize(response, opts = {}) + # @param [Symbol] parse (:automatic) How to parse the response body + # @param [Boolean] snaky (true) Whether to convert parsed response to snake_case using SnakyHash + # @param [Class, nil] snaky_hash_klass (nil) Custom class for snake_case hash conversion + # @param [Hash] options Additional options for the response + # @option options [Symbol] :parse (:automatic) Parse strategy (:query, :json, or :automatic) + # @option options [Boolean] :snaky (true) Enable/disable snake_case conversion + # @option options [Class] :snaky_hash_klass (SnakyHash::StringKeyed) Class to use for hash conversion + # @return [OAuth2::Response] The new Response instance + def initialize(response, parse: :automatic, snaky: true, snaky_hash_klass: nil, **options) @response = response - @options = {:parse => :automatic}.merge(opts) + @options = { + parse: parse, + snaky: snaky, + snaky_hash_klass: snaky_hash_klass, + }.merge(options) end # The HTTP response headers + # + # @return [Hash] The response headers def headers response.headers end # The HTTP response status code + # + # @return [Integer] The response status code def status response.status end # The HTTP response body + # + # @return [String] The response body or empty string if nil def body - response.body || '' + response.body || "" end - # The {#response} {#body} as parsed by {#parser}. + # The parsed response body # - # @return [Object] As returned by {#parser} if it is #call-able. - # @return [nil] If the {#parser} is not #call-able. + # @return [Object, SnakyHash::StringKeyed] The parsed response body + # @return [nil] If no parser is available def parsed return @parsed if defined?(@parsed) @@ -79,33 +118,37 @@ def parsed end end - @parsed = OAuth2::SnakyHash.build(@parsed) if @parsed.is_a?(Hash) + if options[:snaky] && @parsed.is_a?(Hash) + hash_klass = options[:snaky_hash_klass] || DEFAULT_OPTIONS[:snaky_hash_klass] + @parsed = hash_klass[@parsed] + end @parsed end - # Attempts to determine the content type of the response. + # Determines the content type of the response + # + # @return [String, nil] The content type or nil if headers are not present def content_type - return nil unless response.headers - ((response.headers.values_at('content-type', 'Content-Type').compact.first || '').split(';').first || '').strip.downcase + return unless response.headers + + ((response.headers.values_at("content-type", "Content-Type").compact.first || "").split(";").first || "").strip.downcase end - # Determines the parser (a Proc or other Object which responds to #call) - # that will be passed the {#body} (and optionall {#response}) to supply - # {#parsed}. + # Determines the parser to be used for the response body # - # The parser can be supplied as the +:parse+ option in the form of a Proc - # (or other Object responding to #call) or a Symbol. In the latter case, - # the actual parser will be looked up in {@@parsers} by the supplied Symbol. + # @note The parser can be supplied as the +:parse+ option in the form of a Proc + # (or other Object responding to #call) or a Symbol. In the latter case, + # the actual parser will be looked up in {@@parsers} by the supplied Symbol. # - # If no +:parse+ option is supplied, the lookup Symbol will be determined - # by looking up {#content_type} in {@@content_types}. + # @note If no +:parse+ option is supplied, the lookup Symbol will be determined + # by looking up {#content_type} in {@@content_types}. # - # If {#parser} is a Proc, it will be called with no arguments, just - # {#body}, or {#body} and {#response}, depending on the Proc's arity. + # @note If {#parser} is a Proc, it will be called with no arguments, just + # {#body}, or {#body} and {#response}, depending on the Proc's arity. # - # @return [Proc, #call] If a parser was found. - # @return [nil] If no parser was found. + # @return [Proc, #call] The parser proc or callable object + # @return [nil] If no suitable parser is found def parser return @parser if defined?(@parser) @@ -121,10 +164,21 @@ def parser end end -OAuth2::Response.register_parser(:xml, ['text/xml', 'application/rss+xml', 'application/rdf+xml', 'application/atom+xml', 'application/xml']) do |body| - MultiXml.parse(body) rescue body # rubocop:disable RescueModifier +# Register XML parser +# @api private +OAuth2::Response.register_parser(:xml, ["text/xml", "application/rss+xml", "application/rdf+xml", "application/atom+xml", "application/xml"]) do |body| + next body unless body.respond_to?(:to_str) + + MultiXml.parse(body) end -OAuth2::Response.register_parser(:json, ['application/json', 'text/javascript', 'application/hal+json', 'application/vnd.collection+json', 'application/vnd.api+json']) do |body| - MultiJson.load(body) rescue body # rubocop:disable RescueModifier +# Register JSON parser +# @api private +OAuth2::Response.register_parser(:json, ["application/json", "text/javascript", "application/hal+json", "application/vnd.collection+json", "application/vnd.api+json", "application/problem+json"]) do |body| + next body unless body.respond_to?(:to_str) + + body = body.dup.force_encoding(Encoding::ASCII_8BIT) if body.respond_to?(:force_encoding) + next body if body.respond_to?(:empty?) && body.empty? + + JSON.parse(body) end diff --git a/lib/oauth2/snaky_hash.rb b/lib/oauth2/snaky_hash.rb deleted file mode 100644 index 568160d4..00000000 --- a/lib/oauth2/snaky_hash.rb +++ /dev/null @@ -1,40 +0,0 @@ -module OAuth2 - # Hash which allow assign string key in camel case - # and query on both camel and snake case - class SnakyHash < ::Hash - # Build from another hash or SnakyHash - # - # @param [Hash, SnakyHash] hash initial values for hash - def self.build(hash) - new.merge!(hash) - end - - def [](key) - super(key) || super(camelize(key)) || super(camelize_upcase_first_letter(key)) - end - - def fetch(key, *extras) - super(key) { nil } || super(camelize(key)) { nil } || super(camelize_upcase_first_letter(key), *extras) - rescue KeyError - raise KeyError.new("key not found: \"#{key}\"") - end - - def key?(key) - super(key) || super(camelize(key)) || super(camelize_upcase_first_letter(key)) - end - - private - - def camelize_upcase_first_letter(string) - string.sub(/^[a-z\d]*/) { |match| match.capitalize } - .gsub(/(?:_|(\/))([a-z\d]*)/) { "#{$1}#{$2.capitalize}" } - .gsub("/", "::") - end - - def camelize(string) - string.sub(/^(?:(?=\b|[A-Z_])|\w)/) { |match| match.downcase } - .gsub(/(?:_|(\/))([a-z\d]*)/) { "#{$1}#{$2.capitalize}" } - .gsub("/", "::") - end - end -end diff --git a/lib/oauth2/strategy/assertion.rb b/lib/oauth2/strategy/assertion.rb index 9dfbc4df..0515b26b 100644 --- a/lib/oauth2/strategy/assertion.rb +++ b/lib/oauth2/strategy/assertion.rb @@ -1,19 +1,21 @@ -require 'jwt' +# frozen_string_literal: true + +require "jwt" module OAuth2 module Strategy # The Client Assertion Strategy # - # @see https://tools.ietf.org/html/rfc7523 + # @see https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-10#section-4.1.3 # # Sample usage: # client = OAuth2::Client.new(client_id, client_secret, # :site => 'http://localhost:8080/', # :auth_scheme => :request_body) # - # claimset = { + # claim_set = { # :iss => "http://localhost:3001/", - # :aud => "http://localhost:8080/oauth2/token" + # :aud => "http://localhost:8080/oauth2/token", # :sub => "me@example.com", # :exp => Time.now.utc.to_i + 3600, # } @@ -23,7 +25,7 @@ module Strategy # :key => 'secret_key', # } # - # access = client.assertion.get_token(claimset, encoding) + # access = client.assertion.get_token(claim_set, encoding) # access.token # actual access_token string # access.get("/api/stuff") # making api calls with access token in header # @@ -32,7 +34,7 @@ class Assertion < Base # # @raise [NotImplementedError] def authorize_url - raise(NotImplementedError, 'The authorization endpoint is not used in this strategy') + raise(NotImplementedError, "The authorization endpoint is not used in this strategy") end # Retrieve an access token given the specified client. @@ -41,15 +43,15 @@ def authorize_url # # For reading on JWT and claim keys: # @see https://github.com/jwt/ruby-jwt - # @see https://tools.ietf.org/html/rfc7519#section-4.1 - # @see https://tools.ietf.org/html/rfc7523#section-3 + # @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1 + # @see https://datatracker.ietf.org/doc/html/rfc7523#section-3 # @see https://www.iana.org/assignments/jwt/jwt.xhtml # # There are many possible claim keys, and applications may ask for their own custom keys. # Some typically required ones: # :iss (issuer) # :aud (audience) - # :sub (subject) -- formerly :prn https://tools.ietf.org/html/draft-ietf-oauth-json-web-token-06#appendix-F + # :sub (subject) -- formerly :prn https://datatracker.ietf.org/doc/html/draft-ietf-oauth-json-web-token-06#appendix-F # :exp, (expiration time) -- in seconds, e.g. Time.now.utc.to_i + 3600 # # Note that this method does *not* validate presence of those four claim keys indicated as required by RFC 7523. @@ -61,15 +63,15 @@ def authorize_url # # These two options are passed directly to `JWT.encode`. For supported encoding arguments: # @see https://github.com/jwt/ruby-jwt#algorithms-and-usage - # @see https://tools.ietf.org/html/rfc7518#section-3.1 + # @see https://datatracker.ietf.org/doc/html/rfc7518#section-3.1 # # The object type of `:key` may depend on the value of `:algorithm`. Sample arguments: - # get_token(claimset, {:algorithm => 'HS256', :key => 'secret_key'}) - # get_token(claimset, {:algorithm => 'RS256', :key => OpenSSL::PKCS12.new(File.read('my_key.p12'), 'not_secret')}) + # `get_token(claim_set, {:algorithm => 'HS256', :key => 'secret_key'})` + # `get_token(claim_set, {:algorithm => 'RS256', :key => OpenSSL::PKCS12.new(File.read('my_key.p12'), 'not_secret')})` # # @param [Hash] request_opts options that will be used to assemble the request # @option request_opts [String] :scope the url parameter `scope` that may be required by some endpoints - # @see https://tools.ietf.org/html/rfc7521#section-4.1 + # @see https://datatracker.ietf.org/doc/html/rfc7521#section-4.1 # # @param [Hash] response_opts this will be merged with the token response to create the AccessToken object # @see the access_token_opts argument to Client#get_token @@ -78,24 +80,25 @@ def get_token(claims, encoding_opts, request_opts = {}, response_opts = {}) assertion = build_assertion(claims, encoding_opts) params = build_request(assertion, request_opts) - @client.get_token(params, response_opts.merge('refresh_token' => nil)) + @client.get_token(params, response_opts) end private def build_request(assertion, request_opts = {}) { - :grant_type => 'urn:ietf:params:oauth:grant-type:jwt-bearer', - :assertion => assertion, + grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer", + assertion: assertion, }.merge(request_opts) end def build_assertion(claims, encoding_opts) - if !encoding_opts.is_a?(Hash) || ([:algorithm, :key] - encoding_opts.keys).any? - raise ArgumentError.new(:message => 'Please provide an encoding_opts hash with :algorithm and :key') - end + raise ArgumentError.new(message: "Please provide an encoding_opts hash with :algorithm and :key") if !encoding_opts.is_a?(Hash) || (%i[algorithm key] - encoding_opts.keys).any? + + headers = {} + headers[:kid] = encoding_opts[:kid] if encoding_opts.key?(:kid) - JWT.encode(claims, encoding_opts[:key], encoding_opts[:algorithm]) + JWT.encode(claims, encoding_opts[:key], encoding_opts[:algorithm], headers) end end end diff --git a/lib/oauth2/strategy/auth_code.rb b/lib/oauth2/strategy/auth_code.rb index 3d1b8e5c..ff909a37 100644 --- a/lib/oauth2/strategy/auth_code.rb +++ b/lib/oauth2/strategy/auth_code.rb @@ -1,14 +1,26 @@ +# frozen_string_literal: true + module OAuth2 module Strategy # The Authorization Code Strategy # - # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.1 + # OAuth 2.1 notes: + # - PKCE is required for all OAuth clients using the authorization code flow (especially public clients). + # This library does not enforce PKCE generation/verification; implement PKCE in your application when required. + # - Redirect URIs must be compared using exact string matching by the Authorization Server. + # This client forwards redirect_uri but does not perform server-side validation. + # + # References: + # - OAuth 2.1 draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13 + # - OAuth for native apps (RFC 8252) and PKCE (RFC 7636) + # + # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.1 class AuthCode < Base # The required query parameters for the authorize URL # # @param [Hash] params additional query parameters def authorize_params(params = {}) - params.merge('response_type' => 'code', 'client_id' => @client.id) + params.merge("response_type" => "code", "client_id" => @client.id) end # The authorization URL endpoint of the provider @@ -23,21 +35,22 @@ def authorize_url(https://github.com/params%20=%20%7B%7D) # # @param [String] code The Authorization Code value # @param [Hash] params additional params - # @param [Hash] opts options + # @param [Hash] opts access_token_opts, @see Client#get_token # @note that you must also provide a :redirect_uri with most OAuth 2.0 providers def get_token(code, params = {}, opts = {}) - params = {'grant_type' => 'authorization_code', 'code' => code}.merge(@client.redirection_params).merge(params) - params.keys.each do |key| - params[key.to_s] = params.delete(key) if key.is_a?(Symbol) + params = {"grant_type" => "authorization_code", "code" => code}.merge(@client.redirection_params).merge(params) + params_dup = params.dup + params.each_key do |key| + params_dup[key.to_s] = params_dup.delete(key) if key.is_a?(Symbol) end - @client.get_token(params, opts) + @client.get_token(params_dup, opts) end private def assert_valid_params(params) - raise(ArgumentError, 'client_secret is not allowed in authorize URL query params') if params.key?(:client_secret) || params.key?('client_secret') + raise(ArgumentError, "client_secret is not allowed in authorize URL query params") if params.key?(:client_secret) || params.key?("client_secret") end end end diff --git a/lib/oauth2/strategy/base.rb b/lib/oauth2/strategy/base.rb index 9d16bb4a..801a723e 100644 --- a/lib/oauth2/strategy/base.rb +++ b/lib/oauth2/strategy/base.rb @@ -1,3 +1,5 @@ +# frozen_string_literal: true + module OAuth2 module Strategy class Base diff --git a/lib/oauth2/strategy/client_credentials.rb b/lib/oauth2/strategy/client_credentials.rb index 35ac5fd8..00a3ed80 100644 --- a/lib/oauth2/strategy/client_credentials.rb +++ b/lib/oauth2/strategy/client_credentials.rb @@ -1,14 +1,16 @@ +# frozen_string_literal: true + module OAuth2 module Strategy # The Client Credentials Strategy # - # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.4 + # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.4 class ClientCredentials < Base # Not used for this strategy # # @raise [NotImplementedError] def authorize_url - raise(NotImplementedError, 'The authorization endpoint is not used in this strategy') + raise(NotImplementedError, "The authorization endpoint is not used in this strategy") end # Retrieve an access token given the specified client. @@ -16,8 +18,8 @@ def authorize_url # @param [Hash] params additional params # @param [Hash] opts options def get_token(params = {}, opts = {}) - params = params.merge('grant_type' => 'client_credentials') - @client.get_token(params, opts.merge('refresh_token' => nil)) + params = params.merge("grant_type" => "client_credentials") + @client.get_token(params, opts) end end end diff --git a/lib/oauth2/strategy/implicit.rb b/lib/oauth2/strategy/implicit.rb index 41ecb8da..8dfd0a64 100644 --- a/lib/oauth2/strategy/implicit.rb +++ b/lib/oauth2/strategy/implicit.rb @@ -1,14 +1,24 @@ +# frozen_string_literal: true + module OAuth2 module Strategy # The Implicit Strategy # - # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-26#section-4.2 + # IMPORTANT (OAuth 2.1): The Implicit grant (response_type=token) is omitted from the OAuth 2.1 draft specification. + # It remains here for backward compatibility with OAuth 2.0 providers. Prefer the Authorization Code flow with PKCE. + # + # References: + # - OAuth 2.1 draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13 + # - Why drop implicit: https://aaronparecki.com/2019/12/12/21/its-time-for-oauth-2-dot-1 + # - Background: https://fusionauth.io/learn/expert-advice/oauth/differences-between-oauth-2-oauth-2-1/ + # + # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-26#section-4.2 class Implicit < Base # The required query parameters for the authorize URL # # @param [Hash] params additional query parameters def authorize_params(params = {}) - params.merge('response_type' => 'token', 'client_id' => @client.id) + params.merge("response_type" => "token", "client_id" => @client.id) end # The authorization URL endpoint of the provider @@ -23,13 +33,13 @@ def authorize_url(https://github.com/params%20=%20%7B%7D) # # @raise [NotImplementedError] def get_token(*) - raise(NotImplementedError, 'The token is accessed differently in this strategy') + raise(NotImplementedError, "The token is accessed differently in this strategy") end private def assert_valid_params(params) - raise(ArgumentError, 'client_secret is not allowed in authorize URL query params') if params.key?(:client_secret) || params.key?('client_secret') + raise(ArgumentError, "client_secret is not allowed in authorize URL query params") if params.key?(:client_secret) || params.key?("client_secret") end end end diff --git a/lib/oauth2/strategy/password.rb b/lib/oauth2/strategy/password.rb index 49bfc6e3..9621e684 100644 --- a/lib/oauth2/strategy/password.rb +++ b/lib/oauth2/strategy/password.rb @@ -1,14 +1,24 @@ +# frozen_string_literal: true + module OAuth2 module Strategy # The Resource Owner Password Credentials Authorization Strategy # - # @see http://tools.ietf.org/html/draft-ietf-oauth-v2-15#section-4.3 + # IMPORTANT (OAuth 2.1): The Resource Owner Password Credentials grant is omitted in OAuth 2.1. + # It remains here for backward compatibility with OAuth 2.0 providers. Prefer Authorization Code + PKCE. + # + # References: + # - OAuth 2.1 draft: https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13 + # - Okta explainer: https://developer.okta.com/blog/2019/12/13/oauth-2-1-how-many-rfcs + # - FusionAuth blog: https://fusionauth.io/blog/2020/04/15/whats-new-in-oauth-2-1 + # + # @see http://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-15#section-4.3 class Password < Base # Not used for this strategy # # @raise [NotImplementedError] def authorize_url - raise(NotImplementedError, 'The authorization endpoint is not used in this strategy') + raise(NotImplementedError, "The authorization endpoint is not used in this strategy") end # Retrieve an access token given the specified End User username and password. @@ -17,9 +27,11 @@ def authorize_url # @param [String] password the End User password # @param [Hash] params additional params def get_token(username, password, params = {}, opts = {}) - params = {'grant_type' => 'password', - 'username' => username, - 'password' => password}.merge(params) + params = { + "grant_type" => "password", + "username" => username, + "password" => password, + }.merge(params) @client.get_token(params, opts) end end diff --git a/lib/oauth2/version.rb b/lib/oauth2/version.rb index 9b02e785..b5e51565 100644 --- a/lib/oauth2/version.rb +++ b/lib/oauth2/version.rb @@ -1,59 +1,7 @@ +# frozen_string_literal: true + module OAuth2 module Version - module_function - - # The major version - # - # @return [Integer] - def major - 1 - end - - # The minor version - # - # @return [Integer] - def minor - 4 - end - - # The patch version - # - # @return [Integer] - def patch - 3 - end - - # The pre-release version, if any - # - # @return [Integer, NilClass] - def pre - nil - end - - # The version number as a hash - # - # @return [Hash] - def to_h - { - :major => major, - :minor => minor, - :patch => patch, - :pre => pre, - } - end - - # The version number as an array - # - # @return [Array] - def to_a - [major, minor, patch, pre].compact - end - - # The version number as a string - # - # @return [String] - def to_s - to_a.join('.') - end + VERSION = "2.0.18" end end diff --git a/oauth2.gemspec b/oauth2.gemspec index 093ae436..a1d34e52 100644 --- a/oauth2.gemspec +++ b/oauth2.gemspec @@ -1,52 +1,204 @@ # coding: utf-8 +# frozen_string_literal: true -lib = File.expand_path('../lib', __FILE__) -$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib) -require 'oauth2/version' +gem_version = + if RUBY_VERSION >= "3.1" # rubocop:disable Gemspec/RubyVersionGlobalsUsage + # Loading Version into an anonymous module allows version.rb to get code coverage from SimpleCov! + # See: https://github.com/simplecov-ruby/simplecov/issues/557#issuecomment-2630782358 + # See: https://github.com/panorama-ed/memo_wise/pull/397 + Module.new.tap { |mod| Kernel.load("#{__dir__}/lib/oauth2/version.rb", mod) }::OAuth2::Version::VERSION + else + require_relative "lib/oauth2/version" + OAuth2::Version::VERSION + end Gem::Specification.new do |spec| - spec.add_dependency 'faraday', ['>= 0.8', '< 2.0'] - spec.add_dependency 'jwt', ['>= 1.0', '< 3.0'] - spec.add_dependency 'multi_json', '~> 1.3' - spec.add_dependency 'multi_xml', '~> 0.5' - spec.add_dependency 'rack', ['>= 1.2', '< 3'] - - spec.authors = ['Peter Boling', 'Michael Bleigh', 'Erik Michaels-Ober'] - spec.description = 'A Ruby wrapper for the OAuth 2.0 protocol built with a similar style to the original OAuth spec.' - spec.email = ['peter.boling@gmail.com'] - spec.homepage = 'https://github.com/oauth-xx/oauth2' - spec.licenses = %w[MIT] - spec.name = 'oauth2' - spec.required_ruby_version = '>= 1.9.0' - spec.required_rubygems_version = '>= 1.3.5' - spec.summary = 'A Ruby wrapper for the OAuth 2.0 protocol.' - spec.version = OAuth2::Version - - spec.metadata = { - 'bug_tracker_uri' => 'https://github.com/oauth-xx/oauth2/issues', - 'changelog_uri' => "https://github.com/oauth-xx/oauth2/blob/v#{spec.version}/CHANGELOG.md", - 'documentation_uri' => "https://www.rubydoc.info/gems/oauth2/#{spec.version}", - 'source_code_uri' => "https://github.com/oauth-xx/oauth2/tree/v#{spec.version}", - 'wiki_uri' => 'https://github.com/oauth-xx/oauth2/wiki' - } - - spec.require_paths = %w[lib] - spec.bindir = 'exe' - spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) } - spec.files = `git ls-files -z`.split("\x0").reject do |f| - f.match(%r{^(bin|test|spec|features)/}) + spec.name = "oauth2" + spec.version = gem_version + spec.authors = ["Peter Boling", "Erik Michaels-Ober", "Michael Bleigh"] + spec.email = ["floss@galtzo.com", "oauth-ruby@googlegroups.com"] + + spec.summary = "🔐 OAuth 2.0, 2.1 & OIDC Core Ruby implementation" + spec.description = "🔐 A Ruby wrapper for the OAuth 2.0 Authorization Framework, including the OAuth 2.1 draft spec, and OpenID Connect (OIDC)" + spec.homepage = "https://github.com/ruby-oauth/oauth2" + spec.licenses = ["MIT"] + spec.required_ruby_version = ">= 2.2.0" + + # Linux distros often package gems and securely certify them independent + # of the official RubyGem certification process. Allowed via ENV["SKIP_GEM_SIGNING"] + # Ref: https://gitlab.com/ruby-oauth/version_gem/-/issues/3 + # Hence, only enable signing if `SKIP_GEM_SIGNING` is not set in ENV. + # See CONTRIBUTING.md + unless ENV.include?("SKIP_GEM_SIGNING") + user_cert = "certs/#{ENV.fetch("https://github.com/GEM_CERT_USER", ENV["USER"])}.pem" + cert_file_path = File.join(__dir__, user_cert) + cert_chain = cert_file_path.split(",") + cert_chain.select! { |fp| File.exist?(fp) } + if cert_file_path && cert_chain.any? + spec.cert_chain = cert_chain + if $PROGRAM_NAME.end_with?("gem") && ARGV[0] == "build" + spec.signing_key = File.join(Gem.user_home, ".ssh", "gem-private_key.pem") + end + end end - spec.add_development_dependency 'addressable', '~> 2.3' - spec.add_development_dependency 'backports', '~> 3.11' - spec.add_development_dependency 'bundler', '>= 1.16' - spec.add_development_dependency 'coveralls', '~> 0.8' - spec.add_development_dependency 'rake', '>= 11' - spec.add_development_dependency 'rdoc', ['>= 5.0', '< 7'] - spec.add_development_dependency 'rspec', '~> 3.0' - spec.add_development_dependency 'rspec-stubbed_env' - spec.add_development_dependency 'rspec-pending_for' - spec.add_development_dependency 'rspec-block_is_expected' - spec.add_development_dependency 'silent_stream' - spec.add_development_dependency 'wwtd' + gl_homepage = "https://gitlab.com/ruby-oauth/#{spec.name}" + + spec.post_install_message = %{ +---+++--- oauth2 v#{gem_version} ---+++--- + +(minor) ⚠️ BREAKING CHANGES ⚠️ when upgrading from < v2 +• Summary of breaking changes: #{gl_homepage}#what-is-new-for-v20 +• Changes in this patch: #{gl_homepage}/-/blob/v#{gem_version}/CHANGELOG.md#2015-2025-09-08 + +News: +1. New documentation website, including for OAuth 2.1 and OIDC: https://oauth2.galtzo.com +2. New official Discord for discussion and support: https://discord.gg/3qme4XHNKN +3. New org name "ruby-oauth" on Open Source Collective, GitHub, GitLab, Codeberg (update git remotes!) +4. Non-commercial support for the 2.x series will end by April, 2026. Please make a plan to upgrade to the next version prior to that date. +Support will be dropped for Ruby 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 3.0, 3.1 and any other Ruby versions which will also have reached EOL by then. +5. Gem releases are cryptographically signed with a 20-year cert; SHA-256 & SHA-512 checksums by stone_checksums. +6. Please consider supporting this project: + • https://opencollective.com/ruby-oauth (new!) + • https://liberapay.com/pboling + • https://github.com/sponsors/pboling + • https://www.paypal.com/paypalme/peterboling + • https://ko-fi.com/pboling + • https://www.buymeacoffee.com/pboling + • https://tidelift.com/funding/github/rubygems/oauth + • Hire me - I can build anything + • Report issues, and star the project +Thanks, @pboling / @galtzo +} + + spec.metadata["homepage_uri"] = "https://#{spec.name.tr("_", "-")}.galtzo.com/" + spec.metadata["source_code_uri"] = "#{spec.homepage}/tree/v#{spec.version}" + spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/v#{spec.version}/CHANGELOG.md" + spec.metadata["bug_tracker_uri"] = "#{spec.homepage}/issues" + spec.metadata["documentation_uri"] = "https://www.rubydoc.info/gems/#{spec.name}/#{spec.version}" + spec.metadata["mailing_list_uri"] = "https://groups.google.com/g/oauth-ruby" + spec.metadata["funding_uri"] = "https://github.com/sponsors/pboling" + spec.metadata["wiki_uri"] = "#{gl_homepage}/-/wiki" + spec.metadata["news_uri"] = "https://www.railsbling.com/tags/#{spec.name}" + spec.metadata["discord_uri"] = "https://discord.gg/3qme4XHNKN" + spec.metadata["rubygems_mfa_required"] = "true" + + # Specify which files are part of the released package. + spec.files = Dir[ + # Code / tasks / data (NOTE: exe/ is specified via spec.bindir and spec.executables below) + "lib/**/*.rb", + "lib/**/*.rake", + # Signatures + "sig/**/*.rbs", + ] + + # Automatically included with gem package, no need to list again in files. + spec.extra_rdoc_files = Dir[ + # Files (alphabetical) + "CHANGELOG.md", + "CITATION.cff", + "CODE_OF_CONDUCT.md", + "CONTRIBUTING.md", + "FUNDING.md", + "LICENSE.txt", + "IRP.md", + "OIDC.md", + "README.md", + "REEK", + "RUBOCOP.md", + "SECURITY.md", + "THREAT_MODEL.md", + ] + spec.rdoc_options += [ + "--title", + "#{spec.name} - #{spec.summary}", + "--main", + "README.md", + "--exclude", + "^sig/", + "--line-numbers", + "--inline-source", + "--quiet", + ] + spec.require_paths = ["lib"] + spec.bindir = "exe" + # Listed files are the relative paths from bindir above. + spec.executables = [] + + # Utilities + spec.add_dependency("faraday", [">= 0.17.3", "< 4.0"]) # ruby >= 1.9 + spec.add_dependency("jwt", [">= 1.0", "< 4.0"]) # ruby >= 0 + spec.add_dependency("logger", "~> 1.2") # ruby >= 0 + spec.add_dependency("multi_xml", "~> 0.5") # ruby >= 0 + spec.add_dependency("rack", [">= 1.2", "< 4"]) # ruby >= 0 + spec.add_dependency("snaky_hash", "~> 2.0", ">= 2.0.3") # ruby >= 2.2 + spec.add_dependency("version_gem", "~> 1.1", ">= 1.1.9") # ruby >= 2.2.0 + + # NOTE: It is preferable to list development dependencies in the gemspec due to increased + # visibility and discoverability. + # However, development dependencies in gemspec will install on + # all versions of Ruby that will run in CI. + # This gem, and its gemspec runtime dependencies, will install on Ruby down to 2.2.0. + # This gem, and its gemspec development dependencies, will install on Ruby down to 2.3. + # Thus, dev dependencies in gemspec must have + # + # required_ruby_version ">= 2.3" (or lower) + # + # Development dependencies that require strictly newer Ruby versions should be in a "gemfile", + # and preferably a modular one (see gemfiles/modular/*.gemfile). + + spec.add_development_dependency("addressable", "~> 2.8", ">= 2.8.7") # ruby >= 2.2 + spec.add_development_dependency("nkf", "~> 0.2") # ruby >= 2.3 + spec.add_development_dependency("rexml", "~> 3.2", ">= 3.2.5") # ruby >= 0 + + # Dev, Test, & Release Tasks + spec.add_development_dependency("kettle-dev", "~> 1.1") # ruby >= 2.3.0 + + # Security + spec.add_development_dependency("bundler-audit", "~> 0.9.2") # ruby >= 2.0.0 + + # Tasks + spec.add_development_dependency("rake", "~> 13.0") # ruby >= 2.2.0 + + # Debugging + spec.add_development_dependency("require_bench", "~> 1.0", ">= 1.0.4") # ruby >= 2.2.0 + + # Testing + spec.add_development_dependency("appraisal2", "~> 3.0") # ruby >= 1.8.7, for testing against multiple versions of dependencies + spec.add_development_dependency("kettle-test", "~> 1.0", ">= 1.0.6") # ruby >= 2.3 + + # Releasing + spec.add_development_dependency("ruby-progressbar", "~> 1.13") # ruby >= 0 + spec.add_development_dependency("stone_checksums", "~> 1.0", ">= 1.0.2") # ruby >= 2.2.0 + + # Git integration (optional) + # The 'git' gem is optional; oauth2 falls back to shelling out to `git` if it is not present. + # The current release of the git gem depends on activesupport, which makes it too heavy to depend on directly + # spec.add_dependency("git", ">= 1.19.1") # ruby >= 2.3 + + # Development tasks + # The cake is a lie. erb v2.2, the oldest release, was never compatible with Ruby 2.3. + # This means we have no choice but to use the erb that shipped with Ruby 2.3 + # /opt/hostedtoolcache/Ruby/2.3.8/x64/lib/ruby/gems/2.3.0/gems/erb-2.2.2/lib/erb.rb:670:in `prepare_trim_mode': undefined method `match?' for "-":String (NoMethodError) + # spec.add_development_dependency("erb", ">= 2.2") # ruby >= 2.3.0, not SemVer, old rubies get dropped in a patch. + spec.add_development_dependency("gitmoji-regex", "~> 1.0", ">= 1.0.3") # ruby >= 2.3.0 + + # HTTP recording for deterministic specs + # Ruby 2.3 / 2.4 can fail with: + # | An error occurred while loading spec_helper. + # | Failure/Error: require "vcr" + # | + # | NoMethodError: + # | undefined method `delete_prefix' for "CONTENT_LENGTH":String + # | # ./spec/config/vcr.rb:3:in `require' + # | # ./spec/config/vcr.rb:3:in `' + # | # ./spec/spec_helper.rb:8:in `require_relative' + # | # ./spec/spec_helper.rb:8:in `' + # So that's why we need backports. + spec.add_development_dependency("backports", "~> 3.25", ">= 3.25.1") # ruby >= 0 + # In Ruby 3.5 (HEAD) the CGI library has been pared down, so we also need to depend on gem "cgi" for ruby@head + # This is done in the "head" appraisal. + # See: https://github.com/vcr/vcr/issues/1057 + # spec.add_development_dependency("vcr", ">= 4") # 6.0 claims to support ruby >= 2.3, but fails on ruby 2.4 + # spec.add_development_dependency("webmock", ">= 3") # Last version to support ruby >= 2.3 end diff --git a/sig/oauth2.rbs b/sig/oauth2.rbs new file mode 100644 index 00000000..ac5d074c --- /dev/null +++ b/sig/oauth2.rbs @@ -0,0 +1,9 @@ +module OAuth2 + OAUTH_DEBUG: bool + + DEFAULT_CONFIG: untyped + @config: untyped + + def self.config: () -> untyped + def self.configure: () { (untyped) -> void } -> void +end diff --git a/sig/oauth2/access_token.rbs b/sig/oauth2/access_token.rbs new file mode 100644 index 00000000..06779891 --- /dev/null +++ b/sig/oauth2/access_token.rbs @@ -0,0 +1,25 @@ +module OAuth2 + class AccessToken + def self.from_hash: (OAuth2::Client, Hash[untyped, untyped]) -> OAuth2::AccessToken + def self.from_kvform: (OAuth2::Client, String) -> OAuth2::AccessToken + + def initialize: (OAuth2::Client, String, ?Hash[Symbol, untyped]) -> void + def []: (String | Symbol) -> untyped + def expires?: () -> bool + def expired?: () -> bool + def refresh: (?Hash[untyped, untyped], ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::AccessToken + def revoke: (?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response + def to_hash: () -> Hash[Symbol, untyped] + def request: (Symbol, String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response + def get: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response + def post: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response + def put: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response + def patch: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response + def delete: (String, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response + def headers: () -> Hash[String, String] + def configure_authentication!: (Hash[Symbol, untyped], Symbol) -> void + def convert_expires_at: (untyped) -> (Time | Integer | nil) + + attr_accessor response: OAuth2::Response + end +end diff --git a/sig/oauth2/authenticator.rbs b/sig/oauth2/authenticator.rbs new file mode 100644 index 00000000..a9eb50db --- /dev/null +++ b/sig/oauth2/authenticator.rbs @@ -0,0 +1,22 @@ +module OAuth2 + class Authenticator + include OAuth2::FilteredAttributes + + attr_reader mode: (Symbol | String) + attr_reader id: String? + attr_reader secret: String? + + def initialize: (String? id, String? secret, (Symbol | String) mode) -> void + + def apply: (Hash[untyped, untyped]) -> Hash[untyped, untyped] + + def self.encode_basic_auth: (String, String) -> String + + private + + def apply_params_auth: (Hash[untyped, untyped]) -> Hash[untyped, untyped] + def apply_client_id: (Hash[untyped, untyped]) -> Hash[untyped, untyped] + def apply_basic_auth: (Hash[untyped, untyped]) -> Hash[untyped, untyped] + def basic_auth_header: () -> Hash[String, String] + end +end diff --git a/sig/oauth2/client.rbs b/sig/oauth2/client.rbs new file mode 100644 index 00000000..900be57d --- /dev/null +++ b/sig/oauth2/client.rbs @@ -0,0 +1,52 @@ +module OAuth2 + class Client + RESERVED_REQ_KEYS: Array[String] + RESERVED_PARAM_KEYS: Array[String] + + include OAuth2::FilteredAttributes + + attr_reader id: String + attr_reader secret: String + attr_reader site: String? + attr_accessor options: Hash[Symbol, untyped] + attr_writer connection: untyped + + def initialize: (String client_id, String client_secret, ?Hash[Symbol, untyped]) { (untyped) -> void } -> void + + def site=: (String) -> String + + def connection: () -> untyped + + def authorize_url: (?Hash[untyped, untyped]) -> String + def token_url: (?Hash[untyped, untyped]) -> String + def revoke_url: (?Hash[untyped, untyped]) -> String + + def request: (Symbol verb, String url, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response + + def get_token: (Hash[untyped, untyped] params, ?Hash[Symbol, untyped] access_token_opts, ?Proc) { (Hash[Symbol, untyped]) -> void } -> (OAuth2::AccessToken | nil) + + def revoke_token: (String token, ?String token_type_hint, ?Hash[Symbol, untyped]) { (untyped) -> void } -> OAuth2::Response + + def http_method: () -> Symbol + + def auth_code: () -> OAuth2::Strategy::AuthCode + def implicit: () -> OAuth2::Strategy::Implicit + def password: () -> OAuth2::Strategy::Password + def client_credentials: () -> OAuth2::Strategy::ClientCredentials + def assertion: () -> OAuth2::Strategy::Assertion + + def redirection_params: () -> Hash[String, String] + + private + + def params_to_req_opts: (Hash[untyped, untyped]) -> Hash[Symbol, untyped] + def parse_snaky_params_headers: (Hash[untyped, untyped]) -> [Symbol, bool, untyped, (Symbol | nil), Hash[untyped, untyped], Hash[String, String]] + def execute_request: (Symbol verb, String url, ?Hash[Symbol, untyped]) { (Faraday::Request) -> void } -> OAuth2::Response + def authenticator: () -> OAuth2::Authenticator + def parse_response_legacy: (OAuth2::Response, Hash[Symbol, untyped], Proc) -> (OAuth2::AccessToken | nil) + def parse_response: (OAuth2::Response, Hash[Symbol, untyped]) -> (OAuth2::AccessToken | nil) + def build_access_token: (OAuth2::Response, Hash[Symbol, untyped], untyped) -> OAuth2::AccessToken + def build_access_token_legacy: (OAuth2::Response, Hash[Symbol, untyped], Proc) -> (OAuth2::AccessToken | nil) + def oauth_debug_logging: (untyped) -> void + end +end diff --git a/sig/oauth2/error.rbs b/sig/oauth2/error.rbs new file mode 100644 index 00000000..fa732848 --- /dev/null +++ b/sig/oauth2/error.rbs @@ -0,0 +1,8 @@ +module OAuth2 + class Error < StandardError + def initialize: (OAuth2::Response) -> void + def code: () -> (String | Integer | nil) + def description: () -> (String | nil) + def response: () -> OAuth2::Response + end +end diff --git a/sig/oauth2/filtered_attributes.rbs b/sig/oauth2/filtered_attributes.rbs new file mode 100644 index 00000000..da7e30f6 --- /dev/null +++ b/sig/oauth2/filtered_attributes.rbs @@ -0,0 +1,6 @@ +module OAuth2 + module FilteredAttributes + def self.included: (untyped) -> untyped + def filtered_attributes: (*String) -> void + end +end diff --git a/sig/oauth2/response.rbs b/sig/oauth2/response.rbs new file mode 100644 index 00000000..866d0e50 --- /dev/null +++ b/sig/oauth2/response.rbs @@ -0,0 +1,18 @@ +module OAuth2 + class Response + DEFAULT_OPTIONS: Hash[Symbol, untyped] + + def self.register_parser: (Symbol key, (Array[String] | String) mime_types) { (String) -> untyped } -> void + + def initialize: (untyped response, parse: Symbol?, snaky: bool?, snaky_hash_klass: untyped?, options: Hash[Symbol, untyped]?) -> void + def headers: () -> Hash[untyped, untyped] + def status: () -> Integer + def body: () -> String + def parsed: () -> untyped + def content_type: () -> (String | nil) + def parser: () -> (untyped | nil) + + attr_reader response: untyped + attr_accessor options: Hash[Symbol, untyped] + end +end diff --git a/sig/oauth2/strategy.rbs b/sig/oauth2/strategy.rbs new file mode 100644 index 00000000..bbce9aea --- /dev/null +++ b/sig/oauth2/strategy.rbs @@ -0,0 +1,34 @@ +module OAuth2 + module Strategy + class Base + def initialize: (OAuth2::Client) -> void + end + + class AuthCode < Base + def authorize_params: (?Hash[untyped, untyped]) -> Hash[untyped, untyped] + def authorize_url: (?Hash[untyped, untyped]) -> String + def get_token: (String, ?Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken + end + + class Implicit < Base + def authorize_params: (?Hash[untyped, untyped]) -> Hash[untyped, untyped] + def authorize_url: (?Hash[untyped, untyped]) -> String + def get_token: (*untyped) -> void + end + + class Password < Base + def authorize_url: () -> void + def get_token: (String, String, ?Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken + end + + class ClientCredentials < Base + def authorize_url: () -> void + def get_token: (?Hash[untyped, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken + end + + class Assertion < Base + def authorize_url: () -> void + def get_token: (Hash[untyped, untyped], Hash[Symbol, untyped], ?Hash[Symbol, untyped], ?Hash[Symbol, untyped]) -> OAuth2::AccessToken + end + end +end diff --git a/sig/oauth2/version.rbs b/sig/oauth2/version.rbs new file mode 100644 index 00000000..64614ac4 --- /dev/null +++ b/sig/oauth2/version.rbs @@ -0,0 +1,5 @@ +module OAuth2 + module Version + VERSION: String + end +end diff --git a/spec/config/constants.rb b/spec/config/constants.rb new file mode 100644 index 00000000..0c1b205b --- /dev/null +++ b/spec/config/constants.rb @@ -0,0 +1 @@ +VERBS = %i[get post put delete patch].freeze diff --git a/spec/config/debug.rb b/spec/config/debug.rb new file mode 100644 index 00000000..140b10e3 --- /dev/null +++ b/spec/config/debug.rb @@ -0,0 +1,5 @@ +load_debugger = ENV.fetch("https://github.com/DEBUG", "false").casecmp("true") == 0 + +puts "LOADING DEBUGGER: #{load_debugger}" if load_debugger + +require "debug" if load_debugger diff --git a/spec/config/faraday.rb b/spec/config/faraday.rb new file mode 100644 index 00000000..e9158898 --- /dev/null +++ b/spec/config/faraday.rb @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +require "faraday" + +Faraday.default_adapter = :test diff --git a/spec/config/multi_xml.rb b/spec/config/multi_xml.rb new file mode 100644 index 00000000..8d579c28 --- /dev/null +++ b/spec/config/multi_xml.rb @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +require "multi_xml" + +MultiXml.parser = :rexml diff --git a/spec/examples/google_spec.rb b/spec/examples/google_spec.rb index b3f1224d..34a7287c 100644 --- a/spec/examples/google_spec.rb +++ b/spec/examples/google_spec.rb @@ -1,18 +1,20 @@ -require 'jwt' +# frozen_string_literal: true -RSpec.describe 'using OAuth2 with Google' do +require "jwt" + +RSpec.describe "using OAuth2 with Google" do # This describes authenticating to a Google API via a service account. # See their docs: https://developers.google.com/identity/protocols/OAuth2ServiceAccount - describe 'via 2-legged JWT assertion' do + describe "via 2-legged JWT assertion" do let(:client) do OAuth2::Client.new( - '', - '', - :site => 'https://accounts.google.com/', - :authorize_url => '/o/oauth2/auth', - :token_url => '/o/oauth2/token', - :auth_scheme => :request_body + "", + "", + site: "https://accounts.google.com/", + authorize_url: "/o/oauth2/auth", + token_url: "/o/oauth2/token", + auth_scheme: :request_body, ) end @@ -20,44 +22,44 @@ let(:required_claims) do { - 'iss' => '761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com', + "iss" => "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", # The email address of the service account. - 'scope' => 'https://www.googleapis.com/auth/devstorage.readonly%20https://www.googleapis.com/auth/prediction', + "scope" => "https://www.googleapis.com/auth/devstorage.readonly%20https://www.googleapis.com/auth/prediction", # A space-delimited list of the permissions that the application requests. - 'aud' => 'https://www.googleapis.com/oauth2/v4/token', + "aud" => "https://www.googleapis.com/oauth2/v4/token", # A descriptor of the intended target of the assertion. When making an access token request this value # is always https://www.googleapis.com/oauth2/v4/token. - 'exp' => Time.now.to_i + 3600, + "exp" => Time.now.to_i + 3600, # The expiration time of the assertion, specified as seconds since 00:00:00 UTC, January 1, 1970. This value # has a maximum of 1 hour after the issued time. - 'iat' => Time.now.to_i, + "iat" => Time.now.to_i, # The time the assertion was issued, specified as seconds since 00:00:00 UTC, January 1, 1970. } end let(:optional_claims) do { - 'sub' => 'some.user@example.com' + "sub" => "some.user@example.com", # The email address of the user for which the application is requesting delegated access. } end - let(:algorithm) { 'RS256' } + let(:algorithm) { "RS256" } # Per Google: "Service accounts rely on the RSA SHA-256 algorithm" let(:key) do begin - OpenSSL::PKCS12.new(File.read('spec/fixtures/google_service_account_key.p12'), 'notasecret').key + OpenSSL::PKCS12.new(File.read("spec/fixtures/google_service_account_key.p12"), "notasecret").key # This simulates the .p12 file that Google gives you to download and keep somewhere. This is meant to # illustrate extracting the key and using it to generate the JWT. rescue OpenSSL::PKCS12::PKCS12Error # JRuby CI builds are blowing up trying to extract a sample key for some reason. This simulates the end result # of actually figuring out the problem. - OpenSSL::PKey::RSA.new(1024) + OpenSSL::PKey::RSA.new(2048) end end # Per Google: @@ -65,25 +67,26 @@ # "Take note of the service account's email address and store the service account's P12 private key file in a # location accessible to your application. Your application needs them to make authorized API calls." - let(:encoding_options) { {:key => key, :algorithm => algorithm} } + let(:encoding_options) { {key: key, algorithm: algorithm} } before do - client.connection.build do |builder| + client.connection = Faraday.new(client.site, client.options[:connection_opts]) do |builder| + builder.request :url_encoded builder.adapter :test do |stub| - stub.post('https://accounts.google.com/o/oauth2/token') do |token_request| - @request_body = token_request.body + stub.post("https://accounts.google.com/o/oauth2/token") do |token_request| + @request_body = Rack::Utils.parse_nested_query(token_request.body).transform_keys(&:to_sym) [ 200, { - 'Content-Type' => 'application/json', + "Content-Type" => "application/json", }, { - 'access_token' => '1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M', - 'token_type' => 'Bearer', - 'expires_in' => 3600, + "access_token" => "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M", + "token_type" => "Bearer", + "expires_in" => 3600, }.to_json, ] end @@ -91,18 +94,18 @@ end end - context 'when passing the required claims' do + context "when passing the required claims" do let(:claims) { required_claims } - it 'sends a JWT with the 5 keys' do + it "sends a JWT with the 5 keys" do client.assertion.get_token(claims, encoding_options) - expect(@request_body).not_to be_nil, 'No access token request was made!' - expect(@request_body[:grant_type]).to eq('urn:ietf:params:oauth:grant-type:jwt-bearer') + expect(@request_body).not_to be_nil, "No access token request was made!" + expect(@request_body[:grant_type]).to eq("urn:ietf:params:oauth:grant-type:jwt-bearer") expect(@request_body[:assertion]).to be_a(String) - payload, header = JWT.decode(@request_body[:assertion], key, true, :algorithm => algorithm) - expect(header['alg']).to eq('RS256') + payload, header = JWT.decode(@request_body[:assertion], key, true, algorithm: algorithm) + expect(header["alg"]).to eq("RS256") expect(payload.keys).to match_array(%w[iss scope aud exp iat]) # Note that these specifically do _not_ include the 'sub' claim, which is indicated as being 'required' @@ -115,18 +118,18 @@ end end - context 'when including the optional `sub` claim' do + context "when including the optional `sub` claim" do let(:claims) { required_claims.merge(optional_claims) } - it 'sends a JWT with the 6 keys' do + it "sends a JWT with the 6 keys" do client.assertion.get_token(claims, encoding_options) - expect(@request_body).not_to be_nil, 'No access token request was made!' - expect(@request_body[:grant_type]).to eq('urn:ietf:params:oauth:grant-type:jwt-bearer') + expect(@request_body).not_to be_nil, "No access token request was made!" + expect(@request_body[:grant_type]).to eq("urn:ietf:params:oauth:grant-type:jwt-bearer") expect(@request_body[:assertion]).to be_a(String) - payload, header = JWT.decode(@request_body[:assertion], key, true, :algorithm => algorithm) - expect(header['alg']).to eq('RS256') + payload, header = JWT.decode(@request_body[:assertion], key, true, algorithm: algorithm) + expect(header["alg"]).to eq("RS256") expect(payload.keys).to match_array(%w[iss scope aud exp iat sub]) payload.each do |key, value| diff --git a/spec/ext/backports.rb b/spec/ext/backports.rb new file mode 100644 index 00000000..322d8f4d --- /dev/null +++ b/spec/ext/backports.rb @@ -0,0 +1,4 @@ +# frozen_string_literal: true + +require "backports/2.5.0/hash/transform_keys" +require "backports/2.5.0/string/delete_prefix" diff --git a/spec/fixtures/README.md b/spec/fixtures/README.md new file mode 100644 index 00000000..e8ed536a --- /dev/null +++ b/spec/fixtures/README.md @@ -0,0 +1,11 @@ +# RS256 + +## How keys were made + +```shell +# No passphrase +# Generates the public and private keys: +ssh-keygen -t rsa -b 4096 -m PEM -f jwtRS256.key +# Converts the key to PEM format +openssl rsa -in jwtRS256.key -pubout -outform PEM -out jwtRS256.key.pub +``` diff --git a/spec/fixtures/RS256/jwtRS256.key b/spec/fixtures/RS256/jwtRS256.key new file mode 100644 index 00000000..72005e50 --- /dev/null +++ b/spec/fixtures/RS256/jwtRS256.key @@ -0,0 +1,51 @@ +-----BEGIN RSA PRIVATE KEY----- +MIIJKwIBAAKCAgEA5hdXV/4YSymY1T9VNvK2bWRfulwIty1RnAPNINQmfh3aRRkV ++PNrbC2Crji9G0AHmQwgW1bZ3kgkkpIm6RVn44fHvBvuXkZ9ABgXw0d2cLIHmwOF +xSKmWAm/EW//GszUTLLLsMZUe2udtFJW0jxXB2GRY0WVYuo6Oo58RCeP719lw3Ag +s0YF9/IobxKkGd4BautUPw6ZszAa3o+j0zR74x7ouPxybZAOuPsMxqanyeYJeH4o +sJjLMYV9qem9uG2sj7GENJ8UszcpmGbqxBhexPEB7mgDeONIF0XJF23zdOf8ANE5 +mAU2h2v7M6moAfkdUzJ+j48+VT2omHAzAL5yNcmrl2xiWdyoxOw1Y1UmfEmJYV5V +gGYyZ12JZRKY+szPT+vR+MDuYxbquF40O7kvkFNBfL1yCpzfSQCLnEs4rX8qRzZX +ciLeyq4Ht5FLuRFgxjA//XI8LAmp0u7gk+Q7FUH1UgW3kmJDTG0XaxQxYTBSIO7m +cmyjDyBgKVuQmt5E1ycFeteOVdPD/CG/fPYhthvc4UytEFwsMdNy3iD6/wuUH68t +AKam28UZaOb0qK+00cQQD8fulY9rKtSL10LvJFWUOa/SJyLvk9vUmfvFn182il1n +X6GpyxyMmE/FCnH4CT/DjrSZf08mOO8eL5ofYHMK/oiXr1eODqx+pOwClNsCAwEA +AQKCAgEAy34vMFI4WBk04rx9d/hWoQ7Znu8QgjihaZLvEy6t0HJEfUH/bcqS4fyq +C72Aeh452gCgiUeZrf4t4jdCFHhrBg8q9dHaEiTTHocwVPPZ6zd4hH8sCrpnVYth +IWHkw2YOCLtEbFYrl3AI7Na5lHvrGEsREzQSN4Yh83Has0guAy1iyeNb+FFgq/XO +DtX0ri/rHw1717zo8FIGIXn2EK/lNWw7tIcICKAUdUMK/JGd6XD6RUeGYxDu/CAs +kF55/Sd6Kyd7XjKnUwzhS7kRvlYzUog4BgqVr4+LTZHZlFAYtfcJqAtinXFW1ZQJ +eZp9TSlt5wvMZNjx7t92QUNRyEGmrQAU+8COHnT0/drFf0MCiyHSUN0E7/5fswhc +uMSU9XiJA9G0wYvJl4zIuOuIYWZWhIqvjYSkvdlP70t9XO2gk/ZcCWsMW8i+xbwC +w1+MMjsKsNedXxI99TIPPHcCNMxqlt1E1kHH3SAwCuEH/ez7PRMyEQQ0EyAk22x/ +piYIWXkX5835cLbLRIYafXgOiugWZjCwIqfRIcIpscmcijZwCF2DyevveYdx3krR +FGA2PFydFyxCNG7XwvKb9kHb7WBERUPV/H3eCqu2SZ/RvF+I94LUYP4bu6CmFdO9 +wCJcGJoL1P7tVhS9lA5Oj0QWczrjnejCoI9XMMduWk032rR1VYECggEBAPZDnTBY +H2uiVmGdMfWTAmX86kiHVpkL03OG6rgvDMsMOYKnik9Lb3gNeUIuPeAWFNrXCoD1 +qp0loxPhKSojNOOM8Yiz/GwQ/QI9dzgtxs7E7rFFyTuJcY48Do8uOFyUHbAbeOBF +b9UL/uBfWZGVV1YY753xyqYlCpxTVQGms1jsbVFdZE1iVpOwAkFVuoLYaHLut4zB +01ORyBSoWan173P+IQH6F1uNXE2Kk/FIMDN6bgP1pXkdkrTx4WjAmRnP/Sc4r38/ +F1xN+gxnWGPUKDVRPYBpVzDR036w65ODgg2FROK2vIxlStiAC/rc0JLsvaWfb1Rn +dsWdJJ1V6mZ6a5sCggEBAO8wC1jcIoiBz3xoA8E5BSt8qLJ7ZuSFaaidvWX2/xj6 +lSWJxCGQfhR7P6ozvH6UDo1WbJT6nNyXPkiDkAzcmAdsYVjULW3K2LI9oPajaJxY +L7KJpylgh9JhMvbMz3VVjTgYRt+kjX+3uFMZNx1YfiBP+S6xx5sjK9CKDz3H99kC +q9bX95YFqZ7yFE3aBCR6CENo2tXpMN96CLQGpwa0bwt3xNzC4MhZMXbGR3DdBYbD +tS9lJfQvAVUYxbSE/2FBgjpO6ArMyU2ZUEDFx9J6IhfhVbQV4VeITMyRNo0XwBiQ +/+XpLXgHkw7LiNMIoc7d+M7yLA1Vz7+r8XxWHHZCL8ECggEBAPK8VrYORno7e1Wg +MlxS2WxZzTxMWmlkpLoc5END7SI/HHjSV5wtSORWs40uM0MrwMasa+gNPmzDamjv +6Tllln4ssO8EKe0DGcAZgefYBzxMFNKbbOzIXyvJurga4Ocv/8tUaOL2znJ67nGO +yqSbRYjR724JpKv7mufXo9SK0gD2mhI3MeSs55WPScnIjJzoXpva/QU7D+gxq7vg +7PCAP9RfS329W0Sco7yyuXx8oTY8mTBB8ybcpXzBZmNwY/hzcJ42W5XbRFVxbuTH +APL1beSP/UUTkCPIzuTz0mCGoaxeDjZB1Lu2I/4eyLAu80+/FneoHX5etU23xR1o +UDFOvb0CggEBALTTc6CoPAtLaBs7X6tSelAYHEli9bTKD8kEB83wX4b42ozYjEh7 +vnWpf8Yi+twO/rlnnws6NCCoztNvcxXmJ6FlFGtdbULV2eFWqjwL6ehY2yZ03sVv +Tv+DsE3ZJPYlyW+hGuO0uazWrilUpNAwuJmhHFdq2+azPkqYNVGVvhB37oWsHGd0 +vHmHtkXtDris8VZVDSwu8V3iGnZPmTJ+cn0O/OuRAPM2SyjqWdQ/pA/wIShFpd3n +M3CsG7uP2KokJloCkXaov39E6uEtJRZAc0nudyaAbC4Kw1Tca4tba0SnSm78S/20 +bD8BLN2uZvXH5nQ9rYQfXcIgMZ64UygsfYECggEBAIw0fQaIVmafa0Hz3ipD4PJI +5QNkh2t9hvOCSKm1xYTNATl0q/VIkZoy1WoxY6SSchcObLxQKbJ9ORi4XNr+IJK5 +3C1Qz/3iv/S3/ktgmqGhQiqybkkHZcbqTXB2wxrx+aaLS7PEfYiuYCrPbX93160k +MVns8PjvYU8KCNMbL2e+AiKEt1KkKAZIpNQdeeJOEhV9wuLYFosd400aYssuSOVW +IkJhGI0lT/7FDJaw0LV98DhQtauANPSUQKN5iw6vciwtsaF1kXMfGlMXj58ntiMq +NizQPR6/Ar1ewLPMh1exDoAfLnCIMk8nbSraW+cebLAZctPugUpfpu3j2LM98aE= +-----END RSA PRIVATE KEY----- diff --git a/spec/fixtures/RS256/jwtRS256.key.pub b/spec/fixtures/RS256/jwtRS256.key.pub new file mode 100644 index 00000000..1a2f63d1 --- /dev/null +++ b/spec/fixtures/RS256/jwtRS256.key.pub @@ -0,0 +1,14 @@ +-----BEGIN PUBLIC KEY----- +MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA5hdXV/4YSymY1T9VNvK2 +bWRfulwIty1RnAPNINQmfh3aRRkV+PNrbC2Crji9G0AHmQwgW1bZ3kgkkpIm6RVn +44fHvBvuXkZ9ABgXw0d2cLIHmwOFxSKmWAm/EW//GszUTLLLsMZUe2udtFJW0jxX +B2GRY0WVYuo6Oo58RCeP719lw3Ags0YF9/IobxKkGd4BautUPw6ZszAa3o+j0zR7 +4x7ouPxybZAOuPsMxqanyeYJeH4osJjLMYV9qem9uG2sj7GENJ8UszcpmGbqxBhe +xPEB7mgDeONIF0XJF23zdOf8ANE5mAU2h2v7M6moAfkdUzJ+j48+VT2omHAzAL5y +Ncmrl2xiWdyoxOw1Y1UmfEmJYV5VgGYyZ12JZRKY+szPT+vR+MDuYxbquF40O7kv +kFNBfL1yCpzfSQCLnEs4rX8qRzZXciLeyq4Ht5FLuRFgxjA//XI8LAmp0u7gk+Q7 +FUH1UgW3kmJDTG0XaxQxYTBSIO7mcmyjDyBgKVuQmt5E1ycFeteOVdPD/CG/fPYh +thvc4UytEFwsMdNy3iD6/wuUH68tAKam28UZaOb0qK+00cQQD8fulY9rKtSL10Lv +JFWUOa/SJyLvk9vUmfvFn182il1nX6GpyxyMmE/FCnH4CT/DjrSZf08mOO8eL5of +YHMK/oiXr1eODqx+pOwClNsCAwEAAQ== +-----END PUBLIC KEY----- diff --git a/spec/helper.rb b/spec/helper.rb deleted file mode 100644 index 0d9cb10d..00000000 --- a/spec/helper.rb +++ /dev/null @@ -1,39 +0,0 @@ -require 'oauth2' -require 'simplecov' -require 'coveralls' -require 'rspec' -require 'rspec/stubbed_env' -require 'silent_stream' - -SimpleCov.formatters = SimpleCov::Formatter::MultiFormatter.new([ - SimpleCov::Formatter::HTMLFormatter, - Coveralls::SimpleCov::Formatter -]) - -SimpleCov.start do - add_filter '/spec' - minimum_coverage(95) -end - -require 'addressable/uri' - -Faraday.default_adapter = :test - -DEBUG = ENV['DEBUG'] == 'true' -if DEBUG && RUBY_VERSION >= '2.6' - require 'byebug' -end - -# This is dangerous - HERE BE DRAGONS. -# It allows us to refer to classes without the namespace, but at what cost?!? -# TODO: Refactor to use explicit references everywhere -include OAuth2 - -RSpec.configure do |config| - config.expect_with :rspec do |c| - c.syntax = :expect - end - config.include SilentStream -end - -VERBS = [:get, :post, :put, :delete].freeze diff --git a/spec/oauth2/access_token_spec.rb b/spec/oauth2/access_token_spec.rb index b1a51b7f..97f9a706 100644 --- a/spec/oauth2/access_token_spec.rb +++ b/spec/oauth2/access_token_spec.rb @@ -1,247 +1,1180 @@ -RSpec.describe AccessToken do - subject { described_class.new(client, token) } +# frozen_string_literal: true - let(:token) { 'monkey' } - let(:refresh_body) { MultiJson.encode(:access_token => 'refreshed_foo', :expires_in => 600, :refresh_token => 'refresh_bar') } +RSpec.describe OAuth2::AccessToken do + subject { described_class.new(client, token, token_options) } + + let(:base_options) { {site: "https://api.example.com/"} } + let(:token_options) { {} } + let(:options) { {} } + let(:token) { "monkey" } + let(:refresh_body) { JSON.dump(access_token: "refreshed_foo", expires_in: 600, refresh_token: "refresh_bar") } let(:client) do - Client.new('abc', 'def', :site => 'https://api.example.com/') do |builder| + OAuth2::Client.new("abc", "def", options.merge(base_options)) do |builder| builder.request :url_encoded builder.adapter :test do |stub| VERBS.each do |verb| - stub.send(verb, '/token/header') { |env| [200, {}, env[:request_headers]['Authorization']] } - stub.send(verb, "/token/query?access_token=#{token}") { |env| [200, {}, Addressable::URI.parse(env[:url]).query_values['access_token']] } - stub.send(verb, '/token/query_string') { |env| [200, {}, CGI.unescape(Addressable::URI.parse(env[:url]).query)] } - stub.send(verb, '/token/body') { |env| [200, {}, env[:body]] } + stub.send(verb, "/token/header") { |env| [200, {}, env[:request_headers]["Authorization"]] } + stub.send(verb, "/token/query?access_token=#{token}") { |env| [200, {}, Addressable::URI.parse(env[:url]).query_values["access_token"]] } + stub.send(verb, "/token/query_string") { |env| [200, {}, CGI.unescape(Addressable::URI.parse(env[:url]).query)] } + stub.send(verb, "/token/body") { |env| [200, {}, env[:body]] } end - stub.post('/oauth/token') { |env| [200, {'Content-Type' => 'application/json'}, refresh_body] } + stub.post("/oauth/token") { |_env| [200, {"Content-Type" => "application/json"}, refresh_body] } + stub.post("/oauth/revoke") { |env| [200, {"Content-type" => "application/json"}, env[:body]] } end end end - describe '#initialize' do - it 'assigns client and token' do + describe ".from_hash" do + subject(:target) { described_class.from_hash(client, hash) } + + let(:hash) do + { + access_token: token, + id_token: "confusing bug here", + refresh_token: "foobar", + expires_at: Time.now.to_i + 200, + foo: "bar", + header_format: "Bearer %", + mode: :header, + param_name: "access_token", + } + end + + it "return a hash equals to the hash used to initialize access token" do + expect(target.to_hash).to eq(hash) + end + + context "with warning for too many tokens" do + subject(:printed) do + capture(:stderr) do + target + end + end + + before do + @original_setw = OAuth2.config.silence_extra_tokens_warning + OAuth2.config.silence_extra_tokens_warning = false + end + + after do + OAuth2.config.silence_extra_tokens_warning = @original_setw + end + + it "warns on STDERR" do + skip("Warning output we spit on Hashie without VERSION constant makes this test invalid") unless defined?(Hashie::VERSION) + msg = <<-MSG.lstrip + OAuth2::AccessToken.from_hash: `hash` contained more than one 'token' key ([:access_token, :id_token]); using :access_token. + MSG + expect(printed).to eq(msg) + end + + context "when one token" do + subject(:printed) do + capture(:stderr) do + target + end + end + + let(:hash) do + { + access_token: token, + } + end + + before do + @original_setw = OAuth2.config.silence_extra_tokens_warning + OAuth2.config.silence_extra_tokens_warning = false + end + + after do + OAuth2.config.silence_extra_tokens_warning = @original_setw + end + + it "does not warn on STDERR" do + skip("Warning output we spit on Hashie without VERSION constant makes this test invalid") unless defined?(Hashie::VERSION) + expect(printed).to eq("") + end + end + + context "when silenced" do + subject(:printed) do + capture(:stderr) do + target + end + end + + before do + @original_setw = OAuth2.config.silence_extra_tokens_warning + OAuth2.config.silence_extra_tokens_warning = true + end + + after do + OAuth2.config.silence_extra_tokens_warning = @original_setw + end + + it "does not warn on STDERR" do + skip("Warning output we spit on Hashie without VERSION constant makes this test invalid") unless defined?(Hashie::VERSION) + expect(printed).to eq("") + end + end + end + + context "with keys in a different order to the lookup" do + subject(:printed) do + capture(:stderr) do + target + end + end + + before do + @original_setw = OAuth2.config.silence_extra_tokens_warning + OAuth2.config.silence_extra_tokens_warning = false + end + + after do + OAuth2.config.silence_extra_tokens_warning = @original_setw + end + + let(:hash) do + { + id_token: "confusing bug here", + access_token: token, + } + end + + it "warns on STDERR and selects the correct key" do + skip("Warning output we spit on Hashie without VERSION constant makes this test invalid") unless defined?(Hashie::VERSION) + msg = <<-MSG.lstrip + OAuth2::AccessToken.from_hash: `hash` contained more than one 'token' key ([:access_token, :id_token]); using :access_token. + MSG + expect(printed).to eq(msg) + end + end + + context "with warning for no token keys" do + subject(:printed) do + capture(:stderr) do + target + end + end + + before do + @original_sntw = OAuth2.config.silence_no_tokens_warning + OAuth2.config.silence_no_tokens_warning = false + end + + after do + OAuth2.config.silence_no_tokens_warning = @original_sntw + end + + let(:options) { {raise_errors: true} } + + let(:hash) do + { + blather: "confusing bug here", + rather: token, + } + end + + it "raises an error" do + block_is_expected.to raise_error(OAuth2::Error) + end + + context "when not raising errors" do + let(:options) { {raise_errors: false} } + + it "warns on STDERR" do + skip("Warning output we spit on Hashie without VERSION constant makes this test invalid") unless defined?(Hashie::VERSION) + msg = <<-MSG.lstrip + OAuth2::AccessToken has no token + MSG + expect(printed).to eq(msg) + end + + context "when custom token_name valid" do + let(:options) { {raise_errors: false} } + + let(:hash) do + { + "lollipop" => token, + :expires_at => Time.now.to_i + 200, + :foo => "bar", + :header_format => "Bearer %", + :mode => :header, + :param_name => "lollipop", + :token_name => "lollipop", + } + end + + it "finds token" do + expect(target.token).to eq("monkey") + end + + it "does not warn when token is found" do + skip("Warning output we spit on Hashie without VERSION constant makes this test invalid") unless defined?(Hashie::VERSION) + expect(printed).to eq("") + end + end + + context "when custom token_name invalid" do + let(:options) { {raise_errors: false} } + + let(:hash) do + { + "babyshark" => token, + :expires_at => Time.now.to_i + 200, + :foo => "bar", + :header_format => "Bearer %", + :mode => :header, + :param_name => "lollipop", + :token_name => "lollipop", + } + end + + context "when silence_no_tokens_warning is false" do + before do + @original_sntw = OAuth2.config.silence_no_tokens_warning + OAuth2.config.silence_no_tokens_warning = false + end + + after do + OAuth2.config.silence_no_tokens_warning = @original_sntw + end + + it "finds no token" do + expect(target.token).to eq("") + end + + it "warns when no token is found" do + skip("Warning output we spit on Hashie without VERSION constant makes this test invalid") unless defined?(Hashie::VERSION) + expect(printed.each_line.to_a).to eq([ + "\n", + "OAuth2::AccessToken#from_hash key mismatch.\n", + %{Custom token_name (lollipop) is not found in (["babyshark", :expires_at, :foo, :header_format, :mode, :param_name, :token_name])\n}, + "You may need to set `snaky: false`. See inline documentation for more info.\n", + " \n", + "OAuth2::AccessToken has no token\n", + ]) + end + end + + context "when silence_no_tokens_warning is true" do + before do + @original_sntw = OAuth2.config.silence_no_tokens_warning + OAuth2.config.silence_no_tokens_warning = true + end + + after do + OAuth2.config.silence_no_tokens_warning = @original_sntw + end + + it "finds no token" do + expect(target.token).to eq("") + end + + it "does not warn when no token is found" do + skip("Warning output we spit on Hashie without VERSION constant makes this test invalid") unless defined?(Hashie::VERSION) + expect(printed.each_line.to_a).to eq([]) + end + end + end + end + end + end + + describe "#initialize" do + it "assigns client and token" do expect(subject.client).to eq(client) expect(subject.token).to eq(token) end - it 'assigns extra params' do - target = described_class.new(client, token, 'foo' => 'bar') - expect(target.params).to include('foo') - expect(target.params['foo']).to eq('bar') + it "assigns extra params" do + target = described_class.new(client, token, "foo" => "bar") + expect(target.params).to include("foo") + expect(target.params["foo"]).to eq("bar") end - def assert_initialized_token(target) # rubocop:disable Metrics/AbcSize + def assert_initialized_token(target) expect(target.token).to eq(token) expect(target).to be_expires - expect(target.params.keys).to include('foo') - expect(target.params['foo']).to eq('bar') + expect(target.params.keys).to include("foo") + expect(target.params["foo"]).to eq("bar") end - it 'initializes with a Hash' do - hash = {:access_token => token, :expires_at => Time.now.to_i + 200, 'foo' => 'bar'} + it "initializes with a Hash" do + hash = {:access_token => token, :expires_at => Time.now.to_i + 200, "foo" => "bar"} target = described_class.from_hash(client, hash) assert_initialized_token(target) end - it 'from_hash does not modify opts hash' do - hash = {:access_token => token, :expires_at => Time.now.to_i} + it "from_hash does not modify opts hash" do + hash = {access_token: token, expires_at: Time.now.to_i} hash_before = hash.dup described_class.from_hash(client, hash) expect(hash).to eq(hash_before) end - it 'initalizes with a form-urlencoded key/value string' do + it "initializes with a form-urlencoded key/value string" do kvform = "access_token=#{token}&expires_at=#{Time.now.to_i + 200}&foo=bar" target = described_class.from_kvform(client, kvform) assert_initialized_token(target) end - it 'sets options' do - target = described_class.new(client, token, :param_name => 'foo', :header_format => 'Bearer %', :mode => :body) - expect(target.options[:param_name]).to eq('foo') - expect(target.options[:header_format]).to eq('Bearer %') - expect(target.options[:mode]).to eq(:body) + context "with options" do + subject(:target) { described_class.new(client, token, options) } + + context "with body mode" do + let(:mode) { :body } + let(:options) { {param_name: "foo", header_format: "Bearer %", mode: mode} } + + it "sets options" do + expect(target.options[:param_name]).to eq("foo") + expect(target.options[:header_format]).to eq("Bearer %") + expect(target.options[:mode]).to eq(mode) + end + end + + context "with header mode" do + let(:mode) { :header } + let(:options) { {headers: {}, mode: mode} } + + it "sets options" do + expect(target.options[:headers]).to be_nil + expect(target.options[:mode]).to eq(mode) + end + end + + context "with query mode" do + let(:mode) { :query } + let(:options) { {params: {}, param_name: "foo", mode: mode} } + + it "sets options" do + expect(target.options[:param_name]).to eq("foo") + expect(target.options[:params]).to be_nil + expect(target.options[:mode]).to eq(mode) + end + end + + context "with invalid mode" do + let(:mode) { :this_is_bad } + let(:options) { {mode: mode} } + + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + context "with request" do + subject(:request) { target.post("/token/header") } + + it "raises" do + block_is_expected.to raise_error("invalid :mode option of #{mode}") + end + end + + context "with client.options[:raise_errors] = true" do + let(:mode) { :this_is_bad } + let(:options) { {mode: mode, raise_errors: true} } + + before do + expect(client.options[:raise_errors]).to be(true) + end + + context "when there is a token" do + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + context "with request" do + subject(:request) { target.post("/token/header") } + + it "raises" do + block_is_expected.to raise_error("invalid :mode option of #{mode}") + end + end + end + + context "when there is empty token" do + let(:token) { "" } + + it "raises on initialize" do + block_is_expected.to raise_error(OAuth2::Error, {error: "OAuth2::AccessToken has no token", error_description: "Options are: #{{mode: :this_is_bad, raise_errors: true}}"}.to_s) + end + end + + context "when there is nil token" do + let(:token) { nil } + + it "raises on initialize" do + block_is_expected.to raise_error(OAuth2::Error, {error: "OAuth2::AccessToken has no token", error_description: "Options are: #{{mode: :this_is_bad, raise_errors: true}}"}.to_s) + end + end + end + end + + context "with verb-dependent mode" do + let(:mode) do + lambda do |verb| + case verb + when :get then :query + when :post, :delete then :header + when :put, :patch then :body + end + end + end + + let(:options) { {mode: mode} } + + VERBS.each do |verb| + it "correctly handles a #{verb.to_s.upcase}" do + expect(subject.__send__(verb, "/token/#{mode.call(verb)}").body).to include(token) + end + end + + context "when invalid" do + subject(:invalid_target) { target.__send__(http_verb, "/token/#{mode.call(http_verb)}") } + + let(:http_verb) { :get } + let(:mode) do + lambda do |_verb| + "foobar" + end + end + + it "correctly handles an invalid mode by raising an error" do + block_is_expected.to raise_error("invalid :mode option of foobar") + end + end + end + + context "with verb-dependent Hash mode" do + let(:mode_hash) do + {get: :query, post: :header, delete: :header, put: :body, patch: :body} + end + let(:options) { {mode: mode_hash} } + + VERBS.each do |verb| + it "correctly handles a #{verb.to_s.upcase} via Hash" do + expected = mode_hash[verb] || :header + expect(subject.__send__(verb, "/token/#{expected}").body).to include(token) + end + end + + context "with fallback to :header for missing key" do + let(:mode_hash) { {get: :query} } + + it "defaults POST to header when not specified" do + expect(subject.post("/token/header").body).to include(token) + end + end + + context "when invalid value" do + let(:mode_hash) { {get: "foobar"} } + + it "raises an error for invalid mapping" do + expect { subject.get("/token/foobar") }.to raise_error("invalid :mode option of foobar") + end + end + end + + context "with client.options[:raise_errors] = false" do + let(:options) { {raise_errors: false} } + + before do + expect(client.options[:raise_errors]).to be(false) + end + + context "when there is a token" do + let(:token) { "hurdygurdy" } + + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has token" do + expect(target.token).to eq(token) + end + + it "has no refresh_token" do + expect(target.refresh_token).to be_nil + end + + context "when there is refresh_token" do + let(:options) { {raise_errors: false, refresh_token: "zxcv"} } + + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has token" do + expect(target.token).to eq(token) + end + + it "has refresh_token" do + expect(target.refresh_token).to eq("zxcv") + end + end + end + + context "when there is empty token" do + let(:token) { "" } + + context "when there is no refresh_token" do + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has no token" do + expect(target.token).to eq("") + end + + it "has no refresh_token" do + expect(target.refresh_token).to be_nil + end + + context "with warning for no token" do + subject(:printed) do + capture(:stderr) do + target + end + end + + before do + @original_sntw = OAuth2.config.silence_no_tokens_warning + OAuth2.config.silence_no_tokens_warning = false + end + + after do + OAuth2.config.silence_no_tokens_warning = @original_sntw + end + + it "warns on STDERR" do + msg = <<-MSG.lstrip + OAuth2::AccessToken has no token + MSG + expect(printed).to eq(msg) + end + end + end + + context "when there is refresh_token" do + let(:options) { {raise_errors: false, refresh_token: "qwer"} } + + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has no token" do + expect(target.token).to eq("") + end + + it "has refresh_token" do + expect(target.refresh_token).to eq("qwer") + end + end + end + + context "when there is nil token" do + let(:token) { nil } + + before do + @original_sntw = OAuth2.config.silence_no_tokens_warning + OAuth2.config.silence_no_tokens_warning = false + end + + after do + OAuth2.config.silence_no_tokens_warning = @original_sntw + end + + context "when there is no refresh_token" do + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has no token" do + expect(target.token).to eq("") + end + + it "has no refresh_token" do + expect(target.refresh_token).to be_nil + end + + context "with warning for no token" do + subject(:printed) do + capture(:stderr) do + target + end + end + + it "warns on STDERR" do + msg = <<-MSG.lstrip + OAuth2::AccessToken has no token + MSG + expect(printed).to eq(msg) + end + end + end + + context "when there is refresh_token" do + let(:options) { {raise_errors: false, refresh_token: "asdf"} } + + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has no token" do + expect(target.token).to eq("") + end + + it "has refresh_token" do + expect(target.refresh_token).to eq("asdf") + end + end + end + end + + context "with client.options[:raise_errors] = true" do + let(:options) { {raise_errors: true} } + + before do + expect(client.options[:raise_errors]).to be(true) + end + + context "when there is a token" do + let(:token) { "hurdygurdy" } + + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has token" do + expect(target.token).to eq(token) + end + + it "has no refresh_token" do + expect(target.refresh_token).to be_nil + end + + context "when there is refresh_token" do + let(:options) { {raise_errors: true, refresh_token: "zxcv"} } + + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has token" do + expect(target.token).to eq(token) + end + + it "has refresh_token" do + expect(target.refresh_token).to eq("zxcv") + end + end + end + + context "when there is empty token" do + let(:token) { "" } + + context "when there is no refresh_token" do + it "raises on initialize" do + block_is_expected.to raise_error(OAuth2::Error, {error: "OAuth2::AccessToken has no token", error_description: "Options are: #{{raise_errors: true}}"}.to_s) + end + end + + context "when there is refresh_token" do + let(:options) { {raise_errors: true, refresh_token: "qwer"} } + + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has no token" do + expect(target.token).to eq("") + end + + it "has refresh_token" do + expect(target.refresh_token).to eq("qwer") + end + end + end + + context "when there is nil token" do + let(:token) { nil } + + context "when there is no refresh_token" do + it "raises on initialize" do + block_is_expected.to raise_error(OAuth2::Error, {error: "OAuth2::AccessToken has no token", error_description: "Options are: #{{raise_errors: true}}"}.to_s) + end + end + + context "when there is refresh_token" do + let(:options) { {raise_errors: true, refresh_token: "asdf"} } + + it "does not raise on initialize" do + block_is_expected.not_to raise_error + end + + it "has no token" do + expect(target.token).to eq("") + end + + it "has refresh_token" do + expect(target.refresh_token).to eq("asdf") + end + end + end + end end - it 'does not modify opts hash' do - opts = {:param_name => 'foo', :header_format => 'Bearer %', :mode => :body} + it "does not modify opts hash" do + opts = {param_name: "foo", header_format: "Bearer %", mode: :body} opts_before = opts.dup described_class.new(client, token, opts) expect(opts).to eq(opts_before) end - it 'initializes with a string expires_at' do - future = Time.now.utc + 100_000 - hash = {:access_token => token, :expires_at => future.iso8601, 'foo' => 'bar'} - target = described_class.from_hash(client, hash) - assert_initialized_token(target) - expect(target.expires_at).to be_a(Integer) - expect(target.expires_at).to eql(future.to_i) + describe "expires_at" do + let(:expires_at) { 1_361_396_829 } + let(:hash) do + { + :access_token => token, + :expires_at => expires_at.to_s, + "foo" => "bar", + } + end + + it "initializes with an integer timestamp expires_at" do + target = described_class.from_hash(client, hash.merge(expires_at: expires_at)) + assert_initialized_token(target) + expect(target.expires_at).to eql(expires_at) + end + + it "initializes with a string timestamp expires_at" do + target = described_class.from_hash(client, hash) + assert_initialized_token(target) + expect(target.expires_at).to eql(expires_at) + end + + it "initializes with a string time expires_at" do + target = described_class.from_hash(client, hash.merge(expires_at: Time.at(expires_at).iso8601)) + assert_initialized_token(target) + expect(target.expires_at).to eql(expires_at) + end end - describe 'expires_latency' do + describe "expires_latency" do let(:expires_at) { 1_530_000_000 } let(:expires_in) { 100 } let(:expires_latency) { 10 } let(:hash) do { - :access_token => token, - :expires_latency => expires_latency, - :expires_in => expires_in, + access_token: token, + expires_latency: expires_latency, + expires_in: expires_in, } end - it 'sets it via options' do - target = described_class.from_hash(client, hash.merge(:expires_latency => expires_latency.to_s)) + it "sets it via options" do + target = described_class.from_hash(client, hash.merge(expires_latency: expires_latency.to_s)) expect(target.expires_latency).to eq expires_latency end - it 'sets it nil by default' do + it "sets it nil by default" do hash.delete(:expires_latency) target = described_class.from_hash(client, hash) expect(target.expires_latency).to be_nil end - it 'reduces expires_at by the given amount' do + it "reduces expires_at by the given amount" do allow(Time).to receive(:now).and_return(expires_at) target = described_class.from_hash(client, hash) expect(target.expires_at).to eq(expires_at + expires_in - expires_latency) end - it 'reduces expires_at by the given amount if expires_at is provided as option' do - target = described_class.from_hash(client, hash.merge(:expires_at => expires_at)) + it "reduces expires_at by the given amount if expires_at is provided as option" do + target = described_class.from_hash(client, hash.merge(expires_at: expires_at)) expect(target.expires_at).to eq(expires_at - expires_latency) end end end - describe '#request' do - context 'with :mode => :header' do + describe "#request" do + context "with :mode => :header" do before do subject.options[:mode] = :header end VERBS.each do |verb| it "sends the token in the Authorization header for a #{verb.to_s.upcase} request" do - expect(subject.post('/token/header').body).to include(token) + expect(subject.post("/token/header").body).to include(token) end end end - context 'with :mode => :query' do + context "with :mode => :query" do before do subject.options[:mode] = :query end VERBS.each do |verb| - it "sends the token in the Authorization header for a #{verb.to_s.upcase} request" do - expect(subject.post('/token/query').body).to eq(token) + it "sends the token in the body for a #{verb.to_s.upcase} request" do + expect(subject.post("/token/query").body).to eq(token) end it "sends a #{verb.to_s.upcase} request and options[:param_name] include [number]." do - subject.options[:param_name] = 'auth[1]' - expect(subject.__send__(verb, '/token/query_string').body).to include("auth[1]=#{token}") + subject.options[:param_name] = "auth[1]" + expect(subject.__send__(verb, "/token/query_string").body).to include("auth[1]=#{token}") end end end - context 'with :mode => :body' do + context "with :mode => :body" do before do subject.options[:mode] = :body end VERBS.each do |verb| - it "sends the token in the Authorization header for a #{verb.to_s.upcase} request" do - expect(subject.post('/token/body').body.split('=').last).to eq(token) + it "sends the token in the body for a #{verb.to_s.upcase} request" do + expect(subject.post("/token/body").body.split("=").last).to eq(token) + end + + context "when options[:param_name] include [number]" do + it "sends a #{verb.to_s.upcase} request when body is a hash" do + subject.options[:param_name] = "auth[1]" + expect(subject.__send__(verb, "/token/body", body: {hi: "there"}).body).to include("auth%5B1%5D=#{token}") + end + + it "sends a #{verb.to_s.upcase} request when body is overridden as string" do + subject.options[:param_name] = "snoo[1]" + expect(subject.__send__(verb, "/token/body", body: "hi_there").body).to include("hi_there&snoo[1]=#{token}") + end end end end - context 'params include [number]' do + context "params include [number]" do VERBS.each do |verb| it "sends #{verb.to_s.upcase} correct query" do - expect(subject.__send__(verb, '/token/query_string', :params => {'foo[bar][1]' => 'val'}).body).to include('foo[bar][1]=val') + expect(subject.__send__(verb, "/token/query_string", params: {"foo[bar][1]" => "val"}).body).to include("foo[bar][1]=val") end end end end - describe '#expires?' do - it 'is false if there is no expires_at' do + describe "#expires?" do + it "is false if there is no expires_at" do expect(described_class.new(client, token)).not_to be_expires end - it 'is true if there is an expires_in' do - expect(described_class.new(client, token, :refresh_token => 'abaca', :expires_in => 600)).to be_expires + it "is true if there is an expires_in" do + expect(described_class.new(client, token, refresh_token: "abaca", expires_in: 600)).to be_expires end - it 'is true if there is an expires_at' do - expect(described_class.new(client, token, :refresh_token => 'abaca', :expires_in => Time.now.getutc.to_i + 600)).to be_expires + it "is true if there is an expires_at" do + expect(described_class.new(client, token, refresh_token: "abaca", expires_in: Time.now.getutc.to_i + 600)).to be_expires end end - describe '#expired?' do - it 'is false if there is no expires_in or expires_at' do + describe "#expired?" do + it "is false if there is no expires_in or expires_at" do expect(described_class.new(client, token)).not_to be_expired end - it 'is false if expires_in is in the future' do - expect(described_class.new(client, token, :refresh_token => 'abaca', :expires_in => 10_800)).not_to be_expired + it "is false if expires_in is 0 (token is permanent)" do + expect(described_class.new(client, token, refresh_token: "abaca", expires_in: 0)).not_to be_expired end - it 'is true if expires_at is in the past' do - access = described_class.new(client, token, :refresh_token => 'abaca', :expires_in => 600) + it "is false if expires_in is in the future" do + expect(described_class.new(client, token, refresh_token: "abaca", expires_in: 10_800)).not_to be_expired + end + + it "is true if expires_at is in the past" do + access = described_class.new(client, token, refresh_token: "abaca", expires_in: 600) @now = Time.now + 10_800 allow(Time).to receive(:now).and_return(@now) expect(access).to be_expired end - it 'is true if expires_at is now' do + it "is true if expires_at is now" do @now = Time.now - access = described_class.new(client, token, :refresh_token => 'abaca', :expires_at => @now.to_i) + access = described_class.new(client, token, refresh_token: "abaca", expires_at: @now.to_i) allow(Time).to receive(:now).and_return(@now) expect(access).to be_expired end end - describe '#refresh' do + describe "#refresh" do + let(:options) { {access_token_class: access_token_class} } + let(:access_token_class) { NewAccessToken } let(:access) do - described_class.new(client, token, :refresh_token => 'abaca', - :expires_in => 600, - :param_name => 'o_param') + described_class.new( + client, + token, + refresh_token: "abaca", + expires_in: 600, + param_name: "o_param", + access_token_class: access_token_class, + ) end let(:new_access) do - NewAccessToken = Class.new(described_class) - NewAccessToken.new(client, token, :refresh_token => 'abaca') + NewAccessToken.new(client, token, refresh_token: "abaca") + end + + before do + custom_class = Class.new(described_class) do + def self.from_hash(client, hash) + new(client, hash.delete("access_token"), hash) + end + + def self.contains_token?(hash) + hash.key?("refresh_token") + end + end + + stub_const("NewAccessToken", custom_class) end - it 'returns a refresh token with appropriate values carried over' do + context "without refresh_token" do + subject(:no_refresh) { no_access.refresh } + + let(:no_access) do + described_class.new( + client, + token, + refresh_token: nil, + expires_in: 600, + param_name: "o_param", + access_token_class: access_token_class, + ) + end + + it "raises when no refresh_token" do + block_is_expected.to raise_error(OAuth2::Error, {error: "A refresh_token is not available"}.to_s) + end + end + + it "returns a refresh token with appropriate values carried over" do refreshed = access.refresh expect(access.client).to eq(refreshed.client) expect(access.options[:param_name]).to eq(refreshed.options[:param_name]) end - it 'returns a refresh token of the same access token class' do + it "returns a refresh token of the same access token class" do refreshed = new_access.refresh! expect(new_access.class).to eq(refreshed.class) end - context 'with a nil refresh_token in the response' do - let(:refresh_body) { MultiJson.encode(:access_token => 'refreshed_foo', :expires_in => 600, :refresh_token => nil) } + context "with a nil refresh_token in the response" do + let(:refresh_body) { JSON.dump(access_token: "refreshed_foo", expires_in: 600, refresh_token: nil) } - it 'copies the refresh_token from the original token' do + it "copies the refresh_token from the original token" do refreshed = access.refresh expect(refreshed.refresh_token).to eq(access.refresh_token) end end + + context "with a not-nil refresh_token in the response" do + let(:refresh_body) { JSON.dump(access_token: "refreshed_foo", expires_in: 600, refresh_token: "qerwer") } + + it "copies the refresh_token from the original token" do + refreshed = access.refresh + + expect(refreshed.token).to eq("refreshed_foo") + expect(refreshed.refresh_token).to eq("qerwer") + end + end + + context "with a not-nil, not camel case, refresh_token in the response" do + let(:refresh_body) { JSON.dump(accessToken: "refreshed_foo", expires_in: 600, refreshToken: "qerwer") } + + it "copies the refresh_token from the original token" do + refreshed = access.refresh + + expect(refreshed.token).to eq("refreshed_foo") + expect(refreshed.refresh_token).to eq("qerwer") + end + end + + context "with a custom access_token_class" do + let(:access_token_class) { NewAccessToken } + + it "returns a refresh token of NewAccessToken" do + refreshed = access.refresh! + + expect(new_access.class).to eq(refreshed.class) + end + end end - describe '#to_hash' do - it 'return a hash equals to the hash used to initialize access token' do - hash = {:access_token => token, :refresh_token => 'foobar', :expires_at => Time.now.to_i + 200, 'foo' => 'bar'} + describe "#revoke" do + let(:token) { "monkey123" } + let(:refresh_token) { "refreshmonkey123" } + let(:access_token) { described_class.new(client, token, refresh_token: refresh_token) } + + context "with no token_type_hint specified" do + it "revokes the access token by default" do + expect(access_token.revoke.status).to eq(200) + end + end + + context "with access_token token_type_hint" do + it "revokes the access token" do + expect { + access_token.revoke(token_type_hint: "access_token") + }.not_to raise_error + end + end + + context "with refresh_token token_type_hint" do + it "revokes the refresh token" do + expect { + access_token.revoke(token_type_hint: "refresh_token") + }.not_to raise_error + end + end + + context "with invalid token_type_hint" do + it "raises an OAuth2::Error" do + expect { + access_token.revoke(token_type_hint: "invalid_type") + }.to raise_error(OAuth2::Error, /token_type_hint must be one of/) + end + end + + context "when refresh_token is specified but not available" do + let(:access_token) { described_class.new(client, "abc", refresh_token: nil) } + + it "raises an OAuth2::Error" do + expect { + access_token.revoke(token_type_hint: "refresh_token") + }.to raise_error(OAuth2::Error, /refresh_token is not available for revoking/) + end + end + + context "when refresh_token is, but access_token is not, available" do + let(:access_token) { described_class.new(client, "abc", refresh_token: refresh_token) } + + before do + allow(client).to receive(:revoke_token). + with(refresh_token, "refresh_token", {}). + and_return(OAuth2::Response.new(double(status: 200))) + # The code path being tested shouldn't be reachable... so this is hacky. + # Testing it for anal level compliance. Revoking a refresh token without an access token is valid. + # In other words, the implementation of AccessToken doesn't allow instantiation without an access token. + # But in a revocation scenario it should theoretically work. + # It is intended that AccessToken be subclassed, so this is worth testing, as subclasses may change behavior. + allow(access_token).to receive(:token).and_return(nil) + end + + it "revokes refresh_token" do + expect { + access_token.revoke + }.not_to raise_error + end + end + + context "when no tokens are available" do + let(:access_token) { described_class.new(client, "abc", refresh_token: nil) } + + before do + # The code path being tested shouldn't be reachable... so this is hacky. + # Testing it for anal level compliance. Revoking a refresh token without an access token is valid. + # In other words, the implementation of AccessToken doesn't allow instantiation without an access token. + # But in a revocation scenario it should theoretically work. + # It is intended that AccessToken be subclassed, so this is worth testing, as subclasses may change behavior. + allow(access_token).to receive(:token).and_return(nil) + end + + it "raises an OAuth2::Error" do + expect { + access_token.revoke + }.to raise_error(OAuth2::Error, /unknown token type is not available for revoking/) + end + end + + context "with additional params" do + before do + allow(client).to receive(:revoke_token). + with(token, "access_token", {extra: "param"}). + and_return(OAuth2::Response.new(double(status: 200))) + end + + it "passes them to the client" do + expect { + access_token.revoke({extra: "param"}) + }.not_to raise_error + end + end + + context "with a block" do + it "passes the block to the client" do + expect { + access_token.revoke do |_req| + puts "Hello from the other side" + end + }.not_to raise_error + end + + it "has status 200" do + expect( + access_token.revoke do |_req| + puts "Hello again" + end.status, + ).to eq(200) + end + + it "executes the block" do + @apple = 0 + access_token.revoke do |_req| + @apple += 1 + end + expect(@apple).to eq(1) + end + end + end + + describe "#to_hash" do + it "return a hash equal to the hash used to initialize access token" do + hash = { + access_token: token, + refresh_token: "foobar", + expires_at: Time.now.to_i + 200, + header_format: "Bearer %", + mode: :header, + param_name: "access_token", + foo: "bar", + } access_token = described_class.from_hash(client, hash.clone) expect(access_token.to_hash).to eq(hash) end + + context "with token_name" do + it "return a hash equal to the hash used to initialize access token" do + hash = { + access_token: "", + refresh_token: "foobar", + expires_at: Time.now.to_i + 200, + header_format: "Bearer %", + mode: :header, + param_name: "access_token", + token_name: "banana_face", + foo: "bar", + } + access_token = described_class.from_hash(client, hash.clone) + expect(access_token.to_hash).to eq(hash) + end + end + end + + describe "#inspect" do + let(:inspect_result) { described_class.new(nil, "secret-token", {refresh_token: "secret-refresh-token"}).inspect } + + it "filters out the @token value" do + expect(inspect_result).to include("@token=[FILTERED]") + end + + it "filters out the @refresh_token value" do + expect(inspect_result).to include("@refresh_token=[FILTERED]") + end end end diff --git a/spec/oauth2/authenticator_spec.rb b/spec/oauth2/authenticator_spec.rb index 57defdcf..f7396c5e 100644 --- a/spec/oauth2/authenticator_spec.rb +++ b/spec/oauth2/authenticator_spec.rb @@ -1,84 +1,174 @@ +# frozen_string_literal: true + RSpec.describe OAuth2::Authenticator do subject do described_class.new(client_id, client_secret, mode) end - let(:client_id) { 'foo' } - let(:client_secret) { 'bar' } + let(:client_id) { "foo" } + let(:client_secret) { "bar" } let(:mode) { :undefined } - it 'raises NotImplementedError for unknown authentication mode' do + it "raises NotImplementedError for unknown authentication mode" do expect { subject.apply({}) }.to raise_error(NotImplementedError) end - describe '#apply' do - context 'with parameter-based authentication' do + describe "#apply" do + context "with parameter-based authentication" do let(:mode) { :request_body } - it 'adds client_id and client_secret to params' do + it "adds client_id and client_secret to params" do output = subject.apply({}) - expect(output).to eq('client_id' => 'foo', 'client_secret' => 'bar') + expect(output).to eq("client_id" => "foo", "client_secret" => "bar") + end + + context "when client_id nil" do + let(:client_id) { nil } + + it "ignores client_id, but adds client_secret to params" do + output = subject.apply({}) + expect(output).to eq("client_secret" => "bar") + end end - it 'does not overwrite existing credentials' do - input = {'client_secret' => 's3cr3t'} + it "does not overwrite existing credentials" do + input = {"client_secret" => "s3cr3t"} output = subject.apply(input) - expect(output).to eq('client_id' => 'foo', 'client_secret' => 's3cr3t') + expect(output).to eq("client_id" => "foo", "client_secret" => "s3cr3t") end - it 'preserves other parameters' do - input = {'state' => '42', :headers => {'A' => 'b'}} + it "preserves other parameters" do + input = {"state" => "42", :headers => {"A" => "b"}} output = subject.apply(input) expect(output).to eq( - 'client_id' => 'foo', - 'client_secret' => 'bar', - 'state' => '42', - :headers => {'A' => 'b'} + "client_id" => "foo", + "client_secret" => "bar", + "state" => "42", + :headers => {"A" => "b"}, ) end - context 'using tls client authentication' do + context "passing nil secret" do + let(:client_secret) { nil } + + it "does not set nil client_secret" do + output = subject.apply({}) + expect(output).to eq("client_id" => "foo") + end + end + + context "using tls client authentication" do let(:mode) { :tls_client_auth } - it 'does not add client_secret' do + it "does not add client_secret" do output = subject.apply({}) - expect(output).to eq('client_id' => 'foo') + expect(output).to eq("client_id" => "foo") end end - context 'using private key jwt authentication' do + context "using private key jwt authentication" do let(:mode) { :private_key_jwt } - it 'does not include client_id or client_secret' do + it "does not include client_id or client_secret" do + output = subject.apply({}) + expect(output).to eq({}) + end + end + end + + context "using tls_client_auth" do + let(:mode) { :tls_client_auth } + + context "when client_id present" do + let(:client_id) { "foobar" } + + it "adds client_id to params" do + output = subject.apply({}) + expect(output).to eq("client_id" => "foobar") + end + end + + context "when client_id nil" do + let(:client_id) { nil } + + it "ignores client_id for params" do output = subject.apply({}) expect(output).to eq({}) end end end - context 'with Basic authentication' do + context "with Basic authentication" do let(:mode) { :basic_auth } - let(:header) { 'Basic ' + Base64.strict_encode64("#{client_id}:#{client_secret}") } + let(:header) { "Basic #{Base64.strict_encode64("#{client_id}:#{client_secret}")}" } - it 'encodes credentials in headers' do + it "encodes credentials in headers" do output = subject.apply({}) - expect(output).to eq(:headers => {'Authorization' => header}) + expect(output).to eq(headers: {"Authorization" => header}) end - it 'does not overwrite existing credentials' do - input = {:headers => {'Authorization' => 'Bearer abc123'}} + it "does not overwrite existing credentials" do + input = {headers: {"Authorization" => "Bearer abc123"}} output = subject.apply(input) - expect(output).to eq(:headers => {'Authorization' => 'Bearer abc123'}) + expect(output).to eq(headers: {"Authorization" => "Bearer abc123"}) end - it 'does not overwrite existing params or headers' do - input = {'state' => '42', :headers => {'A' => 'b'}} + it "does not overwrite existing params or headers" do + input = {"state" => "42", :headers => {"A" => "b"}} output = subject.apply(input) expect(output).to eq( - 'state' => '42', - :headers => {'A' => 'b', 'Authorization' => header} + "state" => "42", + :headers => {"A" => "b", "Authorization" => header}, ) end end end + + describe "#inspect" do + it "filters secret by default" do + expect(described_class.filtered_attribute_names).to include(:secret) + end + + it "filters out the @secret value" do + expect(subject.inspect).to include("@secret=[FILTERED]") + end + + context "when filter is changed" do + before do + @original_filter = described_class.filtered_attribute_names + described_class.filtered_attributes :vanilla + end + + after do + described_class.filtered_attributes(*@original_filter) + end + + it "changes the filter" do + expect(described_class.filtered_attribute_names).to eq([:vanilla]) + end + + it "does not filter out the @secret value" do + expect(subject.inspect).to include("@secret=\"bar\"") + end + end + + context "when filter is empty" do + before do + @original_filter = described_class.filtered_attribute_names + described_class.filtered_attributes + end + + after do + described_class.filtered_attributes(*@original_filter) + end + + it "changes the filter" do + expect(described_class.filtered_attribute_names).to eq([]) + end + + it "does not filter out the @secret value" do + expect(subject.inspect).to include("@secret=\"bar\"") + end + end + end end diff --git a/spec/oauth2/client_spec.rb b/spec/oauth2/client_spec.rb index dd1ab049..741e7568 100644 --- a/spec/oauth2/client_spec.rb +++ b/spec/oauth2/client_spec.rb @@ -1,97 +1,132 @@ # coding: utf-8 +# frozen_string_literal: true -require 'nkf' +require "nkf" RSpec.describe OAuth2::Client do - subject do - described_class.new('abc', 'def', {:site => 'https://api.example.com/'}.merge(options)) do |builder| + subject(:instance) do + described_class.new("abc", "def", {site: "https://api.example.com/"}.merge(options)) do |builder| builder.adapter :test do |stub| - stub.get('/success') { |env| [200, {'Content-Type' => 'text/awesome'}, 'yay'] } - stub.get('/reflect') { |env| [200, {}, env[:body]] } - stub.post('/reflect') { |env| [200, {}, env[:body]] } - stub.get('/unauthorized') { |env| [401, {'Content-Type' => 'application/json'}, MultiJson.encode(:error => error_value, :error_description => error_description_value)] } - stub.get('/conflict') { |env| [409, {'Content-Type' => 'text/plain'}, 'not authorized'] } - stub.get('/redirect') { |env| [302, {'Content-Type' => 'text/plain', 'location' => '/success'}, ''] } - stub.post('/redirect') { |env| [303, {'Content-Type' => 'text/plain', 'location' => '/reflect'}, ''] } - stub.get('/error') { |env| [500, {'Content-Type' => 'text/plain'}, 'unknown error'] } - stub.get('/empty_get') { |env| [204, {}, nil] } - stub.get('/different_encoding') { |env| [500, {'Content-Type' => 'application/json'}, NKF.nkf('-We', MultiJson.encode(:error => error_value, :error_description => '∞'))] } - stub.get('/ascii_8bit_encoding') { |env| [500, {'Content-Type' => 'application/json'}, MultiJson.encode(:error => 'invalid_request', :error_description => 'é').force_encoding('ASCII-8BIT')] } + stub.get("/success") { |_env| [200, {"Content-Type" => "text/awesome"}, "yay"] } + stub.get("/reflect") { |env| [200, {}, env[:body]] } + stub.post("/reflect") { |env| [200, {}, env[:body]] } + stub.get("/unauthorized") { |_env| [401, {"Content-Type" => "application/json"}, JSON.dump(error: error_value, error_description: error_description_value)] } + stub.get("/conflict") { |_env| [409, {"Content-Type" => "text/plain"}, "not authorized"] } + stub.get("/redirect") { |_env| [302, {"Content-Type" => "text/plain", "location" => "/success"}, ""] } + stub.get("/redirect_no_loc") { |_env| [302, {"Content-Type" => "text/plain"}, ""] } + stub.post("/redirect") { |_env| [303, {"Content-Type" => "text/plain", "location" => "/reflect"}, ""] } + stub.get("/error") { |_env| [500, {"Content-Type" => "text/plain"}, "unknown error"] } + stub.get("/unparsable_error") { |_env| [500, {"Content-Type" => "application/json"}, "unknown error"] } + stub.get("/empty_get") { |_env| [204, {}, nil] } + stub.get("/different_encoding") { |_env| [500, {"Content-Type" => "application/json"}, NKF.nkf("-We", JSON.dump(error: error_value, error_description: "∞"))] } + stub.get("/ascii_8bit_encoding") { |_env| [500, {"Content-Type" => "application/json"}, JSON.dump(error: "invalid_request", error_description: "é").force_encoding("ASCII-8BIT")] } + stub.get("/unhandled_status") { |_env| [600, {}, nil] } + stub.post("/oauth/revoke") { |env| [200, {"Content-type" => "application/json"}, env[:body]] } end end end - let!(:error_value) { 'invalid_token' } - let!(:error_description_value) { 'bad bad token' } + let!(:error_value) { "invalid_token" } + let!(:error_description_value) { "bad bad token" } let(:options) { {} } - describe '#initialize' do - it 'assigns id and secret' do - expect(subject.id).to eq('abc') - expect(subject.secret).to eq('def') + describe "#initialize" do + it "assigns id and secret" do + expect(subject.id).to eq("abc") + expect(subject.secret).to eq("def") end - it 'assigns site from the options hash' do - expect(subject.site).to eq('https://api.example.com/') + it "assigns site from the options hash" do + expect(subject.site).to eq("https://api.example.com/") end - it 'assigns Faraday::Connection#host' do - expect(subject.connection.host).to eq('api.example.com') + it "assigns Faraday::Connection#host" do + expect(subject.connection.host).to eq("api.example.com") end - it 'leaves Faraday::Connection#ssl unset' do + it "leaves Faraday::Connection#ssl unset" do expect(subject.connection.ssl).to be_empty end - it 'is able to pass a block to configure the connection' do - builder = double('builder') + it "is able to pass a block to configure the connection" do + builder = double("builder") allow(Faraday).to receive(:new).and_yield(builder) allow(builder).to receive(:response) expect(builder).to receive(:adapter).with(:test) - described_class.new('abc', 'def') do |client| + described_class.new("abc", "def") do |client| client.adapter :test end.connection end - it 'defaults raise_errors to true' do + it "defaults raise_errors to true" do expect(subject.options[:raise_errors]).to be true end - it 'allows true/false for raise_errors option' do - client = described_class.new('abc', 'def', :site => 'https://api.example.com/', :raise_errors => false) + it "allows true/false for raise_errors option" do + client = described_class.new("abc", "def", site: "https://api.example.com/", raise_errors: false) expect(client.options[:raise_errors]).to be false - client = described_class.new('abc', 'def', :site => 'https://api.example.com/', :raise_errors => true) + client = described_class.new("abc", "def", site: "https://api.example.com/", raise_errors: true) expect(client.options[:raise_errors]).to be true end - it 'allows override of raise_errors option' do - client = described_class.new('abc', 'def', :site => 'https://api.example.com/', :raise_errors => true) do |builder| + it "allows override of raise_errors option" do + client = described_class.new("abc", "def", site: "https://api.example.com/", raise_errors: true) do |builder| builder.adapter :test do |stub| - stub.get('/notfound') { |env| [404, {}, nil] } + stub.get("/notfound") { |_env| [404, {}, nil] } end end expect(client.options[:raise_errors]).to be true - expect { client.request(:get, '/notfound') }.to raise_error(OAuth2::Error) - response = client.request(:get, '/notfound', :raise_errors => false) + expect { client.request(:get, "/notfound") }.to raise_error(OAuth2::Error) + response = client.request(:get, "/notfound", raise_errors: false) expect(response.status).to eq(404) end - it 'allows get/post for access_token_method option' do - client = described_class.new('abc', 'def', :site => 'https://api.example.com/', :access_token_method => :get) + it "allows get/post for access_token_method option" do + client = described_class.new("abc", "def", site: "https://api.example.com/", access_token_method: :get) expect(client.options[:access_token_method]).to eq(:get) - client = described_class.new('abc', 'def', :site => 'https://api.example.com/', :access_token_method => :post) + client = described_class.new("abc", "def", site: "https://api.example.com/", access_token_method: :post) expect(client.options[:access_token_method]).to eq(:post) end - it 'does not mutate the opts hash argument' do - opts = {:site => 'http://example.com/'} + it "does not mutate the opts hash argument" do + opts = {site: "http://example.com/"} opts2 = opts.dup - described_class.new 'abc', 'def', opts + described_class.new "abc", "def", opts expect(opts).to eq(opts2) end + + it "raises exception if JSON is expected, but server returns invalid JSON" do + client = instance + expect { client.request(:get, "/unparsable_error") }.to raise_error(JSON::ParserError) + response = client.request(:get, "/unparsable_error", raise_errors: false) + expect(response.status).to eq(500) + end + end + + describe "#site=(val)" do + subject(:site) { instance.site = new_site } + + let(:options) do + {site: "https://example.com/blog"} + end + let(:new_site) { "https://example.com/sharpie" } + + it "sets site" do + block_is_expected.to change(instance, :site).from("https://example.com/blog").to("https://example.com/sharpie") + end + + context "with connection" do + before do + instance.connection + end + + it "allows connection to reset with new url prefix" do + block_is_expected.to change { instance.connection.url_prefix }.from(URI("https://example.com/blog")).to(URI("https://example.com/sharpie")) + end + end end %w[authorize token].each do |url_type| @@ -101,441 +136,1244 @@ end it "is settable via the :#{url_type}_url option" do - subject.options[:"#{url_type}_url"] = '/oauth/custom' - expect(subject.send("#{url_type}_url")).to eq('https://api.example.com/oauth/custom') + subject.options[:"#{url_type}_url"] = "/oauth/custom" + expect(subject.send("#{url_type}_url")).to eq("https://api.example.com/oauth/custom") end - it 'allows a different host than the site' do - subject.options[:"#{url_type}_url"] = 'https://api.foo.com/oauth/custom' - expect(subject.send("#{url_type}_url")).to eq('https://api.foo.com/oauth/custom') + it "allows a different host than the site" do + subject.options[:"#{url_type}_url"] = "https://api.foo.com/oauth/custom" + expect(subject.send("#{url_type}_url")).to eq("https://api.foo.com/oauth/custom") end - context 'when a URL with path is used in the site' do + context "when a URL with path is used in the site" do let(:options) do - {:site => 'https://example.com/blog'} + {site: "https://example.com/blog"} end - it 'generates an authorization URL relative to the site' do + it "generates an authorization URL relative to the site" do expect(subject.send("#{url_type}_url")).to eq("https://example.com/blog/oauth/#{url_type}") end end end end - describe ':redirect_uri option' do + describe ":redirect_uri option" do let(:auth_code_params) do { - 'client_id' => 'abc', - 'client_secret' => 'def', - 'code' => 'code', - 'grant_type' => 'authorization_code', + "client_id" => "abc", + "client_secret" => "def", + "code" => "code", + "grant_type" => "authorization_code", } end - context 'when blank' do - it 'there is no redirect_uri param added to authorization URL' do - expect(subject.authorize_url('https://github.com/a'%20=%3E%20'b')).to eq('https://api.example.com/oauth/authorize?a=b') + context "when blank" do + it "there is no redirect_uri param added to authorization URL" do + expect(subject.authorize_url("https://github.com/a%22%20=%3E%20%22b")).to eq("https://api.example.com/oauth/authorize?a=b") end - it 'does not add the redirect_uri param to the auth_code token exchange request' do - client = described_class.new('abc', 'def', :site => 'https://api.example.com/', :auth_scheme => :request_body) do |builder| + it "does not add the redirect_uri param to the auth_code token exchange request" do + client = described_class.new("abc", "def", site: "https://api.example.com/", auth_scheme: :request_body) do |builder| builder.adapter :test do |stub| - stub.post('/oauth/token', auth_code_params) do - [200, {'Content-Type' => 'application/json'}, '{"access_token":"token"}'] + stub.post("/oauth/token", auth_code_params) do + [200, {"Content-Type" => "application/json"}, '{"access_token":"token"}'] end end end - client.auth_code.get_token('code') + client.auth_code.get_token("code") end end - context 'when set' do - before { subject.options[:redirect_uri] = 'https://site.com/oauth/callback' } + context "when set" do + before { subject.options[:redirect_uri] = "https://site.com/oauth/callback" } - it 'adds the redirect_uri param to authorization URL' do - expect(subject.authorize_url('https://github.com/a'%20=%3E%20'b')).to eq('https://api.example.com/oauth/authorize?a=b&redirect_uri=https%3A%2F%2Fsite.com%2Foauth%2Fcallback') + it "adds the redirect_uri param to authorization URL" do + expect(subject.authorize_url("https://github.com/a%22%20=%3E%20%22b")).to eq("https://api.example.com/oauth/authorize?a=b&redirect_uri=https%3A%2F%2Fsite.com%2Foauth%2Fcallback") end - it 'adds the redirect_uri param to the auth_code token exchange request' do - client = described_class.new('abc', 'def', :redirect_uri => 'https://site.com/oauth/callback', :site => 'https://api.example.com/', :auth_scheme => :request_body) do |builder| + it "adds the redirect_uri param to the auth_code token exchange request" do + client = described_class.new("abc", "def", redirect_uri: "https://site.com/oauth/callback", site: "https://api.example.com/", auth_scheme: :request_body) do |builder| builder.adapter :test do |stub| - stub.post('/oauth/token', auth_code_params.merge('redirect_uri' => 'https://site.com/oauth/callback')) do - [200, {'Content-Type' => 'application/json'}, '{"access_token":"token"}'] + stub.post("/oauth/token", auth_code_params.merge("redirect_uri" => "https://site.com/oauth/callback")) do + [200, {"Content-Type" => "application/json"}, '{"access_token":"token"}'] end end end - client.auth_code.get_token('code') + client.auth_code.get_token("code") end end - describe 'custom headers' do - context 'string key headers' do - it 'adds the custom headers to request' do - client = described_class.new('abc', 'def', :site => 'https://api.example.com/', :auth_scheme => :request_body) do |builder| + describe "custom headers" do + context "string key headers" do + it "adds the custom headers to request" do + client = described_class.new("abc", "def", site: "https://api.example.com/", auth_scheme: :request_body) do |builder| builder.adapter :test do |stub| - stub.post('/oauth/token') do |env| - expect(env.request_headers).to include({'CustomHeader' => 'CustomHeader'}) - [200, {'Content-Type' => 'application/json'}, '{"access_token":"token"}'] + stub.post("/oauth/token") do |env| + expect(env.request_headers).to include("CustomHeader" => "CustomHeader") + [200, {"Content-Type" => "application/json"}, '{"access_token":"token"}'] end end end - header_params = {'headers' => { 'CustomHeader' => 'CustomHeader' }} - client.auth_code.get_token('code', header_params) + header_params = {"headers" => {"CustomHeader" => "CustomHeader"}} + client.auth_code.get_token("code", header_params) end end - context 'symbol key headers' do - it 'adds the custom headers to request' do - client = described_class.new('abc', 'def', :site => 'https://api.example.com/', :auth_scheme => :request_body) do |builder| + context "symbol key headers" do + it "adds the custom headers to request" do + client = described_class.new("abc", "def", site: "https://api.example.com/", auth_scheme: :request_body) do |builder| builder.adapter :test do |stub| - stub.post('/oauth/token') do |env| - expect(env.request_headers).to include({'CustomHeader' => 'CustomHeader'}) - [200, {'Content-Type' => 'application/json'}, '{"access_token":"token"}'] + stub.post("/oauth/token") do |env| + expect(env.request_headers).to include("CustomHeader" => "CustomHeader") + [200, {"Content-Type" => "application/json"}, '{"access_token":"token"}'] end end end - header_params = {headers: { 'CustomHeader' => 'CustomHeader' }} - client.auth_code.get_token('code', header_params) + header_params = {headers: {"CustomHeader" => "CustomHeader"}} + client.auth_code.get_token("code", header_params) end end - context 'string key custom headers with basic auth' do - it 'adds the custom headers to request' do - client = described_class.new('abc', 'def', :site => 'https://api.example.com/') do |builder| + context "string key custom headers with basic auth" do + it "adds the custom headers to request" do + client = described_class.new("abc", "def", site: "https://api.example.com/") do |builder| builder.adapter :test do |stub| - stub.post('/oauth/token') do |env| - expect(env.request_headers).to include({'CustomHeader' => 'CustomHeader'}) - [200, {'Content-Type' => 'application/json'}, '{"access_token":"token"}'] + stub.post("/oauth/token") do |env| + expect(env.request_headers).to include("CustomHeader" => "CustomHeader") + [200, {"Content-Type" => "application/json"}, '{"access_token":"token"}'] end end end - header_params = {'headers' => { 'CustomHeader' => 'CustomHeader' }} - client.auth_code.get_token('code', header_params) + header_params = {"headers" => {"CustomHeader" => "CustomHeader"}} + client.auth_code.get_token("code", header_params) end end - context 'symbol key custom headers with basic auth' do - it 'adds the custom headers to request' do - client = described_class.new('abc', 'def', :site => 'https://api.example.com/') do |builder| + context "symbol key custom headers with basic auth" do + it "adds the custom headers to request" do + client = described_class.new("abc", "def", site: "https://api.example.com/") do |builder| builder.adapter :test do |stub| - stub.post('/oauth/token') do |env| - expect(env.request_headers).to include({'CustomHeader' => 'CustomHeader'}) - [200, {'Content-Type' => 'application/json'}, '{"access_token":"token"}'] + stub.post("/oauth/token") do |env| + expect(env.request_headers).to include("CustomHeader" => "CustomHeader") + [200, {"Content-Type" => "application/json"}, '{"access_token":"token"}'] end end end - header_params = {headers: { 'CustomHeader' => 'CustomHeader' }} - client.auth_code.get_token('code', header_params) + header_params = {headers: {"CustomHeader" => "CustomHeader"}} + client.auth_code.get_token("code", header_params) end end end end - describe '#connection' do - context 'when debugging' do - include_context 'with stubbed env' + describe "#connection" do + context "when debugging" do before do - stub_env('OAUTH_DEBUG' => debug_value) + stub_const("OAuth2::OAUTH_DEBUG", debug_value) end - context 'when OAUTH_DEBUG=true' do - let(:debug_value) { 'true' } - it 'smoothly handles successive requests' do + context "when OAUTH_DEBUG=true" do + let(:debug_value) { true } + + it "smoothly handles successive requests" do silence_all do # first request (always goes smoothly) - subject.request(:get, '/success') + subject.request(:get, "/success") end expect do # second request (used to throw Faraday::RackBuilder::StackLocked) - subject.request(:get, '/success') + subject.request(:get, "/success") end.not_to raise_error end - it 'prints both request and response bodies to STDOUT' do + + it "prints both request and response bodies to STDOUT" do printed = capture(:stdout) do - subject.request(:get, '/success') - subject.request(:get, '/reflect', :body => 'this is magical') + subject.request(:get, "/success") + subject.request(:get, "/reflect", body: "this is magical") end - expect(printed).to match 'request: GET https://api.example.com/success' - expect(printed).to match 'response: Content-Type:' - expect(printed).to match 'response: yay' - expect(printed).to match 'request: this is magical' - expect(printed).to match 'response: this is magical' + expect(printed).to match "request: GET https://api.example.com/success" + expect(printed).to match "response: Content-Type:" + expect(printed).to match "response: yay" + expect(printed).to match "request: this is magical" + expect(printed).to match "response: this is magical" end end - context 'when OAUTH_DEBUG=false' do - let(:debug_value) { 'false' } - it 'smoothly handles successive requests' do + context "when OAUTH_DEBUG=false" do + let(:debug_value) { false } + + it "smoothly handles successive requests" do silence_all do # first request (always goes smoothly) - subject.request(:get, '/success') + subject.request(:get, "/success") end expect do # second request (used to throw Faraday::RackBuilder::StackLocked) - subject.request(:get, '/success') + subject.request(:get, "/success") end.not_to raise_error end - it 'prints nothing to STDOUT' do + + it "prints nothing to STDOUT" do printed = capture(:stdout) do - subject.request(:get, '/success') - subject.request(:get, '/reflect', :body => 'this is magical') + subject.request(:get, "/success") + subject.request(:get, "/reflect", body: "this is magical") end - expect(printed).to eq '' + expect(printed).to eq "" end end end end - describe '#request' do - it 'works with a null response body' do - expect(subject.request(:get, 'empty_get').body).to eq('') - end - - it 'returns on a successful response' do - response = subject.request(:get, '/success') - expect(response.body).to eq('yay') - expect(response.status).to eq(200) - expect(response.headers).to eq('Content-Type' => 'text/awesome') - end - - context 'when OAUTH_DEBUG=true and logger is set to log to /dev/null' do - around do |example| - begin - original = ENV['OAUTH_DEBUG'] - ENV['OAUTH_DEBUG'] = 'true' - - original_logger = subject.options[:logger] - subject.options[:logger] = Logger.new('/dev/null') + describe "#authorize_url" do + subject { instance.authorize_url(https://github.com/params) } - example.call - ensure - subject.options[:logger] = original_logger + context "when space included" do + let(:params) do + {scope: "email profile"} + end - if original.nil? - ENV.delete('OAUTH_DEBUG') - else - ENV['OAUTH_DEBUG'] = original - end + # This doesn't happen on Faraday v0, since it isn't an option until Faraday v1.0.0 + it "encoded as %20" do + if Faraday::VERSION >= "1.0.0" + expect(subject).to include "email%20profile" + else + expect(subject).to include "email+profile" end end + end + end - it 'will not log anything to standard out if logger is overridden to use /dev/null' do - output = capture(:stdout) do - subject.request(:get, '/success') - end + describe "#request" do + it "works with a null response body" do + expect(subject.request(:get, "empty_get").body).to eq("") + end - expect(output).to be_empty - end + it "returns on a successful response" do + response = subject.request(:get, "/success") + expect(response.body).to eq("yay") + expect(response.status).to eq(200) + expect(response.headers).to eq("Content-Type" => "text/awesome") end - context 'with ENV' do - include_context 'with stubbed env' - context 'when OAUTH_DEBUG=true' do - before do - stub_env('OAUTH_DEBUG' => 'true') - end - it 'outputs to $stdout when OAUTH_DEBUG=true' do - output = capture(:stdout) do - subject.request(:get, '/success') - end - logs = [ - 'request: GET https://api.example.com/success', - 'response: Status 200', - 'response: Content-Type: "text/awesome"' - ] - expect(output).to include(*logs) + context "when silence_extra_tokens_warning=false" do + before do + stub_const("OAuth2::OAUTH_DEBUG", true) + end + + it "outputs to $stdout when OAUTH_DEBUG=true" do + output = capture(:stdout) do + subject.request(:get, "/success") end + logs = [ + "request: GET https://api.example.com/success", + "response: Status 200", + 'response: Content-Type: "text/awesome"', + ] + expect(output).to include(*logs) end end - it 'posts a body' do - response = subject.request(:post, '/reflect', :body => 'foo=bar') - expect(response.body).to eq('foo=bar') + it "posts a body" do + response = subject.request(:post, "/reflect", body: "foo=bar") + expect(response.body).to eq("foo=bar") end - it 'follows redirects properly' do - response = subject.request(:get, '/redirect') - expect(response.body).to eq('yay') + it "follows redirects properly" do + response = subject.request(:get, "/redirect") + expect(response.body).to eq("yay") expect(response.status).to eq(200) - expect(response.headers).to eq('Content-Type' => 'text/awesome') + expect(response.headers).to eq("Content-Type" => "text/awesome") + expect(response.response.env.url.to_s).to eq("https://api.example.com/success") end - it 'redirects using GET on a 303' do - response = subject.request(:post, '/redirect', :body => 'foo=bar') + it "redirects using GET on a 303" do + response = subject.request(:post, "/redirect", body: "foo=bar") expect(response.body).to be_empty expect(response.status).to eq(200) + expect(response.response.env.url.to_s).to eq("https://api.example.com/reflect") end - it 'obeys the :max_redirects option' do + it "raises an error if a redirect has no Location header" do + expect { subject.request(:get, "/redirect_no_loc") }.to raise_error(OAuth2::Error, "Got 302 status code, but no Location header was present") + end + + it "obeys the :max_redirects option" do max_redirects = subject.options[:max_redirects] subject.options[:max_redirects] = 0 - response = subject.request(:get, '/redirect') + response = subject.request(:get, "/redirect") expect(response.status).to eq(302) subject.options[:max_redirects] = max_redirects end - it 'returns if raise_errors is false' do + it "returns if raise_errors is false" do subject.options[:raise_errors] = false - response = subject.request(:get, '/unauthorized') + response = subject.request(:get, "/unauthorized") expect(response.status).to eq(401) - expect(response.headers).to eq('Content-Type' => 'application/json') + expect(response.headers).to eq("Content-Type" => "application/json") end %w[/unauthorized /conflict /error /different_encoding /ascii_8bit_encoding].each do |error_path| it "raises OAuth2::Error on error response to path #{error_path}" do + pending_for(engine: "jruby", reason: "https://github.com/jruby/jruby/issues/4921") if error_path == "/different_encoding" expect { subject.request(:get, error_path) }.to raise_error(OAuth2::Error) end end - it 're-encodes response body in the error message' do - expect { subject.request(:get, '/ascii_8bit_encoding') }.to raise_error do |ex| + it "re-encodes response body in the error message" do + expect { subject.request(:get, "/ascii_8bit_encoding") }.to raise_error do |ex| expect(ex.message).to eq("invalid_request: é\n{\"error\":\"invalid_request\",\"error_description\":\"��\"}") - expect(ex.message.encoding.name).to eq('UTF-8') + expect(ex.message.encoding.name).to eq("UTF-8") end end - it 'parses OAuth2 standard error response' do - begin - subject.request(:get, '/unauthorized') - rescue StandardError => e - expect(e.code).to eq(error_value) - expect(e.description).to eq(error_description_value) - expect(e.to_s).to match(/#{error_value}/) - expect(e.to_s).to match(/#{error_description_value}/) + it "parses OAuth2 standard error response" do + expect { subject.request(:get, "/unauthorized") }.to raise_error do |ex| + expect(ex.code).to eq(error_value) + expect(ex.description).to eq(error_description_value) + expect(ex.to_s).to match(/#{error_value}/) + expect(ex.to_s).to match(/#{error_description_value}/) end end - it 'provides the response in the Exception' do - begin - subject.request(:get, '/error') - rescue StandardError => e - expect(e.response).to be_a(OAuth2::Response) - expect(e.to_s).to match(/unknown error/) + it "provides the response in the Exception" do + expect { subject.request(:get, "/error") }.to raise_error do |ex| + expect(ex.response).not_to be_nil + expect(ex.to_s).to match(/unknown error/) + end + end + + it "informs about unhandled status code" do + expect { subject.request(:get, "/unhandled_status") }.to raise_error do |ex| + expect(ex.response).not_to be_nil + expect(ex.to_s).to match(/Unhandled status code value of 600/) + end + end + + context "when errors are raised by Faraday" do + let(:connection) { instance_double(Faraday::Connection, build_url: double) } + + before do + allow(connection).to( + receive(:run_request).and_raise(faraday_exception), + ) + allow(subject).to receive(:connection).and_return(connection) # rubocop:disable RSpec/SubjectStub + end + + shared_examples "failed connection handler" do + it "rescues the exception" do + expect { subject.request(:get, "/redirect") }.to raise_error do |e| + expect(e.class).to eq(expected_exception) + expect(e.message).to eq(faraday_exception.message) + end + end + end + + context "with Faraday::ConnectionFailed" do + let(:faraday_exception) { Faraday::ConnectionFailed.new("fail") } + let(:expected_exception) { OAuth2::ConnectionError } + + it_behaves_like "failed connection handler" + end + + context "with Faraday::TimeoutError" do + let(:faraday_exception) { Faraday::TimeoutError.new("timeout") } + let(:expected_exception) { OAuth2::TimeoutError } + + it_behaves_like "failed connection handler" + end + end + + context "when snaky: true" do + subject(:response_body) do + response = instance.request(:post, "/reflect", **req_options) + response.body + end + + let(:req_options) { + { + headers: {"Content-Type" => "application/json"}, + body: {foo: "bar"}, + snaky: true, + } + } + + it "body a body" do + expect(response_body).to eq({foo: "bar"}) + end + + it "body is a standard hash" do + expect(response_body).to be_a(Hash) + expect(response_body).not_to be_a(SnakyHash::StringKeyed) + expect(response_body).not_to be_a(SnakyHash::SymbolKeyed) end end end - describe '#get_token' do - it 'returns a configured AccessToken' do + describe "#get_token" do + it "returns a configured AccessToken" do client = stubbed_client do |stub| - stub.post('/oauth/token') do - [200, {'Content-Type' => 'application/json'}, MultiJson.encode('access_token' => 'the-token')] + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] end end token = client.get_token({}) expect(token).to be_a OAuth2::AccessToken - expect(token.token).to eq('the-token') + expect(token.token).to eq("the-token") + end + + it "works with a standard Hash if keys are correct" do + client = stubbed_client do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] + end + end + + token = client.get_token({snaky_hash_klass: Hash}) + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") end - it 'authenticates with request parameters' do - client = stubbed_client(:auth_scheme => :request_body) do |stub| - stub.post('/oauth/token', 'client_id' => 'abc', 'client_secret' => 'def') do |env| - [200, {'Content-Type' => 'application/json'}, MultiJson.encode('access_token' => 'the-token')] + context "when parse: :automatic" do + it "returns a configured AccessToken" do + client = stubbed_client do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] + end + end + + token = client.get_token(parse: :automatic) + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + end + end + + context "when parse: :xml but response is JSON" do + it "returns a configured AccessToken" do + client = stubbed_client do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] + end + end + + expect { client.get_token(parse: :xml) }.to raise_error(MultiXml::ParseError) + end + end + + context "when parse is fuzzed" do + it "returns a configured AccessToken" do + client = stubbed_client do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] + end + end + + token = client.get_token(parse: "random") + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + end + end + + context "when parse is correct" do + it "returns a configured AccessToken" do + client = stubbed_client do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] + end + end + + token = client.get_token(parse: :json) + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + end + end + + context "when snaky" do + subject(:token) do + client = stubbed_client(options) do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, response_body] + end + end + + client.get_token(params, access_token_opts) + end + + let(:options) { {raise_errors: false} } + let(:access_token_opts) { {} } + let(:response_body) { JSON.dump("access_token" => "the-token") } + + context "when falsy" do + let(:params) { {snaky: false} } + + context "when response is underscored" do + context "without token_name" do + it "returns a configured AccessToken" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed.to_h).to eq("access_token" => "the-token") + end + + it "parsed is a Hash" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).not_to be_a(SnakyHash::StringKeyed) + end + end + + context "with token_name" do + let(:access_token_opts) { {token_name: "access_token"} } + + it "returns a configured AccessToken" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed.to_h).to eq("access_token" => "the-token") + end + + it "parsed is a Hash" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).not_to be_a(SnakyHash::StringKeyed) + end + + context "with alternate token named" do + let(:access_token_opts) { {token_name: "banana_face"} } + let(:response_body) { JSON.dump("banana_face" => "the-token") } + + it "parsed is a Hash" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).not_to be_a(SnakyHash::StringKeyed) + end + + it "returns a snake-cased key" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed.to_h).to eq("banana_face" => "the-token") + end + end + end + end + + context "when response is camelcased" do + let(:access_token_opts) { {token_name: "accessToken"} } + let(:response_body) { JSON.dump("accessToken" => "the-token") } + + context "without token_name" do + it "parsed is a Hash" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).not_to be_a(SnakyHash::StringKeyed) + end + + it "returns a configured AccessToken" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + parsed_h = token.response.parsed.to_h + expect(parsed_h).to eq("accessToken" => "the-token") + expect(parsed_h).to be_a(Hash) + expect(parsed_h).not_to be_a(SnakyHash::StringKeyed) + end + end + + context "with token_name" do + let(:access_token_opts) { {token_name: "accessToken"} } + + it "returns a configured AccessToken" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + parsed_h = token.response.parsed.to_h + expect(parsed_h).to eq("accessToken" => "the-token") + expect(parsed_h).to be_a(Hash) + expect(parsed_h).not_to be_a(SnakyHash::StringKeyed) + end + + it "parsed is a Hash" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).not_to be_a(SnakyHash::StringKeyed) + end + + context "with alternate token name" do + let(:access_token_opts) { {token_name: "bananaFace"} } + let(:response_body) { JSON.dump("bananaFace" => "the-token") } + + it "parsed is a Hash" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).not_to be_a(SnakyHash::StringKeyed) + end + + it "returns a snake-cased key" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + parsed_h = token.response.parsed.to_h + expect(parsed_h).to eq("bananaFace" => "the-token") + expect(parsed_h).to be_a(Hash) + expect(parsed_h).not_to be_a(SnakyHash::StringKeyed) + end + end + end + end + end + + context "when truthy" do + let(:params) { {snaky: true} } + + context "when response is snake-cased" do + context "with token_name" do + let(:access_token_opts) { {token_name: "access_token"} } + + it "parsed is a SnakyHash::StringKeyed" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).to be_a(SnakyHash::StringKeyed) + end + + it "returns a snake-cased key" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed.to_h).to eq("access_token" => "the-token") + end + + context "with alternate token named" do + let(:access_token_opts) { {token_name: "banana_face"} } + let(:response_body) { JSON.dump("banana_face" => "the-token") } + + it "parsed is a SnakyHash::StringKeyed" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).to be_a(SnakyHash::StringKeyed) + end + + it "returns a snake-cased key" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed.to_h).to eq("banana_face" => "the-token") + end + end + end + + context "without token_name" do + it "returns a configured AccessToken" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed.to_h).to eq("access_token" => "the-token") + end + + it "parsed is a SnakyHash::StringKeyed" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).to be_a(SnakyHash::StringKeyed) + end + end + end + + context "when response is camel-cased" do + let(:response_body) { JSON.dump("accessToken" => "the-token") } + + context "with token_name" do + let(:access_token_opts) { {token_name: "accessToken"} } + + it "parsed is a SnakyHash::StringKeyed, and token is found" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).to be_a(SnakyHash::StringKeyed) + end + + it "returns a snake-cased key" do + expect(token).to be_a OAuth2::AccessToken + expect(token.response.parsed.to_h).to eq("access_token" => "the-token") + end + + context "with alternate snaky token named" do + let(:access_token_opts) { {token_name: "banana_butter_cake"} } + let(:response_body) { JSON.dump("banana-butterCake" => "the-token") } + + it "parsed is a SnakyHash::StringKeyed" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).to be_a(SnakyHash::StringKeyed) + end + + it "returns a snake-cased key" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed.to_h).to eq("banana_butter_cake" => "the-token") + end + end + end + + context "without token_name" do + it "parsed is a SnakyHash::StringKeyed" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed).to be_a(Hash) + expect(token.response.parsed).to be_a(SnakyHash::StringKeyed) + end + + it "returns a snake-cased key" do + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + expect(token.response.parsed.to_h).to eq("access_token" => "the-token") + end + end + end + end + end + + it "authenticates with request parameters" do + client = stubbed_client(auth_scheme: :request_body) do |stub| + stub.post("/oauth/token", "client_id" => "abc", "client_secret" => "def") do |_env| + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] end end client.get_token({}) end - it 'authenticates with Basic auth' do - client = stubbed_client(:auth_scheme => :basic_auth) do |stub| - stub.post('/oauth/token') do |env| - raise Faraday::Adapter::Test::Stubs::NotFound unless env[:request_headers]['Authorization'] == OAuth2::Authenticator.encode_basic_auth('abc', 'def') - [200, {'Content-Type' => 'application/json'}, MultiJson.encode('access_token' => 'the-token')] + it "authenticates with Basic auth" do + client = stubbed_client(auth_scheme: :basic_auth) do |stub| + stub.post("/oauth/token") do |env| + raise Faraday::Adapter::Test::Stubs::NotFound unless env[:request_headers]["Authorization"] == OAuth2::Authenticator.encode_basic_auth("abc", "def") + + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] end end client.get_token({}) end - it 'sets the response object on the access token' do + it "authenticates with JSON" do + client = stubbed_client(auth_scheme: :basic_auth) do |stub| + stub.post("/oauth/token") do |env| + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] + end + end + client.get_token(headers: {"Content-Type" => "application/json"}) + end + + it "sets the response object on the access token" do client = stubbed_client do |stub| - stub.post('/oauth/token') do - [200, {'Content-Type' => 'application/json'}, MultiJson.encode('access_token' => 'the-token')] + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] end end token = client.get_token({}) expect(token.response).to be_a OAuth2::Response - expect(token.response.parsed).to eq('access_token' => 'the-token') + expect(token.response.parsed).to eq("access_token" => "the-token") end - context 'when the :raise_errors flag is set to false' do - context 'when the request body is nil' do - it 'returns a nil :access_token' do - client = stubbed_client(:raise_errors => false) do |stub| - stub.post('/oauth/token') do - [500, {'Content-Type' => 'application/json'}, nil] + context "when the :raise_errors flag is set to false" do + let(:body) { nil } + let(:status_code) { 500 } + let(:content_type) { "application/json" } + let(:client) do + stubbed_client(raise_errors: false) do |stub| + stub.post("/oauth/token") do + [status_code, {"Content-Type" => content_type}, body] + end + end + end + + context "when the request body is nil" do + subject(:get_token) { client.get_token({}) } + + it "does not raise error" do + block_is_expected { get_token }.not_to raise_error + end + + context "when extract_access_token raises an exception" do + let(:status_code) { 200 } + let(:extract_proc) { proc { |client, hash| raise ArgumentError } } + + it "returns a nil :access_token" do + expect(client.get_token({}, {}, extract_proc)).to be_nil + end + end + end + + context "when the request body is empty" do + subject(:get_token) { client.get_token({}) } + + let(:body) { "" } + + it "does not raise error" do + block_is_expected { get_token }.not_to raise_error + end + + context "when extract_access_token raises an exception" do + let(:status_code) { 200 } + let(:extract_proc) { proc { |client, hash| raise ArgumentError } } + + it "returns a nil :access_token" do + expect(client.get_token({}, {}, extract_proc)).to be_nil + end + end + end + + context "when the request body is not valid JSON" do + subject(:get_token) { client.get_token({}) } + + let(:body) { "BLOOP" } + + it "raises error" do + block_is_expected { get_token }.to raise_error(JSON::ParserError, /unexpected.*'BLOOP'/) + end + + context "when extract_access_token raises an exception" do + let(:status_code) { 200 } + let(:extract_proc) { proc { |client, hash| raise ArgumentError } } + + it "returns a nil :access_token" do + expect(client.get_token({}, {}, extract_proc)).to be_nil + end + end + end + + context "when status code is 200" do + let(:status_code) { 200 } + + context "when the request body is not nil" do + let(:body) { JSON.dump("access_token" => "the-token") } + + it "returns the parsed :access_token from body" do + token = client.get_token({}) + expect(token.response).to be_a OAuth2::Response + expect(token.response.parsed).to eq("access_token" => "the-token") + end + end + + context "when Content-Type is not JSON" do + let(:content_type) { "text/plain" } + let(:body) { "hello world" } + + it "returns the parsed :access_token from body" do + expect(client.get_token({})).to be_nil + end + end + end + end + + describe "with custom access_token_class option" do + let(:options) { {access_token_class: CustomAccessToken} } + let(:payload) { {"custom_token" => "the-token"} } + let(:content_type) { "application/json" } + let(:client) do + stubbed_client(options) do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => content_type}, JSON.dump(payload)] + end + end + end + + before do + custom_class = Class.new(OAuth2::AccessToken) do + attr_accessor :response + + def self.from_hash(client, hash) + new(client, hash.delete("custom_token")) + end + + def self.contains_token?(hash) + hash.key?("custom_token") + end + end + + stub_const("CustomAccessToken", custom_class) + end + + it "returns the parsed :custom_token from body" do + client.get_token({}) + end + + context "when the :raise_errors flag is set to true" do + let(:options) { {access_token_class: CustomAccessToken, raise_errors: true} } + let(:payload) { {} } + + it "raises an error" do + expect { client.get_token({}) }.to raise_error(OAuth2::Error) + end + + context "when the legacy extract_access_token" do + let(:extract_access_token) do + proc do |client, hash| + token = hash["data"]["access_token"] + OAuth2::AccessToken.new(client, token, hash) end end + let(:options) { {raise_errors: true} } + let(:payload) { {} } + + it "raises an error" do + expect { client.get_token({}, {}, extract_access_token) }.to raise_error(OAuth2::Error) + end + end + end + + context "when status code is 200" do + let(:status_code) { 200 } + + context "when the request body is blank" do + let(:payload) { {} } + + it "raises an error" do + expect { client.get_token({}) }.to raise_error(OAuth2::Error) + end + end + + context "when Content-Type is not JSON" do + let(:content_type) { "text/plain" } + let(:body) { "hello world" } + + it "raises an error" do + expect { client.get_token({}) }.to raise_error(OAuth2::Error) + end + end + end + + context "when access token instance responds to response=" do + let(:options) { {access_token_class: CustomAccessToken, raise_errors: false} } - expect(client.get_token({})).to eq(nil) + it "sets response" do + expect(client.get_token({}).response).to be_a(OAuth2::Response) end end - context 'when the request body is not nil' do - it 'returns the parsed :access_token from body' do - client = stubbed_client do |stub| - stub.post('/oauth/token') do - [200, {'Content-Type' => 'application/json'}, MultiJson.encode('access_token' => 'the-token')] + context "when request has a block" do + subject(:request) do + client.get_token({}) do |req| + raise "Block is executing" + end + end + + let(:options) { {access_token_class: CustomAccessToken, raise_errors: false} } + + it "sets response" do + block_is_expected.to raise_error("Block is executing") + end + end + end + + describe "abnormal custom access_token_class option" do + let(:payload) { {"custom_token" => "the-token"} } + let(:content_type) { "application/json" } + let(:client) do + stubbed_client(options) do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => content_type}, JSON.dump(payload)] + end + end + end + + before do + custom_class = Class.new do + def initialize(client, hash) + end + + def self.from_hash(client, hash) + new(client, hash.delete("custom_token")) + end + + def self.contains_token?(hash) + hash.key?("custom_token") + end + end + + stub_const("StrangeAccessToken", custom_class) + end + + context "when the :raise_errors flag is set to true" do + let(:options) { {access_token_class: StrangeAccessToken, raise_errors: true} } + let(:payload) { {} } + + it "raises an error" do + expect { client.get_token({}) }.to raise_error(OAuth2::Error) + end + end + + context "when access token instance does not responds to response=" do + let(:options) { {access_token_class: StrangeAccessToken} } + let(:payload) { {"custom_token" => "the-token"} } + + it "sets response" do + token_access = client.get_token({}) + expect(token_access).to be_a(StrangeAccessToken) + expect(token_access).not_to respond_to(:response=) + expect(token_access).not_to respond_to(:response) + end + end + + context "when request has a block" do + subject(:request) do + client.get_token({}) do |req| + raise "Block is executing" + end + end + + let(:options) { {access_token_class: StrangeAccessToken} } + + it "sets response" do + block_is_expected.to raise_error("Block is executing") + end + end + end + + describe "with extract_access_token option" do + let(:client) do + stubbed_client(extract_access_token: extract_access_token) do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, JSON.dump("data" => {"access_token" => "the-token"})] + end + end + end + + let(:extract_access_token) do + proc do |client, hash| + token = hash["data"]["access_token"] + OAuth2::AccessToken.new(client, token, hash) + end + end + + it "returns a configured AccessToken" do + token = client.get_token({}) + expect(token).to be_a OAuth2::AccessToken + expect(token.token).to eq("the-token") + end + + context "with deprecation" do + subject(:printed) do + capture(:stderr) do + client.get_token({}) + end + end + + it "warns on STDERR" do + msg = <<-MSG.lstrip + OAuth2::Client#initialize argument `extract_access_token` will be removed in oauth2 v3. Refactor to use `access_token_class`. + MSG + expect(printed).to eq(msg) + end + + context "on request" do + subject(:printed) do + capture(:stderr) do + client.get_token({}, {}, extract_access_token) + end + end + + let(:client) do + stubbed_client do |stub| + stub.post("/oauth/token") do + [200, {"Content-Type" => "application/json"}, JSON.dump("data" => {"access_token" => "the-token"})] + end end end - token = client.get_token({}) - expect(token.response).to be_a OAuth2::Response - expect(token.response.parsed).to eq('access_token' => 'the-token') + it "warns on STDERR" do + msg = <<-MSG.lstrip + OAuth2::Client#get_token argument `extract_access_token` will be removed in oauth2 v3. Refactor to use `access_token_class` on #initialize. + MSG + expect(printed).to eq(msg) + end + end + end + end + + it "forwards given token parameters" do + client = stubbed_client(auth_scheme: :request_body) do |stub| + stub.post("/oauth/token", "arbitrary" => "parameter", "client_id" => "abc", "client_secret" => "def") do |_env| + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] end end + expect { + client.get_token({"arbitrary" => "parameter"}) # rubocop:disable Style/BracesAroundHashParameters + }.not_to raise_error end - it 'forwards given token parameters' do - client = stubbed_client(:auth_scheme => :request_body) do |stub| - stub.post('/oauth/token', 'arbitrary' => 'parameter', 'client_id' => 'abc', 'client_secret' => 'def') do |env| - [200, {'Content-Type' => 'application/json'}, MultiJson.encode('access_token' => 'the-token')] + context "when token_method is set to post_with_query_string" do + it "uses the http post method and passes parameters in the query string" do + client = stubbed_client(token_method: :post_with_query_string) do |stub| + stub.post("/oauth/token?state=abc123") do |_env| + [200, {"Content-Type" => "application/json"}, JSON.dump("access_token" => "the-token")] + end end + expect { + client.get_token({"state" => "abc123"}) # rubocop:disable Style/BracesAroundHashParameters + }.not_to raise_error + end + end + end + + describe "#revoke_token" do + let(:token) { "banana-foster" } + + context "with token string" do + it "makes request with token param" do + expect { + instance.revoke_token(token) + }.not_to raise_error + end + + it "has status 200" do + expect(instance.revoke_token(token).status).to eq(200) + end + end + + context "with token_type_hint" do + it "makes request with token_type_hint param" do + expect { + instance.revoke_token(token, "access_token") + }.not_to raise_error + end + + it "has status 200" do + expect(instance.revoke_token(token, "access_token").status).to eq(200) + end + end + + context "with additional params" do + it "merges additional params" do + expect { + instance.revoke_token(token, nil, extra: "param") + }.not_to raise_error + end + + it "submits params in request body" do + client = stubbed_client do |stub| + stub.post("/oauth/revoke") do |req| + expect(req.body[:token]).to eq(token) + expect(req.params).to be_empty + + [200, {"Content-Type" => "application/json"}, ""] + end + end + + client.revoke_token(token, "access_token", token_method: :post) + end + + it "has status 200" do + expect(instance.revoke_token(token, nil, extra: "param").status).to eq(200) end - client.get_token('arbitrary' => 'parameter') end - def stubbed_client(params = {}, &stubs) - params = {:site => 'https://api.example.com/'}.merge(params) - OAuth2::Client.new('abc', 'def', params) do |builder| - builder.adapter :test, &stubs + context "with block" do + it "passes block to request" do + expect { + instance.revoke_token(token) do |_req| + puts "Hello from the other side" + end + }.not_to raise_error + end + + it "has status 200" do + expect( + instance.revoke_token(token) do |_req| + puts "Hello there" + end.status, + ).to eq(200) + end + + it "executes block" do + @apple = 0 + instance.revoke_token(token) do |_req| + @apple += 1 + end + expect(@apple).to eq(1) end end end - it 'instantiates an AuthCode strategy with this client' do - expect(subject.auth_code).to be_kind_of(OAuth2::Strategy::AuthCode) + it "instantiates an HTTP Method with this client" do + expect(subject.http_method).to be_a(Symbol) + end + + it "instantiates an AuthCode strategy with this client" do + expect(subject.auth_code).to be_a(OAuth2::Strategy::AuthCode) end - it 'instantiates an Implicit strategy with this client' do - expect(subject.implicit).to be_kind_of(OAuth2::Strategy::Implicit) + it "instantiates an Implicit strategy with this client" do + expect(subject.implicit).to be_a(OAuth2::Strategy::Implicit) end - context 'with SSL options' do + context "with SSL options" do subject do - cli = described_class.new('abc', 'def', :site => 'https://api.example.com/', :ssl => {:ca_file => 'foo.pem'}) - cli.connection.build do |b| + cli = described_class.new("abc", "def", site: "https://api.example.com/", ssl: {ca_file: "foo.pem"}) + cli.connection = Faraday.new(cli.site, cli.options[:connection_opts]) do |b| b.adapter :test end cli end - it 'passes the SSL options along to Faraday::Connection#ssl' do - expect(subject.connection.ssl.fetch(:ca_file)).to eq('foo.pem') + it "passes the SSL options along to Faraday::Connection#ssl" do + expect(subject.connection.ssl.fetch(:ca_file)).to eq("foo.pem") end end - context 'without a connection-configuration block' do + context "without a connection-configuration block" do subject do - described_class.new('abc', 'def', :site => 'https://api.example.com/') + described_class.new("abc", "def", site: "https://api.example.com/") end - it 'applies default faraday middleware to the connection' do + it "applies default faraday middleware to the connection" do expect(subject.connection.builder.handlers).to include(Faraday::Request::UrlEncoded) end end + + describe "#inspect" do + it "filters out the @secret value" do + expect(subject.inspect).to include("@secret=[FILTERED]") + end + end + + context "when using Faraday::FlatParamsEncoder" do + before do + skip("Faraday::FlatParamsEncoder not available in this Faraday version") unless defined?(Faraday::FlatParamsEncoder) + end + + it "does not discard repeated params and encodes them as flat keys" do + client = stubbed_client(connection_opts: {request: {params_encoder: Faraday::FlatParamsEncoder}}) do |stub| + stub.get("/v1/orders") do |env| + # Query string should contain two repeated filter keys with encoded operators + qs = env.url.query.to_s + expect(qs).to include("filter=order.clientCreatedTime%3E1445006997000") + expect(qs).to include("filter=order.clientCreatedTime%3C1445611797000") + # Ensure both occurrences exist (not collapsed) + expect(qs.scan(/\bfilter=/).size).to be >= 2 + [200, {"Content-Type" => "application/json"}, JSON.dump({ok: true})] + end + end + + token = OAuth2::AccessToken.new(client, "token123") + token.get( + "/v1/orders", + params: { + filter: [ + "order.clientCreatedTime>1445006997000", + "order.clientCreatedTime<1445611797000", + ], + }, + ) + end + end + + def stubbed_client(params = {}, &stubs) + params = {site: "https://api.example.com/"}.merge(params) + OAuth2::Client.new("abc", "def", params) do |builder| + builder.adapter :test, &stubs + end + end end diff --git a/spec/oauth2/error_spec.rb b/spec/oauth2/error_spec.rb index b38ac93d..281d93f8 100644 --- a/spec/oauth2/error_spec.rb +++ b/spec/oauth2/error_spec.rb @@ -1,158 +1,652 @@ -# encoding: UTF-8 +# encoding: utf-8 +# frozen_string_literal: true + +class StirredHash < Hash + def to_str + '{"hello":"� Cool � StirredHash"}' + end +end + +class XmledString < String + XML = ' + + +� Cool � XmledString + + +' + def to_str + XML + end +end RSpec.describe OAuth2::Error do - let(:subject) { described_class.new(response) } + subject { described_class.new(response) } + let(:response) do raw_response = Faraday::Response.new( - :status => 418, - :response_headers => response_headers, - :body => response_body + status: 418, + response_headers: response_headers, + body: response_body, ) OAuth2::Response.new(raw_response) end - let(:response_headers) { {'Content-Type' => 'application/json'} } - let(:response_body) { {:text => 'Coffee brewing failed'}.to_json } + let(:response_headers) { {"Content-Type" => "application/json"} } + let(:response_body) { {text: "Coffee brewing failed"}.to_json } - it 'sets the response object to #response on self' do + it "sets the response object to #response on self" do error = described_class.new(response) expect(error.response).to equal(response) end - describe 'attr_readers' do - it 'has code' do + describe "attr_readers" do + it "has code" do expect(subject).to respond_to(:code) end - it 'has description' do + it "has description" do expect(subject).to respond_to(:description) end - it 'has response' do + it "has response" do expect(subject).to respond_to(:response) end end - context 'when the response is parseable as a hash' do + context "when the response is parsed" do let(:response_body) { response_hash.to_json } - let(:response_hash) { {:text => 'Coffee brewing failed'} } + let(:response_hash) { {text: "Coffee brewing failed"} } - context 'when the response has an error and error_description' do + context "when the response has an error and error_description" do before do - response_hash[:error_description] = 'Short and stout' - response_hash[:error] = 'i_am_a_teapot' + response_hash["error_description"] = "Short and stout" + response_hash["error"] = "i_am_a_teapot" + end + + it "sets the code attribute" do + expect(subject.code).to eq("i_am_a_teapot") end - it 'prepends to the error message with a return character' do + it "sets the description attribute" do + expect(subject.description).to eq("Short and stout") + end + + it "prepends to the error message with a return character" do expect(subject.message.each_line.to_a).to eq( [ - 'i_am_a_teapot: Short and stout' + "\n", + "i_am_a_teapot: Short and stout\n", '{"text":"Coffee brewing failed","error_description":"Short and stout","error":"i_am_a_teapot"}', + ], + ) + end + + context "when the response needs to be encoded" do + let(:response_body) { JSON.dump(response_hash).force_encoding("ASCII-8BIT") } + + context "with invalid characters present" do + before do + response_body.gsub!("stout", "\255 invalid \255") + end + + it "replaces them" do + encoding = {reason: "encoding isn't working right on JRuby"} + skip_for(encoding.merge(engine: "jruby")) + # See https://bibwild.wordpress.com/2013/03/12/removing-illegal-bytes-for-encoding-in-ruby-1-9-strings/ + + raise "Invalid characters not replaced" unless subject.message.include?("� invalid �") + # This will fail if {:invalid => replace} is not passed into `encode` + end + end + + context "with undefined characters present" do + before do + response_hash["error_description"] += ": 'A magical voyage of tea 🍵'" + end + + it "replaces them" do + raise "Undefined characters not replaced" unless subject.message.include?("tea �") + # This will fail if {:undef => replace} is not passed into `encode` + end + end + end + + context "when the response is not an encodable thing" do + let(:response_headers) { {"Content-Type" => "who knows"} } + let(:response_body) { {text: "Coffee brewing failed"} } + + before do + expect(response_body).not_to respond_to(:encode) + # i.e. a Ruby hash + end + + it "does not try to encode the message string" do + expect(subject.message).to eq(response_body.to_s) + end + end + + context "when using :json parser with non-encodable data" do + let(:response_headers) { {"Content-Type" => "application/hal+json"} } + let(:response_body) do + StirredHash[ + "_links": { + "self": {"href": "/orders/523"}, + "warehouse": {"href": "/warehouse/56"}, + "invoice": {"href": "/invoices/873"}, + }, + "currency": "USD", + "status": "shipped", + "total": 10.20, ] + end + + before do + expect(response_body).not_to respond_to(:force_encoding) + expect(response_body).to respond_to(:to_str) + end + + it "does not force encode the message" do + expect(subject.message).to eq('{"hello":"� Cool � StirredHash"}') + end + end + + context "when using :xml parser" do + let(:response_headers) { {"Content-Type" => "text/xml"} } + let(:response_body) do + XmledString.new(XmledString::XML) + end + + before do + expect(response_body).to respond_to(:to_str) + end + + it "parses the XML" do + expect(subject.message).to eq(XmledString::XML) + end + end + + context "when using :xml parser with non-String-like thing" do + let(:response_headers) { {"Content-Type" => "text/xml"} } + let(:response_body) { {hello: :world} } + + before do + expect(response_body).not_to respond_to(:to_str) + end + + it "just returns the thing if it can" do + expect(subject.message).to eq({hello: :world}.to_s) + end + end + end + + it "sets the code attribute to nil" do + expect(subject.code).to be_nil + end + + it "sets the description attribute" do + expect(subject.description).to be_nil + end + + context "when there is no error description" do + before do + expect(response_hash).not_to have_key("error") + expect(response_hash).not_to have_key("error_description") + end + + it "does not prepend anything to the message" do + expect(subject.message.lines.count).to eq(1) + expect(subject.message).to eq '{"text":"Coffee brewing failed"}' + end + + it "does not set code" do + expect(subject.code).to be_nil + end + + it "does not set description" do + expect(subject.description).to be_nil + end + end + + context "when there is code (error)" do + before do + response_hash["error_description"] = "Short and stout" + response_hash["error"] = "i_am_a_teapot" + response_hash["status"] = "418" + end + + it "prepends to the error message with a return character" do + expect(subject.message.each_line.to_a).to eq( + [ + "i_am_a_teapot: Short and stout\n", + { + "text": "Coffee brewing failed", + "error_description": "Short and stout", + "error": "i_am_a_teapot", + "status": "418", + }.to_json, + ], ) end - context 'when the response needs to be encoded' do - let(:response_body) { MultiJson.encode(response_hash).force_encoding('ASCII-8BIT') } + context "when the response needs to be encoded" do + let(:response_body) { JSON.dump(response_hash).force_encoding("ASCII-8BIT") } - context 'with invalid characters present' do + context "with invalid characters present" do before do - response_body.gsub!('stout', "\255 invalid \255") + response_body.gsub!("stout", "\255 invalid \255") end - it 'replaces them' do + it "replaces them" do # The skip can be removed once support for < 2.1 is dropped. - encoding = {:reason => 'encode/scrub only works as of Ruby 2.1'} - skip_for(encoding.merge(:engine => 'ruby', :versions => %w[1.8.7 1.9.3 2.0.0])) - skip_for(encoding.merge(:engine => 'jruby')) + encoding = {reason: "encode/scrub only works as of Ruby 2.1"} + skip_for(encoding.merge(engine: "jruby")) # See https://bibwild.wordpress.com/2013/03/12/removing-illegal-bytes-for-encoding-in-ruby-1-9-strings/ - raise 'Invalid characters not replaced' unless subject.message.include?('� invalid �') + raise "Invalid characters not replaced" unless subject.message.include?("� invalid �") # This will fail if {:invalid => replace} is not passed into `encode` end end - context 'with undefined characters present' do + context "with undefined characters present" do before do - response_hash[:error_description] << ": 'A magical voyage of tea 🍵'" + response_hash["error_description"] += ": 'A magical voyage of tea 🍵'" end - it 'replaces them' do - raise 'Undefined characters not replaced' unless subject.message.include?('tea �') + it "replaces them" do + raise "Undefined characters not replaced" unless subject.message.include?("tea �") # This will fail if {:undef => replace} is not passed into `encode` end end end - context 'when the response is not an encodable thing' do - let(:response_headers) { {'Content-Type' => 'who knows'} } - let(:response_body) { {:text => 'Coffee brewing failed'} } + context "when the response is not an encodable thing" do + let(:response_headers) { {"Content-Type" => "who knows"} } + let(:response_body) { {text: "Coffee brewing failed"} } before do expect(response_body).not_to respond_to(:encode) # i.e. a Ruby hash end - it 'does not try to encode the message string' do + it "does not try to encode the message string" do expect(subject.message).to eq(response_body.to_s) end end - it 'sets the code attribute' do - expect(subject.code).to eq('i_am_a_teapot') + it "sets the code attribute" do + expect(subject.code).to eq("i_am_a_teapot") end - it 'sets the description attribute' do - expect(subject.description).to eq('Short and stout') + it "sets the description attribute" do + expect(subject.description).to eq("Short and stout") end end - context 'when there is no error description' do + context "when there is code (error) but no error_description" do before do - expect(response_hash).not_to have_key(:error) - expect(response_hash).not_to have_key(:error_description) + response_hash.delete("error_description") + response_hash["error"] = "i_am_a_teapot" + response_hash["status"] = "418" end - it 'does not prepend anything to the message' do + it "prepends to the error message with a return character" do + expect(subject.message.each_line.to_a).to eq( + [ + "i_am_a_teapot: \n", + { + "text": "Coffee brewing failed", + "error": "i_am_a_teapot", + "status": "418", + }.to_json, + ], + ) + end + + context "when the response needs to be encoded" do + let(:response_body) { JSON.dump(response_hash).force_encoding("ASCII-8BIT") } + + context "with invalid characters present" do + before do + response_body.gsub!("brewing", "\255 invalid \255") + end + + it "replaces them" do + # The skip can be removed once support for < 2.1 is dropped. + encoding = {reason: "encode/scrub only works as of Ruby 2.1"} + skip_for(encoding.merge(engine: "jruby")) + # See https://bibwild.wordpress.com/2013/03/12/removing-illegal-bytes-for-encoding-in-ruby-1-9-strings/ + + raise "Invalid characters not replaced" unless subject.message.include?("� invalid �") + # This will fail if {:invalid => replace} is not passed into `encode` + end + end + end + + context "when the response is not an encodable thing" do + let(:response_headers) { {"Content-Type" => "who knows"} } + let(:response_body) { {text: "Coffee brewing failed"} } + + before do + expect(response_body).not_to respond_to(:encode) + # i.e. a Ruby hash + end + + it "does not try to encode the message string" do + expect(subject.message).to eq(response_body.to_s) + end + end + + it "sets the code attribute from error" do + expect(subject.code).to eq("i_am_a_teapot") + end + + it "does not set the description attribute" do + expect(subject.description).to be_nil + end + end + + context "when there is error_description but no code (error)" do + before do + response_hash["error_description"] = "Short and stout" + response_hash.delete("error") + end + + it "prepends to the error message with a return character" do + expect(subject.message.each_line.to_a).to eq( + [ + "Short and stout\n", + { + "text": "Coffee brewing failed", + "error_description": "Short and stout", + }.to_json, + ], + ) + end + + context "when the response needs to be encoded" do + let(:response_body) { JSON.dump(response_hash).force_encoding("ASCII-8BIT") } + + context "with invalid characters present" do + before do + response_body.gsub!("stout", "\255 invalid \255") + end + + it "replaces them" do + # The skip can be removed once support for < 2.1 is dropped. + encoding = {reason: "encode/scrub only works as of Ruby 2.1"} + skip_for(encoding.merge(engine: "jruby")) + # See https://bibwild.wordpress.com/2013/03/12/removing-illegal-bytes-for-encoding-in-ruby-1-9-strings/ + + raise "Invalid characters not replaced" unless subject.message.include?("� invalid �") + # This will fail if {:invalid => replace} is not passed into `encode` + end + end + + context "with undefined characters present" do + before do + response_hash["error_description"] += ": 'A magical voyage of tea 🍵'" + end + + it "replaces them" do + raise "Undefined characters not replaced" unless subject.message.include?("tea �") + # This will fail if {:undef => replace} is not passed into `encode` + end + end + end + + context "when the response is not an encodable thing" do + let(:response_headers) { {"Content-Type" => "who knows"} } + let(:response_body) { {text: "Coffee brewing failed"} } + + before do + expect(response_body).not_to respond_to(:encode) + # i.e. a Ruby hash + end + + it "does not try to encode the message string" do + expect(subject.message).to eq(response_body.to_s) + end + end + + it "sets the code attribute" do + expect(subject.code).to be_nil + end + + it "sets the description attribute" do + expect(subject.description).to eq("Short and stout") + end + end + end + + context "when the response is simple hash, not parsed" do + subject { described_class.new(response_hash) } + + let(:response_hash) { {text: "Coffee brewing failed"} } + + it "sets the code attribute to nil" do + expect(subject.code).to be_nil + end + + it "sets the description attribute" do + expect(subject.description).to be_nil + end + + context "when the response has an error and error_description" do + before do + response_hash["error_description"] = "Short and stout" + response_hash["error"] = "i_am_a_teapot" + end + + it "sets the code attribute" do + expect(subject.code).to eq("i_am_a_teapot") + end + + it "sets the description attribute" do + expect(subject.description).to eq("Short and stout") + end + + it "prepends to the error message with a return character" do + expect(subject.message.each_line.to_a).to eq( + [ + "i_am_a_teapot: Short and stout\n", + {:text => "Coffee brewing failed", "error_description" => "Short and stout", "error" => "i_am_a_teapot"}.to_s, + ], + ) + end + + context "when using :xml parser with non-String-like thing" do + let(:response_headers) { {"Content-Type" => "text/xml"} } + let(:response_hash) { {hello: :world} } + + before do + expect(response_hash).not_to respond_to(:to_str) + end + + it "just returns whatever it can" do + expect(subject.message.each_line.to_a).to eq( + [ + "i_am_a_teapot: Short and stout\n", + {:hello => :world, "error_description" => "Short and stout", "error" => "i_am_a_teapot"}.to_s, + ], + ) + end + end + end + + context "when using :xml parser with non-String-like thing" do + let(:response_headers) { {"Content-Type" => "text/xml"} } + let(:response_hash) { {hello: :world} } + + before do + expect(response_hash).not_to respond_to(:to_str) + end + + it "just returns the thing if it can" do + expect(subject.message).to eq({hello: :world}.to_s) + end + end + + context "when there is no error description" do + before do + expect(response_hash).not_to have_key("error") + expect(response_hash).not_to have_key("error_description") + end + + it "does not prepend anything to the message" do expect(subject.message.lines.count).to eq(1) - expect(subject.message).to eq '{"text":"Coffee brewing failed"}' + expect(subject.message).to eq({text: "Coffee brewing failed"}.to_s) end - it 'does not set code' do + it "does not set code" do expect(subject.code).to be_nil end - it 'does not set description' do + it "does not set description" do + expect(subject.description).to be_nil + end + end + + context "when there is code (error)" do + before do + response_hash["error_description"] = "Short and stout" + response_hash["error"] = "i_am_a_teapot" + response_hash["status"] = "418" + end + + it "prepends to the error message with a return character" do + expect(subject.message.each_line.to_a).to eq( + [ + "i_am_a_teapot: Short and stout\n", + {:text => "Coffee brewing failed", "error_description" => "Short and stout", "error" => "i_am_a_teapot", "status" => "418"}.to_s, + ], + ) + end + + it "sets the code attribute" do + expect(subject.code).to eq("i_am_a_teapot") + end + + it "sets the description attribute" do + expect(subject.description).to eq("Short and stout") + end + end + + context "when there is code (error) but no error_description" do + before do + response_hash.delete("error_description") + response_hash["error"] = "i_am_a_teapot" + response_hash["status"] = "418" + end + + it "sets the code attribute from error" do + expect(subject.code).to eq("i_am_a_teapot") + end + + it "does not set the description attribute" do expect(subject.description).to be_nil end + + it "prepends to the error message with a return character" do + expect(subject.message.each_line.to_a).to eq( + [ + "i_am_a_teapot: \n", + {:text => "Coffee brewing failed", "error" => "i_am_a_teapot", "status" => "418"}.to_s, + ], + ) + end + end + + context "when there is error_description but no code (error)" do + before do + response_hash["error_description"] = "Short and stout" + response_hash.delete("error") + end + + it "prepends to the error message with a return character" do + expect(subject.message.each_line.to_a).to eq( + [ + "Short and stout\n", + {:text => "Coffee brewing failed", "error_description" => "Short and stout"}.to_s, + ], + ) + end + + context "when the response is not an encodable thing" do + let(:response_headers) { {"Content-Type" => "who knows"} } + let(:response_hash) { {text: "Coffee brewing failed"} } + + before do + expect(response_hash).not_to respond_to(:encode) + # i.e. a Ruby hash + end + + it "does not try to encode the message string" do + expect(subject.message.each_line.to_a).to eq( + [ + "Short and stout\n", + {:text => "Coffee brewing failed", "error_description" => "Short and stout"}.to_s, + ], + ) + end + end + + it "sets the code attribute" do + expect(subject.code).to be_nil + end + + it "sets the description attribute" do + expect(subject.description).to eq("Short and stout") + end + end + end + + context "when the response is not a hash, not parsed" do + subject { described_class.new(response_thing) } + + let(:response_thing) { [200, "Success"] } + + it "sets the code attribute to nil" do + expect(subject.code).to be_nil + end + + it "sets the description attribute" do + expect(subject.description).to be_nil + end + + it "sets the body attribute" do + expect(subject.body).to eq(response_thing) + end + + it "sets the response attribute" do + expect(subject.response).to eq(response_thing) end end - context 'when the response does not parse to a hash' do - let(:response_headers) { {'Content-Type' => 'text/html'} } - let(:response_body) { 'Hello, I am a teapot' } + context "when the response does not parse to a hash" do + let(:response_headers) { {"Content-Type" => "text/html"} } + let(:response_body) { "Hello, I am a teapot" } before do expect(response.parsed).not_to be_a(Hash) end - it 'does not do anything to the message' do + it "does not do anything to the message" do expect(subject.message.lines.count).to eq(1) expect(subject.message).to eq(response_body) end - it 'does not set code' do + it "does not set code" do expect(subject.code).to be_nil end - it 'does not set description' do + it "does not set description" do expect(subject.description).to be_nil end end - describe 'parsing json' do - it 'does not blow up' do + describe "parsing json" do + it "does not blow up" do expect { subject.to_json }.not_to raise_error expect { subject.response.to_json }.not_to raise_error end diff --git a/spec/oauth2/mac_token_spec.rb b/spec/oauth2/mac_token_spec.rb deleted file mode 100644 index b82b7ad2..00000000 --- a/spec/oauth2/mac_token_spec.rb +++ /dev/null @@ -1,117 +0,0 @@ -RSpec.describe MACToken do - subject { described_class.new(client, token, 'abc123') } - - let(:token) { 'monkey' } - let(:client) do - Client.new('abc', 'def', :site => 'https://api.example.com/') do |builder| - builder.request :url_encoded - builder.adapter :test do |stub| - VERBS.each do |verb| - stub.send(verb, '/token/header') { |env| [200, {}, env[:request_headers]['Authorization']] } - end - end - end - end - - describe '#initialize' do - it 'assigns client and token' do - expect(subject.client).to eq(client) - expect(subject.token).to eq(token) - end - - it 'assigns secret' do - expect(subject.secret).to eq('abc123') - end - - it 'defaults algorithm to hmac-sha-256' do - expect(subject.algorithm).to be_instance_of(OpenSSL::Digest::SHA256) - end - - it 'handles hmac-sha-256' do - mac = described_class.new(client, token, 'abc123', :algorithm => 'hmac-sha-256') - expect(mac.algorithm).to be_instance_of(OpenSSL::Digest::SHA256) - end - - it 'handles hmac-sha-1' do - mac = described_class.new(client, token, 'abc123', :algorithm => 'hmac-sha-1') - expect(mac.algorithm).to be_instance_of(OpenSSL::Digest::SHA1) - end - - it 'raises on improper algorithm' do - expect { described_class.new(client, token, 'abc123', :algorithm => 'invalid-sha') }.to raise_error(ArgumentError) - end - end - - describe '#request' do - VERBS.each do |verb| - it "sends the token in the Authorization header for a #{verb.to_s.upcase} request" do - expect(subject.post('/token/header').body).to include("MAC id=\"#{token}\"") - end - end - end - - describe '#header' do - it 'does not generate the same header twice' do - header = subject.header('get', 'https://www.example.com/hello') - duplicate_header = subject.header('get', 'https://www.example.com/hello') - - expect(header).not_to eq(duplicate_header) - end - - it 'generates the proper format' do - header = subject.header('get', 'https://www.example.com/hello?a=1') - expect(header).to match(/MAC id="#{token}", ts="[0-9]+", nonce="[^"]+", mac="[^"]+"/) - end - - it 'passes ArgumentError with an invalid url' do - expect { subject.header('get', 'this-is-not-valid') }.to raise_error(ArgumentError) - end - - it 'passes URI::InvalidURIError through' do - expect { subject.header('get', nil) }.to raise_error(URI::InvalidURIError) - end - end - - describe '#signature' do - it 'generates properly' do - signature = subject.signature(0, 'random-string', 'get', URI('https://www.google.com/')) - expect(signature).to eq('rMDjVA3VJj3v1OmxM29QQljKia6msl5rjN83x3bZmi8=') - end - end - - describe '#headers' do - it 'is an empty hash' do - expect(subject.headers).to eq({}) - end - end - - describe '.from_access_token' do - subject { described_class.from_access_token(access_token, 'hello') } - - let(:access_token) do - AccessToken.new( - client, token, - :expires_at => 1, - :expires_in => 1, - :refresh_token => 'abc', - :random => 1 - ) - end - - it 'initializes client, token, and secret properly' do - expect(subject.client).to eq(client) - expect(subject.token).to eq(token) - expect(subject.secret).to eq('hello') - end - - it 'initializes configuration options' do - expect(subject.expires_at).to eq(1) - expect(subject.expires_in).to eq(1) - expect(subject.refresh_token).to eq('abc') - end - - it 'initializes params' do - expect(subject.params).to eq(:random => 1) - end - end -end diff --git a/spec/oauth2/response_spec.rb b/spec/oauth2/response_spec.rb index 5078d1f5..2a1c42be 100644 --- a/spec/oauth2/response_spec.rb +++ b/spec/oauth2/response_spec.rb @@ -1,234 +1,724 @@ +# frozen_string_literal: true + RSpec.describe OAuth2::Response do - let(:raw_response) { Faraday::Response.new(:status => status, :response_headers => headers, :body => body) } - let(:status) { 200 } - let(:headers) { {'foo' => 'bar'} } - let(:body) { 'foo' } + subject { described_class.new(raw_response) } - let(:subject) { described_class.new(raw_response) } + let(:raw_response) { Faraday::Response.new(status: status, response_headers: headers, body: body) } + let(:status) { 200 } + let(:headers) { {"foo" => "bar"} } + let(:body) { "foo" } - describe '#initialize' do - it 'returns the status, headers and body' do + describe "#initialize" do + it "returns the status, headers and body" do expect(subject.headers).to eq(headers) expect(subject.status).to eq(status) expect(subject.body).to eq(body) end end - describe '.register_parser' do + describe ".register_parser" do let(:response) do - double('response', :headers => {'Content-Type' => 'application/foo-bar'}, - :status => 200, - :body => 'baz') + double( + "response", + headers: {"Content-Type" => "application/foo-bar"}, + status: 200, + body: "baz", + ) end before do - described_class.register_parser(:foobar, 'application/foo-bar') do |body| + described_class.register_parser(:foobar, ["application/foo-bar"]) do |body| "foobar #{body}" end end - it 'adds to the content types and parsers' do + it "adds to the content types and parsers" do expect(described_class.send(:class_variable_get, :@@parsers).keys).to include(:foobar) - expect(described_class.send(:class_variable_get, :@@content_types).keys).to include('application/foo-bar') + expect(described_class.send(:class_variable_get, :@@content_types).keys).to include("application/foo-bar") end - it 'is able to parse that content type automatically' do - expect(described_class.new(response).parsed).to eq('foobar baz') + it "is able to parse that content type automatically" do + expect(described_class.new(response).parsed).to eq("foobar baz") end end - describe '#content_type' do - context 'when headers are blank' do + describe "#content_type" do + context "when headers are blank" do let(:headers) { nil } - it 'returns nil' do + it "returns nil" do expect(subject.content_type).to be_nil end end - context 'when content-type is not present' do - let(:headers) { {'a fuzzy' => 'fuzzer'} } + context "when content-type is not present" do + let(:headers) { {"a fuzzy" => "fuzzer"} } - it 'returns empty string' do - expect(subject.content_type).to eq('') + it "returns empty string" do + expect(subject.content_type).to eq("") end end - context 'when content-type is present' do - let(:headers) { {'Content-Type' => 'application/x-www-form-urlencoded'} } + context "when content-type is present" do + let(:headers) { {"Content-Type" => "application/x-www-form-urlencoded"} } - it 'returns the content type header contents' do - expect(subject.content_type).to eq('application/x-www-form-urlencoded') + it "returns the content type header contents" do + expect(subject.content_type).to eq("application/x-www-form-urlencoded") end end end - describe '#parsed' do - it 'parses application/x-www-form-urlencoded body' do - headers = {'Content-Type' => 'application/x-www-form-urlencoded'} - body = 'foo=bar&answer=42' - response = double('response', :headers => headers, :body => body) - subject = described_class.new(response) - expect(subject.parsed.keys.size).to eq(2) - expect(subject.parsed['foo']).to eq('bar') - expect(subject.parsed['answer']).to eq('42') + describe "#parsed" do + subject(:parsed) do + headers = {"Content-Type" => content_type} + response = double("response", headers: headers, body: body) + instance = described_class.new(response) + instance.parsed end - it 'parses application/json body' do - headers = {'Content-Type' => 'application/json'} - body = MultiJson.encode(:foo => 'bar', :answer => 42) - response = double('response', :headers => headers, :body => body) - subject = described_class.new(response) - expect(subject.parsed.keys.size).to eq(2) - expect(subject.parsed['foo']).to eq('bar') - expect(subject.parsed['answer']).to eq(42) + shared_examples_for "parsing JSON-like" do + it "has num keys" do + expect(parsed.keys.size).to eq(6) + end + + it "parses string" do + expect(parsed["foo"]).to eq("bar") + expect(parsed.key("bar")).to eq("foo") + end + + it "parses non-zero number" do + expect(parsed["answer"]).to eq(42) + expect(parsed.key(42)).to eq("answer") + end + + it "parses nil as NilClass" do + expect(parsed["krill"]).to be_nil + expect(parsed.key(nil)).to eq("krill") + end + + it "parses zero as number" do + expect(parsed["zero"]).to eq(0) + expect(parsed.key(0)).to eq("zero") + end + + it "parses false as FalseClass" do + expect(parsed["malign"]).to be(false) + expect(parsed.key(false)).to eq("malign") + end + + it "parses false as TrueClass" do + expect(parsed["shine"]).to be(true) + expect(parsed.key(true)).to eq("shine") + end end - it 'parses alternative application/json extension bodies' do - headers = {'Content-Type' => 'application/hal+json'} - body = MultiJson.encode(:foo => 'bar', :answer => 42) - response = double('response', :headers => headers, :body => body) - subject = described_class.new(response) - expect(subject.parsed.keys.size).to eq(2) - expect(subject.parsed['foo']).to eq('bar') - expect(subject.parsed['answer']).to eq(42) + context "when application/json" do + let(:content_type) { "application/json" } + let(:body) { JSON.dump(foo: "bar", answer: 42, krill: nil, zero: 0, malign: false, shine: true) } + + it_behaves_like "parsing JSON-like" + end + + context "when application/Json" do + let(:content_type) { "application/Json" } + let(:body) { JSON.dump(foo: "bar", answer: 42, krill: nil, zero: 0, malign: false, shine: true) } + + it_behaves_like "parsing JSON-like" end - it 'parses application/vnd.collection+json body' do - headers = {'Content-Type' => 'application/vnd.collection+json'} - body = MultiJson.encode(:collection => {}) - response = double('response', :headers => headers, :body => body) + context "when application/hal+json" do + let(:content_type) { "application/hal+json" } + let(:body) { JSON.dump(foo: "bar", answer: 42, krill: nil, zero: 0, malign: false, shine: true) } + + it_behaves_like "parsing JSON-like" + end + + context "when application/x-www-form-urlencoded" do + let(:content_type) { "application/x-www-form-urlencoded" } + let(:body) { "foo=bar&answer=42&krill=&zero=0&malign=false&shine=true" } + + it "has num keys" do + expect(parsed.keys.size).to eq(6) + end + + it "parses string" do + expect(parsed["foo"]).to eq("bar") + expect(parsed.key("bar")).to eq("foo") + end + + it "parses non-zero number as string" do + expect(parsed["answer"]).to eq("42") + expect(parsed.key("42")).to eq("answer") + end + + it "parses nil as empty string" do + expect(parsed["krill"]).to eq("") + expect(parsed.key("")).to eq("krill") + end + + it "parses zero as string" do + expect(parsed["zero"]).to eq("0") + expect(parsed.key("0")).to eq("zero") + end + + it "parses false as string" do + expect(parsed["malign"]).to eq("false") + expect(parsed.key("false")).to eq("malign") + end + + it "parses true as string" do + expect(parsed["shine"]).to eq("true") + expect(parsed.key("true")).to eq("shine") + end + end + + it "parses application/vnd.collection+json body" do + headers = {"Content-Type" => "application/vnd.collection+json"} + body = JSON.dump(collection: {}) + response = double("response", headers: headers, body: body) subject = described_class.new(response) expect(subject.parsed.keys.size).to eq(1) end - it 'parses application/vnd.api+json body' do - headers = {'Content-Type' => 'application/vnd.api+json'} - body = MultiJson.encode(:collection => {}) - response = double('response', :headers => headers, :body => body) + it "parses application/vnd.api+json body" do + headers = {"Content-Type" => "application/vnd.api+json"} + body = JSON.dump(collection: {}) + response = double("response", headers: headers, body: body) subject = described_class.new(response) expect(subject.parsed.keys.size).to eq(1) end - it "parses application/Json body" do - headers = {'Content-Type' => 'application/Json'} - body = MultiJson.encode(:foo => 'bar', :answer => 42) - response = double('response', :headers => headers, :body => body) - subject = Response.new(response) + it "parses application/problem+json body" do + headers = {"Content-Type" => "application/problem+json"} + body = JSON.dump(type: "https://tools.ietf.org/html/rfc7231#section-6.5.4", title: "Not Found") + response = double("response", headers: headers, body: body) + subject = described_class.new(response) expect(subject.parsed.keys.size).to eq(2) - expect(subject.parsed['foo']).to eq('bar') - expect(subject.parsed['answer']).to eq(42) + expect(subject.parsed["type"]).to eq("https://tools.ietf.org/html/rfc7231#section-6.5.4") + expect(subject.parsed["title"]).to eq("Not Found") end it "doesn't try to parse other content-types" do - headers = {'Content-Type' => 'text/html'} - body = '' + headers = {"Content-Type" => "text/html"} + body = "" - response = double('response', :headers => headers, :body => body) + response = double("response", headers: headers, body: body) - expect(MultiJson).not_to receive(:decode) - expect(MultiJson).not_to receive(:load) + expect(JSON).not_to receive(:parse) expect(Rack::Utils).not_to receive(:parse_query) subject = described_class.new(response) expect(subject.parsed).to be_nil end - it "should snakecase json keys when parsing" do - headers = {'Content-Type' => 'application/json'} - body = MultiJson.encode("accessToken" => 'bar', "MiGever" => "Ani") - response = double('response', :headers => headers, :body => body) - subject = Response.new(response) + it "doesn't parse bodies which have previously been parsed" do + headers = {"Content-Type" => "application/json"} + body = {foo: "bar", answer: 42, krill: nil, zero: 0, malign: false, shine: true} + + response = double("response", headers: headers, body: body) + + expect(JSON).not_to receive(:parse) + expect(Rack::Utils).not_to receive(:parse_query) + + subject = described_class.new(response) + expect(subject.parsed.keys.size).to eq(6) + end + + it "snakecases json keys when parsing" do + headers = {"Content-Type" => "application/json"} + body = JSON.dump("accessToken" => "bar", "MiGever" => "Ani") + response = double("response", headers: headers, body: body) + subject = described_class.new(response) expect(subject.parsed.keys.size).to eq(2) - expect(subject.parsed['access_token']).to eq('bar') - expect(subject.parsed['mi_gever']).to eq("Ani") + expect(subject.parsed["access_token"]).to eq("bar") + expect(subject.parsed["mi_gever"]).to eq("Ani") + end + + context "when not snaky" do + it "does not snakecase json keys when parsing" do + headers = {"Content-Type" => "application/json"} + body = JSON.dump("accessToken" => "bar", "MiGever" => "Ani") + response = double("response", headers: headers, body: body) + subject = described_class.new(response, snaky: false) + expect(subject.parsed.keys.size).to eq(2) + expect(subject.parsed["accessToken"]).to eq("bar") + expect(subject.parsed["MiGever"]).to eq("Ani") + expect(subject.parsed["access_token"]).to be_nil + expect(subject.parsed["mi_gever"]).to be_nil + end end - it 'supports registered parsers with arity == 0; passing nothing' do + it "supports registered parsers with arity == 0; passing nothing" do described_class.register_parser(:arity_0, []) do - 'a-ok' + "a-ok" end - headers = {'Content-Type' => 'text/html'} - body = '' - response = double('response', :headers => headers, :body => body) + headers = {"Content-Type" => "text/html"} + body = "" + response = double("response", headers: headers, body: body) - subject = described_class.new(response, :parse => :arity_0) + subject = described_class.new(response, parse: :arity_0) - expect(subject.parsed).to eq('a-ok') + expect(subject.parsed).to eq("a-ok") end - it 'supports registered parsers with arity == 2; passing body and response' do - headers = {'Content-Type' => 'text/html'} - body = '' - response = double('response', :headers => headers, :body => body) + it "supports registered parsers with arity == 2; passing body and response" do + headers = {"Content-Type" => "text/html"} + body = "" + response = double("response", headers: headers, body: body) described_class.register_parser(:arity_2, []) do |passed_body, passed_response| expect(passed_body).to eq(body) expect(passed_response).to eq(response) - 'a-ok' + "a-ok" end - subject = described_class.new(response, :parse => :arity_2) + subject = described_class.new(response, parse: :arity_2) - expect(subject.parsed).to eq('a-ok') + expect(subject.parsed).to eq("a-ok") end - it 'supports registered parsers with arity > 2; passing body and response' do - headers = {'Content-Type' => 'text/html'} - body = '' - response = double('response', :headers => headers, :body => body) + it "supports registered parsers with arity > 2; passing body and response" do + headers = {"Content-Type" => "text/html"} + body = "" + response = double("response", headers: headers, body: body) described_class.register_parser(:arity_3, []) do |passed_body, passed_response, *args| expect(passed_body).to eq(body) expect(passed_response).to eq(response) expect(args).to eq([]) - 'a-ok' + "a-ok" end - subject = described_class.new(response, :parse => :arity_3) + subject = described_class.new(response, parse: :arity_3) + + expect(subject.parsed).to eq("a-ok") + end + + it "supports directly passed parsers" do + headers = {"Content-Type" => "text/html"} + body = "" + response = double("response", headers: headers, body: body) + + subject = described_class.new(response, parse: -> { "a-ok" }) - expect(subject.parsed).to eq('a-ok') + expect(subject.parsed).to eq("a-ok") end - it 'supports directly passed parsers' do - headers = {'Content-Type' => 'text/html'} - body = '' - response = double('response', :headers => headers, :body => body) + it "supports no parsing" do + headers = {"Content-Type" => "text/html"} + body = "" + response = double("response", headers: headers, body: body) - subject = described_class.new(response, :parse => lambda { 'a-ok' }) + subject = described_class.new(response, parse: false) - expect(subject.parsed).to eq('a-ok') + expect(subject.parsed).to be_nil end end - context 'with xml parser registration' do - it 'tries to load multi_xml and use it' do + context "with xml parser registration" do + it "tries to load multi_xml.rb and use it" do expect(described_class.send(:class_variable_get, :@@parsers)[:xml]).not_to be_nil end - it 'is able to parse xml' do - headers = {'Content-Type' => 'text/xml'} + it "is able to parse xml" do + headers = {"Content-Type" => "text/xml"} body = 'baz' - response = double('response', :headers => headers, :body => body) - expect(described_class.new(response).parsed).to eq('foo' => {'bar' => 'baz'}) + response = double("response", headers: headers, body: body) + expect(described_class.new(response).parsed).to eq("foo" => {"bar" => "baz"}) end - it 'is able to parse application/xml' do - headers = {'Content-Type' => 'application/xml'} + it "is able to parse application/xml" do + headers = {"Content-Type" => "application/xml"} body = 'baz' - response = double('response', :headers => headers, :body => body) - expect(described_class.new(response).parsed).to eq('foo' => {'bar' => 'baz'}) + response = double("response", headers: headers, body: body) + expect(described_class.new(response).parsed).to eq("foo" => {"bar" => "baz"}) end end - describe 'converting to json' do - it 'does not blow up' do + describe "converting to json" do + it "does not blow up" do expect { subject.to_json }.not_to raise_error end end + + describe "with custom vanilla snaky_hash_klass" do + let(:parsed_response) { {"some_key" => "some_value"} } + let(:custom_hash_class) do + Class.new(Hash) + end + + before do + @response = double( + "response", + headers: {"Content-Type" => "application/json"}, + status: 200, + body: parsed_response.to_json, + ) + end + + it "uses the specified hash class when snaky is true" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed).not_to be_a(OAuth2::Response::DEFAULT_OPTIONS[:snaky_hash_klass]) + expect(response.parsed).to eq({"some_key" => "some_value"}) + expect(response.parsed["some_key"]).to eq("some_value") + end + + it "uses the default hash class when snaky_hash_klass is not specified" do + response = described_class.new(@response, parse: :automatic, snaky: true) + expect(response.parsed).not_to be_a(custom_hash_class) + expect(response.parsed).to be_a(OAuth2::Response::DEFAULT_OPTIONS[:snaky_hash_klass]) + end + + it "doesn't convert to any special hash class when snaky is false" do + response = described_class.new(@response, parse: :automatic, snaky: false, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(Hash) + expect(response.parsed).not_to be_a(custom_hash_class) + end + end + + describe "with dump_value & load_value extensions" do + let(:custom_hash_class) do + klass = Class.new(SnakyHash::StringKeyed) do + # Give this hash class `dump` and `load` abilities! + extend SnakyHash::Serializer + + unless instance_methods.include?(:transform_keys) + # Patch our custom Hash to support Ruby < 2.4.2 + def transform_keys! + keys.each do |key| + ref = delete(key) + self[key] = yield(ref) + end + end + + def transform_keys + dup.transform_keys! { |key| yield(key) } + end + end + end + + # Act on the non-hash values as they are dumped to JSON + klass.dump_value_extensions.add(:to_fruit) do |value| + "banana" + end + + # Act on the non-hash values as they are loaded from the JSON dump + klass.load_value_extensions.add(:to_stars) do |value| + "asdf***qwer" + end + + klass + end + + before do + @response = double( + "response", + headers: {"Content-Type" => "application/json"}, + status: 200, + body: parsed_response.to_json, + ) + end + + context "when hash with top-level hashes" do + let(:parsed_response) { {"a-b_c-d_e-F_G-H" => "i-j_k-l_m-n_o-P_Q-R", "arr" => [1, 2, 3]} } + + it "uses the specified hash class when snaky is true" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed).to eq("a_b_c_d_e_f_g_h" => "i-j_k-l_m-n_o-P_Q-R", "arr" => [1, 2, 3]) + expect(response.parsed["a_b_c_d_e_f_g_h"]).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(response.parsed[:a_b_c_d_e_f_g_h]).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(response.parsed.a_b_c_d_e_f_g_h).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(response.parsed["arr"]).to eq([1, 2, 3]) + expect(response.parsed[:arr]).to eq([1, 2, 3]) + expect(response.parsed.arr).to eq([1, 2, 3]) + end + + it "can dump the hash" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed.class.dump_value_extensions.has?(:to_fruit)).to be(true) + dump = custom_hash_class.dump(response.parsed) + expect(dump).to eq("{\"a_b_c_d_e_f_g_h\":\"banana\",\"arr\":[\"banana\",\"banana\",\"banana\"]}") + end + + it "can load the dump, and run extensions on values" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed.class.load_value_extensions.has?(:to_stars)).to be(true) + dump = custom_hash_class.dump(response.parsed) + hydrated = custom_hash_class.load(dump) + expect(hydrated).not_to eq(response.parsed.to_hash) + expect(hydrated).to eq({ + "a_b_c_d_e_f_g_h" => "asdf***qwer", + "arr" => %w[asdf***qwer asdf***qwer asdf***qwer], + }) + expect(hydrated["a_b_c_d_e_f_g_h"]).to eq("asdf***qwer") + expect(hydrated[:a_b_c_d_e_f_g_h]).to eq("asdf***qwer") + expect(hydrated.a_b_c_d_e_f_g_h).to eq("asdf***qwer") + expect(hydrated["arr"]).to eq(%w[asdf***qwer asdf***qwer asdf***qwer]) + expect(hydrated[:arr]).to eq(%w[asdf***qwer asdf***qwer asdf***qwer]) + expect(hydrated.arr).to eq(%w[asdf***qwer asdf***qwer asdf***qwer]) + end + + it "doesn't convert to any special hash class when snaky is false" do + response = described_class.new(@response, parse: :automatic, snaky: false, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(Hash) + expect(response.parsed).not_to be_a(custom_hash_class) + expect(response.parsed).to eq("a-b_c-d_e-F_G-H" => "i-j_k-l_m-n_o-P_Q-R", "arr" => [1, 2, 3]) + expect(response.parsed["a-b_c-d_e-F_G-H"]).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(response.parsed["arr"]).to eq([1, 2, 3]) + end + end + + context "when hash with nested hashes" do + let(:parsed_response) { {"a-b_c-d_e-F_G-H" => {"i-j_k-l_m-n_o-P_Q-R" => "s-t_u-v_w-X_Y-Z"}, "arr" => [1, 2, 3]} } + + it "uses the specified hash class when snaky is true" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed).to eq("a_b_c_d_e_f_g_h" => {"i_j_k_l_m_n_o_p_q_r" => "s-t_u-v_w-X_Y-Z"}, "arr" => [1, 2, 3]) + expect(response.parsed["a_b_c_d_e_f_g_h"]).to eq({"i_j_k_l_m_n_o_p_q_r" => "s-t_u-v_w-X_Y-Z"}) + expect(response.parsed[:a_b_c_d_e_f_g_h]).to eq({"i_j_k_l_m_n_o_p_q_r" => "s-t_u-v_w-X_Y-Z"}) + expect(response.parsed.a_b_c_d_e_f_g_h).to eq({"i_j_k_l_m_n_o_p_q_r" => "s-t_u-v_w-X_Y-Z"}) + expect(response.parsed["arr"]).to eq([1, 2, 3]) + expect(response.parsed[:arr]).to eq([1, 2, 3]) + expect(response.parsed.arr).to eq([1, 2, 3]) + end + + it "can dump the hash" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed.class.dump_value_extensions.has?(:to_fruit)).to be(true) + dump = custom_hash_class.dump(response.parsed) + expect(dump).to eq("{\"a_b_c_d_e_f_g_h\":{\"i_j_k_l_m_n_o_p_q_r\":\"banana\"},\"arr\":[\"banana\",\"banana\",\"banana\"]}") + end + + it "can load the dump, and run extensions on values" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed.class.load_value_extensions.has?(:to_stars)).to be(true) + dump = custom_hash_class.dump(response.parsed) + hydrated = custom_hash_class.load(dump) + expect(hydrated).not_to eq(response.parsed.to_hash) + expect(hydrated).to eq({ + "a_b_c_d_e_f_g_h" => + { + "i_j_k_l_m_n_o_p_q_r" => "asdf***qwer", + }, + "arr" => %w[asdf***qwer asdf***qwer asdf***qwer], + }) + expect(hydrated["a_b_c_d_e_f_g_h"]).to eq({"i_j_k_l_m_n_o_p_q_r" => "asdf***qwer"}) + expect(hydrated[:a_b_c_d_e_f_g_h]).to eq({"i_j_k_l_m_n_o_p_q_r" => "asdf***qwer"}) + expect(hydrated.a_b_c_d_e_f_g_h).to eq({"i_j_k_l_m_n_o_p_q_r" => "asdf***qwer"}) + expect(hydrated["arr"]).to eq(%w[asdf***qwer asdf***qwer asdf***qwer]) + expect(hydrated[:arr]).to eq(%w[asdf***qwer asdf***qwer asdf***qwer]) + expect(hydrated.arr).to eq(%w[asdf***qwer asdf***qwer asdf***qwer]) + end + + it "doesn't convert to any special hash class when snaky is false" do + response = described_class.new(@response, parse: :automatic, snaky: false, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(Hash) + expect(response.parsed).not_to be_a(custom_hash_class) + expect(response.parsed).to eq("a-b_c-d_e-F_G-H" => {"i-j_k-l_m-n_o-P_Q-R" => "s-t_u-v_w-X_Y-Z"}, "arr" => [1, 2, 3]) + expect(response.parsed["a-b_c-d_e-F_G-H"]).to eq({"i-j_k-l_m-n_o-P_Q-R" => "s-t_u-v_w-X_Y-Z"}) + expect(response.parsed["arr"]).to eq([1, 2, 3]) + end + end + end + + describe "with dump_hash & load_hash extensions" do + let(:custom_hash_class) do + klass = Class.new(SnakyHash::StringKeyed) do + # Give this hash class `dump` and `load` abilities! + extend SnakyHash::Serializer + + unless instance_methods.include?(:transform_keys) + # Patch our custom Hash to support Ruby < 2.4.2 + def transform_keys! + keys.each do |key| + ref = delete(key) + self[key] = yield(ref) + end + end + + def transform_keys + dup.transform_keys! { |key| yield(key) } + end + end + end + + # Act on the entire hash as it is prepared for dumping to JSON + klass.dump_hash_extensions.add(:to_cheese) do |value| + if value.is_a?(Hash) + # TODO: Drop this hack when dropping support for Ruby 2.6 + ref = value.transform_keys do |key| + # This is an example tailored to this specific test! + # It is not a generalized solution for anything! + split = key.split("_") + first_word = split[0] + key.sub(first_word, "cheese") + end + # TODO: Drop this hack when dropping support for Ruby <= 2.4 + if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.4.2") + ref + else + puts + klass[ref] + end + else + value + end + end + + # Act on the entire hash as it is loaded from the JSON dump + klass.load_hash_extensions.add(:to_pizza) do |value| + if value.is_a?(Hash) + # TODO: Drop this hack when dropping support for Ruby <= 2.4 + if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new("2.4.2") + value.transform_keys do |key| + # This is an example tailored to this specific test! + # It is not a generalized solution for anything! + split = key.split("_") + last_word = split[-1] + key.sub(last_word, "pizza") + end + else + res = klass.new + value.keys.each_with_object(res) do |key, result| + split = key.split("_") + last_word = split[-1] + new_key = key.sub(last_word, "pizza") + result[new_key] = value[key] + end + res + end + else + value + end + end + + klass + end + + before do + @response = double( + "response", + headers: {"Content-Type" => "application/json"}, + status: 200, + body: parsed_response.to_json, + ) + end + + context "when hash with top-level hashes" do + let(:parsed_response) { {"a-b_c-d_e-F_G-H" => "i-j_k-l_m-n_o-P_Q-R", "arr" => [1, 2, 3]} } + + it "uses the specified hash class when snaky is true" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed).to eq("a_b_c_d_e_f_g_h" => "i-j_k-l_m-n_o-P_Q-R", "arr" => [1, 2, 3]) + expect(response.parsed["a_b_c_d_e_f_g_h"]).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(response.parsed[:a_b_c_d_e_f_g_h]).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(response.parsed.a_b_c_d_e_f_g_h).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(response.parsed["arr"]).to eq([1, 2, 3]) + expect(response.parsed[:arr]).to eq([1, 2, 3]) + expect(response.parsed.arr).to eq([1, 2, 3]) + end + + it "can dump the hash" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed.class.dump_hash_extensions.has?(:to_cheese)).to be(true) + puts "response.parsed: #{response.parsed.inspect} (#{response.parsed})" + dump = custom_hash_class.dump(response.parsed) + expect(dump).to eq("{\"cheese_b_c_d_e_f_g_h\":\"i-j_k-l_m-n_o-P_Q-R\",\"cheese\":[1,2,3]}") + end + + it "can load the dump, and run extensions on values" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed.class.load_hash_extensions.has?(:to_pizza)).to be(true) + dump = custom_hash_class.dump(response.parsed) + hydrated = custom_hash_class.load(dump) + expect(hydrated).not_to eq(response.parsed.to_hash) + expect(hydrated).to eq({ + "cpizzaeese_b_c_d_e_f_g_h" => "i-j_k-l_m-n_o-P_Q-R", + "pizza" => [1, 2, 3], + }) + expect(hydrated["cpizzaeese_b_c_d_e_f_g_h"]).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(hydrated[:cpizzaeese_b_c_d_e_f_g_h]).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(hydrated.cpizzaeese_b_c_d_e_f_g_h).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(hydrated["pizza"]).to eq([1, 2, 3]) + expect(hydrated[:pizza]).to eq([1, 2, 3]) + expect(hydrated.pizza).to eq([1, 2, 3]) + end + + it "doesn't convert to any special hash class when snaky is false" do + response = described_class.new(@response, parse: :automatic, snaky: false, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(Hash) + expect(response.parsed).not_to be_a(custom_hash_class) + expect(response.parsed).to eq("a-b_c-d_e-F_G-H" => "i-j_k-l_m-n_o-P_Q-R", "arr" => [1, 2, 3]) + expect(response.parsed["a-b_c-d_e-F_G-H"]).to eq("i-j_k-l_m-n_o-P_Q-R") + expect(response.parsed["arr"]).to eq([1, 2, 3]) + end + end + + context "when hash with nested hashes" do + let(:parsed_response) { {"a-b_c-d_e-F_G-H" => {"i-j_k-l_m-n_o-P_Q-R" => "s-t_u-v_w-X_Y-Z"}, "arr" => [1, 2, 3]} } + + it "uses the specified hash class when snaky is true" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed).to eq("a_b_c_d_e_f_g_h" => {"i_j_k_l_m_n_o_p_q_r" => "s-t_u-v_w-X_Y-Z"}, "arr" => [1, 2, 3]) + expect(response.parsed["a_b_c_d_e_f_g_h"]).to eq({"i_j_k_l_m_n_o_p_q_r" => "s-t_u-v_w-X_Y-Z"}) + expect(response.parsed[:a_b_c_d_e_f_g_h]).to eq({"i_j_k_l_m_n_o_p_q_r" => "s-t_u-v_w-X_Y-Z"}) + expect(response.parsed.a_b_c_d_e_f_g_h).to eq({"i_j_k_l_m_n_o_p_q_r" => "s-t_u-v_w-X_Y-Z"}) + expect(response.parsed["arr"]).to eq([1, 2, 3]) + expect(response.parsed[:arr]).to eq([1, 2, 3]) + expect(response.parsed.arr).to eq([1, 2, 3]) + end + + it "can dump the hash" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed.class.dump_hash_extensions.has?(:to_cheese)).to be(true) + dump = custom_hash_class.dump(response.parsed) + expect(dump).to eq("{\"cheese_b_c_d_e_f_g_h\":{\"cheese_j_k_l_m_n_o_p_q_r\":\"s-t_u-v_w-X_Y-Z\"},\"cheese\":[1,2,3]}") + end + + it "can load the dump, and run extensions on values" do + response = described_class.new(@response, parse: :automatic, snaky: true, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(custom_hash_class) + expect(response.parsed.class.load_hash_extensions.has?(:to_pizza)).to be(true) + dump = custom_hash_class.dump(response.parsed) + hydrated = custom_hash_class.load(dump) + expect(hydrated).not_to eq(response.parsed.to_hash) + expect(hydrated).to eq({ + "cpizzaeese_b_c_d_e_f_g_h" => {"cheese_j_k_l_m_n_o_p_q_pizza" => "s-t_u-v_w-X_Y-Z"}, + "pizza" => [1, 2, 3], + }) + expect(hydrated["cpizzaeese_b_c_d_e_f_g_h"]).to eq({"cheese_j_k_l_m_n_o_p_q_pizza" => "s-t_u-v_w-X_Y-Z"}) + expect(hydrated[:cpizzaeese_b_c_d_e_f_g_h]).to eq({"cheese_j_k_l_m_n_o_p_q_pizza" => "s-t_u-v_w-X_Y-Z"}) + expect(hydrated.cpizzaeese_b_c_d_e_f_g_h).to eq({"cheese_j_k_l_m_n_o_p_q_pizza" => "s-t_u-v_w-X_Y-Z"}) + expect(hydrated["pizza"]).to eq([1, 2, 3]) + expect(hydrated[:pizza]).to eq([1, 2, 3]) + expect(hydrated.pizza).to eq([1, 2, 3]) + end + + it "doesn't convert to any special hash class when snaky is false" do + response = described_class.new(@response, parse: :automatic, snaky: false, snaky_hash_klass: custom_hash_class) + expect(response.parsed).to be_a(Hash) + expect(response.parsed).not_to be_a(custom_hash_class) + expect(response.parsed).to eq("a-b_c-d_e-F_G-H" => {"i-j_k-l_m-n_o-P_Q-R" => "s-t_u-v_w-X_Y-Z"}, "arr" => [1, 2, 3]) + expect(response.parsed["a-b_c-d_e-F_G-H"]).to eq({"i-j_k-l_m-n_o-P_Q-R" => "s-t_u-v_w-X_Y-Z"}) + expect(response.parsed["arr"]).to eq([1, 2, 3]) + end + end + end end diff --git a/spec/oauth2/snaky_hash_spec.rb b/spec/oauth2/snaky_hash_spec.rb deleted file mode 100644 index 14d4ef66..00000000 --- a/spec/oauth2/snaky_hash_spec.rb +++ /dev/null @@ -1,132 +0,0 @@ -RSpec.describe SnakyHash do - subject { described_class.new } - - describe '.build' do - context 'build from hash' do - subject { described_class.build({ 'AccessToken' => '1' }) } - - it 'create correct snake hash' do - expect(subject).to be_a(described_class) - expect(subject['AccessToken']).to eq('1') - expect(subject['access_token']).to eq('1') - end - end - - context 'build from snake_hash' do - subject do - h = described_class.new - h['AccessToken'] = '1' - - described_class.build(h) - end - - it 'create correct snake hash' do - expect(subject).to be_a(described_class) - expect(subject['AccessToken']).to eq('1') - expect(subject['access_token']).to eq('1') - end - end - end - - describe 'assign and query' do - it 'returns assigned value with camel key' do - subject['AccessToken'] = '1' - - expect(subject['AccessToken']).to eq('1') - expect(subject['access_token']).to eq('1') - end - - it 'returns assigned value with snake key only' do - subject['access_token'] = '1' - - expect(subject['AccessToken']).to eq(nil) - expect(subject['access_token']).to eq('1') - end - - it 'overwrite snake key' do - subject['AccessToken'] = '1' - - expect(subject['AccessToken']).to eq('1') - expect(subject['access_token']).to eq('1') - - subject['access_token'] = '2' - - expect(subject['AccessToken']).to eq('1') - expect(subject['access_token']).to eq('2') - end - end - - describe '#fetch' do - context 'Camel case key' do - subject { described_class.build('AccessToken' => '1') } - - it 'return correct token' do - expect(subject.fetch('https://github.com/access_token')).to eq('1') - end - end - - context 'Camel case key with dowcased first letter' do - subject { described_class.build('accessToken' => '1') } - - it 'return correct token' do - expect(subject.fetch('https://github.com/access_token')).to eq('1') - end - end - - context 'snake case key' do - subject { described_class.build('access_token' => '1') } - - it 'return correct token' do - expect(subject.fetch('https://github.com/access_token')).to eq('1') - end - end - - context 'missing any key' do - subject { described_class.new } - - it 'raise KeyError with key' do - expect { - subject.fetch('https://github.com/access_token') - }.to raise_error(KeyError, /access_token/) - end - - it 'return default value' do - expect(subject.fetch('https://github.com/access_token') {'default'}).to eq('default') - end - end - end - - describe '#key?' do - context 'Camel case key' do - subject { described_class.build('AccessToken' => '1') } - - it 'return true' do - expect(subject.key?('access_token')).to eq(true) - end - end - - context 'Camel case key with dowcased first letter' do - subject { described_class.build('accessToken' => '1') } - - it 'return true' do - expect(subject.key?('access_token')).to eq(true) - end - end - - context 'snake case key' do - subject { described_class.build('access_token' => '1') } - - it 'return true' do - expect(subject.key?('access_token')).to eq(true) - end - end - - context 'missing any key' do - subject { described_class.new } - - it 'return false' do - expect(subject.key?('access_token')).to eq(false) - end - end - end -end diff --git a/spec/oauth2/strategy/assertion_spec.rb b/spec/oauth2/strategy/assertion_spec.rb index fdc04804..d8d3af46 100644 --- a/spec/oauth2/strategy/assertion_spec.rb +++ b/spec/oauth2/strategy/assertion_spec.rb @@ -1,22 +1,26 @@ -require 'jwt' +# frozen_string_literal: true + +require "openssl" +require "jwt" RSpec.describe OAuth2::Strategy::Assertion do - subject { client.assertion } + let(:client_assertion) { client.assertion } let(:client) do - cli = OAuth2::Client.new('abc', 'def', :site => 'http://api.example.com/', :auth_scheme => auth_scheme) - cli.connection.build do |b| + cli = OAuth2::Client.new("abc", "def", site: "http://api.example.com/", auth_scheme: auth_scheme) + cli.connection = Faraday.new(cli.site, cli.options[:connection_opts]) do |b| + b.request :url_encoded b.adapter :test do |stub| - stub.post('/oauth/token') do |token_request| - @request_body = token_request.body + stub.post("/oauth/token") do |token_request| + @request_body = Rack::Utils.parse_nested_query(token_request.body).transform_keys(&:to_sym) case @response_format - when 'formencoded' - [200, {'Content-Type' => 'application/x-www-form-urlencoded'}, 'expires_in=600&access_token=salmon&refresh_token=trout'] - when 'json' - [200, {'Content-Type' => 'application/json'}, '{"expires_in":600,"access_token":"salmon","refresh_token":"trout"}'] + when "formencoded" + [200, {"Content-Type" => "application/x-www-form-urlencoded"}, "expires_in=600&access_token=salmon&refresh_token=trout"] + when "json" + [200, {"Content-Type" => "application/json"}, '{"expires_in":600,"access_token":"salmon","refresh_token":"trout"}'] else - raise 'Please define @response_format to choose a response content type!' + raise "Please define @response_format to choose a response content type!" end end end @@ -26,56 +30,48 @@ let(:auth_scheme) { :request_body } - describe '#authorize_url' do - it 'raises NotImplementedError' do - expect { subject.authorize_url }.to raise_error(NotImplementedError) + describe "#authorize_url" do + it "raises NotImplementedError" do + expect { client_assertion.authorize_url }.to raise_error(NotImplementedError) end end - describe '#get_token' do - let(:algorithm) { 'HS256' } - let(:key) { 'arowana' } + describe "#get_token" do + let(:algorithm) { "HS256" } + let(:key) { "arowana" } let(:timestamp) { Time.now.to_i } let(:claims) do { - :iss => 'carp@example.com', - :scope => 'https://oauth.example.com/auth/flounder', - :aud => 'https://sturgeon.example.com/oauth2/token', - :exp => timestamp + 3600, - :iat => timestamp, - :sub => '12345', - :custom_claim => 'ling cod', + iss: "carp@example.com", + scope: "https://oauth.example.com/auth/flounder", + aud: "https://sturgeon.example.com/oauth2/token", + exp: timestamp + 3600, + iat: timestamp, + sub: "12345", + custom_claim: "ling cod", } end before do - @response_format = 'json' + @response_format = "json" end - describe 'assembling a JWT assertion' do + describe "assembling a JWT assertion" do let(:jwt) do - payload, header = JWT.decode(@request_body[:assertion], key, true, :algorithm => algorithm) - {:payload => payload, :header => header} + payload, header = JWT.decode(@request_body[:assertion], key, true, algorithm: algorithm) + {payload: payload, header: header} end let(:payload) { jwt[:payload] } let(:header) { jwt[:header] } - context 'when encoding as HS256' do - let(:algorithm) { 'HS256' } - let(:key) { 'super_secret!' } - - before do - subject.get_token(claims, :algorithm => algorithm, :key => key) - raise 'No request made!' if @request_body.nil? - end - - it 'indicates HS256 in the header' do + shared_examples_for "encodes the JWT" do + it "indicates algorithm in the header" do expect(header).not_to be_nil - expect(header['alg']).to eq('HS256') + expect(header["alg"]).to eq(algorithm) end - it 'encodes the JWT as HS256' do + it "has claims" do expect(payload).not_to be_nil expect(payload.keys).to match_array(%w[iss scope aud exp iat sub custom_claim]) payload.each do |key, claim| @@ -84,122 +80,161 @@ end end - context 'when encoding as RS256' do - let(:algorithm) { 'RS256' } - let(:key) { OpenSSL::PKey::RSA.new(1024) } + context "when encoding as HS256" do + let(:algorithm) { "HS256" } + let(:key) { "super_secret!" } before do - subject.get_token(claims, :algorithm => algorithm, :key => key) - raise 'No request made!' if @request_body.nil? + client_assertion.get_token(claims, algorithm: algorithm, key: key) + raise "No request made!" if @request_body.nil? end - it 'indicates RS256 in the header' do - expect(header).not_to be_nil - expect(header['alg']).to eq('RS256') + it_behaves_like "encodes the JWT" + + context "with real key" do + let(:key) { "1883be842495c3b58f68ca71fbf1397fbb9ed2fdf8990f8404a25d0a1b995943" } + + it_behaves_like "encodes the JWT" end + end - it 'encodes the JWT as RS256' do - expect(payload).not_to be_nil - expect(payload.keys).to match_array(%w[iss scope aud exp iat sub custom_claim]) - payload.each do |key, claim| - expect(claims[key.to_sym]).to eq(claim) - end + context "when encoding as RS256" do + let(:algorithm) { "RS256" } + let(:key) { OpenSSL::PKey::RSA.new(2048) } + + before do + client_assertion.get_token(claims, algorithm: algorithm, key: key) + raise "No request made!" if @request_body.nil? + end + + it_behaves_like "encodes the JWT" + + context "with private key" do + let(:private_key_file) { "spec/fixtures/RS256/jwtRS256.key" } + let(:password) { "" } + let(:key) { OpenSSL::PKey::RSA.new(File.read(private_key_file), password) } + + it_behaves_like "encodes the JWT" end end - context 'with bad encoding params' do - let(:encoding_opts) { {:algorithm => algorithm, :key => key} } + context "with bad encoding params" do + let(:encoding_opts) { {algorithm: algorithm, key: key} } - describe 'non-supported algorithms' do - let(:algorithm) { 'the blockchain' } - let(:key) { 'machine learning' } + describe "non-supported algorithms" do + let(:algorithm) { "the blockchain" } + let(:key) { "machine learning" } - it 'raises NotImplementedError' do + it "raises JWT::EncodeError" do # this behavior is handled by the JWT gem, but this should make sure it is consistent - expect { subject.get_token(claims, encoding_opts) }.to raise_error(NotImplementedError) + # On old Ruby (versions 2.4 and below) the error raised was different because + # an old version (< v2.4) of the jwt gem gets installed. + if defined?(JWT::VERSION::STRING) && Gem::Version.create(JWT::VERSION::STRING) >= Gem::Version.create("2.4") + expect { client_assertion.get_token(claims, encoding_opts) }.to raise_error(JWT::EncodeError, "Unsupported signing method") + else + expect { client_assertion.get_token(claims, encoding_opts) }.to raise_error(NotImplementedError) + end end end - describe 'of a wrong object type' do - let(:encoding_opts) { 'the cloud' } + describe "of a wrong object type" do + let(:encoding_opts) { "the cloud" } - it 'raises ArgumentError' do - expect { subject.get_token(claims, encoding_opts) }.to raise_error(ArgumentError, /encoding_opts/) + it "raises ArgumentError" do + expect { client_assertion.get_token(claims, encoding_opts) }.to raise_error(ArgumentError, /encoding_opts/) end end - describe 'missing encoding_opts[:algorithm]' do + describe "missing encoding_opts[:algorithm]" do before do encoding_opts.delete(:algorithm) end - it 'raises ArgumentError' do - expect { subject.get_token(claims, encoding_opts) }.to raise_error(ArgumentError, /encoding_opts/) + it "raises ArgumentError" do + expect { client_assertion.get_token(claims, encoding_opts) }.to raise_error(ArgumentError, /encoding_opts/) end end - describe 'missing encoding_opts[:key]' do + describe "missing encoding_opts[:key]" do before do encoding_opts.delete(:key) end - it 'raises ArgumentError' do - expect { subject.get_token(claims, encoding_opts) }.to raise_error(ArgumentError, /encoding_opts/) + it "raises ArgumentError" do + expect { client_assertion.get_token(claims, encoding_opts) }.to raise_error(ArgumentError, /encoding_opts/) + end + end + + context "when including a Key ID (kid)" do + let(:algorithm) { "HS256" } + let(:key) { "new_secret_key" } + let(:kid) { "my_super_secure_key_id_123" } + + before do + client_assertion.get_token(claims, algorithm: algorithm, key: key, kid: kid) + raise "No request made!" if @request_body.nil? + end + + it_behaves_like "encodes the JWT" + + it "includes the kid in the JWT header" do + expect(header).not_to be_nil + expect(header["kid"]).to eq(kid) end end end end - describe 'POST request parameters' do - context 'when using :auth_scheme => :request_body' do + describe "POST request parameters" do + context "when using :auth_scheme => :request_body" do let(:auth_scheme) { :request_body } - it 'includes assertion and grant_type, along with the client parameters' do - subject.get_token(claims, :algorithm => algorithm, :key => key) + it "includes assertion and grant_type, along with the client parameters" do + client_assertion.get_token(claims, algorithm: algorithm, key: key) expect(@request_body).not_to be_nil - expect(@request_body.keys).to match_array([:assertion, :grant_type, 'client_id', 'client_secret']) - expect(@request_body[:grant_type]).to eq('urn:ietf:params:oauth:grant-type:jwt-bearer') + expect(@request_body.keys).to match_array(%i[assertion grant_type client_id client_secret]) + expect(@request_body[:grant_type]).to eq("urn:ietf:params:oauth:grant-type:jwt-bearer") expect(@request_body[:assertion]).to be_a(String) - expect(@request_body['client_id']).to eq('abc') - expect(@request_body['client_secret']).to eq('def') + expect(@request_body[:client_id]).to eq("abc") + expect(@request_body[:client_secret]).to eq("def") end - it 'includes other params via request_options' do - subject.get_token(claims, {:algorithm => algorithm, :key => key}, :scope => 'dover sole') + it "includes other params via request_options" do + client_assertion.get_token(claims, {algorithm: algorithm, key: key}, {scope: "dover sole"}) expect(@request_body).not_to be_nil - expect(@request_body.keys).to match_array([:assertion, :grant_type, :scope, 'client_id', 'client_secret']) - expect(@request_body[:grant_type]).to eq('urn:ietf:params:oauth:grant-type:jwt-bearer') + expect(@request_body.keys).to match_array(%i[assertion grant_type scope client_id client_secret]) + expect(@request_body[:grant_type]).to eq("urn:ietf:params:oauth:grant-type:jwt-bearer") expect(@request_body[:assertion]).to be_a(String) - expect(@request_body[:scope]).to eq('dover sole') - expect(@request_body['client_id']).to eq('abc') - expect(@request_body['client_secret']).to eq('def') + expect(@request_body[:scope]).to eq("dover sole") + expect(@request_body[:client_id]).to eq("abc") + expect(@request_body[:client_secret]).to eq("def") end end - context 'when using :auth_scheme => :basic_auth' do + context "when using :auth_scheme => :basic_auth" do let(:auth_scheme) { :basic_auth } - it 'includes assertion and grant_type by default' do - subject.get_token(claims, :algorithm => algorithm, :key => key) + it "includes assertion and grant_type by default" do + client_assertion.get_token(claims, algorithm: algorithm, key: key) expect(@request_body).not_to be_nil - expect(@request_body.keys).to match_array([:assertion, :grant_type]) - expect(@request_body[:grant_type]).to eq('urn:ietf:params:oauth:grant-type:jwt-bearer') + expect(@request_body.keys).to match_array(%i[assertion grant_type]) + expect(@request_body[:grant_type]).to eq("urn:ietf:params:oauth:grant-type:jwt-bearer") expect(@request_body[:assertion]).to be_a(String) end - it 'includes other params via request_options' do - subject.get_token(claims, {:algorithm => algorithm, :key => key}, :scope => 'dover sole') + it "includes other params via request_options" do + client_assertion.get_token(claims, {algorithm: algorithm, key: key}, {scope: "dover sole"}) expect(@request_body).not_to be_nil - expect(@request_body.keys).to match_array([:assertion, :grant_type, :scope]) - expect(@request_body[:grant_type]).to eq('urn:ietf:params:oauth:grant-type:jwt-bearer') + expect(@request_body.keys).to match_array(%i[assertion grant_type scope]) + expect(@request_body[:grant_type]).to eq("urn:ietf:params:oauth:grant-type:jwt-bearer") expect(@request_body[:assertion]).to be_a(String) - expect(@request_body[:scope]).to eq('dover sole') + expect(@request_body[:scope]).to eq("dover sole") end end end - describe 'returning the response' do - let(:access_token) { subject.get_token(claims, {:algorithm => algorithm, :key => key}, {}, response_opts) } + describe "returning the response" do + let(:access_token) { client_assertion.get_token(claims, {algorithm: algorithm, key: key}, {}, response_opts) } let(:response_opts) { {} } %w[json formencoded].each do |mode| @@ -208,42 +243,42 @@ @response_format = mode end - it 'returns an AccessToken' do - expect(access_token).to be_an(AccessToken) + it "returns an AccessToken" do + expect(access_token).to be_an(OAuth2::AccessToken) end - it 'returns AccessToken with same Client' do + it "returns AccessToken with same Client" do expect(access_token.client).to eq(client) end - it 'returns AccessToken with #token' do - expect(access_token.token).to eq('salmon') + it "returns AccessToken with #token" do + expect(access_token.token).to eq("salmon") end - it 'returns AccessToken with #expires_in' do + it "returns AccessToken with #expires_in" do expect(access_token.expires_in).to eq(600) end - it 'returns AccessToken with #expires_at' do + it "returns AccessToken with #expires_at" do expect(access_token.expires_at).not_to be_nil end - it 'sets AccessToken#refresh_token to nil' do - expect(access_token.refresh_token).to eq(nil) + it "sets AccessToken#refresh_token to nil" do + expect(access_token.refresh_token).to eq("trout") end - context 'with custom response_opts' do - let(:response_opts) { {:custom_token_option => 'mackerel'} } + context "with custom response_opts" do + let(:response_opts) { {"custom_token_option" => "mackerel"} } - it 'passes them into the token params' do + it "passes them into the token params" do expect(access_token.params).to eq(response_opts) end end - context 'when no custom opts are passed in' do + context "when no custom opts are passed in" do let(:response_opts) { {} } - it 'does not set any params by default' do + it "does not set any params by default" do expect(access_token.params).to eq({}) end end diff --git a/spec/oauth2/strategy/auth_code_spec.rb b/spec/oauth2/strategy/auth_code_spec.rb index 72bffe1d..ed3817b4 100644 --- a/spec/oauth2/strategy/auth_code_spec.rb +++ b/spec/oauth2/strategy/auth_code_spec.rb @@ -1,119 +1,133 @@ # encoding: utf-8 +# frozen_string_literal: true RSpec.describe OAuth2::Strategy::AuthCode do subject { client.auth_code } - let(:code) { 'sushi' } - let(:kvform_token) { 'expires_in=600&access_token=salmon&refresh_token=trout&extra_param=steve' } - let(:facebook_token) { kvform_token.gsub('_in', '') } - let(:json_token) { MultiJson.encode(:expires_in => 600, :access_token => 'salmon', :refresh_token => 'trout', :extra_param => 'steve') } - let(:redirect_uri) { 'http://example.com/redirect_uri' } - let(:microsoft_token) { 'id_token=jwt' } + let(:code) { "sushi" } + let(:kvform_token) { "expires_in=600&access_token=salmon&refresh_token=trout&extra_param=steve" } + let(:facebook_token) { kvform_token.gsub("_in", "") } + let(:json_token) { JSON.dump(expires_in: 600, access_token: "salmon", refresh_token: "trout", extra_param: "steve") } + let(:redirect_uri) { "http://example.com/redirect_uri" } + let(:microsoft_token) { "id_token=i_am_MSFT" } let(:client) do - OAuth2::Client.new('abc', 'def', :site => 'http://api.example.com/') do |builder| + OAuth2::Client.new("abc", "def", site: "http://api.example.com/") do |builder| builder.adapter :test do |stub| - stub.get("/oauth/token?client_id=abc&code=#{code}&grant_type=authorization_code") do |env| + stub.get("/oauth/token?client_id=abc&code=#{code}&grant_type=authorization_code") do |_env| case @mode - when 'formencoded' - [200, {'Content-Type' => 'application/x-www-form-urlencoded'}, kvform_token] - when 'json' - [200, {'Content-Type' => 'application/json'}, json_token] - when 'from_facebook' - [200, {'Content-Type' => 'application/x-www-form-urlencoded'}, facebook_token] - when 'from_microsoft' - [200, {'Content-Type' => 'application/x-www-form-urlencoded'}, microsoft_token] + when "formencoded" + [200, {"Content-Type" => "application/x-www-form-urlencoded"}, kvform_token] + when "json" + [200, {"Content-Type" => "application/json"}, json_token] + when "from_facebook" + [200, {"Content-Type" => "application/x-www-form-urlencoded"}, facebook_token] + when "from_microsoft" + [200, {"Content-Type" => "application/x-www-form-urlencoded"}, microsoft_token] + else raise ArgumentError, "Bad @mode: #{@mode}" end end - stub.post('/oauth/token', 'client_id' => 'abc', 'client_secret' => 'def', 'code' => 'sushi', 'grant_type' => 'authorization_code') do |env| + stub.post("/oauth/token", "client_id" => "abc", "client_secret" => "def", "code" => "sushi", "grant_type" => "authorization_code") do |_env| case @mode - when 'formencoded' - [200, {'Content-Type' => 'application/x-www-form-urlencoded'}, kvform_token] - when 'json' - [200, {'Content-Type' => 'application/json'}, json_token] - when 'from_facebook' - [200, {'Content-Type' => 'application/x-www-form-urlencoded'}, facebook_token] + when "formencoded" + [200, {"Content-Type" => "application/x-www-form-urlencoded"}, kvform_token] + when "json" + [200, {"Content-Type" => "application/json"}, json_token] + when "from_facebook" + [200, {"Content-Type" => "application/x-www-form-urlencoded"}, facebook_token] + else raise ArgumentError, "Bad @mode: #{@mode}" end end - stub.post('/oauth/token', 'client_id' => 'abc', 'client_secret' => 'def', 'code' => 'sushi', 'grant_type' => 'authorization_code', 'redirect_uri' => redirect_uri) do |env| - [200, {'Content-Type' => 'application/json'}, json_token] + stub.post("/oauth/token", "client_id" => "abc", "client_secret" => "def", "code" => "sushi", "grant_type" => "authorization_code", "redirect_uri" => redirect_uri) do |_env| + [200, {"Content-Type" => "application/json"}, json_token] end end end end - describe '#authorize_url' do - it 'includes the client_id' do - expect(subject.authorize_url).to include('client_id=abc') + describe "#authorize_url" do + it "includes the client_id" do + expect(subject.authorize_url).to include("client_id=abc") end - it 'includes the type' do - expect(subject.authorize_url).to include('response_type=code') + it "includes the type" do + expect(subject.authorize_url).to include("response_type=code") end - it 'does not include the client_secret' do - expect(subject.authorize_url).not_to include('client_secret=def') + it "does not include the client_secret" do + expect(subject.authorize_url).not_to include("client_secret=def") end - it 'raises an error if the client_secret is passed in' do - expect { subject.authorize_url(https://github.com/:client_secret%20=%3E%20'def') }.to raise_error(ArgumentError) + it "raises an error if the client_secret is passed in" do + expect { subject.authorize_url(https://github.com/client_secret:%20%22def") }.to raise_error(ArgumentError) end - it 'raises an error if the client_secret is passed in with string keys' do - expect { subject.authorize_url('https://github.com/client_secret'%20=%3E%20'def') }.to raise_error(ArgumentError) + it "raises an error if the client_secret is passed in with string keys" do + expect { subject.authorize_url("https://github.com/client_secret%22%20=%3E%20%22def") }.to raise_error(ArgumentError) end - it 'includes passed in options' do - cb = 'http://myserver.local/oauth/callback' - expect(subject.authorize_url(https://github.com/:redirect_uri%20=%3E%20cb)).to include("redirect_uri=#{CGI.escape(cb)}") + it "includes passed in options" do + cb = "http://myserver.local/oauth/callback" + expect(subject.authorize_url(https://github.com/redirect_uri:%20cb)).to include("redirect_uri=#{CGI.escape(cb)}") end end - describe '#get_token (with dynamic redirect_uri)' do + describe "#get_token (with dynamic redirect_uri)" do before do - @mode = 'json' + @mode = "json" client.options[:token_method] = :post client.options[:auth_scheme] = :request_body client.options[:redirect_uri] = redirect_uri end - it 'includes redirect_uri once in the request parameters' do - expect { subject.get_token(code, :redirect_uri => redirect_uri) }.not_to raise_error + it "does not raise error" do + expect { subject.get_token(code, redirect_uri: redirect_uri) }.not_to raise_error + end + + it "gets a token" do + access = subject.get_token(code, redirect_uri: redirect_uri) + + expect(access.token).to eq("salmon") end end - describe '#get_token (handling utf-8 data)' do - let(:json_token) { MultiJson.encode(:expires_in => 600, :access_token => 'salmon', :refresh_token => 'trout', :extra_param => 'André') } + describe "#get_token (handling utf-8 data)" do + let(:json_token) { JSON.dump(expires_in: 600, access_token: "salmon", refresh_token: "trout", extra_param: "André") } before do - @mode = 'json' + @mode = "json" client.options[:token_method] = :post client.options[:auth_scheme] = :request_body end - it 'does not raise an error' do + it "does not raise an error" do expect { subject.get_token(code) }.not_to raise_error end - it 'does not create an error instance' do + it "does not create an error instance" do expect(OAuth2::Error).not_to receive(:new) subject.get_token(code) end + + it "can get a token" do + access = subject.get_token(code) + expect(access.token).to eq("salmon") + end end - describe '#get_token' do + describe "#get_token (from microsoft)" do it "doesn't treat an OpenID Connect token with only an id_token (like from Microsoft) as invalid" do - @mode = 'from_microsoft' + @mode = "from_microsoft" client.options[:token_method] = :get client.options[:auth_scheme] = :request_body @access = subject.get_token(code) - expect(@access['id_token']).to eq('jwt') + expect(@access.token).to eq("i_am_MSFT") end end %w[json formencoded from_facebook].each do |mode| - [:get, :post].each do |verb| + %i[get post].each do |verb| describe "#get_token (#{mode}, access_token_method=#{verb}" do before do @mode = mode @@ -122,28 +136,28 @@ @access = subject.get_token(code) end - it 'returns AccessToken with same Client' do + it "returns AccessToken with same Client" do expect(@access.client).to eq(client) end - it 'returns AccessToken with #token' do - expect(@access.token).to eq('salmon') + it "returns AccessToken with #token" do + expect(@access.token).to eq("salmon") end - it 'returns AccessToken with #refresh_token' do - expect(@access.refresh_token).to eq('trout') + it "returns AccessToken with #refresh_token" do + expect(@access.refresh_token).to eq("trout") end - it 'returns AccessToken with #expires_in' do + it "returns AccessToken with #expires_in" do expect(@access.expires_in).to eq(600) end - it 'returns AccessToken with #expires_at' do - expect(@access.expires_at).to be_kind_of(Integer) + it "returns AccessToken with #expires_at" do + expect(@access.expires_at).to be_a(Integer) end - it 'returns AccessToken with params accessible via []' do - expect(@access['extra_param']).to eq('steve') + it "returns AccessToken with params accessible via []" do + expect(@access["extra_param"]).to eq("steve") end end end diff --git a/spec/oauth2/strategy/base_spec.rb b/spec/oauth2/strategy/base_spec.rb index 63fbeec1..4d0e4dec 100644 --- a/spec/oauth2/strategy/base_spec.rb +++ b/spec/oauth2/strategy/base_spec.rb @@ -1,5 +1,7 @@ +# frozen_string_literal: true + RSpec.describe OAuth2::Strategy::Base do - it 'initializes with a Client' do - expect { described_class.new(OAuth2::Client.new('abc', 'def')) }.not_to raise_error + it "initializes with a Client" do + expect { described_class.new(OAuth2::Client.new("abc", "def")) }.not_to raise_error end end diff --git a/spec/oauth2/strategy/client_credentials_spec.rb b/spec/oauth2/strategy/client_credentials_spec.rb index df77a39b..e0baad92 100644 --- a/spec/oauth2/strategy/client_credentials_spec.rb +++ b/spec/oauth2/strategy/client_credentials_spec.rb @@ -1,43 +1,47 @@ +# frozen_string_literal: true + RSpec.describe OAuth2::Strategy::ClientCredentials do subject { client.client_credentials } - let(:kvform_token) { 'expires_in=600&access_token=salmon&refresh_token=trout' } + let(:kvform_token) { "expires_in=600&access_token=salmon&refresh_token=trout" } let(:json_token) { '{"expires_in":600,"access_token":"salmon","refresh_token":"trout"}' } let(:client) do - OAuth2::Client.new('abc', 'def', :site => 'http://api.example.com/') do |builder| + OAuth2::Client.new("abc", "def", site: "http://api.example.com/") do |builder| builder.adapter :test do |stub| - stub.post('/oauth/token', 'grant_type' => 'client_credentials') do |env| - client_id, client_secret = Base64.decode64(env[:request_headers]['Authorization'].split(' ', 2)[1]).split(':', 2) - client_id == 'abc' && client_secret == 'def' || raise(Faraday::Adapter::Test::Stubs::NotFound) + stub.post("/oauth/token", "grant_type" => "client_credentials") do |env| + client_id, client_secret = Base64.decode64(env[:request_headers]["Authorization"].split(" ", 2)[1]).split(":", 2) + (client_id == "abc" && client_secret == "def") || raise(Faraday::Adapter::Test::Stubs::NotFound) @last_headers = env[:request_headers] case @mode - when 'formencoded' - [200, {'Content-Type' => 'application/x-www-form-urlencoded'}, kvform_token] - when 'json' - [200, {'Content-Type' => 'application/json'}, json_token] + when "formencoded" + [200, {"Content-Type" => "application/x-www-form-urlencoded"}, kvform_token] + when "json" + [200, {"Content-Type" => "application/json"}, json_token] + else raise ArgumentError, "Bad @mode: #{@mode}" end end - stub.post('/oauth/token', 'client_id' => 'abc', 'client_secret' => 'def', 'grant_type' => 'client_credentials') do |env| + stub.post("/oauth/token", "client_id" => "abc", "client_secret" => "def", "grant_type" => "client_credentials") do |_env| case @mode - when 'formencoded' - [200, {'Content-Type' => 'application/x-www-form-urlencoded'}, kvform_token] - when 'json' - [200, {'Content-Type' => 'application/json'}, json_token] + when "formencoded" + [200, {"Content-Type" => "application/x-www-form-urlencoded"}, kvform_token] + when "json" + [200, {"Content-Type" => "application/json"}, json_token] + else raise ArgumentError, "Bad @mode: #{@mode}" end end end end end - describe '#authorize_url' do - it 'raises NotImplementedError' do + describe "#authorize_url" do + it "raises NotImplementedError" do expect { subject.authorize_url }.to raise_error(NotImplementedError) end end %w[json formencoded].each do |mode| - [:basic_auth, :request_body].each do |auth_scheme| + %i[basic_auth request_body].each do |auth_scheme| describe "#get_token (#{mode}) (#{auth_scheme})" do before do @mode = mode @@ -45,37 +49,49 @@ @access = subject.get_token end - it 'returns AccessToken with same Client' do + it "returns AccessToken with same Client" do expect(@access.client).to eq(client) end - it 'returns AccessToken with #token' do - expect(@access.token).to eq('salmon') + it "returns AccessToken with #token" do + expect(@access.token).to eq("salmon") end - it 'returns AccessToken without #refresh_token' do - expect(@access.refresh_token).to be_nil + it "returns AccessToken without #refresh_token" do + expect(@access.refresh_token).to eq("trout") end - it 'returns AccessToken with #expires_in' do + it "returns AccessToken with #expires_in" do expect(@access.expires_in).to eq(600) end - it 'returns AccessToken with #expires_at' do + it "returns AccessToken with #expires_at" do expect(@access.expires_at).not_to be_nil end end end end - describe '#get_token (with extra header parameters)' do + describe "#get_token (with extra header parameters)" do + before do + @mode = "json" + @access = subject.get_token(headers: {"X-Extra-Header" => "wow"}) + end + + it "sends the header correctly." do + expect(@last_headers["X-Extra-Header"]).to eq("wow") + end + end + + describe "#get_token (with option overriding response)" do before do - @mode = 'json' - @access = subject.get_token(:headers => {'X-Extra-Header' => 'wow'}) + @mode = "json" + @access = subject.get_token({}, {"refresh_token" => "guppy"}) end - it 'sends the header correctly.' do - expect(@last_headers['X-Extra-Header']).to eq('wow') + it "override is applied" do + expect(@access.token).to eq("salmon") + expect(@access.refresh_token).to eq("guppy") end end end diff --git a/spec/oauth2/strategy/implicit_spec.rb b/spec/oauth2/strategy/implicit_spec.rb index d2434817..b443da48 100644 --- a/spec/oauth2/strategy/implicit_spec.rb +++ b/spec/oauth2/strategy/implicit_spec.rb @@ -1,37 +1,39 @@ +# frozen_string_literal: true + RSpec.describe OAuth2::Strategy::Implicit do subject { client.implicit } - let(:client) { OAuth2::Client.new('abc', 'def', :site => 'http://api.example.com/') } + let(:client) { OAuth2::Client.new("abc", "def", site: "http://api.example.com/") } - describe '#authorize_url' do - it 'includes the client_id' do - expect(subject.authorize_url).to include('client_id=abc') + describe "#authorize_url" do + it "includes the client_id" do + expect(subject.authorize_url).to include("client_id=abc") end - it 'includes the type' do - expect(subject.authorize_url).to include('response_type=token') + it "includes the type" do + expect(subject.authorize_url).to include("response_type=token") end - it 'does not include the client_secret' do - expect(subject.authorize_url).not_to include('client_secret=def') + it "does not include the client_secret" do + expect(subject.authorize_url).not_to include("client_secret=def") end - it 'raises an error if the client_secret is passed in' do - expect { subject.authorize_url(https://github.com/:client_secret%20=%3E%20'def') }.to raise_error(ArgumentError) + it "raises an error if the client_secret is passed in" do + expect { subject.authorize_url(https://github.com/client_secret:%20%22def") }.to raise_error(ArgumentError) end - it 'raises an error if the client_secret is passed in with string keys' do - expect { subject.authorize_url('https://github.com/client_secret'%20=%3E%20'def') }.to raise_error(ArgumentError) + it "raises an error if the client_secret is passed in with string keys" do + expect { subject.authorize_url("https://github.com/client_secret%22%20=%3E%20%22def") }.to raise_error(ArgumentError) end - it 'includes passed in options' do - cb = 'http://myserver.local/oauth/callback' - expect(subject.authorize_url(https://github.com/:redirect_uri%20=%3E%20cb)).to include("redirect_uri=#{CGI.escape(cb)}") + it "includes passed in options" do + cb = "http://myserver.local/oauth/callback" + expect(subject.authorize_url(https://github.com/redirect_uri:%20cb)).to include("redirect_uri=#{CGI.escape(cb)}") end end - describe '#get_token' do - it 'raises NotImplementedError' do + describe "#get_token" do + it "raises NotImplementedError" do expect { subject.get_token }.to raise_error(NotImplementedError) end end diff --git a/spec/oauth2/strategy/password_spec.rb b/spec/oauth2/strategy/password_spec.rb index 3ab6da8c..b3dbe9e8 100644 --- a/spec/oauth2/strategy/password_spec.rb +++ b/spec/oauth2/strategy/password_spec.rb @@ -1,16 +1,20 @@ +# frozen_string_literal: true + RSpec.describe OAuth2::Strategy::Password do subject { client.password } let(:client) do - cli = OAuth2::Client.new('abc', 'def', :site => 'http://api.example.com/') - cli.connection.build do |b| + cli = OAuth2::Client.new("abc", "def", site: "http://api.example.com/") + cli.connection = Faraday.new(cli.site, cli.options[:connection_opts]) do |b| + b.request :url_encoded b.adapter :test do |stub| - stub.post('/oauth/token') do |env| + stub.post("/oauth/token") do |_env| case @mode - when 'formencoded' - [200, {'Content-Type' => 'application/x-www-form-urlencoded'}, 'expires_in=600&access_token=salmon&refresh_token=trout'] - when 'json' - [200, {'Content-Type' => 'application/json'}, '{"expires_in":600,"access_token":"salmon","refresh_token":"trout"}'] + when "formencoded" + [200, {"Content-Type" => "application/x-www-form-urlencoded"}, "expires_in=600&access_token=salmon&refresh_token=trout"] + when "json" + [200, {"Content-Type" => "application/json"}, '{"expires_in":600,"access_token":"salmon","refresh_token":"trout"}'] + else raise ArgumentError, "Bad @mode: #{@mode}" end end end @@ -18,8 +22,8 @@ cli end - describe '#authorize_url' do - it 'raises NotImplementedError' do + describe "#authorize_url" do + it "raises NotImplementedError" do expect { subject.authorize_url }.to raise_error(NotImplementedError) end end @@ -28,26 +32,26 @@ describe "#get_token (#{mode})" do before do @mode = mode - @access = subject.get_token('username', 'password') + @access = subject.get_token("username", "password") end - it 'returns AccessToken with same Client' do + it "returns AccessToken with same Client" do expect(@access.client).to eq(client) end - it 'returns AccessToken with #token' do - expect(@access.token).to eq('salmon') + it "returns AccessToken with #token" do + expect(@access.token).to eq("salmon") end - it 'returns AccessToken with #refresh_token' do - expect(@access.refresh_token).to eq('trout') + it "returns AccessToken with #refresh_token" do + expect(@access.refresh_token).to eq("trout") end - it 'returns AccessToken with #expires_in' do + it "returns AccessToken with #expires_in" do expect(@access.expires_in).to eq(600) end - it 'returns AccessToken with #expires_at' do + it "returns AccessToken with #expires_at" do expect(@access.expires_at).not_to be_nil end end diff --git a/spec/oauth2/version_spec.rb b/spec/oauth2/version_spec.rb index be0658b4..b17c61bb 100644 --- a/spec/oauth2/version_spec.rb +++ b/spec/oauth2/version_spec.rb @@ -1,8 +1,9 @@ +# frozen_string_literal: true + RSpec.describe OAuth2::Version do - it 'has a version number' do - expect(described_class).not_to be nil - end - it 'is greater than 0.1.0' do - expect(Gem::Version.new(described_class) > Gem::Version.new('0.1.0')).to be(true) + it_behaves_like "a Version module", described_class + + it "is greater than 1.0.0" do + expect(Gem::Version.new(described_class) >= Gem::Version.new("1.0.0")).to(be(true)) end end diff --git a/spec/oauth2_spec.rb b/spec/oauth2_spec.rb new file mode 100644 index 00000000..8271c9b3 --- /dev/null +++ b/spec/oauth2_spec.rb @@ -0,0 +1,38 @@ +# frozen_string_literal: true + +RSpec.describe OAuth2 do + it "silence_extra_tokens_warning is a boolean" do + expect(described_class.config.silence_extra_tokens_warning).to be(true).or be(false) + end + + describe ".configure" do + subject(:configure) do + described_class.configure do |config| + config.silence_extra_tokens_warning = true + config.silence_no_tokens_warning = true + end + end + + before do + described_class.configure do |config| + config.silence_extra_tokens_warning = false + config.silence_no_tokens_warning = false + end + end + + after do + described_class.configure do |config| + config.silence_extra_tokens_warning = false + config.silence_no_tokens_warning = false + end + end + + it "can change setting of silence_extra_tokens_warning" do + block_is_expected.to change(described_class.config, :silence_extra_tokens_warning).from(false).to(true) + end + + it "can change setting of silence_no_tokens_warning" do + block_is_expected.to change(described_class.config, :silence_no_tokens_warning).from(false).to(true) + end + end +end diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index 0618ddf9..bd0d13c4 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -1,16 +1,33 @@ -require 'bundler/setup' -require 'oauth2' -require 'helper' -require 'rspec/pending_for' +# frozen_string_literal: true -RSpec.configure do |config| - # Enable flags like --only-failures and --next-failure - config.example_status_persistence_file_path = '.rspec_status' +# ensure test env +ENV["RACK_ENV"] = "test" - # Disable RSpec exposing methods globally on `Module` and `main` - config.disable_monkey_patching! +# Global Extensions +require_relative "ext/backports" - config.expect_with :rspec do |c| - c.syntax = :expect - end +# External libraries +require "addressable/uri" +require "rspec/pending_for" + +# Family libraries +require "kettle/test/rspec" + +# Library Configs +require_relative "config/debug" +require_relative "config/multi_xml" +require_relative "config/faraday" +require_relative "config/constants" + +# NOTE: Gemfiles for older rubies won't have kettle-soup-cover. +# The rescue LoadError handles that scenario. +begin + require "kettle-soup-cover" + require "simplecov" if Kettle::Soup::Cover::DO_COV # `.simplecov` is run here! +rescue LoadError => error + # check the error message, and re-raise if not what is expected + raise error unless error.message.include?("kettle") end + +# This gem +require "oauth2"