verikloak-audience 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ff2e2e97325963725431051763d956fad12ae1b2ea04476d849a8f1d085e8e6
-  data.tar.gz: c9ca99b0c0b0c0089abc3f854a8a50234000d27a93ae7092f322ac1c2283e59e
+  metadata.gz: f7b437ab60e6ddce3b76539ce7806633ef21509c2541d645ad1040ff0d840cd0
+  data.tar.gz: 3f181a7ffe9aef9973e27aee57ce14840937eb16dc7a2dcf00951b30115d367d
 SHA512:
-  metadata.gz: 36f0c7cbddc7fcc7f2eea2a90743a5c7abd9a3d03b9f279a0bf35c99e77557af8f579e847c5169c56ecdc50794f5b99058eecc866565f03f2796e6e5a694e243
-  data.tar.gz: 6e908e9720198cf36a40b91bd3b345c6ed622805cf7d10b53af0dd94c76a137fa94b64f66d7858aa1a7c007612445154c9c0a61a445eaa3930fd72a313b4febf
+  metadata.gz: 58bf73692f747dd60d6e8da0985fde737202152df279fe56d3eeecd684846e4ea3bb186583d735dc709b8a048b27a40709cb7bbd2c133e992eacadb306c22f69
+  data.tar.gz: 9b2d528270ebe27dc89a4c0d78f915ef43956e535f3d0cf9a40e2452e112136aaa654b31df97045d2a49f32e68b4ad51bd1217769f2cde725cd9bb790780a54e

data/CHANGELOG.md

@@ -7,11 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.1] - 2025-09-22
+
+### Fixed
+- Skip configuration validation while Rails generators run so `rails g verikloak:install` can execute before `required_aud` is configured.
+
+## [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 error handling in YARD.
-- Expanded error class documentation for clearer release guidance.
+- 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
 

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/configuration.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'verikloak/audience/errors'
+
 module Verikloak
   module Audience
     # Configuration holder for verikloak-audience.
@@ -20,6 +22,8 @@ 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,
                     :suggest_in_logs
       attr_reader :env_claims_key
@@ -30,7 +34,7 @@ module Verikloak
       def initialize
         @profile         = :strict_single
         @required_aud    = []
-        @resource_client = 'rails-api'
+        @resource_client = DEFAULT_RESOURCE_CLIENT
         self.env_claims_key = 'verikloak.user'
         @suggest_in_logs = true
       end
@@ -61,6 +65,25 @@ module Verikloak
         @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.
@@ -76,6 +99,11 @@ module Verikloak
         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?
 
@@ -83,6 +111,45 @@ module Verikloak
 
         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/middleware.rb

@@ -24,6 +24,7 @@ module Verikloak
         @app = app
         @config = Verikloak::Audience.config.dup
         apply_overrides!(opts)
+        @config.validate!
       end
 
       # Evaluate the request against the audience profile.
@@ -38,7 +39,8 @@ module Verikloak
         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',
@@ -51,7 +53,7 @@ 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
@@ -67,6 +69,21 @@ module Verikloak
           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
   end
 end

data/lib/verikloak/audience/railtie.rb

@@ -33,6 +33,14 @@ module Verikloak
         self.class.insert_middleware(app)
       end
 
+      initializer 'verikloak_audience.configuration' do
+        config.after_initialize do
+          next if Verikloak::Audience::Railtie.skip_configuration_validation?
+
+          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.
@@ -44,6 +52,35 @@ module Verikloak
 
         app.middleware.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
       end
+
+      COMMANDS_SKIPPING_VALIDATION = %w[generate g destroy d].freeze
+
+      # Detect whether Rails is currently executing a generator-style command.
+      # Generators boot the application before configuration exists, so we
+      # temporarily skip validation to let the install task complete.
+      #
+      # @return [Boolean]
+      def self.skip_configuration_validation?
+        return false unless defined?(Rails::Generators)
+
+        command = first_rails_command
+        COMMANDS_SKIPPING_VALIDATION.include?(command)
+      end
+
+      # Capture the first non-option argument passed to the Rails CLI,
+      # ignoring wrapper tokens such as "rails".
+      #
+      # @return [String, nil]
+      def self.first_rails_command
+        ARGV.each do |arg|
+          next if arg.start_with?('-')
+          next if arg == 'rails'
+
+          return arg
+        end
+
+        nil
+      end
     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.1'
+    VERSION = '0.2.1'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-audience
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - taiyaky
@@ -35,20 +35,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.2
+        version: 0.2.0
     - - "<"
       - !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.2.0
     - - "<"
       - !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.1
+  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.2.1
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: