verikloak 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41b02d67b2d6182f8af59436549e9d68cccf08559ecdee0539793ee3baef77a7
-  data.tar.gz: 5cd807c55d6635370149cf0090644698f470d15c9e01dc78a9332adb6659e2f8
+  metadata.gz: d175a574b17bd1ce5e096dbb69769d12a470f49c8444a5246881afd61d06fa52
+  data.tar.gz: 3c59a660bb142c194b6e0db2d338952c41c8a88afc479382203b4d767ab7691c
 SHA512:
-  metadata.gz: eba3a601c8c67080326955bd0557cfcc8d8098469694ef42ffac590b10a91c48cf4c3cb7250645d6db39e8208a8a05bd0bfa8b59cbdb9ced6e57e55241aa4da1
-  data.tar.gz: 553050d22b04de79bac27c00358f2c1a0779d380556297ffa2ca7bb5fa1944fe9ee55f9450ccc52cf004c7899c880484457b703d149404e80097079fff303341
+  metadata.gz: 92edd8a2df134f115c3f887683246278c5778291bb86bfff22ebc873b2b92d6ff09d9c85a1f798e2f49caa09adc8c3ef18ffc83309f95799997ebbdb54b58228
+  data.tar.gz: 0e223f0055e69448899be53fc22c9ac32c5d43c410aa041daa38761ed13a00aae8d655bcb6eaff521927a5a029937fcd480c7b90dcfccddf8e6b028aaf0bf555

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.0] - 2025-09-22
+
+### Added
+- Middleware options `token_env_key` and `user_env_key` for customizing where the token and decoded claims are stored in the Rack env.
+- Middleware option `realm` to change the `WWW-Authenticate` realm value emitted on 401 responses.
+- Middleware option `logger` so unexpected internal errors can be sent to the host application's logger instead of STDERR.
+
+### Changed
+- Update gem version to 0.2.0 to stay aligned with the rest of the Verikloak ecosystem gems.
+
+---
+
 ## [0.1.5] - 2025-09-21
 
 ### Added

data/README.md

@@ -94,6 +94,26 @@ config.middleware.use Verikloak::Middleware,
 ```
 This makes the configuration secure and flexible across environments.
 
+#### Advanced middleware options
+
+`Verikloak::Middleware` exposes a few optional knobs that help integrate with
+different Rack stacks:
+
+- `token_env_key` (default: `"verikloak.token"`) — where the raw JWT is stored in the Rack env
+- `user_env_key` (default: `"verikloak.user"`) — where decoded claims are stored
+- `realm` (default: `"verikloak"`) — value used in the `WWW-Authenticate` header for 401 responses
+- `logger` — an object responding to `error` (and optionally `debug`) that receives unexpected 500-level failures
+
+```ruby
+config.middleware.use Verikloak::Middleware,
+  discovery_url: ENV.fetch("DISCOVERY_URL"),
+  audience: ENV.fetch("CLIENT_ID"),
+  token_env_key: "rack.session.token",
+  user_env_key: "rack.session.claims",
+  realm: "my-api",
+  logger: Rails.logger
+```
+
 ### Accessing claims in controllers
 
 Once the middleware is enabled, Verikloak adds the decoded token and raw JWT to the Rack environment.  

data/lib/verikloak/middleware.rb

@@ -349,6 +349,10 @@ module Verikloak
     include SkipPathMatcher
     include MiddlewareTokenVerification
 
+    DEFAULT_REALM = 'verikloak'
+    DEFAULT_TOKEN_ENV_KEY = 'verikloak.token'
+    DEFAULT_USER_ENV_KEY = 'verikloak.user'
+
     # @param app [#call] downstream Rack app
     # @param discovery_url [String] OIDC discovery endpoint URL
     # @param audience [String, #call] Expected `aud` claim. When a callable is provided it
@@ -362,6 +366,7 @@ module Verikloak
     # @param token_verify_options [Hash] Additional JWT verification options passed through
     #   to TokenDecoder.
     #   e.g., { verify_iat: false, leeway: 10 }
+    # rubocop:disable Metrics/ParameterLists
     def initialize(app,
                    discovery_url:,
                    audience:,
@@ -370,7 +375,11 @@ module Verikloak
                    jwks_cache: nil,
                    connection: nil,
                    leeway: Verikloak::TokenDecoder::DEFAULT_LEEWAY,
-                   token_verify_options: {})
+                   token_verify_options: {},
+                   token_env_key: DEFAULT_TOKEN_ENV_KEY,
+                   user_env_key: DEFAULT_USER_ENV_KEY,
+                   realm: DEFAULT_REALM,
+                   logger: nil)
       @app             = app
       @connection      = connection || Verikloak::HTTP.default_connection
       @audience_source = audience
@@ -381,9 +390,14 @@ module Verikloak
       @issuer        = nil
       @mutex         = Mutex.new
       @decoder_cache = {}
+      @token_env_key = normalize_env_key(token_env_key, 'token_env_key')
+      @user_env_key  = normalize_env_key(user_env_key, 'user_env_key')
+      @realm         = normalize_realm(realm)
+      @logger        = logger
 
       compile_skip_paths(skip_paths)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Rack entrypoint.
     #
@@ -418,8 +432,8 @@ module Verikloak
     # @return [Array(Integer, Hash, Array<String>)] Rack response triple
     def handle_request(env, token)
       claims = decode_token(env, token)
-      env['verikloak.token'] = token
-      env['verikloak.user']  = claims
+      env[@token_env_key] = token
+      env[@user_env_key]  = claims
       @app.call(env)
     end
 
@@ -475,7 +489,7 @@ module Verikloak
       headers = { 'Content-Type' => 'application/json' }
       if status == 401
         headers['WWW-Authenticate'] =
-          %(Bearer realm="verikloak", error="#{code}", error_description="#{message.gsub('"', '\\"')}")
+          %(Bearer realm="#{@realm}", error="#{code}", error_description="#{message.gsub('"', '\\"')}")
       end
       [status, headers, [body]]
     end
@@ -485,8 +499,62 @@ module Verikloak
     # @param error [Exception]
     # @return [void]
     def log_internal_error(error)
-      warn "[verikloak] Internal error: #{error.class} - #{error.message}"
-      warn error.backtrace.join("\n") if error.backtrace
+      message = "[verikloak] Internal error: #{error.class} - #{error.message}"
+      backtrace = error.backtrace&.join("\n")
+
+      if logger_available?
+        log_with_logger(message, backtrace)
+      else
+        warn message
+        warn backtrace if backtrace
+      end
+    end
+
+    def logger_available?
+      return false unless @logger
+
+      @logger.respond_to?(:error) || @logger.respond_to?(:warn) || @logger.respond_to?(:debug)
+    end
+
+    def log_with_logger(message, backtrace)
+      log_message(@logger, message)
+      log_backtrace(@logger, backtrace)
+    end
+
+    def log_message(logger, message)
+      if logger.respond_to?(:error)
+        logger.error(message)
+      elsif logger.respond_to?(:warn)
+        logger.warn(message)
+      end
+    end
+
+    def log_backtrace(logger, backtrace)
+      return unless backtrace
+
+      if logger.respond_to?(:debug)
+        logger.debug(backtrace)
+      elsif logger.respond_to?(:error)
+        logger.error(backtrace)
+      elsif logger.respond_to?(:warn)
+        logger.warn(backtrace)
+      end
+    end
+
+    def normalize_env_key(value, option_name)
+      normalized = value.to_s.strip
+      raise ArgumentError, "#{option_name} cannot be blank" if normalized.empty?
+
+      normalized
+    end
+
+    def normalize_realm(value)
+      return DEFAULT_REALM if value.nil?
+
+      normalized = value.to_s.strip
+      raise ArgumentError, 'realm cannot be blank' if normalized.empty?
+
+      normalized
     end
   end
 end

data/lib/verikloak/version.rb

@@ -2,5 +2,5 @@
 
 module Verikloak
   # Defines the current version of the Verikloak gem.
-  VERSION = '0.1.5'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.2.0
 platform: ruby
 authors:
 - taiyaky
@@ -109,7 +109,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak
   changelog_uri: https://github.com/taiyaky/verikloak/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak/0.1.5
+  documentation_uri: https://rubydoc.info/gems/verikloak/0.2.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: