rack-jwt-verifier 0.1.0 → 0.3.0

data/lib/rack_jwt_verifier/errors.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "jwt"
+
+module RackJwtVerifier
+  # Base class for every error this gem raises on its own behalf. Token
+  # verification failures keep raising ruby-jwt's JWT::DecodeError family.
+  class Error < StandardError; end
+
+  # Raised at boot for an unusable option set: no key source, a shared secret
+  # next to a public key, HS* mixed with RS*/ES*, a too-short secret, missing
+  # iss/aud, ... Raised from Middleware.new / Verifier.new, never per request.
+  class ConfigurationError < Error; end
+
+  # Raised when the verification key material cannot be obtained or parsed:
+  # the remote endpoint is down or slow, returned something that is not a
+  # key, or the configured static key does not parse.
+  class KeyFetchError < Error; end
+
+  # Raised when the replay cache (jti store) cannot be read or written. The
+  # middleware answers 503: the operator asked for replay protection, so a
+  # request whose jti cannot be checked is refused rather than waved through.
+  class ReplayCacheError < Error; end
+
+  # Raised when a token's jti has already been seen. Subclasses ruby-jwt's
+  # InvalidJtiError so it travels the same 401 path as any other bad claim.
+  class ReplayedTokenError < JWT::InvalidJtiError; end
+
+  # Handed to the :on_error hook when a token lacks a scope listed in
+  # require_scopes. Carries what was required and what was missing.
+  class InsufficientScopeError < Error
+    attr_reader :required, :missing
+
+    def initialize(required:, missing:)
+      @required = required
+      @missing = missing
+      super("Token lacks required scope(s): #{missing.join(' ')}")
+    end
+  end
+end

data/lib/rack_jwt_verifier/in_process_cache.rb

@@ -8,38 +8,45 @@ module RackJwtVerifier
     # The cache lifespan in seconds (5 minutes)
     DEFAULT_EXPIRY = 300
 
-    def initialize
+    # Expiry is measured on the monotonic clock, so a wall-clock jump (NTP
+    # correction, DST) cannot extend or cut short an entry's life.
+    MONOTONIC_CLOCK = -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+    # Expired entries are swept whenever the store grows past this many
+    # entries, and the threshold then doubles from whatever survived. Amortised
+    # O(1) per write, so a jti-per-request workload cannot grow the store
+    # without bound while a single-key workload never pays for a sweep.
+    SWEEP_THRESHOLD = 1024
+
+    # @param clock [#call] Returns the current time in seconds; injectable for tests.
+    def initialize(clock: MONOTONIC_CLOCK)
       @store = {}
       @lock = Mutex.new # Ensure thread safety for multi-threaded environments
+      @clock = clock
+      @sweep_at = SWEEP_THRESHOLD
     end
 
     # Reads the value for a given key. Automatically checks for expiry.
     # @param key [String] The cache key.
     # @return [Object, nil] The cached value or nil if expired or not found.
     def read(key)
-      @lock.synchronize do
-        entry = @store[key]
-        return nil unless entry
-
-        value, expires_at = entry
-        
-        # Check if the entry is expired
-        return nil if Time.now.to_i >= expires_at
-        
-        value
-      end
+      @lock.synchronize { live_value(key) }
     end
 
     # Writes a value to the cache with an optional expiration time.
     # @param key [String] The cache key.
     # @param value [Object] The value to store.
-    # @param options [Hash] Options, expecting :expires_in (seconds).
-    # @return [Object] The stored value.
+    # @param options [Hash] :expires_in (seconds); :unless_exist (true to keep
+    #   an existing live entry, as ActiveSupport stores do).
+    # @return [Object, false] The stored value, or false when :unless_exist
+    #   was given and a live entry already existed.
     def write(key, value, options = {})
       @lock.synchronize do
+        return false if options[:unless_exist] && !live_value(key).nil?
+
         expiry = options[:expires_in] || DEFAULT_EXPIRY
-        expires_at = Time.now.to_i + expiry
-        @store[key] = [value, expires_at]
+        @store[key] = [value, @clock.call + expiry]
+        sweep_if_needed
         value
       end
     end
@@ -49,8 +56,45 @@ module RackJwtVerifier
     # @return [Object, nil] The deleted entry value or nil.
     def delete(key)
       @lock.synchronize do
-        @store.delete(key)
+        entry = @store.delete(key)
+        entry&.first
+      end
+    end
+
+    # Removes every entry.
+    def clear
+      @lock.synchronize do
+        @store.clear
+        @sweep_at = SWEEP_THRESHOLD
       end
+      nil
+    end
+
+    # Number of entries held, expired ones included until the next sweep.
+    def size
+      @lock.synchronize { @store.size }
+    end
+
+    private
+
+    # Caller holds the lock.
+    def live_value(key)
+      entry = @store[key]
+      return nil unless entry
+
+      value, expires_at = entry
+      return nil if @clock.call >= expires_at
+
+      value
+    end
+
+    # Caller holds the lock.
+    def sweep_if_needed
+      return if @store.size <= @sweep_at
+
+      now = @clock.call
+      @store.delete_if { |_, (_, expires_at)| now >= expires_at }
+      @sweep_at = [@store.size * 2, SWEEP_THRESHOLD].max
     end
   end
 end

data/lib/rack_jwt_verifier/jwt_helper.rb

@@ -3,53 +3,77 @@
 require 'jwt'
 require 'openssl'
 
-# A helper class for handling JWT creation and verification using RSA keys (RS256).
-# This is typically used by the application or a separate service to *create* tokens.
 module RackJwtVerifier
+  # @deprecated Will be removed in 0.4.0. Issues (and, for round-trip checks,
+  #   decodes) RS256 tokens from an RSA private key.
+  #
+  # This is a second token issuer living inside the verifier: it sets neither
+  # `iss`, `aud`, `nbf` nor `jti`, so what it mints does not pass the claim
+  # policy the middleware now enforces. Issue tokens with the `jwt_auth_client`
+  # gem instead (HMAC today, RS256/ES256 from its 0.3.0); in a test suite,
+  # sign with `JWT.encode` directly — see spec/support/token_factory.rb in this
+  # repository for a helper you can copy.
   class JwtHelper
-    # The private_key must be an OpenSSL::PKey::RSA object (or similar).
+    ALGORITHM = 'RS256'
+
+    DEPRECATION = 'RackJwtVerifier::JwtHelper is deprecated and will be removed in 0.4.0: issue tokens with the ' \
+                  'jwt_auth_client gem, or sign test tokens with JWT.encode. Set ' \
+                  'RACK_JWT_VERIFIER_SILENCE_DEPRECATIONS=1 to silence this warning.'
+
+    @warned = false
+    @warn_lock = Mutex.new
+
+    class << self
+      # Emits the deprecation warning once per process.
+      def warn_deprecated
+        return if ENV['RACK_JWT_VERIFIER_SILENCE_DEPRECATIONS'] == '1'
+
+        @warn_lock.synchronize do
+          return if @warned
+
+          @warned = true
+        end
+        Kernel.warn(DEPRECATION, uplevel: 2)
+      end
+
+      # Forget that the warning was emitted. Intended for test suites.
+      def reset_deprecation_warning!
+        @warn_lock.synchronize { @warned = false }
+      end
+    end
+
     attr_reader :private_key, :public_key
 
-    # Initializes the helper with the RSA Private Key used for signing.
-    #
-    # @param private_key_pem [String] The PEM string of the RSA Private Key.
+    # @param private_key_pem [String, OpenSSL::PKey::RSA] The RSA private key used for signing.
     def initialize(private_key_pem)
-      # !! IMPORTANT !!
-      # This key signs the tokens.
-      @private_key = OpenSSL::PKey::RSA.new(private_key_pem)
+      self.class.warn_deprecated
+      @private_key = private_key_pem.is_a?(OpenSSL::PKey::RSA) ? private_key_pem : OpenSSL::PKey::RSA.new(private_key_pem)
       @public_key = @private_key.public_key
     end
 
-    # Encodes a payload into a JWT.
+    # Encodes a payload into a JWT, adding `iat` and `exp`.
     #
-    # @param payload [Hash] The data to be encoded in the JWT (e.g., user ID, roles).
-    # @param expires_in [Integer] Time in seconds until the token expires (default: 1 hour).
+    # @param payload [Hash] Claims (string or symbol keys; an explicit `exp` in the payload wins).
+    # @param expires_in [Integer] Seconds until the token expires (default: 1 hour).
     # @return [String] The signed JWT string.
     def encode(payload, expires_in = 3600)
-      # Set standard expiration time (exp) and issued-at time (iat) claims
-      time = Time.now.to_i
-      payload_with_claims = payload.merge({
-        iat: time,
-        exp: time + expires_in
-      })
-
-      JWT.encode(payload_with_claims, @private_key, 'RS256')
+      now = Time.now.to_i
+      # Normalise to string keys first so a caller's 'exp' and our :exp cannot
+      # both end up in the JSON as duplicate "exp" members.
+      claims = { 'iat' => now, 'exp' => now + expires_in }.merge(payload.transform_keys(&:to_s))
+      JWT.encode(claims, @private_key, ALGORITHM)
     end
 
-    # Decodes and verifies a JWT using the public key.
-    #
-    # NOTE: This method is used primarily for self-testing in the application
-    # but the primary verification logic for the middleware is in the Verifier class.
+    # Decodes and verifies a JWT with the public key. Meant for self-checks;
+    # the middleware's verification lives in Verifier.
     #
     # @param token [String] The JWT string to decode.
+    # @param options [Hash] Extra options for JWT.decode (leeway, iss, verify_iss, ...).
     # @return [Hash] The decoded payload if verification is successful.
-    # @raise [JWT::VerificationError, JWT::DecodeError] If the token is invalid or expired.
-    def decode(token)
-      # Decodes using the public key, performs signature verification (true),
-      # and restricts the algorithm to 'RS256'.
-      decoded = JWT.decode(token, @public_key, true, { algorithm: 'RS256' })
-      # Returns only the payload (the first element of the array).
-      decoded.first
+    # @raise [JWT::DecodeError] If the token is invalid or expired.
+    def decode(token, options = {})
+      payload, _header = JWT.decode(token, @public_key, true, { algorithm: ALGORITHM }.merge(options))
+      payload
     end
   end
 end

data/lib/rack_jwt_verifier/key_source.rb

@@ -0,0 +1,344 @@
+# 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 ConfigurationError, "public_key is not a valid PEM public key or certificate: #{e.message}"
+      end
+
+      def jwks?
+        false
+      end
+
+      def refresh!
+        false
+      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
+    # 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 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 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. 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 = +""
+
+        Net::HTTP.start(uri.host, uri.port,
+                        use_ssl: uri.scheme == "https",
+                        open_timeout: @http_timeout,
+                        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
+
+          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, Net::WriteTimeout
+        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