verikloak-bff 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3034b92c69f7147be681038b8f91a5a0c4ec1d577144a4372cad33b6645adb3a
+  data.tar.gz: a52b1ccc320fee7d5526f612fa509218a5b2232ce678d6d6e03a42d5c0122df0
+SHA512:
+  metadata.gz: a9e31d538da66f06b1f18412b41520a3c1a5f0f5e3adf88af19f4aa68451420717002c11dc639a2f1dbc9441b64b68b74de2729d2ef8a5af805d862b7568dd75
+  data.tar.gz: cb2f118b465d7cb4a64f0aa9eb77cb81ec0bd5a82ae2b33c1e9992b1b518e5690dee84f7c5ae69189b83e0394de784d559c57daef41154c24f396390cb0d8bab

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [0.1.0] - 2025-09-14
+
+### Added
+- Rack middleware `Verikloak::BFF::HeaderGuard`
+- Bearer normalization (`ensure_bearer`), Authorization seeding (`token_header_priority`)
+- Trust evaluation: REMOTE_ADDR first, XFF fallback (`peer_preference`, `xff_strategy`)
+- Config keys: `forwarded_header_name`, `auth_request_headers`, `log_with`
+- Claims/header consistency checks、`X-Auth-Request-*` stripping
+- Env passthrough: `verikloak.bff.token`, `verikloak.bff.selected_peer`
+- Docs: README、ERRORS、Rails guide (`docs/rails.md`)
+- RSpec coverage for trust/consistency/seeding/env

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2025 taiyaky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,126 @@
+# verikloak-bff
+
+[![CI](https://github.com/taiyaky/verikloak-bff/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/taiyaky/verikloak-bff/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/verikloak-bff)](https://rubygems.org/gems/verikloak-bff)
+![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.1-blue)
+[![Downloads](https://img.shields.io/gem/dt/verikloak-bff)](https://rubygems.org/gems/verikloak-bff)
+
+
+A framework-agnostic Rack middleware that hardens the **BFF / reverse-auth** boundary (oauth2-proxy, Nginx `auth_request`, etc.). It **normalizes** access tokens from `X-Forwarded-Access-Token` into `Authorization` and optionally checks **consistency** between `X-Auth-Request-*` headers and JWT claims. Signature and `iss/aud/exp` validation are performed by the core `verikloak` middleware placed after this middleware.
+
+## Features
+- Prefer / require `X-Forwarded-Access-Token` (configurable)
+- Trust-boundary checking for proxy IPs (X-Forwarded-For parsing)
+- Header consistency enforcement (Authorization vs Forwarded)
+- Claims consistency checks (e.g., email/sub/groups) against `X-Auth-Request-*`
+- Strip suspicious/forged headers before downstream
+- Logging hooks for `request_id`, `sub`, `kid`, `iss/aud`
+
+## Installation
+```bash
+bundle add verikloak-bff
+```
+
+## Usage
+
+- Rack-only apps: `use Verikloak::BFF::HeaderGuard` before your core Verikloak middleware.
+- Rails apps: see the full guide in [docs/rails.md](docs/rails.md) (Gemfile, middleware order、initializer、proxy examples)。
+
+## Consistency mapping
+
+| Key      | Header                   | JWT claim/path          | Rule        |
+|----------|---------------------------|-------------------------|-------------|
+| `email`  | `X-Auth-Request-Email`   | `email`                 | equality    |
+| `user`   | `X-Auth-Request-User`    | `sub`                   | equality    |
+| `groups` | `X-Auth-Request-Groups`  | `realm_access.roles`    | subset      |
+
+Use `enforce_claims_consistency: { email: :email, user: :sub, groups: :realm_roles }` to enable. Header names can be remapped via `auth_request_headers`.
+
+See `examples/rack.ru` for a tiny Rack app demo.
+
+## Configuration
+
+| Key                          | Type                                 | Default      | Description |
+|----------------------------- |--------------------------------------|--------------|-------------|
+| `trusted_proxies`            | Array[String/Regexp/Proc]            | `[]`         | Allowlist for proxy peers (by IP/CIDR/regex/proc). |
+| `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. |
+| `enforce_claims_consistency` | Hash                                 | `{}`         | Mapping of header→claim to compare (e.g., `{ email: :email, user: :sub, groups: :realm_roles }`). |
+| `strip_suspicious_headers`   | Boolean                              | `true`       | Remove external `X-Auth-Request-*` before passing downstream. |
+| `xff_strategy`               | Symbol (`:rightmost`/`:leftmost`)    | `:rightmost` | Which peer to pick from `X-Forwarded-For`. |
+| `peer_preference`            | Symbol (`:remote_then_xff`/`:xff_only`) | `:remote_then_xff` | Whether to prefer `REMOTE_ADDR` before falling back to XFF. |
+| `clock_skew_leeway`          | Integer (seconds)                    | `30`         | Reserved for small exp/nbf skew handled by core verifier. |
+| `logger`                     | `Logger` or `nil`                    | `nil`        | Logger for audit tags (`rid`, `sub`, `kid`, `iss/aud`). |
+| `token_header_priority`      | Array[String]                        | see code     | When Authorization is empty and no token chosen, seed it from these env headers in order. `HTTP_AUTHORIZATION` is ignored as a source; forwarded header is considered only from trusted peers. |
+| `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 }`. |
+
+## Errors
+This gem returns concise, RFC 6750–style error responses with stable codes. See [ERRORS.md](ERRORS.md) for details and examples.
+
+**Note:** This middleware does not verify JWT signatures or `iss/aud/exp` itself; it normalizes and guards headers so the core `verikloak` middleware always performs final verification.
+
+For full reverse proxy examples (Nginx auth_request / oauth2-proxy), see [docs/rails.md](docs/rails.md).
+
+## Tips & Advanced Usage
+
+- Peer preference: prefer `REMOTE_ADDR` before XFF
+  - Set `peer_preference: :remote_then_xff` (default) to evaluate trust using the direct peer first, then fall back to the nearest (rightmost) `X-Forwarded-For` value.
+  - If you run only behind a single, known proxy chain and want to rely solely on XFF ordering, use `peer_preference: :xff_only` and control position with `xff_strategy`.
+
+- Header name customization
+  - Forwarded-access-token header can be changed via:
+    - `forwarded_header_name: 'HTTP_X_CUSTOM_FORWARD_TOKEN'`
+  - X-Auth-Request-* header names can be remapped via:
+    - `auth_request_headers: { email: 'HTTP_X_EMAIL', user: 'HTTP_X_USER', groups: 'HTTP_X_GROUPS' }`
+
+- Authorization seeding from priority headers
+  - When no token is chosen and `HTTP_AUTHORIZATION` is empty, the middleware consults `token_header_priority` to seed Authorization.
+  - `HTTP_AUTHORIZATION` itself is never used as a source; forwarded headers are considered only from trusted peers.
+
+- Observability helpers
+  - Downstream can inspect `env['verikloak.bff.token']` (chosen token, unverified) and `env['verikloak.bff.selected_peer']` (peer IP selected for trust decisions).
+  - Provide a structured log hook with `log_with: ->(payload) { logger.info(payload.to_json) }` to consume the same fields emitted to `logger`.
+  - Caution: avoid logging the entire Rack `env` in application logs. Treat `env['verikloak.bff.token']` as sensitive; never emit raw tokens or PII (e.g., emails) to logs.
+
+## Development (for contributors)
+Clone and install dependencies:
+
+```bash
+git clone https://github.com/taiyaky/verikloak-bff.git
+cd verikloak-bff
+bundle install
+```
+See **Testing** below to run specs and RuboCop. For releasing, see **Publishing**.
+
+## 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.
+
+To run the test suite locally:
+
+```bash
+docker compose run --rm dev rspec
+docker compose run --rm dev rubocop -a
+```
+
+## Contributing
+Bug reports and pull requests are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## Security
+If you find a security vulnerability, please follow the instructions in [SECURITY.md](SECURITY.md).
+
+## License
+This project is licensed under the [MIT License](LICENSE).
+
+## Publishing (for maintainers)
+Gem release instructions are documented separately in [MAINTAINERS.md](MAINTAINERS.md).
+
+## Changelog
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## References
+- Verikloak (core): https://github.com/taiyaky/verikloak
+- verikloak-rails (Rails integration): https://github.com/taiyaky/verikloak-rails
+- verikloak-bff on RubyGems: https://rubygems.org/gems/verikloak-bff

data/lib/verikloak/bff/configuration.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Configuration object for verikloak-bff. Holds middleware settings such as
+# proxy trust rules, header consistency policies, and logging options.
+#
+# @!attribute [rw] trusted_proxies
+#   @return [Array<String, Regexp, Proc>] allowlist of trusted proxy peers
+# @!attribute [rw] prefer_forwarded
+#   @return [Boolean] prefer X-Forwarded-Access-Token over Authorization
+# @!attribute [rw] require_forwarded_header
+#   @return [Boolean] require X-Forwarded-Access-Token to be present
+# @!attribute [rw] enforce_header_consistency
+#   @return [Boolean] when both headers exist, require equality
+# @!attribute [rw] enforce_claims_consistency
+#   @return [Hash] mapping of header keys to claim keys (e.g., { email: :email })
+# @!attribute [rw] strip_suspicious_headers
+#   @return [Boolean] strip X-Auth-Request-* headers before downstream
+# @!attribute [rw] xff_strategy
+#   @return [Symbol] :rightmost or :leftmost peer selection from XFF
+# @!attribute [rw] clock_skew_leeway
+#   @return [Integer] reserved leeway (seconds) for exp/nbf (handled in core)
+# @!attribute [rw] logger
+#   @return [Logger, nil] optional logger for audit tags
+
+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,
+                    :enforce_header_consistency, :enforce_claims_consistency,
+                    :strip_suspicious_headers, :xff_strategy, :clock_skew_leeway,
+                    :logger, :token_header_priority, :peer_preference,
+                    :forwarded_header_name, :auth_request_headers, :log_with
+
+      # enforce_claims_consistency example:
+      # { email: :email, user: :sub, groups: :realm_roles }
+      def initialize
+        @trusted_proxies = []
+        @prefer_forwarded = true
+        @require_forwarded_header = false
+        @enforce_header_consistency = true
+        @enforce_claims_consistency = {}
+        @strip_suspicious_headers = true
+        @xff_strategy = :rightmost
+        @peer_preference = :remote_then_xff
+        @clock_skew_leeway = 30
+        @logger = nil
+        @log_with = nil
+        @forwarded_header_name = 'HTTP_X_FORWARDED_ACCESS_TOKEN'
+        @auth_request_headers = {
+          email: 'HTTP_X_AUTH_REQUEST_EMAIL',
+          user: 'HTTP_X_AUTH_REQUEST_USER',
+          groups: 'HTTP_X_AUTH_REQUEST_GROUPS'
+        }
+        # When Authorization is empty and no chosen token exists, try these env headers (in order)
+        # to seed Authorization, similar to verikloak-rails behavior. HTTP_AUTHORIZATION is ignored as a source.
+        @token_header_priority = %w[
+          HTTP_X_FORWARDED_ACCESS_TOKEN
+          HTTP_AUTHORIZATION
+        ]
+      end
+    end
+  end
+end

data/lib/verikloak/bff/consistency_checks.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# Helpers to compare X-Auth-Request-* headers with JWT claims according to a
+# provided mapping. Intended for lightweight, unverified JWT parsing only.
+#
+# @see .enforce!
+
+require 'json'
+require 'jwt' # used only to parse segments safely without verify
+
+module Verikloak
+  module BFF
+    # Compares X-Auth-Request-* headers with JWT claims according to a mapping.
+    module ConsistencyChecks
+      module_function
+
+      # Parse JWT payload without verifying (verikloak core will verify later).
+      # Decode JWT payload without verification.
+      #
+      # @param token [String, nil]
+      # @return [Hash] claims or empty hash on error
+      def decode_claims(token)
+        return {} unless token
+
+        parts = token.split('.')
+        return {} unless parts.size >= 2
+
+        payload = JWT::Base64.url_decode(parts[1])
+        JSON.parse(payload)
+      rescue StandardError
+        {}
+      end
+
+      # mapping: { email: :email, user: :sub, groups: :realm_roles }
+      # Enforce consistency according to the provided mapping.
+      #
+      # @param env [Hash]
+      # @param token [String, nil]
+      # @param mapping [Hash] e.g., { email: :email, user: :sub, groups: :realm_roles }
+      # @return [true, Array(:error, Symbol)] true or error tuple with failing field
+      def enforce!(env, token, mapping, headers_map = nil)
+        return true if mapping.nil? || mapping.empty?
+
+        claims = decode_claims(token)
+
+        mapping.each do |header_key, claim_key|
+          hdr_val = extract_header_value(env, header_key, headers_map)
+          next if hdr_val.nil? # no header → skip comparison
+
+          case claim_key
+          when :realm_roles
+            roles = Array((claims['realm_access'] || {})['roles'] || [])
+            hdr_list = split_list(hdr_val)
+            return error(:groups) unless (hdr_list - roles).empty?
+          else
+            claim_val = dig_claim(claims, claim_key)
+            return error(header_key) unless claim_val && hdr_val.to_s == claim_val.to_s
+          end
+        end
+        true
+      end
+
+      # Extract an X-Auth-Request-* header value mapped from a symbolic key.
+      #
+      # @param env [Hash]
+      # @param key [Symbol]
+      # @return [String, nil]
+      def extract_header_value(env, key, headers_map = nil)
+        return env[headers_map[key]] if headers_map && headers_map[key]
+
+        case key
+        when :email
+          env['HTTP_X_AUTH_REQUEST_EMAIL']
+        when :user
+          env['HTTP_X_AUTH_REQUEST_USER']
+        when :groups
+          env['HTTP_X_AUTH_REQUEST_GROUPS']
+        end
+      end
+
+      # Split a comma-separated list into an array.
+      #
+      # @param val [String]
+      # @return [Array<String>]
+      def split_list(val)
+        Array(val.to_s.split(',').map(&:strip).reject(&:empty?))
+      end
+
+      # Dig into JWT claims by a symbol/string key or an array path.
+      #
+      # @param claims [Hash]
+      # @param key [Symbol, String, Array<String,Symbol>]
+      # @return [Object, nil]
+      def dig_claim(claims, key)
+        case key
+        when Symbol, String
+          claims[key.to_s]
+        when Array
+          key.reduce(claims) { |acc, k| acc.is_a?(Hash) ? acc[k.to_s] : nil }
+        end
+      end
+
+      # Build an error tuple for a failed field.
+      #
+      # @param field [Symbol]
+      # @return [Array(:error, Symbol)]
+      def error(field)
+        [:error, field]
+      end
+    end
+  end
+end

data/lib/verikloak/bff/errors.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Error types emitted by verikloak-bff. These map to RFC6750-style responses
+# with stable error codes for easy handling at clients and logs.
+
+module Verikloak
+  module BFF
+    # Base error class with HTTP status and short code.
+    #
+    # @attr_reader [String] code
+    # @attr_reader [Integer] http_status
+    class Error < StandardError
+      attr_reader :code, :http_status
+
+      def initialize(message = nil, code: 'bff_error', http_status: 401)
+        super(message || code)
+        @code = code
+        @http_status = http_status
+      end
+    end
+
+    # Raised when a request did not pass through a trusted proxy peer.
+    class UntrustedProxyError < Error
+      def initialize(msg = 'request did not pass through a trusted proxy')
+        super(msg, code: 'untrusted_proxy', http_status: 401)
+      end
+    end
+
+    # Raised when require_forwarded_header is enabled but the forwarded token is absent.
+    class MissingForwardedTokenError < Error
+      def initialize(msg = 'missing X-Forwarded-Access-Token')
+        super(msg, code: 'missing_forwarded_token', http_status: 401)
+      end
+    end
+
+    # Raised when Authorization and X-Forwarded-Access-Token both exist and differ.
+    class HeaderMismatchError < Error
+      def initialize(msg = 'authorization and forwarded token mismatch')
+        super(msg, code: 'header_mismatch', http_status: 401)
+      end
+    end
+
+    # Raised when X-Auth-Request-* headers conflict with JWT claims.
+    class ClaimsMismatchError < Error
+      def initialize(field, msg = nil)
+        super(msg || "claims/header mismatch for #{field}", code: 'claims_mismatch', http_status: 403)
+      end
+    end
+  end
+end

data/lib/verikloak/bff/forwarded_token.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+# Utilities to extract, normalize, and manipulate forwarded/auth headers.
+#
+# @see .extract
+
+module Verikloak
+  module BFF
+    # Helpers to extract and normalize forwarded/access token headers.
+    module ForwardedToken
+      module_function
+
+      FORWARDED_HEADER = 'HTTP_X_FORWARDED_ACCESS_TOKEN'
+      AUTH_HEADER      = 'HTTP_AUTHORIZATION'
+
+      # Extract normalized tokens from the Rack env.
+      #
+      # @param env [Hash]
+      # @return [Array(String, String)] [auth_token, forwarded_token]
+      def extract(env, forwarded_header_name = FORWARDED_HEADER, auth_header_name = AUTH_HEADER)
+        fwd_raw = env[forwarded_header_name]
+        auth_raw = env[auth_header_name]
+        [normalize_auth(auth_raw), normalize_forwarded(fwd_raw)]
+      end
+
+      # Only accept Bearer scheme for Authorization header.
+      #
+      # @param raw [String, nil]
+      # @return [String, nil] token or nil when not Bearer
+      def normalize_auth(raw)
+        return nil unless raw
+
+        token = raw.to_s.strip
+        return ::Regexp.last_match(1) if token =~ /^Bearer\s+(.+)$/i
+        return token[6..] if token =~ /^Bearer(?!\s)/i
+
+        nil
+      end
+
+      # Accept either bare token or Bearer for forwarded header.
+      #
+      # @param raw [String, nil]
+      # @return [String, nil] token or nil
+      def normalize_forwarded(raw)
+        return nil unless raw
+
+        token = raw.to_s.strip
+        return ::Regexp.last_match(1) if token =~ /^Bearer\s+(.+)$/i
+
+        token.empty? ? nil : token
+      end
+
+      # Normalize to a proper 'Bearer <token>' header value.
+      # - Detects scheme case-insensitively
+      # - Inserts a missing space (e.g., 'BearerXYZ' => 'Bearer XYZ')
+      # - Collapses multiple spaces/tabs after the scheme to a single space
+      # @param token [String]
+      # @return [String]
+      def ensure_bearer(token)
+        s = token.to_s.strip
+        # Case-insensitive 'Bearer' with spaces/tabs after
+        if s =~ /\ABearer[ \t]+/i
+          rest = s.sub(/\ABearer[ \t]+/i, '')
+          return "Bearer #{rest}"
+        end
+
+        # Case-insensitive 'Bearer' with no separator (e.g., 'BearerXYZ')
+        if s =~ /\ABearer(?![ \t])/i
+          rest = s[6..] || ''
+          return "Bearer #{rest}"
+        end
+
+        # No scheme present; add it
+        "Bearer #{s}"
+      end
+
+      # Set Authorization header to a normalized Bearer value (no overwrite when present).
+      #
+      # @param env [Hash]
+      # @param token [String]
+      def set_authorization!(env, token)
+        existing = env[AUTH_HEADER].to_s
+        # Overwrite only if Authorization is empty or not a valid Bearer value
+        return unless existing.empty? || normalize_auth(existing).nil?
+
+        env[AUTH_HEADER] = ensure_bearer(token)
+      end
+
+      # Remove potentially forged X-Auth-Request-* headers before passing
+      # downstream when not emitted by a trusted proxy.
+      #
+      # @param env [Hash]
+      def strip_suspicious!(env, headers = nil)
+        if headers.is_a?(Hash)
+          headers.each_value { |h| env.delete(h) }
+          return
+        end
+        env.delete('HTTP_X_AUTH_REQUEST_EMAIL')
+        env.delete('HTTP_X_AUTH_REQUEST_USER')
+        env.delete('HTTP_X_AUTH_REQUEST_GROUPS')
+      end
+    end
+  end
+end

data/lib/verikloak/bff/header_guard.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+# Rack middleware that hardens the BFF boundary by normalizing tokens and
+# enforcing header/claims consistency before the core verifier runs.
+#
+# Typical usage (Rack/Rails):
+#   use Verikloak::BFF::HeaderGuard, trusted_proxies: ['127.0.0.1']
+#
+# The middleware prefers `X-Forwarded-Access-Token` (configurable), enforces
+# header equality when both tokens exist, optionally checks `X-Auth-Request-*`
+# headers against JWT claims, and normalizes the request into
+# `HTTP_AUTHORIZATION: Bearer <token>` for the downstream verifier.
+require 'rack'
+require 'json'
+require 'jwt'
+require 'verikloak/bff/configuration'
+require 'verikloak/bff/errors'
+require 'verikloak/bff/proxy_trust'
+require 'verikloak/bff/forwarded_token'
+require 'verikloak/bff/consistency_checks'
+
+module Verikloak
+  module BFF
+    # Rack middleware that enforces BFF boundary and header/claims consistency.
+    class HeaderGuard
+      # Accept both Rack 2 and Rack 3 builder call styles:
+      # - new(app, key: val)
+      # - new(app, { key: val })
+      #
+      # @param app [#call]
+      # @param opts [Hash, nil]
+      # @param opts_kw [Hash]
+      def initialize(app, opts = nil, **opts_kw)
+        @app = app
+        # Use a per-instance copy of global config to avoid cross-request/test side effects
+        @config = Verikloak::BFF.config.dup
+        combined = {}
+        combined.merge!(opts) if opts.is_a?(Hash)
+        combined.merge!(opts_kw) if opts_kw && !opts_kw.empty?
+        apply_overrides!(combined)
+      end
+
+      # Process a Rack request.
+      #
+      # @param env [Hash]
+      # @return [Array(Integer, Hash, Array<#to_s>)] Rack response triple
+      def call(env)
+        ensure_trusted_proxy!(env)
+        auth_token, fwd_token = ForwardedToken.extract(env, @config.forwarded_header_name)
+        ensure_forwarded_if_required!(fwd_token)
+        chosen = choose_token(auth_token, fwd_token)
+        chosen = seed_authorization_if_needed(env, chosen)
+
+        enforce_header_consistency!(env, auth_token, fwd_token)
+        enforce_claims_consistency!(env, chosen)
+        ForwardedToken.strip_suspicious!(env, @config.auth_request_headers) if @config.strip_suspicious_headers
+        normalize_authorization!(env, chosen, auth_token, fwd_token)
+        expose_env_hints(env, chosen)
+        @app.call(env)
+      rescue Verikloak::BFF::Error => e
+        respond_with_error(env, e)
+      end
+
+      private
+
+      # Apply per-instance configuration overrides.
+      #
+      # @param opts [Hash]
+      def apply_overrides!(opts)
+        cfg = @config
+        opts.each do |k, v|
+          cfg.public_send("#{k}=", v) if cfg.respond_to?("#{k}=")
+        end
+      end
+
+      # Choose a token based on preference and presence.
+      #
+      # @param auth_token [String, nil]
+      # @param fwd_token [String, nil]
+      # @return [String, nil]
+      def choose_token(auth_token, fwd_token)
+        return fwd_token if @config.prefer_forwarded && fwd_token
+
+        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 selected JWT tags for audit logging (best-effort, unverified).
+      #
+      # @param token [String, nil]
+      # @return [Hash] subset of {sub, iss, aud, kid}
+      def token_tags(token)
+        return {} unless token
+
+        payload, header = decode_unverified(token)
+        {
+          sub: payload['sub'],
+          iss: payload['iss'],
+          aud: (payload['aud'].is_a?(Array) ? payload['aud'].join(' ') : payload['aud']).to_s,
+          kid: header['kid']
+        }.compact
+      rescue StandardError
+        {}
+      end
+
+      # Decode JWT header/payload without validation (for logging only).
+      #
+      # @param token [String]
+      # @return [Array(Hash, Hash)] [payload, header]
+      def decode_unverified(token)
+        parts = token.to_s.split('.')
+        return [{}, {}] unless parts.size >= 2
+
+        payload = begin
+          JSON.parse(::JWT::Base64.url_decode(parts[1]))
+        rescue StandardError
+          {}
+        end
+        header = begin
+          JSON.parse(::JWT::Base64.url_decode(parts[0]))
+        rescue StandardError
+          {}
+        end
+        [payload, header]
+      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]
+      def log_event(env, kind, **attrs)
+        lg = logger(env)
+        payload = { event: 'bff.header_guard', kind: kind, rid: request_id(env) }.merge(attrs).compact
+        if @config.log_with.respond_to?(:call)
+          begin
+            @config.log_with.call(payload)
+          rescue StandardError
+            # ignore log hook failures
+          end
+        end
+        return unless lg
+
+        msg = payload.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]
+      def ensure_trusted_proxy!(env)
+        return if ProxyTrust.trusted?(env, @config.trusted_proxies, @config.xff_strategy)
+
+        raise UntrustedProxyError
+      end
+
+      # Enforce presence of forwarded token when required.
+      #
+      # @param fwd_token [String, nil]
+      def ensure_forwarded_if_required!(fwd_token)
+        return unless @config.require_forwarded_header
+        raise MissingForwardedTokenError if fwd_token.nil? || fwd_token.to_s.strip.empty?
+      end
+
+      # Enforce equality when both Authorization and Forwarded tokens exist.
+      #
+      # @param env [Hash]
+      # @param auth_token [String, nil]
+      # @param fwd_token [String, nil]
+      def enforce_header_consistency!(env, auth_token, fwd_token)
+        return unless @config.enforce_header_consistency
+        return unless auth_token && fwd_token
+        return if auth_token == fwd_token
+
+        log_event(env, :mismatch, reason: 'authorization_vs_forwarded')
+        raise HeaderMismatchError
+      end
+
+      # Enforce X-Auth-Request-* ↔ JWT claims mapping when configured.
+      #
+      # @param env [Hash]
+      # @param chosen [String, nil]
+      def enforce_claims_consistency!(env, chosen)
+        res = ConsistencyChecks.enforce!(env, chosen, @config.enforce_claims_consistency, @config.auth_request_headers)
+        return unless res.is_a?(Array) && res.first == :error
+
+        field = res.last
+        log_event(env, :claims_mismatch, field: field.to_s)
+        raise ClaimsMismatchError, field
+      end
+
+      # Set normalized Authorization header and emit success log.
+      #
+      # @param env [Hash]
+      # @param chosen [String, nil]
+      # @param auth_token [String, nil]
+      # @param fwd_token [String, nil]
+      def normalize_authorization!(env, chosen, auth_token, fwd_token)
+        return unless chosen
+
+        ForwardedToken.set_authorization!(env, chosen)
+        log_event(env, :ok, source: token_source(auth_token, fwd_token), **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]]
+      end
+
+      # Resolve the first env header from which to source a bearer token.
+      # Forwarded is considered only when the peer is trusted; HTTP_AUTHORIZATION is never a source.
+      # @param env [Hash]
+      # @return [String, nil]
+      def resolve_first_token_header(env)
+        candidates = Array(@config.token_header_priority).dup
+        candidates -= ['HTTP_AUTHORIZATION']
+        fwd_key = 'HTTP_X_FORWARDED_ACCESS_TOKEN'
+        if candidates.include?(fwd_key) && !ProxyTrust.from_trusted_proxy?(env, @config.trusted_proxies)
+          candidates -= [fwd_key]
+        end
+        candidates.find { |k| (v = env[k]) && !v.to_s.empty? }
+      end
+
+      # Seed Authorization from priority headers if nothing chosen and empty Authorization
+      # @param env [Hash]
+      # @param chosen [String, nil]
+      # @return [String, nil] possibly updated chosen token
+      def seed_authorization_if_needed(env, chosen)
+        return chosen unless chosen.nil? && env['HTTP_AUTHORIZATION'].to_s.empty?
+        return chosen unless Array(@config.token_header_priority).any?
+
+        seeded = resolve_first_token_header(env)
+        if seeded
+          ForwardedToken.set_authorization!(env, env[seeded])
+          return ForwardedToken.normalize_forwarded(env[seeded]) || env[seeded].to_s
+        end
+        chosen
+      end
+
+      # Expose hints to downstream
+      # @param env [Hash]
+      # @param chosen [String, nil]
+      def expose_env_hints(env, chosen)
+        env['verikloak.bff.token'] = chosen if chosen
+        env['verikloak.bff.selected_peer'] =
+          ProxyTrust.selected_peer(env, @config.peer_preference, @config.xff_strategy)
+      end
+    end
+  end
+end

data/lib/verikloak/bff/proxy_trust.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# Utilities to determine whether a request peer (via REMOTE_ADDR / XFF) is
+# allow‑listed as a trusted proxy.
+require 'ipaddr'
+
+module Verikloak
+  module BFF
+    # Determines whether the selected peer (via XFF/REMOTE_ADDR) is a trusted proxy.
+    module ProxyTrust
+      module_function
+
+      # Determine if the immediate peer (based on REMOTE_ADDR / X-Forwarded-For) is trusted.
+      # strategy :rightmost (typical when proxy appends client IP to the right)
+      #
+      # @param env [Hash] Rack environment
+      # @param trusted [Array<String, Regexp, Proc>, nil] Allowlist of proxy peers.
+      #   - String: exact IP (e.g. "127.0.0.1") or CIDR (e.g. "10.0.0.0/8")
+      #   - Regexp: matched against the selected peer IP
+      #   - Proc: called as `->(ip, env) { ... }` and returns truthy when trusted
+      # @param strategy [Symbol, String] `:rightmost` (default) or `:leftmost` for XFF parsing
+      # @return [Boolean] true if the selected peer is trusted
+      # @example CIDR + Regex allowlist
+      #   ProxyTrust.trusted?(env, ["10.0.0.0/8", /^192\.168\./], :rightmost)
+      def trusted?(env, trusted, strategy = :rightmost)
+        return true if trusted.nil? || trusted.empty?
+
+        # Rails-aligned: prefer REMOTE_ADDR; fallback to nearest XFF entry
+        remote = (env['REMOTE_ADDR'] || '').to_s.strip
+        remote = extract_peer_ip(env, strategy) if remote.empty?
+        return false unless remote
+
+        remote_ip = ip_or_nil(remote)
+        trusted.any? { |rule| rule_trusts?(rule, remote, remote_ip, env) }
+      rescue StandardError
+        false
+      end
+
+      # Select the peer IP from X-Forwarded-For according to strategy or fall back to REMOTE_ADDR.
+      #
+      # @param env [Hash] Rack environment
+      # @param strategy [Symbol, String] `:rightmost` (default) or `:leftmost`
+      # @return [String, nil] Selected peer IP, or nil if not determinable
+      def extract_peer_ip(env, strategy)
+        mode = strategy.to_s.to_sym
+        xff = env['HTTP_X_FORWARDED_FOR']
+        if xff && !xff.strip.empty?
+          parts = xff.split(',').map(&:strip)
+          ip = mode == :leftmost ? parts.first : parts.last
+          return ip
+        end
+        env['REMOTE_ADDR']
+      end
+
+      # Return the selected peer IP according to preference and strategy.
+      # @param env [Hash]
+      # @param preference [Symbol] :remote_then_xff or :xff_only
+      # @param strategy [Symbol] :rightmost or :leftmost
+      # @return [String, nil]
+      def selected_peer(env, preference, strategy)
+        case preference.to_s.to_sym
+        when :remote_then_xff
+          ip = (env['REMOTE_ADDR'] || '').to_s.strip
+          return ip unless ip.nil? || ip.empty?
+
+          extract_peer_ip(env, :rightmost) # nearest by default
+        else
+          extract_peer_ip(env, strategy)
+        end
+      end
+
+      # Parse string to IPAddr or nil on failure.
+      # @param str [String]
+      # @return [IPAddr, nil]
+      def ip_or_nil(str)
+        IPAddr.new(str)
+      rescue StandardError
+        nil
+      end
+
+      # Check whether a single rule trusts the selected remote.
+      # @param rule [String, Regexp, Proc]
+      # @param remote [String]
+      # @param remote_ip [IPAddr, nil]
+      # @param env [Hash]
+      # @return [Boolean]
+      def rule_trusts?(rule, remote, remote_ip, env)
+        case rule
+        when String
+          if rule.include?('/') # CIDR
+            cidr = IPAddr.new(rule)
+            remote_ip ? cidr.include?(remote_ip) : false
+          else
+            remote == rule
+          end
+        when Regexp
+          remote =~ rule
+        when Proc
+          rule.call(remote, env)
+        else
+          false
+        end
+      end
+
+      # Determine if the request originates from a trusted proxy subnet.
+      # Rails-aligned behavior: prefer REMOTE_ADDR, fallback to nearest (rightmost) X-Forwarded-For.
+      # @param env [Hash]
+      # @param trusted [Array<String, Regexp, Proc>, nil]
+      # @return [Boolean]
+      def self.from_trusted_proxy?(env, trusted)
+        return true if trusted.nil? || trusted.empty?
+
+        ip = (env['REMOTE_ADDR'] || '').to_s.strip
+        ip = env['HTTP_X_FORWARDED_FOR'].to_s.split(',').last.to_s.strip if ip.empty? && env['HTTP_X_FORWARDED_FOR']
+        return false if ip.empty?
+
+        remote_ip = ip_or_nil(ip)
+        return false unless remote_ip
+
+        trusted.any? { |rule| rule_trusts?(rule, ip, remote_ip, env) }
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/verikloak/bff/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Version constant for verikloak-bff.
+#
+# @return [String]
+module Verikloak
+  module BFF
+    VERSION = '0.1.0'
+  end
+end

data/lib/verikloak/bff.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Namespace for BFF-related configuration and helpers used by verikloak-bff.
+#
+# @see Verikloak::BFF::Configuration
+
+module Verikloak
+  # Top-level namespace for verikloak-bff features and configuration.
+  module BFF
+    class << self
+      # Configure global settings for the BFF middleware.
+      #
+      # @yieldparam config [Verikloak::BFF::Configuration]
+      # @return [Verikloak::BFF::Configuration]
+      def configure
+        @config ||= Configuration.new
+        yield @config if block_given?
+        @config
+      end
+
+      # Current global configuration.
+      #
+      # @return [Verikloak::BFF::Configuration]
+      def config
+        @config ||= Configuration.new
+      end
+    end
+  end
+end

data/lib/verikloak-bff.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# verikloak-bff — library entrypoint.
+#
+# Requiring this file loads the BFF namespace, configuration, middleware, and
+# supporting utilities. Applications typically need only:
+#
+#   require 'verikloak-bff'
+#   use Verikloak::BFF::HeaderGuard, trusted_proxies: ['127.0.0.1']
+#
+# @see Verikloak::BFF::HeaderGuard
+# @see Verikloak::BFF::Configuration
+require 'verikloak/bff'
+require 'verikloak/bff/version'
+require 'verikloak/bff/configuration'
+require 'verikloak/bff/errors'
+require 'verikloak/bff/proxy_trust'
+require 'verikloak/bff/forwarded_token'
+require 'verikloak/bff/consistency_checks'
+require 'verikloak/bff/header_guard'

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: verikloak-bff
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- taiyaky
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: verikloak
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: Framework-agnostic Rack middleware that normalizes forwarded tokens,
+  enforces trust boundaries, and checks header/claims consistency before verikloak.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/verikloak-bff.rb
+- lib/verikloak/bff.rb
+- lib/verikloak/bff/configuration.rb
+- lib/verikloak/bff/consistency_checks.rb
+- lib/verikloak/bff/errors.rb
+- lib/verikloak/bff/forwarded_token.rb
+- lib/verikloak/bff/header_guard.rb
+- lib/verikloak/bff/proxy_trust.rb
+- lib/verikloak/bff/version.rb
+homepage: https://github.com/taiyaky/verikloak-bff
+licenses:
+- MIT
+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.1.0
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: BFF header guard for verikloak (oauth2-proxy / auth_request integration)
+test_files: []