verikloak 0.1.1

data/lib/verikloak/errors.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Verikloak
+  # Base error class for all Verikloak-related exceptions.
+  #
+  # All errors raised by this library inherit from this class so they can be
+  # rescued in a consistent way. Each error may carry a short, programmatic
+  # `code` (e.g., "invalid_token", "jwks_fetch_failed") that middleware and
+  # callers can use to map to HTTP statuses or telemetry.
+  #
+  # @attr_reader [String, Symbol, nil] code
+  #   A short error code identifier suitable for programmatic handling.
+  #
+  # @example Raising with a code
+  #   raise Verikloak::Error.new("Something went wrong", code: "internal_error")
+  class Error < StandardError
+    attr_reader :code
+
+    # @param message [String, nil] Human-readable error message.
+    # @param code [String, Symbol, nil] Optional short error code for programmatic handling.
+    def initialize(message = nil, code: nil)
+      super(message)
+      @code = code
+    end
+  end
+
+  # Raised when discovery document fetching or validation fails.
+  #
+  # Typical causes include network failures, non-200 responses, invalid JSON,
+  # missing required fields (e.g., `jwks_uri`, `issuer`), or redirect issues.
+  #
+  # @see Verikloak::Discovery
+  # @raise [DiscoveryError] from {Verikloak::Discovery#fetch!}
+  class DiscoveryError < Error; end
+
+  # Raised for middleware-level failures while processing a Rack request.
+  #
+  # Examples include missing/invalid Authorization headers, JWKS cache
+  # initialization failures, or infrastructure issues detected by the
+  # middleware itself.
+  #
+  # @see Verikloak::Middleware
+  class MiddlewareError < Error; end
+
+  # Raised when JWT token verification fails or the token is invalid.
+  #
+  # Common causes:
+  # - Invalid or unsupported algorithm
+  # - Invalid signature
+  # - Expired (`exp`) or not-yet-valid (`nbf`) token
+  # - Invalid `iss` / `aud` claims
+  # - Malformed token structure or decode failures
+  #
+  # @see Verikloak::TokenDecoder
+  # @raise [TokenDecoderError] from {Verikloak::TokenDecoder#decode!}
+  class TokenDecoderError < Error; end
+
+  # Raised when JWKS fetching, validation, or cache handling fails.
+  #
+  # Causes include HTTP failures, invalid JSON, missing required JWK fields,
+  # or receiving 304 Not Modified without a prior cached value.
+  #
+  # @see Verikloak::JwksCache
+  # @raise [JwksCacheError] from {Verikloak::JwksCache#fetch!}
+  class JwksCacheError < Error; end
+end

data/lib/verikloak/jwks_cache.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'json'
+
+module Verikloak
+  # Caches and revalidates JSON Web Key Sets (JWKS) fetched from a remote endpoint.
+  #
+  # This cache supports two HTTP cache mechanisms:
+  # - **ETag revalidation** via `If-None-Match` → returns `304 Not Modified` when unchanged.
+  # - **TTL freshness** via `Cache-Control: max-age` → avoids HTTP requests while fresh.
+  #
+  # On a successful `200 OK`, the cache:
+  # - Parses the JWKS JSON (`{"keys":[...]}`) and validates each JWK has `kid`, `kty`, `n`, `e`.
+  # - Stores the keys in-memory, records `ETag`, and computes freshness from `Cache-Control`.
+  #
+  # On a `304 Not Modified`, the cache:
+  # - Keeps existing keys and ETag, optionally updates TTL from new `Cache-Control`, and refreshes `fetched_at`.
+  #
+  # Errors are raised as {Verikloak::JwksCacheError} with structured `code` values:
+  # - `jwks_fetch_failed` (network/HTTP errors)
+  # - `jwks_parse_failed` (invalid JSON / structure)
+  # - `jwks_cache_miss`   (304 received but nothing cached)
+  #
+  # @example Basic usage
+  #   cache = Verikloak::JwksCache.new(jwks_uri: "https://issuer.example.com/protocol/openid-connect/certs")
+  #   keys  = cache.fetch! # → Array<Hash> of JWKs
+  #
+  # @see #fetch!
+  # @see #cached
+  class JwksCache
+    # @param jwks_uri [String] HTTPS URL of the JWKS endpoint
+    # @raise [JwksCacheError] if the URI is not an HTTP(S) URL
+    def initialize(jwks_uri:)
+      unless jwks_uri.is_a?(String) && jwks_uri.strip.match?(%r{^https?://})
+        raise JwksCacheError.new('Invalid JWKS URI: must be a non-empty HTTP(S) URL', code: 'jwks_fetch_failed')
+      end
+
+      @jwks_uri    = jwks_uri
+      @cached_keys = nil
+      @etag        = nil
+      @fetched_at  = nil
+      @max_age     = nil
+    end
+
+    # Fetches the JWKS and updates the in-memory cache.
+    #
+    # Performs an HTTP GET with `If-None-Match` when an ETag is present and handles:
+    # - 200: parses/validates body, updates keys, ETag, TTL and `fetched_at`.
+    # - 304: keeps cached keys, updates TTL from headers (if present), refreshes `fetched_at`.
+    #
+    # @return [Array<Hash>] the cached JWKs after fetch/revalidation
+    # @raise [JwksCacheError] on HTTP failures, invalid JSON, invalid structure, or cache miss on 304
+    def fetch!
+      with_error_handling do
+        # Build conditional request headers (ETag-based)
+        headers  = build_conditional_headers
+        # Perform HTTP GET request
+        response = Faraday.get(@jwks_uri, nil, headers)
+        # Handle HTTP response according to status code
+        handle_response(response)
+      end
+    end
+
+    # Returns the last cached JWKs without performing a network request.
+    # @return [Array<Hash>, nil] cached keys, or nil if never fetched
+    def cached
+      @cached_keys
+    end
+
+    # Timestamp of the last successful fetch or revalidation.
+    # @return [Time, nil]
+    attr_reader :fetched_at
+
+    # Whether the cache is considered stale.
+    #
+    # Uses `Cache-Control: max-age` semantics when available:
+    # returns `true` if `max-age` has elapsed or nothing is cached.
+    #
+    # @return [Boolean]
+    def stale?
+      !fresh_by_ttl?
+    end
+
+    # @api private
+    # Wraps network/parse errors into {JwksCacheError} with structured codes.
+    # @raise [JwksCacheError]
+    def with_error_handling
+      yield
+    rescue JwksCacheError
+      raise
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError
+      raise JwksCacheError.new('Connection failed', code: 'jwks_fetch_failed')
+    rescue Faraday::Error => e
+      raise JwksCacheError.new("JWKS fetch failed: #{e.message}", code: 'jwks_fetch_failed')
+    rescue JSON::ParserError
+      raise JwksCacheError.new('Response is not valid JSON', code: 'jwks_parse_failed')
+    rescue StandardError => e
+      raise JwksCacheError.new("Unexpected JWKS fetch error: #{e.message}", code: 'jwks_fetch_failed')
+    end
+
+    # @api private
+    # Builds conditional headers for revalidation.
+    # @return [Hash] `{ 'If-None-Match' => etag }` when present, otherwise `{}`.
+    def build_conditional_headers
+      @etag ? { 'If-None-Match' => @etag } : {}
+    end
+
+    # @api private
+    # True when cached keys are still fresh per `Cache-Control: max-age`.
+    # @return [Boolean]
+    def fresh_by_ttl?
+      return false unless @cached_keys && @fetched_at && @max_age
+
+      (Time.now - @fetched_at) < @max_age
+    end
+
+    # @api private
+    # Parses a `Cache-Control` header and extracts `max-age` in seconds.
+    #
+    # Ignores `no-store` / `no-cache`. Returns `nil` when `max-age` is not present or invalid.
+    #
+    # @param cache_control [String, nil]
+    # @return [Integer, nil] seconds
+    def extract_max_age(cache_control)
+      return nil unless cache_control
+
+      # Normalize and split directives
+      directives = cache_control.to_s.downcase.split(',').map(&:strip)
+      return nil if directives.include?('no-store') || directives.include?('no-cache')
+
+      max_age_directive = directives.find { |d| d.start_with?('max-age=') }
+      return nil unless max_age_directive
+
+      value = max_age_directive.split('=', 2)[1]
+      Integer(value)
+    rescue ArgumentError
+      nil
+    end
+
+    # @api private
+    # Parses the response body into JSON.
+    # @param body [#to_s]
+    # @return [Hash]
+    # @raise [JwksCacheError] when JSON is invalid
+    def parse_json!(body)
+      JSON.parse(body.to_s)
+    rescue JSON::ParserError
+      raise JwksCacheError.new('Response is not valid JSON', code: 'jwks_parse_failed')
+    end
+
+    # @api private
+    # Extracts and validates the `keys` array from a JWKS JSON document.
+    # Ensures each key has `kid`, `kty`, `n`, and `e`.
+    #
+    # @param json [Hash]
+    # @return [Array&lt;Hash&gt;]
+    # @raise [JwksCacheError] when structure or attributes are invalid
+    def extract_and_validate_keys!(json)
+      keys = json['keys']
+      unless keys.is_a?(Array)
+        raise JwksCacheError.new("Response does not contain 'keys' array",
+                                 code: 'jwks_parse_failed')
+      end
+
+      keys.each_with_index do |key, idx|
+        %w[kid kty n e].each do |attr|
+          raise JwksCacheError.new("JWK at index #{idx} missing '#{attr}'", code: 'jwks_parse_failed') unless key[attr]
+        end
+      end
+
+      keys
+    end
+
+    # @api private
+    # Updates cached keys and freshness metadata from a 200 OK response.
+    #
+    # @param response [Faraday::Response]
+    # @param keys [Array&lt;Hash&gt;]
+    # @return [void]
+    def update_cache_from_ok(response, keys)
+      @cached_keys = keys
+
+      new_etag = response.headers['etag']
+      @etag = new_etag if new_etag
+
+      cache_control = response.headers['cache-control']
+      @max_age      = extract_max_age(cache_control)
+      @fetched_at   = Time.now
+    end
+
+    # @api private
+    # Dispatches handling based on HTTP status.
+    # @param response [Faraday::Response]
+    # @return [Array&lt;Hash&gt;]
+    # @raise [JwksCacheError]
+    def handle_response(response)
+      case response.status
+      when 200
+        process_successful_response(response)
+      when 304
+        # Revalidation succeeded; update freshness from 304 headers if present
+        process_not_modified(response)
+      else
+        raise JwksCacheError.new("Failed to fetch JWKS: status #{response.status}", code: 'jwks_fetch_failed')
+      end
+    end
+
+    # @api private
+    # Handles a 200 OK JWKS response.
+    # @param response [Faraday::Response]
+    # @return [Array&lt;Hash&gt;] parsed and cached keys
+    def process_successful_response(response)
+      json = parse_json!(response.body)
+      keys = extract_and_validate_keys!(json)
+      update_cache_from_ok(response, keys)
+      keys
+    end
+
+    # @api private
+    # Handles a 304 Not Modified JWKS response: updates TTL and timestamp, returns cached keys.
+    # @param response [Faraday::Response]
+    # @return [Array&lt;Hash&gt;]
+    # @raise [JwksCacheError] when cache is empty
+    def process_not_modified(response)
+      # Update TTL from response headers (some servers include Cache-Control on 304)
+      cache_control = response.headers['cache-control']
+      @max_age      = extract_max_age(cache_control) || @max_age
+      @fetched_at   = Time.now if @cached_keys
+      return_from_cache_or_fail
+    end
+
+    # @api private
+    # Returns cached keys or raises when 304 is received without prior cache.
+    # @return [Array&lt;Hash&gt;]
+    # @raise [JwksCacheError]
+    def return_from_cache_or_fail
+      @cached_keys || raise(JwksCacheError.new('JWKS cache is empty but received 304 Not Modified',
+                                               code: 'jwks_cache_miss'))
+    end
+  end
+end

data/lib/verikloak/middleware.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require 'rack'
+require 'json'
+
+module Verikloak
+  # Internal helper mixin that encapsulates error-to-HTTP mapping logic
+  # used by {Verikloak::Middleware}. By extracting this mapping into a
+  # separate module, the middleware class remains shorter and easier to
+  # reason about.
+  #
+  # This module does not depend on Rack internals; it only interprets
+  # Verikloak error objects and their `code` attributes.
+  #
+  # @api private
+  module MiddlewareErrorMapping
+    # Set of token/client-side error codes that should map to **401 Unauthorized**.
+    # @return [Array<String>]
+    AUTH_ERROR_CODES = %w[
+      invalid_token expired_token not_yet_valid invalid_issuer invalid_audience
+      invalid_signature unsupported_algorithm missing_authorization_header invalid_authorization_header
+    ].freeze
+
+    # Set of middleware/infrastructure error codes that should map to **503 Service Unavailable**.
+    # @return [Array<String>]
+    INFRA_ERROR_CODES = %w[jwks_fetch_failed jwks_cache_miss].freeze
+
+    # @param code [String, nil] short error code
+    # @return [Boolean] true if the error should be treated as a 403 Forbidden
+    def forbidden?(code)
+      code == 'forbidden'
+    end
+
+    # @param code [String, nil]
+    # @return [Boolean] true if the error belongs to {AUTH_ERROR_CODES}
+    def auth_error?(code)
+      code && AUTH_ERROR_CODES.include?(code)
+    end
+
+    # Maps dependency-layer errors to a pair of `[code, http_status]`.
+    #
+    # @param error [Exception]
+    # @return [Array(String, Integer), nil] two-element tuple or nil when not applicable
+    def dependency_error_tuple(error)
+      if error.is_a?(Verikloak::DiscoveryError)
+        [error.code || 'discovery_error', 503]
+      elsif error.is_a?(Verikloak::JwksCacheError)
+        [error.code || 'jwks_error', 503]
+      end
+    end
+
+    # Maps middleware infrastructure errors to a pair of `[code, http_status]`.
+    #
+    # @param error [Exception]
+    # @param code [String, nil]
+    # @return [Array(String, Integer), nil]
+    def infra_error_tuple(error, code)
+      return unless error.is_a?(Verikloak::MiddlewareError) && code && INFRA_ERROR_CODES.include?(code)
+
+      [code, 503]
+    end
+
+    # Final mapping fallback when no other rule has handled the error.
+    #
+    # @param error [Exception]
+    # @param code [String, nil]
+    # @return [Array(String, Integer)] two-element tuple
+    def fallback_tuple(error, code)
+      case error
+      when Verikloak::TokenDecoderError
+        ['invalid_token', 401]
+      when Verikloak::MiddlewareError
+        [code || 'invalid_token', 401]
+      else
+        ['internal_server_error', 500]
+      end
+    end
+  end
+
+  # Rack middleware that verifies incoming JWT access tokens (Keycloak) using
+  # OpenID Connect discovery and JWKS. On success, it populates:
+  #
+  # * `env['verikloak.token']` — the raw JWT string
+  # * `env['verikloak.user']`  — the decoded JWT claims Hash
+  #
+  # Failures are converted to JSON error responses with appropriate status codes.
+  class Middleware
+    # @param app [#call] downstream Rack app
+    # @param discovery_url [String] OIDC discovery endpoint URL
+    # @param audience [String] Expected `aud` claim
+    # @param skip_paths [Array<String>] Literal paths or wildcard patterns to bypass auth
+    # @param discovery [Discovery, nil] Custom discovery instance (for DI/tests)
+    # @param jwks_cache [JwksCache, nil] Custom JWKS cache instance (for DI/tests)
+    def initialize(app,
+                   discovery_url:,
+                   audience:,
+                   skip_paths: [],
+                   discovery: nil,
+                   jwks_cache: nil)
+      @app           = app
+      @audience      = audience
+      @skip_paths    = skip_paths
+      @discovery     = discovery || Discovery.new(discovery_url: discovery_url)
+      @jwks_cache    = jwks_cache
+      @issuer        = nil
+      @mutex         = Mutex.new
+    end
+
+    # Rack entrypoint.
+    #
+    # @param env [Hash] Rack environment
+    # @return [Array(Integer, Hash, Array<String>)] standard Rack response
+    def call(env)
+      path = env['PATH_INFO']
+      return @app.call(env) if skip?(path)
+
+      token = extract_token(env)
+
+      handle_request(env, token)
+    rescue Verikloak::Error => e
+      code, status = map_error(e)
+      error_response(code, e.message, status)
+    rescue StandardError => e
+      log_internal_error(e)
+      error_response('internal_server_error', 'An unexpected error occurred', 500)
+    end
+
+    private
+
+    include MiddlewareErrorMapping
+
+    # Determines whether a token verification failure warrants a one-time JWKS refresh
+    # and retry (e.g., after key rotation).
+    #
+    # @param error [Exception]
+    # @return [Boolean]
+    # @api private
+    def retryable_decoder_error?(error)
+      return false unless error.is_a?(TokenDecoderError)
+
+      return true if error.code == 'invalid_signature'
+      return true if error.code == 'invalid_token' && error.message&.include?('Key with kid=')
+
+      false
+    end
+
+    # Ensures JWKS are up-to-date by invoking {#ensure_jwks_cache!}.
+    # Errors are not swallowed and are handled by the caller.
+    #
+    # @return [void]
+    # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError]
+    # @api private
+    def refresh_jwks!
+      # Ensure discovery has been performed so we have a jwks_cache instance.
+      ensure_jwks_cache!
+    end
+
+    # Checks whether the request path matches any skip pattern.
+    #
+    # Supported patterns:
+    # * `'/'` — matches only the root path
+    # * `'/foo/*'` — matches `/foo` itself and any nested path under it
+    # * `'/api/public'` — exact match only (no wildcard)
+    #
+    # @param path [String]
+    # @return [Boolean]
+    def skip?(path)
+      @skip_paths.any? do |pattern|
+        if pattern == '/'
+          path == '/'
+        elsif pattern.end_with?('/*')
+          prefix = pattern.chomp('/*')
+          path == prefix || path.start_with?("#{prefix}/")
+        else
+          path == pattern || path.start_with?("#{pattern}/")
+        end
+      end
+    end
+
+    # Verifies the token, stores result in Rack env, and forwards to the downstream app.
+    #
+    # @param env [Hash]
+    # @param token [String]
+    # @return [Array(Integer, Hash, Array<String>)]
+    def handle_request(env, token)
+      claims = decode_token(token)
+      env['verikloak.token'] = token
+      env['verikloak.user']  = claims
+      @app.call(env)
+    end
+
+    # Extracts the Bearer token from the `Authorization` header.
+    #
+    # @param env [Hash]
+    # @return [String] the raw JWT string
+    # @raise [Verikloak::MiddlewareError] when the header is missing or malformed
+    def extract_token(env)
+      auth = env['HTTP_AUTHORIZATION']
+      if auth.to_s.strip.empty?
+        raise MiddlewareError.new('Missing Authorization header',
+                                  code: 'missing_authorization_header')
+      end
+
+      scheme, token = auth.split(' ', 2)
+      unless scheme && token && scheme.casecmp('Bearer').zero?
+        raise MiddlewareError.new('Invalid Authorization header format', code: 'invalid_authorization_header')
+      end
+
+      token
+    end
+
+    # Decodes and verifies the JWT using the cached JWKS. On certain verification
+    # failures (e.g., key rotation), it refreshes the JWKS and retries once.
+    #
+    # @param token [String]
+    # @return [Hash] decoded JWT claims
+    # @raise [Verikloak::Error] bubbles up verification/fetch errors for centralized handling
+    def decode_token(token)
+      ensure_jwks_cache!
+      if @jwks_cache.cached.nil? || @jwks_cache.cached.empty?
+        raise MiddlewareError.new('JWKS cache is empty, cannot verify token', code: 'jwks_cache_miss')
+      end
+
+      # First attempt
+      decoder = TokenDecoder.new(
+        jwks: @jwks_cache.cached,
+        issuer: @issuer,
+        audience: @audience
+      )
+
+      begin
+        decoder.decode!(token)
+      rescue TokenDecoderError => e
+        # On key rotation or signature mismatch, refresh JWKS and retry once.
+        raise unless retryable_decoder_error?(e)
+
+        refresh_jwks!
+
+        # Rebuild decoder with refreshed keys and try once more.
+        decoder = TokenDecoder.new(
+          jwks: @jwks_cache.cached,
+          issuer: @issuer,
+          audience: @audience
+        )
+        decoder.decode!(token)
+      end
+    end
+
+    # Ensures that discovery metadata and JWKS cache are initialized and up-to-date.
+    # This method is thread-safe.
+    #
+    # * When the cache instance is missing, it is created from discovery metadata.
+    # * JWKS are (re)fetched every time; ETag/Cache-Control headers minimize traffic.
+    #
+    # @return [void]
+    # @raise [Verikloak::DiscoveryError, Verikloak::JwksCacheError, Verikloak::MiddlewareError]
+    def ensure_jwks_cache!
+      @mutex.synchronize do
+        if @jwks_cache.nil?
+          config   = @discovery.fetch!
+          @issuer  = config['issuer']
+          jwks_uri = config['jwks_uri']
+          @jwks_cache = JwksCache.new(jwks_uri: jwks_uri)
+        end
+
+        @jwks_cache.fetch!
+      end
+    rescue Verikloak::DiscoveryError, Verikloak::JwksCacheError => e
+      # Re-raise so that specific error codes can be mapped in the middleware
+      raise e
+    rescue StandardError => e
+      raise MiddlewareError.new("Failed to initialize JWKS cache: #{e.message}", code: 'jwks_fetch_failed')
+    end
+
+    # Converts a raised error into a `[code, http_status]` tuple for response rendering.
+    #
+    # @param error [Exception]
+    # @return [Array(String, Integer)]
+    def map_error(error)
+      code = error.respond_to?(:code) ? error.code : nil
+
+      return [code, 403] if forbidden?(code)
+      return [code, 401] if auth_error?(code)
+
+      if (dep = dependency_error_tuple(error))
+        return dep
+      end
+
+      if (infra = infra_error_tuple(error, code))
+        return infra
+      end
+
+      fallback_tuple(error, code)
+    end
+
+    # Builds a JSON error response with RFC 6750 `WWW-Authenticate` header for 401.
+    #
+    # @param code [String]
+    # @param message [String]
+    # @param status [Integer]
+    # @return [Array(Integer, Hash, Array<String>)] Rack response triple
+    def error_response(code = 'unauthorized', message = 'Unauthorized', status = 401)
+      body = { error: code, message: message }.to_json
+      headers = { 'Content-Type' => 'application/json' }
+      if status == 401
+        headers['WWW-Authenticate'] =
+          %(Bearer realm="verikloak", error="#{code}", error_description="#{message.gsub('"', '\\"')}")
+      end
+      [status, headers, [body]]
+    end
+
+    # Logs unexpected internal errors to STDERR (non-PII). Used for diagnostics only.
+    #
+    # @param error [Exception]
+    # @return [void]
+    # @api private
+    def log_internal_error(error)
+      warn "[verikloak] Internal error: #{error.class} - #{error.message}"
+      warn error.backtrace.join("\n") if error.backtrace
+    end
+  end
+end