verikloak-bff 0.2.6 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edf579dc8e103482358c6ef7577c90c0b4aa24ae53b31c0c82bf89e5ffb4a68a
-  data.tar.gz: b976af45f7ffef721bd69263ed29cafaea1fdd711a1f94fff75a0045af8fc648
+  metadata.gz: 8a79baf28ee05a8774b36916c71281bd72cd35825148413c15e9f865b85416cb
+  data.tar.gz: 739244544590c0f306eff4d587c27c312adc4c081646a45d2ec4a58e83ce6abb
 SHA512:
-  metadata.gz: 2354503e6faf4768d680057ae347e44d5e0eadfe29ef49f01585a0db859addcb53f881e49f73956e07721799534ac444c2ae13f6c9ac93983256d4d61bdaad0d
-  data.tar.gz: 6543a6dd768d1cd2d11fe71a976dcbbd52bd1ad40021177a7b798dfd4b20b9560384b13cc1f1adb861b61865f5a076b746999d7939b225b65a54bda2249106dd
+  metadata.gz: 713b4e27ee284e38917a6fd4880414cdb8792fbffd4f7713112d2fa619f5ecf3120379a4a0b29eb115ce075c6373e0a4b25f1bca38bd8e8af0ff683944dcd8fd
+  data.tar.gz: ed258207b16fdb79fb079656393e0f7fd4bc1a650d942c6c19060c0aeaf45f8e63fa393a115bb8f80ea87f9c0d84cd025bb55a5ffb5259a981007211c896b786

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.3.0] - 2025-01-01
+
+### Added
+- **`disabled` configuration option**: Explicitly disable the middleware in pass-through mode. When `disabled: false` (default) and `trusted_proxies` is not configured, a `ConfigurationError` is raised at startup.
+
+### Changed
+- **BREAKING**: `trusted_proxies` is now **required** when `disabled: false`. Previously, an empty `trusted_proxies` would silently disable the middleware (fail-open). Now it raises `Verikloak::BFF::HeaderGuard::ConfigurationError` to prevent unintended security gaps.
+
+### Fixed
+- **Security**: Prevent fail-open vulnerability where unset `trusted_proxies` could silently bypass proxy trust validation.
+
+---
+
 ## [0.2.6] - 2025-12-31
 
 ### Fixed

data/README.md

@@ -42,7 +42,7 @@ Run the install generator to create a configuration file:
 bin/rails g verikloak:bff:install
 ```
 
-The generator creates `config/initializers/verikloak_bff.rb` with BFF configuration options. **Edit this file to set `trusted_proxies`** (required) and customize other options as needed.
+The generator creates `config/initializers/verikloak_bff.rb` with BFF configuration options. **Edit this file to set `trusted_proxies`** (required unless `disabled: true`) and customize other options as needed.
 
 **Note**: Middleware insertion is handled automatically by `verikloak-rails`. The generated initializer only contains configuration—no manual middleware setup is required.
 
@@ -69,7 +69,8 @@ See `examples/rack.ru` for a tiny Rack app demo.
 
 | Key                          | Type                                 | Default      | Description |
 |----------------------------- |--------------------------------------|--------------|-------------|
-| `trusted_proxies`            | Array[String/Regexp/Proc]            | *(required)* | Allowlist for proxy peers (by IP/CIDR/regex/proc). |
+| `disabled`                   | Boolean                              | `false`      | Explicitly disable the middleware (pass-through mode). When `false`, `trusted_proxies` must be configured. |
+| `trusted_proxies`            | Array[String/Regexp/Proc]            | *(required)* | Allowlist for proxy peers (by IP/CIDR/regex/proc). **Required** unless `disabled: true`. |
 | `prefer_forwarded`           | Boolean                              | `true`       | Prefer `X-Forwarded-Access-Token` over `Authorization`. |
 | `require_forwarded_header`   | Boolean                              | `false`      | Reject when no `X-Forwarded-Access-Token` (blocks direct access). |
 | `enforce_header_consistency` | Boolean                              | `true`       | If both headers exist, require identical token values. |
@@ -84,6 +85,19 @@ See `examples/rack.ru` for a tiny Rack app demo.
 | `forwarded_header_name`      | String                               | `HTTP_X_FORWARDED_ACCESS_TOKEN` | Env key for forwarded access token. |
 | `auth_request_headers`       | Hash                                 | see code     | Mapping for `X-Auth-Request-*` env keys: `{ email, user, groups }`. |
 
+### Configuration Requirements
+
+When `disabled: false` (the default), you **must** configure `trusted_proxies`. If it is not set, the middleware will raise a `ConfigurationError` at startup to prevent a fail-open security vulnerability.
+
+To explicitly disable the middleware (e.g., for development or testing), set `disabled: true`:
+
+```ruby
+# Pass-through mode: no proxy trust checking
+Verikloak::BFF.configure do |config|
+  config.disabled = true
+end
+```
+
 ## Errors
 This gem returns concise, RFC 6750–style error responses with stable codes. See [ERRORS.md](ERRORS.md) for details and examples.
 

data/lib/generators/verikloak/bff/install/templates/initializer.rb.erb

@@ -20,7 +20,18 @@
 #
 Verikloak::BFF.configure do |config|
   # ==========================================================================
-  # Trust Boundary (REQUIRED)
+  # Disable Middleware (Development/Testing Only)
+  # ==========================================================================
+  # Explicitly disable the middleware (pass-through mode).
+  # When disabled: false (default), trusted_proxies MUST be configured.
+  #
+  # SECURITY WARNING: Only set to true in development/test environments.
+  # Production deployments should ALWAYS configure trusted_proxies.
+  #
+  # config.disabled = ENV.fetch('VERIKLOAK_BFF_DISABLED', 'false') == 'true'
+
+  # ==========================================================================
+  # Trust Boundary (REQUIRED when disabled: false)
   # ==========================================================================
   # Allowlist for trusted proxy peers. Requests from untrusted peers are rejected.
   # Supports IP addresses, CIDR ranges, Regexp, or Proc.
@@ -28,6 +39,9 @@ Verikloak::BFF.configure do |config|
   # SECURITY: Keep this list as specific as possible. Review whenever proxy
   # topology changes to avoid unintentionally widening the trust boundary.
   #
+  # NOTE: This setting is REQUIRED. If not configured and disabled is false,
+  # a ConfigurationError will be raised at startup to prevent fail-open vulnerabilities.
+  #
   config.trusted_proxies = ENV.fetch('TRUSTED_PROXIES', '127.0.0.1').split(',').map(&:strip)
 
   # ==========================================================================

data/lib/verikloak/bff/configuration.rb

@@ -3,6 +3,8 @@
 # Configuration object for verikloak-bff. Holds middleware settings such as
 # proxy trust rules, header consistency policies, and logging options.
 #
+# @!attribute [rw] disabled
+#   @return [Boolean] explicitly disable the middleware (pass-through mode)
 # @!attribute [rw] trusted_proxies
 #   @return [Array<String, Regexp, Proc>] allowlist of trusted proxy peers
 # @!attribute [rw] prefer_forwarded
@@ -28,7 +30,7 @@ module Verikloak
   module BFF
     # Configuration for Verikloak::BFF middleware (trusted proxies, header policies, logging, etc.).
     class Configuration
-      attr_accessor :trusted_proxies, :prefer_forwarded, :require_forwarded_header,
+      attr_accessor :disabled, :trusted_proxies, :prefer_forwarded, :require_forwarded_header,
                     :enforce_header_consistency, :enforce_claims_consistency,
                     :strip_suspicious_headers, :xff_strategy, :clock_skew_leeway,
                     :logger, :peer_preference, :auth_request_headers, :log_with,
@@ -43,6 +45,7 @@ module Verikloak
       #
       # @return [void]
       def initialize
+        @disabled = false
         @trusted_proxies = []
         @prefer_forwarded = true
         @require_forwarded_header = false

data/lib/verikloak/bff/header_guard.rb

@@ -96,10 +96,78 @@ module Verikloak
       def sanitize_string(value)
         value.to_s.encode('UTF-8', invalid: :replace, undef: :replace, replace: '').gsub(LOG_CONTROL_CHARS, '')
       end
+
+      # Describe the source of the chosen token for logging purposes.
+      #
+      # @param prefer_forwarded [Boolean]
+      # @param auth_token [String, nil]
+      # @param fwd_token [String, nil]
+      # @return [String] "authorization" or "forwarded"
+      def token_source(prefer_forwarded, auth_token, fwd_token)
+        return 'forwarded' if prefer_forwarded && fwd_token
+
+        if auth_token && fwd_token
+          'authorization'
+        else
+          (auth_token ? 'authorization' : 'forwarded')
+        end
+      end
+
+      # Extract request id for logging from common headers.
+      #
+      # @param env [Hash]
+      # @return [String, nil]
+      def request_id(env)
+        env['HTTP_X_REQUEST_ID'] || env['action_dispatch.request_id']
+      end
+
+      # Emit a structured log line if a logger is present.
+      #
+      # @param env [Hash]
+      # @param config [Configuration]
+      # @param kind [Symbol] :ok, :mismatch, :claims_mismatch, :error
+      # @param attrs [Hash]
+      # @return [void]
+      def log_event(env, config, kind, **attrs)
+        lg = config.logger || env['rack.logger']
+        payload = { event: 'bff.header_guard', kind: kind, rid: request_id(env) }.merge(attrs).compact
+        sanitized = sanitize_payload(payload)
+        if config.log_with.respond_to?(:call)
+          begin
+            config.log_with.call(sanitized)
+          rescue StandardError
+            # ignore log hook failures
+          end
+        end
+        return unless lg
+
+        msg = sanitized.map { |k, v| v.nil? || v.to_s.empty? ? nil : "#{k}=#{v}" }.compact.join(' ')
+        level = (kind == :ok ? :info : :warn)
+        lg.public_send(level, msg)
+      rescue StandardError
+        # no-op on logging errors
+      end
+
+      # Build a minimal RFC6750-style error response.
+      #
+      # @param env [Hash]
+      # @param config [Configuration]
+      # @param error [Verikloak::BFF::Error]
+      # @return [Array(Integer, Hash, Array<String>)]
+      def respond_with_error(env, config, error)
+        log_event(env, config, :error, code: error.code)
+        body = { error: error.code, message: error.message }.to_json
+        headers = { 'Content-Type' => 'application/json',
+                    'WWW-Authenticate' => %(Bearer error="#{error.code}", error_description="#{error.message}") }
+        [error.http_status, headers, [body]]
+      end
     end
 
     # Rack middleware that enforces BFF boundary and header/claims consistency.
     class HeaderGuard
+      # Error raised when trusted_proxies is not configured and disabled is not explicitly set.
+      class ConfigurationError < StandardError; end
+
       RequestTokens = Struct.new(:auth, :forwarded, :chosen)
 
       # Accept both Rack 2 and Rack 3 builder call styles:
@@ -109,6 +177,7 @@ module Verikloak
       # @param app [#call]
       # @param opts [Hash, nil]
       # @param opts_kw [Hash]
+      # @raise [ConfigurationError] when trusted_proxies is not configured and disabled is false
       def initialize(app, opts = nil, **opts_kw)
         @app = app
         # Use a per-instance copy of global config to avoid cross-request/test side effects
@@ -118,9 +187,15 @@ module Verikloak
         combined.merge!(opts_kw) if opts_kw && !opts_kw.empty?
         apply_overrides!(combined)
 
-        return unless @config.trusted_proxies.nil? || @config.trusted_proxies.empty?
+        # Check configuration validity
+        validate_configuration!
+      end
 
-        raise ArgumentError, 'trusted_proxies must be configured'
+      # Check if the middleware is explicitly disabled.
+      #
+      # @return [Boolean]
+      def disabled?
+        @config.disabled
       end
 
       # Process a Rack request through the BFF header guard pipeline.
@@ -131,9 +206,14 @@ module Verikloak
       # 3. Policy enforcement (forwarded token requirements, consistency checks)
       # 4. Request finalization (Authorization header normalization)
       #
+      # When `disabled: true` is set, the middleware passes through without any processing.
+      #
       # @param env [Hash]
       # @return [Array(Integer, Hash, Array<#to_s>)] Rack response triple
       def call(env)
+        # Pass through if middleware is explicitly disabled
+        return @app.call(env) if disabled?
+
         # Stage 1: Validate request comes from trusted proxy
         ensure_trusted_proxy!(env)
 
@@ -148,11 +228,28 @@ module Verikloak
 
         @app.call(env)
       rescue Verikloak::BFF::Error => e
-        respond_with_error(env, e)
+        HeaderGuardSanitizer.respond_with_error(env, @config, e)
       end
 
       private
 
+      # Validate that required configuration is present.
+      # Raises ConfigurationError if trusted_proxies is not configured and disabled is false.
+      #
+      # @raise [ConfigurationError]
+      # @return [void]
+      def validate_configuration!
+        return if @config.disabled
+
+        proxies = @config.trusted_proxies
+        return unless proxies.nil? || proxies.empty?
+
+        raise ConfigurationError,
+              'trusted_proxies must be configured for Verikloak::BFF::HeaderGuard. ' \
+              'Set trusted_proxies to an array of allowed proxy addresses/CIDRs, ' \
+              'or set disabled: true to explicitly skip BFF protection.'
+      end
+
       # Build token state by extracting, validating, and selecting the active token.
       #
       # @param env [Hash]
@@ -210,63 +307,6 @@ module Verikloak
         auth_token || fwd_token
       end
 
-      # Describe the source of the chosen token for logging purposes.
-      #
-      # @param auth_token [String, nil]
-      # @param fwd_token [String, nil]
-      # @return [String] "authorization" or "forwarded"
-      def token_source(auth_token, fwd_token)
-        return 'forwarded' if @config.prefer_forwarded && fwd_token
-
-        if auth_token && fwd_token
-          'authorization'
-        else
-          (auth_token ? 'authorization' : 'forwarded')
-        end
-      end
-
-      # Extract request id for logging from common headers.
-      #
-      # @param env [Hash]
-      # @return [String, nil]
-      def request_id(env)
-        env['HTTP_X_REQUEST_ID'] || env['action_dispatch.request_id']
-      end
-
-      # Resolve logger to use (config-provided or rack.logger).
-      #
-      # @param env [Hash]
-      # @return [Logger, nil]
-      def logger(env)
-        @config.logger || env['rack.logger']
-      end
-
-      # Emit a structured log line if a logger is present.
-      #
-      # @param env [Hash]
-      # @param kind [Symbol] :ok, :mismatch, :claims_mismatch, :error
-      # @param attrs [Hash]
-      # @return [void]
-      def log_event(env, kind, **attrs)
-        lg = logger(env)
-        payload = { event: 'bff.header_guard', kind: kind, rid: request_id(env) }.merge(attrs).compact
-        sanitized = HeaderGuardSanitizer.sanitize_payload(payload)
-        if @config.log_with.respond_to?(:call)
-          begin
-            @config.log_with.call(sanitized)
-          rescue StandardError
-            # ignore log hook failures
-          end
-        end
-        return unless lg
-
-        msg = sanitized.map { |k, v| v.nil? || v.to_s.empty? ? nil : "#{k}=#{v}" }.compact.join(' ')
-        level = (kind == :ok ? :info : :warn)
-        lg.public_send(level, msg)
-      rescue StandardError
-        # no-op on logging errors
-      end
-
       # Raise when the request did not come through a trusted proxy.
       #
       # @param env [Hash]
@@ -300,7 +340,7 @@ module Verikloak
         digest_b = ::Digest::SHA256.hexdigest(fwd_token)
         return if Rack::Utils.secure_compare(digest_a, digest_b)
 
-        log_event(env, :mismatch, reason: 'authorization_vs_forwarded')
+        HeaderGuardSanitizer.log_event(env, @config, :mismatch, reason: 'authorization_vs_forwarded')
         raise HeaderMismatchError
       end
 
@@ -315,7 +355,7 @@ module Verikloak
         return unless res.is_a?(Array) && res.first == :error
 
         field = res.last
-        log_event(env, :claims_mismatch, field: field.to_s)
+        HeaderGuardSanitizer.log_event(env, @config, :claims_mismatch, field: field.to_s)
         return if claims_consistency_log_only?
 
         raise ClaimsMismatchError, field
@@ -342,20 +382,8 @@ module Verikloak
         return unless chosen
 
         ForwardedToken.set_authorization!(env, chosen)
-        log_event(env, :ok, source: token_source(auth_token, fwd_token), **HeaderGuardSanitizer.token_tags(chosen))
-      end
-
-      # Build a minimal RFC6750-style error response.
-      #
-      # @param env [Hash]
-      # @param error [Verikloak::BFF::Error]
-      # @return [Array(Integer, Hash, Array<String>)]
-      def respond_with_error(env, error)
-        log_event(env, :error, code: error.code)
-        body = { error: error.code, message: error.message }.to_json
-        headers = { 'Content-Type' => 'application/json',
-                    'WWW-Authenticate' => %(Bearer error="#{error.code}", error_description="#{error.message}") }
-        [error.http_status, headers, [body]]
+        source = HeaderGuardSanitizer.token_source(@config.prefer_forwarded, auth_token, fwd_token)
+        HeaderGuardSanitizer.log_event(env, @config, :ok, source: source, **HeaderGuardSanitizer.token_tags(chosen))
       end
 
       # Resolve the first env header from which to source a bearer token.

data/lib/verikloak/bff/version.rb

@@ -5,6 +5,6 @@
 # @return [String]
 module Verikloak
   module BFF
-    VERSION = '0.2.6'
+    VERSION = '0.3.0'
   end
 end

metadata

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