verikloak-audience 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 983947348061c7b7dd379572850ec12de6bddda37b511b03466301b22c15256f
-  data.tar.gz: 2bd99a2a76fdc020d4f3a51a1db11151d0b38e9429847294f0431abb7e47dd17
+  metadata.gz: 5ff2e2e97325963725431051763d956fad12ae1b2ea04476d849a8f1d085e8e6
+  data.tar.gz: c9ca99b0c0b0c0089abc3f854a8a50234000d27a93ae7092f322ac1c2283e59e
 SHA512:
-  metadata.gz: 6bca90d90c7d35408009fcd6007ac317115743eda14dc4e8f1e9853a3fdb9350f4cb5db426e032631faf2e4ef9f96a86885942145bad40d7e809b5eb1a748905
-  data.tar.gz: 3bcc1d7a44a094a3e15d8b33e79fe46ac66e21eb84175799d0469f701522949340e82b43df0d6e029a7396febc9c0ab16a196efdc1cce6bb25358b674019463e
+  metadata.gz: 36f0c7cbddc7fcc7f2eea2a90743a5c7abd9a3d03b9f279a0bf35c99e77557af8f579e847c5169c56ecdc50794f5b99058eecc866565f03f2796e6e5a694e243
+  data.tar.gz: 6e908e9720198cf36a40b91bd3b345c6ed622805cf7d10b53af0dd94c76a137fa94b64f66d7858aa1a7c007612445154c9c0a61a445eaa3930fd72a313b4febf

data/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.1.1] - 2025-09-20
+
+### Changed
+- Documented `Configuration#safe_dup` behaviour and error handling in YARD.
+- Expanded error class documentation for clearer release guidance.
+
 ## [0.1.0] - 2025-09-20
 
 ### Added

data/lib/verikloak/audience/checker.rb

@@ -7,6 +7,8 @@ module Verikloak
     # This module provides predicate helpers used by the middleware to decide
     # whether a given set of claims satisfies the configured profile.
     module Checker
+      VALID_PROFILES = %i[strict_single allow_account resource_or_aud].freeze
+
       module_function
 
       # Returns whether the given claims satisfy the configured profile.
@@ -15,8 +17,16 @@ module Verikloak
       # @param cfg [Verikloak::Audience::Configuration]
       # @return [Boolean]
       def ok?(claims, cfg)
-        profile = cfg.profile.to_sym
-        profile = :strict_single unless %i[strict_single allow_account resource_or_aud].include?(profile)
+        claims = normalize_claims(claims)
+
+        profile = cfg.profile
+        profile = profile.to_sym if profile.respond_to?(:to_sym)
+        profile = :strict_single if profile.nil?
+
+        unless VALID_PROFILES.include?(profile)
+          raise Verikloak::Audience::ConfigurationError,
+                "unknown audience profile #{cfg.profile.inspect}"
+        end
 
         case profile
         when :strict_single
@@ -77,6 +87,8 @@ module Verikloak
       # @param cfg [Verikloak::Audience::Configuration]
       # @return [:strict_single, :allow_account, :resource_or_aud]
       def suggest(claims, cfg)
+        claims = normalize_claims(claims)
+
         aud = Array(claims['aud']).map(&:to_s)
         req = cfg.required_aud_list
         has_roles = !Array(claims.dig('resource_access', cfg.resource_client.to_s, 'roles')).empty?
@@ -87,6 +99,27 @@ module Verikloak
 
         :strict_single
       end
+
+      # Normalize incoming claims to a Hash to guard against unexpected
+      # env payloads or middleware ordering issues.
+      #
+      # @param claims [Object]
+      # @return [Hash]
+      def normalize_claims(claims)
+        return {} if claims.nil?
+        return claims if claims.is_a?(Hash)
+
+        if claims.respond_to?(:to_hash)
+          coerced = claims.to_hash
+          return coerced if coerced.is_a?(Hash)
+        end
+
+        {}
+      rescue StandardError
+        {}
+      end
+      module_function :normalize_claims
+      private_class_method :normalize_claims
     end
   end
 end

data/lib/verikloak/audience/configuration.rb

@@ -21,7 +21,8 @@ module Verikloak
     #   @return [Boolean]
     class Configuration
       attr_accessor :profile, :required_aud, :resource_client,
-                    :env_claims_key, :suggest_in_logs
+                    :suggest_in_logs
+      attr_reader :env_claims_key
 
       # Create a configuration with safe defaults.
       #
@@ -30,16 +31,58 @@ module Verikloak
         @profile         = :strict_single
         @required_aud    = []
         @resource_client = 'rails-api'
-        @env_claims_key  = 'verikloak.user'
+        self.env_claims_key = 'verikloak.user'
         @suggest_in_logs = true
       end
 
+      # Ensure `dup` produces an independent copy.
+      #
+      # @param source [Configuration]
+      # @return [void]
+      def initialize_copy(source)
+        super
+        @profile         = safe_dup(source.profile)
+        @required_aud    = duplicate_required_aud(source.required_aud)
+        @resource_client = safe_dup(source.resource_client)
+        self.env_claims_key = safe_dup(source.env_claims_key)
+        @suggest_in_logs = source.suggest_in_logs
+      end
+
       # Coerce `required_aud` into an array of strings.
       #
       # @return [Array<String>]
       def required_aud_list
         Array(required_aud).map(&:to_s)
       end
+
+      # @param value [#to_s, nil]
+      # @return [void]
+      def env_claims_key=(value)
+        @env_claims_key = value&.to_s
+      end
+
+      private
+
+      # Attempt to duplicate a value while tolerating non-duplicable inputs.
+      # Returns `nil` when given nil and falls back to the original on duplication errors.
+      #
+      # @param value [Object, nil]
+      # @return [Object, nil]
+      def safe_dup(value)
+        return if value.nil?
+
+        value.dup
+      rescue TypeError
+        value
+      end
+
+      def duplicate_required_aud(value)
+        return if value.nil?
+
+        return value.map { |item| safe_dup(item) } if value.is_a?(Array)
+
+        safe_dup(value)
+      end
     end
   end
 end

data/lib/verikloak/audience/errors.rb

@@ -23,12 +23,30 @@ module Verikloak
       end
     end
 
-    # Raised when audience is insufficient for the configured profile.
+    # Raised when verified claims do not satisfy the configured profile.
+    # Typically emitted when the required audience list is empty or
+    # mismatches the token audiences.
     class Forbidden < Error
-      # @param msg [String]
+      # Build a forbidden error with a customizable message while preserving
+      # the standard machine-friendly code and HTTP status.
+      #
+      # @param msg [String] alternate human-readable explanation
       def initialize(msg = 'insufficient audience')
         super(msg, code: 'insufficient_audience', http_status: 403)
       end
     end
+
+    # Raised when configuration is invalid.
+    # Used when runtime configuration checks detect missing or incompatible
+    # values before audience validation takes place.
+    class ConfigurationError < Error
+      # Build a configuration error while keeping a consistent error code
+      # and a 500 HTTP status to signal an internal misconfiguration.
+      #
+      # @param msg [String] alternate human-readable explanation
+      def initialize(msg = 'invalid audience configuration')
+        super(msg, code: 'audience_configuration_error', http_status: 500)
+      end
+    end
   end
 end

data/lib/verikloak/audience/middleware.rb

@@ -22,7 +22,7 @@ module Verikloak
       # @option opts [Boolean] :suggest_in_logs
       def initialize(app, **opts)
         @app = app
-        @config = Verikloak::Audience.configure
+        @config = Verikloak::Audience.config.dup
         apply_overrides!(opts)
       end
 
@@ -31,7 +31,8 @@ module Verikloak
       # @param env [Hash] Rack environment
       # @return [Array(Integer, Hash, #each)] Rack response triple
       def call(env)
-        claims = env[@config.env_claims_key] || {}
+        env_key = @config.env_claims_key
+        claims = env[env_key] || env[env_key&.to_sym] || {}
         return @app.call(env) if Checker.ok?(claims, @config)
 
         if @config.suggest_in_logs
@@ -54,8 +55,16 @@ module Verikloak
       # @return [void]
       def apply_overrides!(opts)
         cfg = @config
+        opts.each_key do |key|
+          writer = "#{key}="
+          next if cfg.respond_to?(writer)
+
+          raise Verikloak::Audience::ConfigurationError,
+                "unknown middleware option :#{key}"
+        end
+
         opts.each do |k, v|
-          cfg.public_send("#{k}=", v) if cfg.respond_to?("#{k}=")
+          cfg.public_send("#{k}=", v)
         end
       end
     end

data/lib/verikloak/audience/version.rb

@@ -4,6 +4,6 @@ module Verikloak
   module Audience
     # Current gem version.
     # @return [String]
-    VERSION = '0.1.0'
+    VERSION = '0.1.1'
   end
 end

metadata

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