rack-jwt-verifier 0.1.0 → 0.2.0

data/lib/rack_jwt_verifier/key_source.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "jwt"
+require "logger"
+require "net/http"
+require "openssl"
+require "uri"
+require_relative "errors"
+require_relative "version"
+
+module RackJwtVerifier
+  # Where the verification key material comes from.
+  #
+  # Every source answers #jwks? and #refresh!. A single-key source (Static,
+  # RemotePem) also answers #verification_key; a JWKS source answers
+  # #jwks_loader, in the shape ruby-jwt's :jwks decode option expects.
+  module KeySource
+    # Turns PEM text into an OpenSSL public key. Accepts a bare public key
+    # (RSA, EC, Ed25519, ...) or an X.509 certificate, which is what many SSO
+    # providers serve at their ".pem" endpoints. An OpenSSL::PKey passes through.
+    def self.parse_public_key(pem)
+      return pem if pem.is_a?(OpenSSL::PKey::PKey)
+
+      text = pem.to_s
+      if text.include?("-----BEGIN CERTIFICATE-----")
+        OpenSSL::X509::Certificate.new(text).public_key
+      else
+        OpenSSL::PKey.read(text)
+      end
+    end
+
+    # A key handed over directly: a PEM string, a certificate PEM, or an
+    # OpenSSL::PKey. Nothing to fetch, cache or refresh.
+    class Static
+      attr_reader :verification_key
+
+      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}"
+      end
+
+      def jwks?
+        false
+      end
+
+      def refresh!
+        false
+      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
+    # body and which cache namespace to use.
+    class Remote
+      # Timeout (seconds) applied separately to opening the connection and to
+      # reading the response. Kept short so a slow endpoint cannot pin every
+      # request thread on a cache miss.
+      DEFAULT_HTTP_TIMEOUT = 5
+      # Largest response body (bytes) we are willing to read. A PEM key is well
+      # under 1 KB and a JWKS with a handful of keys a few KB.
+      MAX_RESPONSE_BYTES = 64 * 1024
+      # How long (seconds) fetched material is served from the cache.
+      DEFAULT_CACHE_TTL = 300
+      # Minimum gap (seconds) between two rotation-triggered refetches, so a
+      # flood of tokens with bad signatures or unknown kids cannot turn into a
+      # flood of requests to the provider.
+      DEFAULT_REFETCH_INTERVAL = 60
+
+      attr_reader :url, :cache_key
+
+      def initialize(url:, cache:, cache_ttl: DEFAULT_CACHE_TTL, http_timeout: DEFAULT_HTTP_TIMEOUT,
+                     refetch_interval: DEFAULT_REFETCH_INTERVAL, allow_insecure_http: false, logger: nil)
+        @url = url.to_s
+        @uri = parse_url(@url, allow_insecure_http: allow_insecure_http)
+        @cache = cache
+        @logger = logger || Logger.new(IO::NULL)
+        @cache_ttl = cache_ttl
+        @http_timeout = http_timeout
+        @refetch_interval = refetch_interval
+        # Scoped to the URL so two verifiers sharing one cache store (two SSO
+        # providers behind one Redis) never read each other's key.
+        @cache_key = "#{cache_key_prefix}:#{Digest::SHA256.hexdigest(@url)[0, 16]}"
+
+        @fetch_lock = Mutex.new # single-flight: one network fetch per process on a cold cache
+        @state_lock = Mutex.new # guards @parsed and @last_refetch_at
+        @parsed = nil           # [body, parsed material] of the last body parsed
+        @last_refetch_at = nil  # monotonic clock
+      end
+
+      # Refetches the material unless a refresh happened less than
+      # refetch_interval seconds ago. Returns true if it actually refetched.
+      def refresh!
+        @state_lock.synchronize do
+          now = monotonic_now
+          return false if @last_refetch_at && now - @last_refetch_at < @refetch_interval
+
+          @last_refetch_at = now
+        end
+        fetch_and_store
+        true
+      end
+
+      private
+
+      # Parsed material, from the cache or (on a miss) the network.
+      def material
+        body = cache_read || fetch_once
+        parsed_for(body)
+      end
+
+      # Only one thread per process performs the fetch on a cold cache; the
+      # others wait for it and then find the body in the cache.
+      def fetch_once
+        @fetch_lock.synchronize do
+          cache_read || fetch_and_store
+        end
+      end
+
+      def fetch_and_store
+        body = fetch_body
+        # Parse *before* caching so a 200 that is not key material (an HTML
+        # maintenance page, say) is never stored and served for the TTL.
+        parse!(body)
+        cache_write(body)
+        body
+      end
+
+      # A broken cache store (Redis down, say) must not take authentication
+      # down with it: treat a failed read as a miss and a failed write as a
+      # no-op, and say so in the log. Fetches then fall back to one per
+      # request per process until the store recovers.
+      def cache_read
+        @cache.read(cache_key)
+      rescue StandardError => e
+        @logger.warn do
+          "rack_jwt_verifier: cache read failed (#{e.class}: #{e.message}); fetching key material directly"
+        end
+        nil
+      end
+
+      def cache_write(body)
+        @cache.write(cache_key, body, expires_in: @cache_ttl)
+      rescue StandardError => e
+        @logger.warn do
+          "rack_jwt_verifier: cache write failed (#{e.class}: #{e.message}); key material will be refetched"
+        end
+        nil
+      end
+
+      # Parsing is not free (and JWKS parsing less so), so the result for a
+      # given body is memoised until the body changes.
+      def parsed_for(body)
+        @state_lock.synchronize do
+          @parsed = [body, parse!(body)] unless @parsed && @parsed[0] == body
+          @parsed[1]
+        end
+      end
+
+      def parse!(body)
+        parse(body)
+      rescue KeyFetchError
+        raise
+      rescue StandardError => e
+        raise KeyFetchError, "Error processing public key: #{e.message}"
+      end
+
+      # The material must travel over TLS: an attacker who can tamper with a
+      # plaintext fetch can substitute their own key and mint arbitrary tokens.
+      def parse_url(url, allow_insecure_http:)
+        uri = URI.parse(url)
+        return uri if uri.is_a?(URI::HTTPS)
+        return uri if uri.is_a?(URI::HTTP) && allow_insecure_http
+
+        raise ArgumentError,
+              "#{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}"
+      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.
+      def fetch_body
+        uri = @uri
+        body = +""
+
+        Net::HTTP.start(uri.host, uri.port,
+                        use_ssl: uri.scheme == "https",
+                        open_timeout: @http_timeout,
+                        read_timeout: @http_timeout) do |http|
+          request = Net::HTTP::Get.new(uri)
+          request["User-Agent"] = "rack_jwt_verifier/#{VERSION}"
+          request["Accept"] = accept_header
+
+          http.request(request) do |response|
+            unless response.is_a?(Net::HTTPSuccess)
+              raise KeyFetchError, "Failed to fetch public key from #{@url}: #{response.code}"
+            end
+
+            response.read_body do |chunk|
+              body << chunk
+              if body.bytesize > MAX_RESPONSE_BYTES
+                raise KeyFetchError, "Public key response from #{@url} exceeds #{MAX_RESPONSE_BYTES} bytes"
+              end
+            end
+          end
+        end
+
+        body
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        raise KeyFetchError, "Timed out fetching public key from #{@url} after #{@http_timeout}s"
+      rescue KeyFetchError
+        raise
+      rescue StandardError => e
+        raise KeyFetchError, "Error fetching public key from #{@url}: #{e.message}"
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    # A single PEM public key (or X.509 certificate) served at a URL.
+    class RemotePem < Remote
+      CACHE_KEY_PREFIX = "rack_jwt_verifier:public_key"
+
+      def verification_key
+        material
+      end
+
+      def jwks?
+        false
+      end
+
+      private
+
+      def cache_key_prefix
+        CACHE_KEY_PREFIX
+      end
+
+      def url_option_name
+        "public_key_url"
+      end
+
+      def accept_header
+        "application/x-pem-file, text/plain, */*"
+      end
+
+      def parse(body)
+        KeySource.parse_public_key(body)
+      end
+    end
+
+    # A JSON Web Key Set served at a URL (typically /.well-known/jwks.json).
+    class RemoteJwks < Remote
+      CACHE_KEY_PREFIX = "rack_jwt_verifier:jwks"
+
+      def jwks?
+        true
+      end
+
+      # ruby-jwt calls the loader once, and again with kid_not_found: true when
+      # the token's kid is absent from the set it got — the rotation signal for
+      # JWKS. Refresh (rate-limited) on that signal, then hand back the set.
+      def jwks_loader
+        lambda do |options|
+          refresh! if options[:kid_not_found] || options[:invalidate]
+          material
+        end
+      end
+
+      private
+
+      def cache_key_prefix
+        CACHE_KEY_PREFIX
+      end
+
+      def url_option_name
+        "jwks_url"
+      end
+
+      def accept_header
+        "application/jwk-set+json, application/json, */*"
+      end
+
+      def parse(body)
+        set = JWT::JWK::Set.new(JSON.parse(body))
+        raise KeyFetchError, "JWKS from #{@url} contains no keys" if set.none?
+
+        set
+      end
+    end
+  end
+end

data/lib/rack_jwt_verifier/middleware.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
-require "rack_jwt_verifier/verifier"
+require "json"
+require "logger"
+require_relative "verifier"
 
 module RackJwtVerifier
   # The primary middleware class responsible for intercepting requests,
@@ -10,61 +12,187 @@ module RackJwtVerifier
     # The default key in the Rack environment used to store the verified JWT payload.
     # This can be accessed by downstream applications (e.g., Rails controllers)
     # to retrieve the authenticated user's details.
-    RACK_ENV_PAYLOAD_KEY = "rack_jwt_verifier.payload".freeze
+    RACK_ENV_PAYLOAD_KEY = "rack_jwt_verifier.payload"
 
+    # Seconds a client is told to wait before retrying after a 503.
+    RETRY_AFTER_SECONDS = 5
+
+    # Used when neither a :logger option nor env["rack.logger"] is available.
+    NULL_LOGGER = Logger.new(IO::NULL)
+
+    # Status and default plain-text body for each way a request can be refused.
+    # The reason symbol doubles as the `error` code in JSON bodies.
+    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."]
+    }.freeze
+
+    # @param app [#call] The downstream Rack application.
+    # @param options [Hash] Middleware options; everything else is forwarded to Verifier.
+    # @option options [Boolean] :require_token Reject requests that carry no Bearer token
+    #   (default: false, pass through).
+    # @option options [Logger] :logger Logger for verification failures
+    #   (default: env["rack.logger"], else silent).
+    # @option options [String] :env_key Rack env key that receives the payload
+    #   (default: RACK_ENV_PAYLOAD_KEY).
+    # @option options [Array<String, Regexp, #call>] :skip Paths (exact string, regexp) or
+    #   predicates on env that bypass the middleware.
+    # @option options [Boolean] :json_errors Render 401/503 bodies as JSON
+    #   `{"error", "error_description"}` (default: plain text).
+    # @option options [#call] :on_error `->(env, reason, exception) { rack_response or nil }`
+    #   to customise refusals.
     def initialize(app, options = {})
       @app = app
-      @options = options
-      
+      @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]
+
       # 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, {}))
     end
 
     def call(env)
+      return @app.call(env) if skip?(env)
+
       token = extract_token(env)
-      
-      # If no token is found, we immediately pass the request down the stack
-      # and the application is responsible for handling the unauthenticated state.
-      return @app.call(env) unless token
 
+      # With no token the request is passed down the stack and the application
+      # decides how to treat the unauthenticated state — unless require_token
+      # is set, in which case it is rejected here.
+      unless token
+        return error_response(env, :missing_token, nil) if @require_token
+
+        return @app.call(env)
+      end
+
+      # Only the verification step is guarded: a JWT::DecodeError raised by the
+      # downstream application must propagate, not be turned into a 401 here.
       begin
         # Use the Verifier to handle the complex crypto and validation logic
         payload = @verifier.verify(token)
-        
-        # On successful verification, store the payload in the Rack environment
-        env[RACK_ENV_PAYLOAD_KEY] = payload
-        
-        @app.call(env)
       rescue JWT::DecodeError => e
-        # If verification fails (invalid signature, expired, invalid claim),
-        # log the error and return an unauthenticated response.
-        warn "JWT Verification Failed: #{e.message}"
-        
-        # Return a 401 Unauthorized response
-        unauthorized_response
+        # Invalid signature, expired, bad claim: the client's problem.
+        logger(env).warn { "rack_jwt_verifier: token rejected: #{e.message}" }
+        return error_response(env, :invalid_token, e)
+      rescue KeyFetchError => e
+        # We could not obtain the key to check the token: our problem, not the
+        # client's, so answer 503 rather than 401.
+        logger(env).error { "rack_jwt_verifier: #{e.message}" }
+        return error_response(env, :key_unavailable, e)
       end
+
+      # On successful verification, store the payload in the Rack environment
+      env[@env_key] = payload
+
+      @app.call(env)
     end
 
     private
 
-    # Extracts the JWT from the standard Authorization header format: "Bearer <token>"
+    # Extracts the JWT from the standard Authorization header format: "Bearer <token>".
+    # The scheme is matched case-insensitively (RFC 7235 §2.1).
     def extract_token(env)
       # Rack converts HTTP_AUTHORIZATION header to ENV['HTTP_AUTHORIZATION']
       auth_header = env["HTTP_AUTHORIZATION"]
-      
+
       return nil unless auth_header
-      
-      scheme, token = auth_header.split(" ", 2)
-      
-      # Only process if the scheme is "Bearer" and a token is present
-      (scheme == "Bearer") ? token : nil
+
+      scheme, token = auth_header.strip.split(/\s+/, 2)
+      return nil unless scheme&.casecmp?("bearer")
+
+      token = token&.strip
+      token.nil? || token.empty? ? nil : token
+    end
+
+    # A skip rule is an exact path string, a regexp matched against the path,
+    # or a callable given the whole env.
+    def skip?(env)
+      return false if @skip.empty?
+
+      path = "#{env['SCRIPT_NAME']}#{env['PATH_INFO']}"
+      @skip.any? do |rule|
+        case rule
+        when String then rule == path
+        when Regexp then rule.match?(path)
+        else rule.call(env)
+        end
+      end
+    end
+
+    def validate_skip_rules(rules)
+      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})"
+      end
+    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)
+
+      (@logger || Kernel).warn(
+        "rack_jwt_verifier: neither :iss nor :aud is set in decode_options, so any " \
+        "token signed by the configured key is accepted. Set decode_options: { iss: ..., aud: ... }."
+      )
+    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)
+      custom = @on_error&.call(env, reason, error)
+      return custom if custom
+
+      status, default_text = ERROR_RESPONSES.fetch(reason)
+      description = error && sanitize_description(error.message)
+
+      headers = {}
+      headers["www-authenticate"] = challenge(reason, description) if status == 401
+      headers["retry-after"] = RETRY_AFTER_SECONDS.to_s if status == 503
+
+      if @json_errors
+        body = JSON.generate(error: reason, error_description: description || default_text)
+        respond(status, body, "application/json", headers)
+      else
+        respond(status, default_text, "text/plain", headers)
+      end
+    end
+
+    # 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.
+    def challenge(reason, description)
+      return "Bearer" if reason == :missing_token
+
+      value = +'Bearer error="invalid_token"'
+      value << ", error_description=\"#{description}\"" if description && !description.empty?
+      value
+    end
+
+    # error_description is a quoted-string: keep it to the characters RFC 6750
+    # allows inside one (printable ASCII minus `"` and `\`) and a sane length.
+    def sanitize_description(message)
+      message.to_s.gsub(/[^\x20-\x21\x23-\x5B\x5D-\x7E]/, "")[0, 200]
     end
 
-    # Standard 401 Unauthorized Rack response
-    def unauthorized_response
-      # Status, Headers, Body (Array of strings)
-      [401, { "Content-Type" => "text/plain", "WWW-Authenticate" => "Bearer error=\"invalid_token\"" }, ["Unauthorized: Invalid or expired JWT."]]
+    # Rack 3 requires lowercase header names; they are equally valid on Rack 2.
+    def respond(status, body, content_type, extra_headers = {})
+      headers = {
+        "content-type" => content_type,
+        "content-length" => body.bytesize.to_s
+      }.merge(extra_headers)
+      [status, headers, [body]]
     end
   end
 end