verikloak-audience 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 983947348061c7b7dd379572850ec12de6bddda37b511b03466301b22c15256f
-  data.tar.gz: 2bd99a2a76fdc020d4f3a51a1db11151d0b38e9429847294f0431abb7e47dd17
+  metadata.gz: 0fb9e7977881b01b0bd15bad81ebf1a49e279ae3f5e2cefb9d978c6579c9fceb
+  data.tar.gz: 778b0260bb771b2e5d14f18b2cda54ce19567a5ee727f85ade281e8331170e44
 SHA512:
-  metadata.gz: 6bca90d90c7d35408009fcd6007ac317115743eda14dc4e8f1e9853a3fdb9350f4cb5db426e032631faf2e4ef9f96a86885942145bad40d7e809b5eb1a748905
-  data.tar.gz: 3bcc1d7a44a094a3e15d8b33e79fe46ac66e21eb84175799d0469f701522949340e82b43df0d6e029a7396febc9c0ab16a196efdc1cce6bb25358b674019463e
+  metadata.gz: 26a8bfcc5c5d714b1376dd88b4e7a27c530806f6d935f8d2b3665b3c7c52d7345782ad1df40a3d7fb63b912e899aa33f27e79ddb6b39c05074b256dfd0c99fe0
+  data.tar.gz: 359a268c4ad3567c83dc93f1a6a348f8a8b8c22cb0067fced9c1473cd9285a7b7bb64b4a10b09d397b4de305a28221678238da1bdc7c0adb4ccf2632a18d0232

data/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.0] - 2025-09-21
+
+### Added
+- README "Operational safeguards" section covering startup validation, logger precedence, and `:resource_or_aud` alignment guidance.
+- YARD documentation for configuration helpers and middleware logging routines.
+
+### Changed
+- Tightened `resource_client` inference/validation to enforce alignment with `required_aud` and infer single-entry clients automatically.
+- Prefer request-scoped loggers over `Kernel#warn` when emitting audience failure messages.
+- Bumped runtime dependency to `verikloak >= 0.1.5` to pick up shared logger support.
+- Improved Rails Railtie test harness to mimic real initializer registration.
+
+## [0.1.1] - 2025-09-20
+
+### Changed
+- Documented `Configuration#safe_dup` behaviour and tightened duplication semantics.
+- Expanded error class YARD docs to clarify operational response codes.
+
 ## [0.1.0] - 2025-09-20
 
 ### Added

data/README.md

@@ -1,5 +1,10 @@
 # verikloak-audience
 
+[![CI](https://github.com/taiyaky/verikloak-audience/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/taiyaky/verikloak-audience/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/verikloak-audience)](https://rubygems.org/gems/verikloak-audience)
+![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.1-blue)
+[![Downloads](https://img.shields.io/gem/dt/verikloak-audience)](https://rubygems.org/gems/verikloak-audience)
+
 Rack middleware for validating the `aud` claim of Keycloak-issued tokens on top of the Verikloak stack. It ships with deploy-friendly presets that address common Keycloak patterns such as `account` co-existence and `resource_access`-driven role enforcement.
 
 For the full error behaviour (response shapes, exception classes, logging hints), see [ERRORS.md](ERRORS.md).
@@ -53,6 +58,11 @@ See [`examples/rack.ru`](examples/rack.ru) for a full Rack sample. In Rails, alw
 
 `env_claims_key` assumes the preceding `Verikloak::Middleware` populates the Rack env. If the middleware order changes, claims will be missing and the audience check will always reject.
 
+### Operational safeguards
+- Middleware initialisation now fails fast when `required_aud` is empty. When Rails loads via the supplied Railtie, `Verikloak::Audience.config.validate!` runs after boot so configuration mistakes surface during startup instead of returning 403 for every request.
+- When audience validation fails, the middleware consults `env['verikloak.logger']`, `env['rack.logger']`, and `env['action_dispatch.logger']` (in that order) before falling back to Ruby's `Kernel#warn`, keeping failure logs consistent with Rails and Verikloak observers.
+- For the `:resource_or_aud` profile, `resource_client` must match one of the values in `required_aud`. A single-element `required_aud` automatically infers the client id, ensuring the same client identifier is shared with downstream BFF/Pundit integrations.
+
 ## Testing
 All pull requests and pushes are automatically tested with [RSpec](https://rspec.info/) and [RuboCop](https://rubocop.org/) via GitHub Actions.
 See the CI badge at the top for current build status.

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'verikloak/audience/errors'
+
 module Verikloak
   module Audience
     # Configuration holder for verikloak-audience.
@@ -20,8 +22,11 @@ module Verikloak
     #   Whether to log a suggestion when audience validation fails.
     #   @return [Boolean]
     class Configuration
+      DEFAULT_RESOURCE_CLIENT = 'rails-api'
+
       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.
       #
@@ -29,17 +34,122 @@ module Verikloak
       def initialize
         @profile         = :strict_single
         @required_aud    = []
-        @resource_client = 'rails-api'
-        @env_claims_key  = 'verikloak.user'
+        @resource_client = DEFAULT_RESOURCE_CLIENT
+        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
+
+      # Validate the configuration to ensure required values are present.
+      #
+      # @return [Configuration] the validated configuration
+      def validate!
+        audiences = required_aud_list
+        if audiences.empty?
+          raise Verikloak::Audience::ConfigurationError,
+                'required_aud must include at least one audience'
+        end
+
+        profile_name = profile
+        profile_name = profile_name.to_sym if profile_name.respond_to?(:to_sym)
+        profile_name ||= :strict_single
+
+        ensure_resource_client!(audiences) if profile_name == :resource_or_aud
+
+        self
+      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
+
+      # Build a deep-ish copy of `required_aud` so that mutations on copies
+      # do not leak back into the original configuration instance.
+      #
+      # @param value [Array<String,Symbol>, String, Symbol, nil]
+      # @return [Array<String,Symbol>, String, Symbol, nil]
+      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
+
+      # Ensure that the configured `resource_client` fits the `required_aud`
+      # list when the :resource_or_aud profile is active. Attempts to infer
+      # the client id from `required_aud` when possible and raises when
+      # ambiguity remains.
+      #
+      # @param audiences [Array<String>] coerced required audiences
+      # @return [void]
+      def ensure_resource_client!(audiences)
+        client = resource_client.to_s
+
+        needs_inference = needs_resource_client_inference?(client, audiences)
+
+        if needs_inference
+          if audiences.one?
+            self.resource_client = audiences.first
+            client = resource_client.to_s
+          else
+            raise Verikloak::Audience::ConfigurationError,
+                  'resource_client must match one of required_aud when using :resource_or_aud profile'
+          end
+        end
+
+        return if audiences.include?(client)
+
+        raise Verikloak::Audience::ConfigurationError,
+              'resource_client must match one of required_aud when using :resource_or_aud profile'
+      end
+
+      # Decide whether the resource client should be inferred from the
+      # required audiences based on the current client value.
+      #
+      # @param client [String]
+      # @param audiences [Array<String>]
+      # @return [Boolean]
+      def needs_resource_client_inference?(client, audiences)
+        client.empty? ||
+          (client == DEFAULT_RESOURCE_CLIENT && !audiences.include?(client))
+      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,8 +22,9 @@ 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)
+        @config.validate!
       end
 
       # Evaluate the request against the audience profile.
@@ -31,13 +32,15 @@ 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
           suggestion = Checker.suggest(claims, @config)
           aud_view = Array(claims['aud']).inspect
-          warn("[verikloak-audience] insufficient_audience; suggestion profile=:#{suggestion} aud=#{aud_view}")
+          log_warning(env,
+                      "[verikloak-audience] insufficient_audience; suggestion profile=:#{suggestion} aud=#{aud_view}")
         end
 
         body = { error: 'insufficient_audience',
@@ -50,12 +53,35 @@ module Verikloak
 
       # Apply provided options to the configuration instance.
       #
-      # @param opts [Hash]
+      # @param opts [Hash] raw overrides provided to the middleware
       # @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
+
+      # Emit a warning for failed audience checks using request-scoped loggers
+      # when available.
+      #
+      # @param env [Hash] Rack environment
+      # @param message [String] warning payload
+      # @return [void]
+      def log_warning(env, message)
+        logger = env['verikloak.logger'] || env['rack.logger'] || env['action_dispatch.logger']
+        if logger.respond_to?(:warn)
+          logger.warn(message)
+        else
+          warn(message)
         end
       end
     end

data/lib/verikloak/audience/railtie.rb

@@ -33,6 +33,12 @@ module Verikloak
         self.class.insert_middleware(app)
       end
 
+      initializer 'verikloak_audience.configuration' do
+        config.after_initialize do
+          Verikloak::Audience.config.validate!
+        end
+      end
+
       # Performs the insertion into the middleware stack when the core
       # Verikloak middleware is available. Extracted for testability without
       # requiring a full Rails boot process.

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.2.0'
   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.2.0
 platform: ruby
 authors:
 - taiyaky
@@ -35,20 +35,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.1.5
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: 1.0.0
 description: |
   Rack middleware that enforces audience checks with deployable profiles,
   layering on top of Verikloak token verification.
@@ -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.2.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: