rack-jwt-verifier 0.1.0 → 0.2.0

data/lib/rack_jwt_verifier/verifier.rb

@@ -1,21 +1,43 @@
 # frozen_string_literal: true
 
 require "jwt"
-require "net/http"
-require "json"
+require_relative "errors"
+require_relative "in_process_cache"
+require_relative "key_source"
 
 module RackJwtVerifier
-  # This class handles the cryptographic heavy lifting: fetching and caching
-  # public keys from the SSO provider, and performing the actual JWT decoding
-  # and signature verification.
+  # Decodes and verifies JWTs against key material from a configured source:
+  # a static PEM, a PEM served at a URL, or a JWKS endpoint. Handles caching,
+  # key rotation and claim enforcement so the middleware does not have to.
   class Verifier
-    # Error raised if we fail to fetch keys from the remote URL
-    class KeyFetchError < StandardError; end
-    
-    # The cache key used to store the public key PEM string
-    PUBLIC_KEY_CACHE_KEY = 'rack_jwt_verifier:public_key'.freeze
-    # The TTL for the cache (5 minutes, must match the default in InProcessCache)
-    CACHE_TTL_SECONDS = 300
+    # Kept under the old constant so existing `rescue Verifier::KeyFetchError`
+    # code keeps working.
+    KeyFetchError = RackJwtVerifier::KeyFetchError
+
+    # Cache namespace for a fetched PEM; the full key also carries a digest of the URL.
+    PUBLIC_KEY_CACHE_KEY = KeySource::RemotePem::CACHE_KEY_PREFIX
+    # Cache namespace for a fetched JWKS; the full key also carries a digest of the URL.
+    JWKS_CACHE_KEY = KeySource::RemoteJwks::CACHE_KEY_PREFIX
+    # The default TTL for cached key material (5 minutes)
+    CACHE_TTL_SECONDS = KeySource::Remote::DEFAULT_CACHE_TTL
+    # Default open/read timeout (seconds) for fetching key material
+    DEFAULT_HTTP_TIMEOUT = KeySource::Remote::DEFAULT_HTTP_TIMEOUT
+    # Largest response body (bytes) accepted as key material
+    MAX_KEY_RESPONSE_BYTES = KeySource::Remote::MAX_RESPONSE_BYTES
+    # Minimum gap (seconds) between rotation-triggered refetches
+    DEFAULT_REFETCH_INTERVAL = KeySource::Remote::DEFAULT_REFETCH_INTERVAL
+
+    # Exactly one of these tells the Verifier where its key comes from.
+    KEY_SOURCE_OPTIONS = %i[public_key public_key_url jwks_url].freeze
+
+    # ruby-jwt only validates an expected claim value (e.g. `iss: "..."`) when
+    # the matching `verify_*` flag is also set. Map each claim to its flag so we
+    # can switch the flag on automatically whenever a value is supplied.
+    CLAIM_VERIFY_FLAGS = {
+      iss: :verify_iss,
+      aud: :verify_aud,
+      sub: :verify_sub
+    }.freeze
 
     # Default options for JWT decoding to ensure strict security compliance
     DEFAULT_DECODE_OPTIONS = {
@@ -23,77 +45,103 @@ module RackJwtVerifier
       # THIS MUST BE TRUE: Ensures the 'exp' claim is checked during decoding
       verify_expiration: true,
       verify_not_before: true,
-      leeway: 60, # Allow a 60-second clock skew for "exp" and "nbf" claims
-      # 'iss' validation will be added later when we configure the Verifier.
-      # verify_iss: true
+      leeway: 60 # Allow a 60-second clock skew for "exp" and "nbf" claims
     }.freeze
 
     # @param options [Hash] Configuration options.
-    # @option options [String] :public_key_url The URL to fetch the public key.
+    # @option options [String, OpenSSL::PKey] :public_key A static PEM public key or X.509 certificate.
+    # @option options [String] :public_key_url The https:// URL serving a PEM public key or certificate.
+    # @option options [String] :jwks_url The https:// URL serving a JSON Web Key Set.
+    # @option options [Array<String>] :algorithms Accepted signing algorithms (default: ["RS256"]).
+    # @option options [Boolean] :allow_insecure_http Permit a plain http:// URL (development only).
+    # @option options [Numeric] :http_timeout Open/read timeout in seconds for the key fetch.
+    # @option options [Integer] :cache_ttl Seconds to cache fetched key material.
+    # @option options [Numeric] :refetch_interval Minimum seconds between rotation-triggered refetches.
     # @option options [Object] :cache_store Optional custom cache object (must respond to #read and #write).
+    # @option options [Logger] :logger Where cache-store failures are reported (default: silent).
     # @option options [Hash] :decode_options Custom options for JWT.decode.
     def initialize(options = {})
-      @public_key_url = options.fetch(:public_key_url)
-      
-      # Inject cache store, defaulting to the simple InProcessCache.
-      # This allows users to pass in a Redis/Memcached client that responds to #read and #write.
-      @cache = options.fetch(:cache_store, InProcessCache.new)
-      
-      # Merge default options over any user-provided options
-      @decode_options = DEFAULT_DECODE_OPTIONS.merge(options.fetch(:decode_options, {}))
+      @key_source = build_key_source(options)
+      @decode_options = build_decode_options(options.fetch(:decode_options, {}), options[:algorithms])
     end
 
     # Decodes and verifies the JWT.
     # @param token [String] The JWT string from the Authorization header.
     # @return [Hash] The decoded payload (the user claims).
     # @raise [JWT::DecodeError] If the token is invalid, expired, or signature fails.
+    # @raise [KeyFetchError] If the key material could not be obtained.
     def verify(token)
-      # 1. Fetch the key from cache or network
-      key = fetch_public_key
-
-      # 2. Perform the cryptographic verification and claim validation
-      # The `true` is required to enable verification checks.
-      payload, _header = JWT.decode(token, key, true, @decode_options)
-      
-      # For standard usage, we only need the payload hash
-      payload
+      decode(token)
+    rescue JWT::VerificationError
+      # A signature mismatch may mean the provider rotated its key. Refresh
+      # once (rate-limited) and retry; if nothing was refreshed, or the retry
+      # fails too, the token is simply bad.
+      raise unless @key_source.refresh!
+
+      decode(token)
     end
 
     private
 
-    # Handles fetching the public key from the remote URL, using the injected cache.
-    def fetch_public_key
-      # 1. Try to read the PEM string from the cache
-      cached_pem = @cache.read(PUBLIC_KEY_CACHE_KEY)
-      
-      if cached_pem
-        # Found in cache, convert PEM to OpenSSL object and return
-        return OpenSSL::PKey::RSA.new(cached_pem)
-      end
+    # Performs the cryptographic verification and claim validation. The `true`
+    # is required to enable verification checks; only the payload is returned.
+    def decode(token)
+      payload, _header =
+        if @key_source.jwks?
+          JWT.decode(token, nil, true, @decode_options.merge(jwks: @key_source.jwks_loader))
+        else
+          JWT.decode(token, @key_source.verification_key, true, @decode_options)
+        end
+      payload
+    end
 
-      # 2. Key is missing or expired, fetch it from the network
-      uri = URI(@public_key_url)
-      response = Net::HTTP.get_response(uri)
+    def build_key_source(options)
+      given = KEY_SOURCE_OPTIONS.select { |name| options[name] }
+      unless given.size == 1
+        raise ArgumentError,
+              "exactly one of #{KEY_SOURCE_OPTIONS.map(&:inspect).join(', ')} must be given" \
+              "#{" (got #{given.map(&:inspect).join(' and ')})" unless given.empty?}"
+      end
 
-      unless response.is_a?(Net::HTTPSuccess)
-        raise KeyFetchError, "Failed to fetch public key from #{@public_key_url}: #{response.code}"
+      case given.first
+      when :public_key
+        KeySource::Static.new(options[:public_key])
+      when :public_key_url
+        KeySource::RemotePem.new(url: options[:public_key_url], **remote_options(options))
+      when :jwks_url
+        KeySource::RemoteJwks.new(url: options[:jwks_url], **remote_options(options))
       end
+    end
 
-      # 3. Process response
-      public_key_pem = response.body
-      
-      # 4. Cache the new key PEM string
-      @cache.write(PUBLIC_KEY_CACHE_KEY, public_key_pem, expires_in: CACHE_TTL_SECONDS)
-      
-      # 5. Return the OpenSSL object for verification
-      OpenSSL::PKey::RSA.new(public_key_pem)
-
-    rescue KeyFetchError
-      # Re-raise explicit KeyFetchError for easier debugging/rescue in middleware
-      raise
-    rescue StandardError => e
-      # Catch all other network/parsing/OpenSSL errors
-      raise KeyFetchError, "Error processing public key: #{e.message}"
+    def remote_options(options)
+      {
+        # Inject cache store, defaulting to the simple InProcessCache. This
+        # allows users to pass in a cache store that responds to #read and #write.
+        cache: options.fetch(:cache_store) { InProcessCache.new },
+        cache_ttl: options.fetch(:cache_ttl, CACHE_TTL_SECONDS),
+        http_timeout: options.fetch(:http_timeout, DEFAULT_HTTP_TIMEOUT),
+        refetch_interval: options.fetch(:refetch_interval, DEFAULT_REFETCH_INTERVAL),
+        allow_insecure_http: options.fetch(:allow_insecure_http, false),
+        logger: options[:logger]
+      }
+    end
+
+    # Merge default options over any user-provided options, then:
+    # - apply a top-level :algorithms list, and drop our :algorithm default
+    #   whenever a list is in play — ruby-jwt consults :algorithm first, so the
+    #   default would otherwise silently override the user's list;
+    # - make sure an expected claim value is actually enforced: `iss: "x"` on
+    #   its own is a no-op in ruby-jwt unless `verify_iss: true` accompanies
+    #   it. An explicit `verify_*: false` from the user is left untouched.
+    def build_decode_options(user_options, algorithms)
+      merged = DEFAULT_DECODE_OPTIONS.merge(user_options)
+      merged[:algorithms] = Array(algorithms) if algorithms
+      merged.delete(:algorithm) if merged.key?(:algorithms) && !user_options.key?(:algorithm)
+
+      CLAIM_VERIFY_FLAGS.each do |claim, flag|
+        merged[flag] = true if merged.key?(claim) && !merged.key?(flag)
+      end
+      merged
     end
   end
 end

data/lib/rack_jwt_verifier/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RackJwtVerifier
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/rack_jwt_verifier.rb

@@ -1,20 +1,16 @@
 # frozen_string_literal: true
 
-# This file serves as the main entry point for the rack_jwt_verifier gem.
-# When a user calls `require 'rack_jwt_verifier'`, this file is loaded.
+# Entry point for the gem: `require "rack_jwt_verifier"` loads everything.
+# (`require "rack-jwt-verifier"`, the gem's name, works too.)
 
 require_relative "rack_jwt_verifier/version"
-
-# Require core component files so they are available under the RackJwtVerifier module.
-# IMPORTANT: These paths rely on you moving `jwt_helper.rb` into the
-# `lib/rack_jwt_verifier/` directory.
-require_relative "rack_jwt_verifier/jwt_helper"
+require_relative "rack_jwt_verifier/errors"
+require_relative "rack_jwt_verifier/in_process_cache"
+require_relative "rack_jwt_verifier/key_source"
 require_relative "rack_jwt_verifier/verifier"
 require_relative "rack_jwt_verifier/middleware"
-require_relative "rack_jwt_verifier/in_process_cache"
-
+require_relative "rack_jwt_verifier/jwt_helper"
 
-# The main namespace module for the gem. All classes (JwtHelper, Verifier,
-# Middleware) are now accessible via RackJwtVerifier::ClassName.
+# Namespace for the gem: Middleware, Verifier, KeySource, InProcessCache, JwtHelper.
 module RackJwtVerifier
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-jwt-verifier
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Daniele Frisanco
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2025-10-20 00:00:00.000000000 Z
+date: 2026-09-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jwt
@@ -25,121 +25,57 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.8'
 - !ruby/object:Gem::Dependency
-  name: rack
+  name: logger
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '1.4'
 - !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: webmock
+  name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
-- !ruby/object:Gem::Dependency
-  name: timecop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+        version: '2.2'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0.9'
-  type: :development
+        version: '4'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.9'
-- !ruby/object:Gem::Dependency
-  name: rack-test
-  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
+        version: '2.2'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: '0'
-description: Verifies JWT signature, validates claims (expiration, issuer), and handles
-  public key retrieval to ensure requests are securely authenticated by an external
-  SSO provider.
+        version: '4'
+description: Verifies JWT signatures against a JWKS endpoint, a PEM URL or a static
+  key, enforces exp/nbf/iss/aud claims, caches key material, handles key rotation,
+  and exposes the verified claims to the application through the Rack environment.
 email:
 - daniele.frisanco@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".rspec_status"
 - CHANGELOG.md
-- Gemfile
-- Gemfile.lock
 - LICENSE.md
 - README.md
+- lib/rack-jwt-verifier.rb
 - lib/rack_jwt_verifier.rb
+- lib/rack_jwt_verifier/errors.rb
 - lib/rack_jwt_verifier/in_process_cache.rb
 - lib/rack_jwt_verifier/jwt_helper.rb
+- lib/rack_jwt_verifier/key_source.rb
 - lib/rack_jwt_verifier/middleware.rb
 - lib/rack_jwt_verifier/verifier.rb
 - lib/rack_jwt_verifier/version.rb
@@ -150,7 +86,8 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/danielefrisanco/rack_jwt_verifier
   source_code_uri: https://github.com/danielefrisanco/rack_jwt_verifier
-  changelog_uri: https://github.com/danielefrisanco/rack_jwt_verifier/CHANGELOG.md
+  changelog_uri: https://github.com/danielefrisanco/rack_jwt_verifier/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -159,16 +96,16 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.6
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.3.26
 signing_key: 
 specification_version: 4
-summary: A Rack middleware for authenticating requests using JWTs (JSON Web Tokens)
-  and injecting user data into the Rack environment.
+summary: Rack middleware that authenticates requests with JWTs from an external identity
+  provider.
 test_files: []

data/.rspec_status

@@ -1,26 +0,0 @@
-example_id                                           | status | run_time        |
----------------------------------------------------- | ------ | --------------- |
-./spec/rack_jwt_verifier/jwt_helper_spec.rb[1:1:1]   | passed | 0.06296 seconds |
-./spec/rack_jwt_verifier/jwt_helper_spec.rb[1:2:1]   | passed | 0.05566 seconds |
-./spec/rack_jwt_verifier/jwt_helper_spec.rb[1:2:2]   | passed | 0.03186 seconds |
-./spec/rack_jwt_verifier/jwt_helper_spec.rb[1:3:1:1] | passed | 0.04063 seconds |
-./spec/rack_jwt_verifier/jwt_helper_spec.rb[1:3:2:1] | passed | 0.06923 seconds |
-./spec/rack_jwt_verifier/jwt_helper_spec.rb[1:3:3:1] | passed | 0.03564 seconds |
-./spec/rack_jwt_verifier/middleware_spec.rb[1:1:1]   | passed | 0.02249 seconds |
-./spec/rack_jwt_verifier/middleware_spec.rb[1:2:1:1] | passed | 0.05022 seconds |
-./spec/rack_jwt_verifier/middleware_spec.rb[1:2:1:2] | passed | 0.02597 seconds |
-./spec/rack_jwt_verifier/middleware_spec.rb[1:2:2:1] | passed | 0.02197 seconds |
-./spec/rack_jwt_verifier/middleware_spec.rb[1:2:3:1] | passed | 0.03074 seconds |
-./spec/rack_jwt_verifier/middleware_spec.rb[1:2:4:1] | passed | 0.02496 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:1:1]     | passed | 0.01668 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:1:2]     | passed | 0.00633 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:1:3]     | passed | 0.05474 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:1:4]     | passed | 0.04057 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:2:1]     | passed | 0.03279 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:2:2]     | passed | 0.04898 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:2:3:1]   | passed | 0.03709 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:2:3:2]   | passed | 0.01822 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:3:1]     | passed | 0.01993 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:3:2]     | passed | 0.01473 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:3:3]     | passed | 0.03322 seconds |
-./spec/rack_jwt_verifier/verifier_spec.rb[1:3:4]     | passed | 0.01368 seconds |

data/Gemfile

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in rack_jwt_verifier.gemspec
-gemspec
-
-# Dependencies for development and testing
-group :development, :test do
-  gem "rack"
-  gem "rspec", "~> 3.12"
-  gem "rack-test"
-  gem "webmock", "~> 3.14" # Added for mocking network requests in Verifier
-end

data/Gemfile.lock

@@ -1,63 +0,0 @@
-PATH
-  remote: .
-  specs:
-    rack-jwt-verifier (0.1.0)
-      jwt (~> 2.8)
-      rack (>= 2.0)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    addressable (2.8.7)
-      public_suffix (>= 2.0.2, < 7.0)
-    base64 (0.2.0)
-    bigdecimal (3.1.8)
-    crack (1.0.0)
-      bigdecimal
-      rexml
-    diff-lcs (1.6.2)
-    hashdiff (1.1.0)
-    jwt (2.8.2)
-      base64
-    public_suffix (5.1.1)
-    rack (3.2.3)
-    rack-test (2.2.0)
-      rack (>= 1.3)
-    rake (13.2.1)
-    rexml (3.3.2)
-      strscan
-    rspec (3.13.1)
-      rspec-core (~> 3.13.0)
-      rspec-expectations (~> 3.13.0)
-      rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.5)
-      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.6)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.13.0)
-    rspec-support (3.13.6)
-    strscan (3.1.0)
-    timecop (0.9.10)
-    webmock (3.23.1)
-      addressable (>= 2.8.0)
-      crack (>= 0.3.2)
-      hashdiff (>= 0.4.0, < 2.0.0)
-
-PLATFORMS
-  x86_64-linux
-
-DEPENDENCIES
-  bundler (~> 2.0)
-  rack
-  rack-jwt-verifier!
-  rack-test
-  rake (~> 13.0)
-  rspec (~> 3.12)
-  timecop (~> 0.9)
-  webmock (~> 3.14)
-
-BUNDLED WITH
-   2.4.22