verikloak-rails 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dbb1d62264480e1ed9e4f045df4d1cd694e1ed7fdc2240c815d98ecd5dd39b33
-  data.tar.gz: 94bbb11fadae1cb555be97cc4715bdf357cf9252464da6b303bf4fb98ea3d77c
+  metadata.gz: 3b4d8e46a9c366b09726841773f09cbf54b44c3fbf2f0870b1994bb365ae9173
+  data.tar.gz: 31f3fdf2f6c9482f06a1a03bf0a4ecdc8109f24c814306e174ff582706659c4f
 SHA512:
-  metadata.gz: 62c094a2c975973123e36f50aba4ccbbb2fc58fb82de69f3ad8b40a2363051fc02b1119fbb393854a3bb7faba30b2618035340aee1bf8cc95620ce0e4cdbe5c1
-  data.tar.gz: 24626f36ab835977055470020cc9371f7d76217a59f4907010a9f2d7761ece802a0ea4f3a57497306e543ffa369ad9ee95f32a8c41c8f027b25ad8c871e0c33e
+  metadata.gz: 6748be8631a59e8d1f0562c96ae6b53b01991d28a5fd094cf0117164d7597508c0d02e8be5ebdc28ad04c801686dac0492eb6f5242ea09e961a1814d4b0ff248
+  data.tar.gz: a41eb76616575e283c7ff139161fa18886b85ffea7f7d953eb4ed846b754fb1e15a93538d3f8ed51b04d92e68f302b3174d54ba881e600b2c58d9f8979687c6b

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.1.0] - 2026-05-09
+
+### Added
+- **RSpec testing helpers** (`Verikloak::Rails::Testing`): a reusable test-support layer so applications no longer have to hand-roll their own Verikloak stubs/claim builders. Composed of three independent modules — `ClaimsBuilder` (build OIDC-shaped claim Hashes from a user-like object), `MiddlewareStub` (stub `Verikloak::Middleware` and, when loaded, `Verikloak::BFF::HeaderGuard` / `Verikloak::Audience::Middleware` to inject claims into `env['verikloak.user']`), and `Helpers` (top-level mix-in plus `Verikloak::Pundit::UserContext` builders when `verikloak-pundit` is loaded). Require `verikloak/rails/testing/rspec` from your `rails_helper.rb` to mix the helpers into request and policy specs and to register the `with verikloak admin auth`, `with verikloak user auth`, and `with verikloak custom auth` shared contexts. Note: `MiddlewareStub` requires RSpec, and controller specs (`type: :controller`) bypass the Rack middleware stack and are therefore not auto-included; set `request.env['verikloak.user']` directly in those specs. See README "Testing Support" for usage.
+
+### Changed
+- **`ClaimsBuilder#build_jwt_claims`** falls back to the user's email when `username` / `preferred_username` is present but blank, preventing the `preferred_username` claim from being silently dropped by `.compact`.
+
+### Security
+- **Bumped `rails` to `>= 8.1.3` and `json` to `>= 2.19.5`** in `Gemfile.lock` to clear known advisories surfaced by `bundler-audit` (Active Storage range-header DoS and json format-string injection).
+
+---
+
 ## [1.0.1] - 2026-03-08
 
 ### Fixed

data/README.md

@@ -224,6 +224,95 @@ end
 | `rescue_pundit` | `VERIKLOAK_RESCUE_PUNDIT` |
 
 
+## Testing Support
+
+`verikloak-rails` ships RSpec helpers so applications no longer need to
+hand-roll their own Verikloak stubs and claim builders.
+
+### Setup
+
+Require the integration once from `spec/rails_helper.rb` (or
+`spec/spec_helper.rb`):
+
+```ruby
+require "verikloak/rails/testing/rspec"
+```
+
+This mixes `Verikloak::Rails::Testing::Helpers` into request and policy
+specs, and registers three shared contexts:
+
+- `"with verikloak admin auth"`  — authenticates as an admin (`groups: ["/admin"]`)
+- `"with verikloak user auth"`   — authenticates as a regular user (`groups: ["/user"]`)
+- `"with verikloak custom auth"` — uses `let(:verikloak_groups)` /
+  `let(:verikloak_extra_claims)` to customise the injected claims
+
+> Controller specs (`type: :controller`) bypass the Rack middleware
+> stack, so `stub_verikloak_middleware` cannot inject claims through
+> them. Prefer `type: :request`; if you must use a controller spec,
+> set `request.env['verikloak.user']`/`request.env['verikloak.token']`
+> directly in a `before` block.
+
+The shared contexts assume a `current_user` factory exists (e.g.
+`create(:user)`); override `let(:current_user)` to inject a different
+object. The user object is duck-typed and only needs to respond to `uid`
+and `email` (with optional `username` / `preferred_username` /
+`first_name` / `last_name`).
+
+### Request specs
+
+```ruby
+RSpec.describe "Users API", type: :request do
+  include_context "with verikloak admin auth"
+
+  it "returns the users list" do
+    get "/api/v1/users"
+    expect(response).to have_http_status(:ok)
+  end
+end
+```
+
+Or call the helpers directly when you need a custom claim shape:
+
+```ruby
+RSpec.describe "Custom claims", type: :request do
+  let(:user) { create(:user) }
+
+  before do
+    claims = build_jwt_claims(
+      user,
+      groups: ["/custom-group"],
+      extra_claims: { "custom" => "value" }
+    )
+    stub_verikloak_middleware(claims)
+  end
+end
+```
+
+`stub_verikloak_middleware` automatically also stubs
+`Verikloak::BFF::HeaderGuard` and `Verikloak::Audience::Middleware` when
+those gems are loaded, and sets `env['verikloak.token']` so controller
+helpers like `current_token` work.
+
+### Policy specs (with `verikloak-pundit`)
+
+When `verikloak-pundit` is loaded, `Verikloak::Pundit::UserContext`
+builders become available:
+
+```ruby
+RSpec.describe UserPolicy, type: :policy do
+  let(:user) { create(:user) }
+  let(:admin_context) { build_admin_user_context(user) }
+  let(:user_context)  { build_user_user_context(user) }
+
+  it "allows admin to index" do
+    expect(described_class.new(admin_context, User).index?).to be true
+  end
+end
+```
+
+If `verikloak-pundit` is not loaded, calling the `*_user_context`
+builders raises a clear error.
+
 ## Errors
 This gem standardizes JSON error responses and HTTP statuses. See [ERRORS.md](ERRORS.md) for details and examples.
 

data/lib/verikloak/rails/testing/claims_builder.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Rails
+    module Testing
+      # Builds JWT-shaped claim Hashes from a user-like object for use in
+      # tests. The returned Hash uses string keys to match what
+      # `Verikloak::Middleware` writes to `env['verikloak.user']` after a
+      # successful token verification.
+      #
+      # The user object is duck-typed: it must respond to `uid` and `email`.
+      # Optional methods used when present:
+      # - `username` or `preferred_username` (for `preferred_username`)
+      # - `first_name` (for `given_name`)
+      # - `last_name` (for `family_name`)
+      module ClaimsBuilder
+        # Build a baseline OIDC-style claim Hash.
+        #
+        # @param user [Object] user-like object responding to `uid`, `email`
+        # @param groups [Array<String>] values for the `groups` claim
+        # @param extra_claims [Hash] additional claims to merge in (overrides
+        #   any keys produced from `user`/`groups`)
+        # @return [Hash{String=>Object}]
+        def build_jwt_claims(user, groups: [], extra_claims: {})
+          base = {
+            'sub' => user.uid,
+            'email' => user.email,
+            'preferred_username' => preferred_username_for(user),
+            'given_name' => safe_call(user, :first_name),
+            'family_name' => safe_call(user, :last_name),
+            'groups' => groups,
+            'realm_access' => { 'roles' => [] },
+            'resource_access' => {},
+            'aud' => ['account']
+          }.compact
+
+          base.merge(stringify_keys(extra_claims))
+        end
+
+        # Convenience wrapper that assigns the configured admin group.
+        #
+        # @param user [Object]
+        # @param admin_group [String] group identifier (default: "/admin")
+        # @param extra_claims [Hash]
+        # @return [Hash{String=>Object}]
+        def build_admin_claims(user, admin_group: '/admin', extra_claims: {})
+          build_jwt_claims(user, groups: [admin_group], extra_claims: extra_claims)
+        end
+
+        # Convenience wrapper that assigns the configured user group.
+        #
+        # @param user [Object]
+        # @param user_group [String] group identifier (default: "/user")
+        # @param extra_claims [Hash]
+        # @return [Hash{String=>Object}]
+        def build_user_claims(user, user_group: '/user', extra_claims: {})
+          build_jwt_claims(user, groups: [user_group], extra_claims: extra_claims)
+        end
+
+        private
+
+        def preferred_username_for(user)
+          candidate = if user.respond_to?(:username)
+                        user.username
+                      elsif user.respond_to?(:preferred_username)
+                        user.preferred_username
+                      end
+
+          # Fall back to email when the configured method exists but
+          # returns a blank value (nil/empty), so the
+          # `preferred_username` claim is always populated when the user
+          # has at least an email address.
+          present?(candidate) ? candidate : user.email
+        end
+
+        def present?(value)
+          return false if value.nil?
+          return false if value.respond_to?(:empty?) && value.empty?
+
+          true
+        end
+
+        def safe_call(user, method)
+          user.public_send(method) if user.respond_to?(method)
+        end
+
+        def stringify_keys(hash)
+          return {} unless hash.is_a?(Hash)
+
+          hash.transform_keys(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/rails/testing/helpers.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'verikloak/rails/testing/claims_builder'
+require 'verikloak/rails/testing/middleware_stub'
+
+module Verikloak
+  module Rails
+    module Testing
+      # Top-level mix-in for RSpec example groups (request and policy specs).
+      # Composes {ClaimsBuilder} and {MiddlewareStub}, and adds
+      # `Verikloak::Pundit::UserContext` builders when the optional
+      # `verikloak-pundit` gem is loaded.
+      module Helpers
+        include ClaimsBuilder
+        include MiddlewareStub
+
+        # Build a `Verikloak::Pundit::UserContext` for policy specs.
+        #
+        # @param user [Object] application user
+        # @param claims [Hash] JWT claims (string keys)
+        # @return [Verikloak::Pundit::UserContext]
+        # @raise [RuntimeError] if `verikloak-pundit` is not loaded
+        def build_pundit_user_context(user, claims)
+          unless defined?(::Verikloak::Pundit::UserContext)
+            raise 'verikloak-pundit gem is not loaded; cannot build a UserContext'
+          end
+
+          ::Verikloak::Pundit::UserContext.new(user, claims)
+        end
+
+        # Convenience wrapper: admin claims + UserContext.
+        #
+        # @param user [Object]
+        # @param admin_group [String]
+        # @return [Verikloak::Pundit::UserContext]
+        def build_admin_user_context(user, admin_group: '/admin')
+          build_pundit_user_context(user, build_admin_claims(user, admin_group: admin_group))
+        end
+
+        # Convenience wrapper: user claims + UserContext.
+        #
+        # @param user [Object]
+        # @param user_group [String]
+        # @return [Verikloak::Pundit::UserContext]
+        def build_user_user_context(user, user_group: '/user')
+          build_pundit_user_context(user, build_user_claims(user, user_group: user_group))
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/rails/testing/middleware_stub.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Rails
+    module Testing
+      # Stubs the Verikloak middleware stack so authenticated request specs
+      # can run without contacting an OIDC provider or signing real JWTs.
+      #
+      # `stub_verikloak_middleware` patches `#call` on the relevant
+      # middlewares so they inject the supplied claims into
+      # `env['verikloak.user']` and pass through to the next middleware.
+      # The companion `verikloak.token` env key is also set when
+      # available so controller helpers like `current_token` work.
+      #
+      # Requires RSpec-style mocks (`allow_any_instance_of`). Load
+      # `verikloak/rails/testing/rspec` to wire things up automatically,
+      # or include this module directly into your example groups.
+      module MiddlewareStub
+        DEFAULT_STUB_TOKEN = 'verikloak-test-token'
+
+        # Stub all loaded Verikloak middlewares to populate the request
+        # environment with the supplied claims.
+        #
+        # @param claims [Hash] value placed into `env['verikloak.user']`
+        # @param token  [String] value placed into `env['verikloak.token']`
+        # @return [void]
+        def stub_verikloak_middleware(claims, token: DEFAULT_STUB_TOKEN)
+          stub_core_middleware(claims, token)
+          stub_bff_middleware(claims, token)           if bff_middleware_loaded?
+          stub_audience_middleware(claims, token)      if audience_middleware_loaded?
+        end
+
+        private
+
+        def stub_core_middleware(claims, token)
+          return unless defined?(::Verikloak::Middleware)
+
+          install_passthrough_stub(::Verikloak::Middleware, claims, token)
+        end
+
+        def stub_bff_middleware(claims, token)
+          install_passthrough_stub(::Verikloak::BFF::HeaderGuard, claims, token)
+        end
+
+        def stub_audience_middleware(claims, token)
+          install_passthrough_stub(::Verikloak::Audience::Middleware, claims, token)
+        end
+
+        def install_passthrough_stub(middleware_class, claims, token)
+          allow_any_instance_of(middleware_class).to receive(:call) do |instance, env|
+            env['verikloak.user']  = claims
+            env['verikloak.token'] = token if token
+            inner_app = instance.instance_variable_get(:@app)
+            inner_app.call(env)
+          end
+        end
+
+        def bff_middleware_loaded?
+          defined?(::Verikloak::BFF::HeaderGuard)
+        end
+
+        def audience_middleware_loaded?
+          defined?(::Verikloak::Audience::Middleware)
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/rails/testing/rspec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# RSpec integration for Verikloak::Rails::Testing.
+#
+# Require this file from `spec/rails_helper.rb` (or `spec/spec_helper.rb`)
+# to:
+#
+# 1. Mix {Verikloak::Rails::Testing::Helpers} into request and policy
+#    specs. Controller specs (`type: :controller`) are intentionally
+#    excluded because they bypass the Rack middleware stack, which is
+#    where `stub_verikloak_middleware` injects claims; use a request
+#    spec instead, or set `request.env['verikloak.user']` directly when
+#    you must use a controller spec.
+# 2. Register the shared contexts:
+#    - `"with verikloak admin auth"`
+#    - `"with verikloak user auth"`
+#    - `"with verikloak custom auth"`
+#
+# The shared contexts assume a `current_user` factory exists in the host
+# application (e.g. `create(:user)`). Override `let(:current_user)` to
+# inject a different user object.
+
+require 'verikloak/rails/testing/helpers'
+
+raise 'verikloak/rails/testing/rspec requires RSpec' unless defined?(RSpec)
+
+RSpec.configure do |config|
+  config.include Verikloak::Rails::Testing::Helpers, type: :request
+  config.include Verikloak::Rails::Testing::Helpers, type: :policy
+end
+
+RSpec.shared_context 'with verikloak admin auth' do
+  let(:current_user) { create(:user) }
+
+  before do
+    stub_verikloak_middleware(build_admin_claims(current_user))
+  end
+end
+
+RSpec.shared_context 'with verikloak user auth' do
+  let(:current_user) { create(:user) }
+
+  before do
+    stub_verikloak_middleware(build_user_claims(current_user))
+  end
+end
+
+RSpec.shared_context 'with verikloak custom auth' do
+  let(:current_user) { create(:user) }
+  let(:verikloak_groups)       { [] }
+  let(:verikloak_extra_claims) { {} }
+
+  before do
+    stub_verikloak_middleware(
+      build_jwt_claims(current_user, groups: verikloak_groups, extra_claims: verikloak_extra_claims)
+    )
+  end
+end

data/lib/verikloak/rails/testing.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module Rails
+    # Test-support helpers for application specs that exercise endpoints
+    # protected by Verikloak.
+    #
+    # Submodules:
+    # - {ClaimsBuilder}  – build JWT-shaped Hashes from a user-like
+    #   object. Pure Ruby, no test-framework dependency, so it can be
+    #   used standalone (e.g. from `Minitest`).
+    # - {MiddlewareStub} – stub Verikloak/BFF/Audience middleware to
+    #   inject pre-built claims into `env['verikloak.user']`. Requires
+    #   RSpec mocks (`allow_any_instance_of`); not usable from
+    #   `Minitest` without bringing in `rspec-mocks`.
+    # - {Helpers}        – mixes in {ClaimsBuilder} and {MiddlewareStub}
+    #   and adds Pundit `UserContext` builders when `verikloak-pundit`
+    #   is loaded.
+    #
+    # The simplest way to wire these into an RSpec suite is to require
+    # `verikloak/rails/testing/rspec` from `spec/rails_helper.rb`.
+    module Testing
+      autoload :ClaimsBuilder,  'verikloak/rails/testing/claims_builder'
+      autoload :MiddlewareStub, 'verikloak/rails/testing/middleware_stub'
+      autoload :Helpers,        'verikloak/rails/testing/helpers'
+    end
+  end
+end

data/lib/verikloak/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Verikloak
   module Rails
-    VERSION = '1.0.1'
+    VERSION = '1.1.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - taiyaky
@@ -83,6 +83,11 @@ files:
 - lib/verikloak/rails/railtie.rb
 - lib/verikloak/rails/railtie_logger.rb
 - lib/verikloak/rails/skip_path_checker.rb
+- lib/verikloak/rails/testing.rb
+- lib/verikloak/rails/testing/claims_builder.rb
+- lib/verikloak/rails/testing/helpers.rb
+- lib/verikloak/rails/testing/middleware_stub.rb
+- lib/verikloak/rails/testing/rspec.rb
 - lib/verikloak/rails/version.rb
 homepage: https://github.com/taiyaky/verikloak-rails
 licenses:
@@ -91,7 +96,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-rails
   changelog_uri: https://github.com/taiyaky/verikloak-rails/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-rails/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-rails/1.0.1
+  documentation_uri: https://rubydoc.info/gems/verikloak-rails/1.1.0
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: