rack-jwt-verifier 0.2.0 → 0.3.0

data/lib/rack_jwt_verifier/key_source.rb

@@ -39,7 +39,7 @@ module RackJwtVerifier
       def initialize(key)
         @verification_key = KeySource.parse_public_key(key)
       rescue OpenSSL::PKey::PKeyError, OpenSSL::X509::CertificateError => e
-        raise ArgumentError, "public_key is not a valid PEM public key or certificate: #{e.message}"
+        raise ConfigurationError, "public_key is not a valid PEM public key or certificate: #{e.message}"
       end
 
       def jwks?
@@ -51,6 +51,49 @@ module RackJwtVerifier
       end
     end
 
+    # An HMAC secret shared with the issuer (jwt_auth_client's mode). Nothing
+    # to fetch or rotate: a secret has no kid, so rotation means redeploying
+    # both sides. The RFC 7518 minimum length is enforced by the Verifier,
+    # which knows the algorithm list.
+    class Secret
+      attr_reader :verification_key
+
+      # @param secret [String, Hash] the secret itself, or { env: "VAR_NAME" }
+      #   to read it from the environment at boot.
+      def initialize(secret)
+        @verification_key = resolve(secret)
+      end
+
+      def jwks?
+        false
+      end
+
+      def refresh!
+        false
+      end
+
+      private
+
+      def resolve(secret)
+        value =
+          case secret
+          when Hash
+            name = secret[:env] || secret["env"]
+            raise ConfigurationError, "shared_secret: { env: ... } needs the variable name" if name.to_s.empty?
+
+            ENV.fetch(name.to_s) { raise ConfigurationError, "shared_secret: environment variable #{name} is not set" }
+          when String
+            secret
+          else
+            raise ConfigurationError, "shared_secret must be a String or { env: \"VAR_NAME\" } (got #{secret.class})"
+          end
+
+        raise ConfigurationError, "shared_secret must not be empty" if value.empty?
+
+        value
+      end
+    end
+
     # Shared machinery for key material fetched over HTTPS: caching, strict
     # timeouts, a size cap, single-flight fetching within the process, and a
     # rate-limited refresh for key rotation. Subclasses say how to parse the
@@ -175,16 +218,17 @@ module RackJwtVerifier
         return uri if uri.is_a?(URI::HTTPS)
         return uri if uri.is_a?(URI::HTTP) && allow_insecure_http
 
-        raise ArgumentError,
+        raise ConfigurationError,
               "#{url_option_name} must be an https:// URL (got #{url.inspect}). " \
               "Pass allow_insecure_http: true to permit http:// in development."
       rescue URI::InvalidURIError
-        raise ArgumentError, "#{url_option_name} is not a valid URL: #{url.inspect}"
+        raise ConfigurationError, "#{url_option_name} is not a valid URL: #{url.inspect}"
       end
 
       # Performs the HTTP GET with strict timeouts and a size cap. The body is
       # streamed so an oversized response is abandoned early rather than
-      # buffered in full.
+      # buffered in full. Redirects are deliberately not followed: a 3xx to
+      # an http:// or third-party host would defeat the https:// requirement.
       def fetch_body
         uri = @uri
         body = +""
@@ -192,7 +236,8 @@ module RackJwtVerifier
         Net::HTTP.start(uri.host, uri.port,
                         use_ssl: uri.scheme == "https",
                         open_timeout: @http_timeout,
-                        read_timeout: @http_timeout) do |http|
+                        read_timeout: @http_timeout,
+                        write_timeout: @http_timeout) do |http|
           request = Net::HTTP::Get.new(uri)
           request["User-Agent"] = "rack_jwt_verifier/#{VERSION}"
           request["Accept"] = accept_header
@@ -212,7 +257,7 @@ module RackJwtVerifier
         end
 
         body
-      rescue Net::OpenTimeout, Net::ReadTimeout
+      rescue Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout
         raise KeyFetchError, "Timed out fetching public key from #{@url} after #{@http_timeout}s"
       rescue KeyFetchError
         raise

data/lib/rack_jwt_verifier/middleware.rb

@@ -2,6 +2,8 @@
 
 require "json"
 require "logger"
+require_relative "errors"
+require_relative "scopes"
 require_relative "verifier"
 
 module RackJwtVerifier
@@ -25,7 +27,9 @@ module RackJwtVerifier
     ERROR_RESPONSES = {
       missing_token: [401, "Unauthorized: Bearer token required."],
       invalid_token: [401, "Unauthorized: Invalid or expired JWT."],
-      key_unavailable: [503, "Service Unavailable: could not fetch the token verification key."]
+      insufficient_scope: [403, "Forbidden: the token does not grant the required scope."],
+      key_unavailable: [503, "Service Unavailable: could not fetch the token verification key."],
+      replay_cache_unavailable: [503, "Service Unavailable: could not check the token for replay."]
     }.freeze
 
     # @param app [#call] The downstream Rack application.
@@ -42,20 +46,26 @@ module RackJwtVerifier
     #   `{"error", "error_description"}` (default: plain text).
     # @option options [#call] :on_error `->(env, reason, exception) { rack_response or nil }`
     #   to customise refusals.
+    # @option options [Array<String>] :require_scopes Scopes every token must grant; a token
+    #   lacking one gets a 403 with an `insufficient_scope` challenge. Implies :require_token.
+    # @option options [Boolean] :require_iss_aud Refuse to boot unless decode_options carries
+    #   both :iss and :aud (default: true). `false` logs a warning instead.
+    # @raise [ConfigurationError] for an unusable option set.
     def initialize(app, options = {})
       @app = app
-      @require_token = options.fetch(:require_token, false)
       @logger = options[:logger]
       @env_key = options.fetch(:env_key, RACK_ENV_PAYLOAD_KEY)
       @skip = validate_skip_rules(Array(options[:skip]))
       @json_errors = options.fetch(:json_errors, false)
       @on_error = options[:on_error]
+      @require_scopes = validate_required_scopes(options[:require_scopes])
+      @require_token = resolve_require_token(options)
 
       # The Verifier instance is initialized with options (like public_key_url)
       # and is responsible for all crypto and key management.
       @verifier = Verifier.new(options)
 
-      warn_if_claims_unrestricted(options.fetch(:decode_options, {}))
+      enforce_claim_policy(options)
     end
 
     def call(env)
@@ -86,6 +96,16 @@ module RackJwtVerifier
         # client's, so answer 503 rather than 401.
         logger(env).error { "rack_jwt_verifier: #{e.message}" }
         return error_response(env, :key_unavailable, e)
+      rescue ReplayCacheError => e
+        logger(env).error { "rack_jwt_verifier: #{e.message}" }
+        return error_response(env, :replay_cache_unavailable, e)
+      end
+
+      missing = Scopes.missing(payload, @require_scopes)
+      unless missing.empty?
+        error = InsufficientScopeError.new(required: @require_scopes, missing: missing)
+        logger(env).warn { "rack_jwt_verifier: #{error.message}" }
+        return error_response(env, :insufficient_scope, error)
       end
 
       # On successful verification, store the payload in the Rack environment
@@ -130,25 +150,65 @@ module RackJwtVerifier
       rules.each do |rule|
         next if rule.is_a?(String) || rule.is_a?(Regexp) || rule.respond_to?(:call)
 
-        raise ArgumentError, "skip: entries must be a String, a Regexp or respond to #call (got #{rule.inspect})"
+        raise ConfigurationError, "skip: entries must be a String, a Regexp or respond to #call (got #{rule.inspect})"
+      end
+    end
+
+    def validate_required_scopes(scopes)
+      list = Array(scopes).map(&:to_s)
+      if list.any?(&:empty?)
+        raise ConfigurationError, "require_scopes: entries must be non-empty strings (got #{scopes.inspect})"
+      end
+
+      list.uniq.freeze
+    end
+
+    # A required scope can only be checked on a token, so require_scopes
+    # implies require_token; saying otherwise explicitly is a contradiction.
+    def resolve_require_token(options)
+      return options.fetch(:require_token, false) if @require_scopes.empty?
+
+      if options.key?(:require_token) && !options[:require_token]
+        raise ConfigurationError, "require_scopes: needs a token to check; drop require_token: false"
       end
+
+      true
     end
 
     def logger(env)
       @logger || env["rack.logger"] || NULL_LOGGER
     end
 
-    # A key alone proves who signed the token, not who it was meant for. Nudge
-    # the operator once at boot if neither iss nor aud is being checked.
-    def warn_if_claims_unrestricted(decode_options)
-      return if decode_options.key?(:iss) || decode_options.key?(:aud)
+    # A key alone proves who signed the token, not who it was meant for — and
+    # a shared secret proves even less. Both iss and aud must be checked
+    # unless the operator explicitly opts out, in which case they get the
+    # warning instead.
+    def enforce_claim_policy(options)
+      decode_options = options.fetch(:decode_options, {})
+      missing = %i[iss aud].reject { |claim| present?(decode_options[claim]) }
+      return if missing.empty?
+
+      if options.fetch(:require_iss_aud, true)
+        raise ConfigurationError,
+              "decode_options must set #{missing.map(&:inspect).join(' and ')} so only tokens issued by " \
+              "your provider, for this application, are accepted. Pass require_iss_aud: false to opt out."
+      end
 
       (@logger || Kernel).warn(
-        "rack_jwt_verifier: neither :iss nor :aud is set in decode_options, so any " \
+        "rack_jwt_verifier: #{missing.map(&:inspect).join(' and ')} not set in decode_options, so any " \
         "token signed by the configured key is accepted. Set decode_options: { iss: ..., aud: ... }."
       )
     end
 
+    def present?(value)
+      case value
+      when nil then false
+      when String then !value.strip.empty?
+      when Array then value.any? { |v| present?(v) }
+      else true
+      end
+    end
+
     # Builds the refusal for `reason`, letting an :on_error hook take over
     # first. Returning nil from the hook falls back to the default response.
     def error_response(env, reason, error)
@@ -159,7 +219,7 @@ module RackJwtVerifier
       description = error && sanitize_description(error.message)
 
       headers = {}
-      headers["www-authenticate"] = challenge(reason, description) if status == 401
+      headers["www-authenticate"] = challenge(reason, description) if [401, 403].include?(status)
       headers["retry-after"] = RETRY_AFTER_SECONDS.to_s if status == 503
 
       if @json_errors
@@ -172,11 +232,14 @@ module RackJwtVerifier
 
     # RFC 6750 §3: a request that carried no credentials at all gets the bare
     # challenge, without an error code; otherwise the code and a description.
+    # An insufficient_scope challenge also names the scopes required (§3.1).
     def challenge(reason, description)
       return "Bearer" if reason == :missing_token
 
-      value = +'Bearer error="invalid_token"'
+      code = reason == :insufficient_scope ? "insufficient_scope" : "invalid_token"
+      value = "Bearer error=\"#{code}\""
       value << ", error_description=\"#{description}\"" if description && !description.empty?
+      value << ", scope=\"#{sanitize_description(@require_scopes.join(' '))}\"" if reason == :insufficient_scope
       value
     end
 

data/lib/rack_jwt_verifier/replay_guard.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "errors"
+
+module RackJwtVerifier
+  # Records each verified token's `jti` in a cache store until the token
+  # expires, and rejects a token whose `jti` is already there.
+  #
+  # The store is the same read/write abstraction used for key material
+  # (InProcessCache, Rails.cache, ...). An in-process store only detects
+  # replays within one worker; use a shared store for real protection.
+  #
+  # Failure mode is closed: a store that raises turns into ReplayCacheError
+  # (a 503 in the middleware). The operator asked for replay protection, so a
+  # request whose jti cannot be checked is not waved through.
+  class ReplayGuard
+    CACHE_KEY_PREFIX = "rack_jwt_verifier:jti"
+
+    # Used when a payload has no numeric `exp` to derive the TTL from (only
+    # possible when the operator removed `exp` from required_claims).
+    FALLBACK_TTL = 24 * 60 * 60
+
+    attr_reader :store, :leeway
+
+    # @param store [#read, #write] the cache store holding seen jtis.
+    # @param leeway [Numeric] clock-skew leeway; a jti is remembered for exp + leeway.
+    def initialize(store, leeway: 0)
+      @store = store
+      @leeway = leeway
+    end
+
+    # @param payload [Hash] the verified claims.
+    # @raise [ReplayedTokenError] if this jti has been seen before.
+    # @raise [JWT::InvalidJtiError] if the payload carries no usable jti.
+    # @raise [ReplayCacheError] if the store cannot be read or written.
+    def check!(payload)
+      jti = payload["jti"].to_s
+      raise JWT::InvalidJtiError, "Missing jti" if jti.strip.empty?
+
+      key = cache_key(jti)
+      ttl = ttl_for(payload)
+
+      # Read first so stores that ignore unless_exist still catch the common
+      # case; the conditional write then closes the window for stores that
+      # honour it (ActiveSupport stores return false when the key exists).
+      seen, stored = store_access(key, ttl)
+      raise ReplayedTokenError, "Token has already been used (jti #{jti})" if seen || stored == false
+
+      nil
+    end
+
+    # @param jti [String]
+    # @return [String] the cache key; jti is hashed so an attacker-chosen value
+    #   cannot produce an unbounded or store-hostile key.
+    def cache_key(jti)
+      "#{CACHE_KEY_PREFIX}:#{Digest::SHA256.hexdigest(jti)}"
+    end
+
+    private
+
+    def store_access(key, ttl)
+      seen = @store.read(key)
+      return [true, nil] if seen
+
+      [false, @store.write(key, 1, expires_in: ttl, unless_exist: true)]
+    rescue StandardError => e
+      raise ReplayCacheError, "replay cache unavailable (#{e.class}: #{e.message})"
+    end
+
+    def ttl_for(payload)
+      exp = payload["exp"]
+      return FALLBACK_TTL unless exp.is_a?(Numeric)
+
+      [(exp - Time.now.to_i + @leeway).ceil, 1].max
+    end
+  end
+end

data/lib/rack_jwt_verifier/scopes.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module RackJwtVerifier
+  # Reads the scopes granted by a verified token.
+  #
+  # Two claim shapes are understood: `scopes`, an Array of Strings (what
+  # jwt_auth_client emits), and `scope`, a space-delimited String (the OAuth 2
+  # convention, RFC 8693 §4.2 / RFC 9068 §2.2.3). Both are normalised to an
+  # Array of Strings.
+  #
+  #   claims = env["rack_jwt_verifier.payload"]
+  #   RackJwtVerifier::Scopes.from(claims)                     # => ["read:invoices"]
+  #   RackJwtVerifier::Scopes.include?(claims, "read:invoices") # => true
+  #   RackJwtVerifier::Scopes.missing(claims, %w[read:x write:x]) # => ["write:x"]
+  module Scopes
+    module_function
+
+    # @param payload [Hash, nil] the verified claims.
+    # @return [Array<String>] granted scopes; empty when there are none.
+    def from(payload)
+      return [] unless payload.is_a?(Hash)
+
+      raw = payload["scopes"] || payload[:scopes]
+      raw = payload["scope"] || payload[:scope] if raw.nil?
+
+      case raw
+      when Array then raw.map(&:to_s).reject(&:empty?)
+      when String then raw.split
+      else []
+      end
+    end
+
+    # @return [Array<String>] the required scopes the payload does not grant.
+    def missing(payload, required)
+      Array(required).map(&:to_s) - from(payload)
+    end
+
+    # @return [Boolean] true when every given scope is granted.
+    def include?(payload, *scopes)
+      missing(payload, scopes.flatten).empty?
+    end
+  end
+end

data/lib/rack_jwt_verifier/verifier.rb

@@ -4,11 +4,13 @@ require "jwt"
 require_relative "errors"
 require_relative "in_process_cache"
 require_relative "key_source"
+require_relative "replay_guard"
 
 module RackJwtVerifier
   # 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.
+  # a static PEM, a PEM served at a URL, a JWKS endpoint, or a shared HMAC
+  # secret. Handles caching, key rotation, claim enforcement and optional jti
+  # replay protection so the middleware does not have to.
   class Verifier
     # Kept under the old constant so existing `rescue Verifier::KeyFetchError`
     # code keeps working.
@@ -27,8 +29,21 @@ module RackJwtVerifier
     # 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
+    # Exactly one of these tells the Verifier where its key comes from. Having
+    # shared_secret in the same exclusive set is what rules out "a secret next
+    # to a public key" — the classic RS256/HS256 confusion setup.
+    KEY_SOURCE_OPTIONS = %i[public_key public_key_url jwks_url shared_secret].freeze
+
+    # The HMAC family, only ever enabled by shared_secret.
+    HMAC_ALGORITHMS = %w[HS256 HS384 HS512].freeze
+
+    # RFC 7518 §3.2: an HMAC key must be at least as long as the hash output.
+    # Same numbers jwt_auth_client enforces on the signing side.
+    MIN_SECRET_BYTES = { "HS256" => 32, "HS384" => 48, "HS512" => 64 }.freeze
+
+    # Default accepted algorithms per key-source family.
+    DEFAULT_ASYMMETRIC_ALGORITHMS = %w[RS256].freeze
+    DEFAULT_HMAC_ALGORITHMS = %w[HS256].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
@@ -39,12 +54,13 @@ module RackJwtVerifier
       sub: :verify_sub
     }.freeze
 
-    # Default options for JWT decoding to ensure strict security compliance
+    # Default options for JWT decoding to ensure strict security compliance.
+    # ruby-jwt only checks exp/nbf when the claim is present, so `exp` is also
+    # listed as required: a token with no expiry would otherwise be valid forever.
     DEFAULT_DECODE_OPTIONS = {
-      algorithm: "RS256", # Must match your SSO provider's algorithm
-      # THIS MUST BE TRUE: Ensures the 'exp' claim is checked during decoding
       verify_expiration: true,
       verify_not_before: true,
+      required_claims: %w[exp].freeze,
       leeway: 60 # Allow a 60-second clock skew for "exp" and "nbf" claims
     }.freeze
 
@@ -52,25 +68,50 @@ module RackJwtVerifier
     # @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 [String, Hash] :shared_secret An HMAC secret (String) or `{ env: "VAR" }`.
+    #   Enables the HS* algorithms; mutually exclusive with the public-key sources.
+    # @option options [Array<String>] :algorithms Accepted signing algorithms
+    #   (default: ["RS256"], or ["HS256"] with :shared_secret).
     # @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 [Numeric] :http_timeout Open/read/write 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 [Boolean, Object] :replay_cache `true` to track `jti` in :cache_store (or a fresh
+    #   InProcessCache), or a cache store to track it in. Tokens are then required to carry a `jti`
+    #   and a second presentation before `exp` is rejected.
     # @option options [Logger] :logger Where cache-store failures are reported (default: silent).
     # @option options [Hash] :decode_options Custom options for JWT.decode.
+    # @raise [ConfigurationError] for an unusable option set.
     def initialize(options = {})
-      @key_source = build_key_source(options)
-      @decode_options = build_decode_options(options.fetch(:decode_options, {}), options[:algorithms])
+      source_name = key_source_name(options)
+      @key_source = build_key_source(source_name, options)
+      @algorithms = build_algorithms(source_name, options)
+      @decode_options = build_decode_options(options.fetch(:decode_options, {}), replay: replay_wanted?(options))
+      @replay_guard = build_replay_guard(options, @decode_options[:leeway])
     end
 
+    # The algorithms this verifier accepts, after defaults and policy.
+    # @return [Array<String>]
+    attr_reader :algorithms
+
     # 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 [JWT::DecodeError] If the token is invalid, expired, replayed, or signature fails.
     # @raise [KeyFetchError] If the key material could not be obtained.
+    # @raise [ReplayCacheError] If replay protection is on and its store is unavailable.
     def verify(token)
+      payload = decode_with_rotation(token)
+      # Only a token that passed every other check is recorded: an expired or
+      # mis-signed token must not be able to "burn" a jti.
+      @replay_guard&.check!(payload)
+      payload
+    end
+
+    private
+
+    def decode_with_rotation(token)
       decode(token)
     rescue JWT::VerificationError
       # A signature mismatch may mean the provider rotated its key. Refresh
@@ -81,8 +122,6 @@ module RackJwtVerifier
       decode(token)
     end
 
-    private
-
     # Performs the cryptographic verification and claim validation. The `true`
     # is required to enable verification checks; only the payload is returned.
     def decode(token)
@@ -95,21 +134,25 @@ module RackJwtVerifier
       payload
     end
 
-    def build_key_source(options)
+    def key_source_name(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
+      return given.first if given.size == 1
+
+      raise ConfigurationError,
+            "exactly one of #{KEY_SOURCE_OPTIONS.map(&:inspect).join(', ')} must be given" \
+            "#{" (got #{given.map(&:inspect).join(' and ')})" unless given.empty?}"
+    end
 
-      case given.first
+    def build_key_source(name, options)
+      case name
       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))
+      when :shared_secret
+        KeySource::Secret.new(options[:shared_secret])
       end
     end
 
@@ -126,21 +169,91 @@ module RackJwtVerifier
       }
     end
 
+    # The effective algorithm list, from (in order of precedence) a
+    # decode_options :algorithm, the top-level :algorithms, a decode_options
+    # :algorithms, or the family default — then checked against the policy:
+    # never "none", and HS* only with a shared secret, never mixed with
+    # asymmetric algorithms. ruby-jwt would happily verify an RS256 token's
+    # public key as an HMAC secret otherwise.
+    def build_algorithms(source_name, options)
+      decode_options = options.fetch(:decode_options, {})
+      hmac = source_name == :shared_secret
+
+      list = decode_options[:algorithm] || options[:algorithms] || decode_options[:algorithms] ||
+             (hmac ? DEFAULT_HMAC_ALGORITHMS : DEFAULT_ASYMMETRIC_ALGORITHMS)
+      list = Array(list).map { |alg| alg.to_s.strip }.reject(&:empty?)
+      raise ConfigurationError, "algorithms must list at least one algorithm" if list.empty?
+
+      if list.any? { |alg| alg.casecmp?("none") }
+        raise ConfigurationError, '"none" is not an acceptable algorithm: it disables signature verification'
+      end
+
+      hmac_algs, other_algs = list.partition { |alg| HMAC_ALGORITHMS.include?(alg.upcase) }
+      if hmac
+        unless other_algs.empty?
+          raise ConfigurationError,
+                "shared_secret only works with #{HMAC_ALGORITHMS.join('/')}; " \
+                "remove #{other_algs.join(', ')} from algorithms or use a public key source"
+        end
+        check_secret_length!(hmac_algs.map(&:upcase))
+      elsif hmac_algs.any?
+        raise ConfigurationError,
+              "#{hmac_algs.join(', ')} require shared_secret; they cannot be mixed with public-key algorithms " \
+              "(a public key would be accepted as the HMAC secret)"
+      end
+
+      list.freeze
+    end
+
+    def check_secret_length!(hmac_algs)
+      needed = hmac_algs.map { |alg| MIN_SECRET_BYTES.fetch(alg) }.max
+      actual = @key_source.verification_key.bytesize
+      return if actual >= needed
+
+      raise ConfigurationError,
+            "shared_secret must be at least #{needed} bytes for #{hmac_algs.join('/')} (got #{actual}); " \
+            "generate one with: openssl rand -hex #{needed}"
+    end
+
+    def replay_wanted?(options)
+      store = options[:replay_cache]
+      !(store.nil? || store == false)
+    end
+
+    def build_replay_guard(options, leeway)
+      return nil unless replay_wanted?(options)
+
+      store = options[:replay_cache]
+      store = options.fetch(:cache_store) { InProcessCache.new } if store == true
+      unless store.respond_to?(:read) && store.respond_to?(:write)
+        raise ConfigurationError, "replay_cache must be true or a cache store responding to #read and #write"
+      end
+
+      ReplayGuard.new(store, leeway: leeway)
+    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;
+    # - install the policy-checked algorithm list and drop any :algorithm so
+    #   ruby-jwt (which consults :algorithm first) sees exactly that 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)
+    #   it. An explicit `verify_*: false` from the user is left untouched;
+    # - require a jti when replay protection is on.
+    def build_decode_options(user_options, replay:)
       merged = DEFAULT_DECODE_OPTIONS.merge(user_options)
-      merged[:algorithms] = Array(algorithms) if algorithms
-      merged.delete(:algorithm) if merged.key?(:algorithms) && !user_options.key?(:algorithm)
+      merged.delete(:algorithm)
+      merged[:algorithms] = @algorithms
 
       CLAIM_VERIFY_FLAGS.each do |claim, flag|
         merged[flag] = true if merged.key?(claim) && !merged.key?(flag)
       end
+      merged[:verify_jti] = true if replay && !merged.key?(:verify_jti)
+
+      leeway = merged[:leeway]
+      unless leeway.is_a?(Numeric) && leeway >= 0
+        raise ConfigurationError, "decode_options[:leeway] must be a non-negative number of seconds"
+      end
+
       merged
     end
   end

data/lib/rack_jwt_verifier/version.rb

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

data/lib/rack_jwt_verifier.rb

@@ -7,10 +7,13 @@ require_relative "rack_jwt_verifier/version"
 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/replay_guard"
+require_relative "rack_jwt_verifier/scopes"
 require_relative "rack_jwt_verifier/verifier"
 require_relative "rack_jwt_verifier/middleware"
 require_relative "rack_jwt_verifier/jwt_helper"
 
-# Namespace for the gem: Middleware, Verifier, KeySource, InProcessCache, JwtHelper.
+# Namespace for the gem: Middleware, Verifier, KeySource, Scopes, ReplayGuard,
+# InProcessCache and the deprecated JwtHelper.
 module RackJwtVerifier
 end