legion-rbac 0.2.8 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59a7e721e473fdb1e65fe31d2da68e7fc7fc0a65e2e077f199f62c98aaf78fb5
-  data.tar.gz: b59c16e31ab6f63b1f93947a6c47ba59c891c2275a4f73463f892f4c0a71d9a8
+  metadata.gz: 222914812dd7014e897e4aa3a6311ea7b4e8062c74ad1c532774f2f3c9e06fca
+  data.tar.gz: 30b265cf04e23b6456f839d5aeeeb47792751d3580f92b2085709b9f786388b5
 SHA512:
-  metadata.gz: c8431ff82ad752660da99454b4170999572d2c37259fe33605238fc4faa6fdabe3d5c50a29dfc0d40c2fb45225107e457f15ac1e14aa0d8c41f6985cb39aa855
-  data.tar.gz: aafee7d9c8e9a3a07974aae8b890a8120dda0a10906a45ec1e967745563db0c2eed90ae39d2e14603d383df900ef450add66484d00cd4254288c573d976a47f2
+  metadata.gz: 5e9e541ca68dffe258a0766c0dbf58069faf39475ca94db674f38b8d33430dc04a14bf75b360ce1dc72807361a7d67f9bfff558541e3287ddf51a7325bf0a416
+  data.tar.gz: c327b53c9b782f461fc163aef47118c075f3367b9aa60585080faab7ebdf43c57092e580c86ea454a22c0ed5ecbd298a3027c442cc327988edd2dfe812047cb9

data/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.3.0] - 2026-04-02
+
+### Changed
+- Uplifted non-Sinatra RBAC library code to `Legion::Logging::Helper` with structured `log.*` usage instead of direct `Legion::Logging.*` calls.
+- Added structured exception handling via `handle_exception` across the RBAC library surface and expanded operational `info`/`debug` logging for setup, authorization, store access, claims mapping, middleware, and capability audit flows.
+- Promoted `legion-logging >= 1.5.0` to a runtime gem dependency and added coverage for the new logging rescue paths.
+- Explicitly load full `legion/logging` from RBAC library files so `require 'legion/rbac'` boots cleanly without preloading logging elsewhere.
+- Exposed `KerberosClaimsMapper` from the gem entrypoint and preserved caller-supplied fallback defaults/profile attributes when Kerberos fallback delegates to Entra.
+- Made `rbac.enabled` disable RBAC setup/enforcement paths consistently and normalized malformed `expires_at` inputs into validation errors with explicit time parsing.
+- Expanded middleware route coverage to include `/api/rbac/*`, honored `rbac.route_permissions` overrides, and compiled route matchers once per permission table.
+- Wired static and DB-backed role assignments into policy evaluation, enforced `target_team` scope in the core evaluator, and made execution authorization intersect role policy with runner grants and cross-team grants.
+- Hardened the smaller runtime edges: static assignment lookups now respect `principal_type`, capability registry reads return copies instead of live internals, capability denials render useful messages, resource regexes compile once, and RBAC collection routes use bounded `limit`/`offset` windows.
+- Synchronized RBAC role index lifecycle state so setup/shutdown expose a stable frozen empty index instead of `nil`, avoiding transitional reads during authorization and route access.
+
+## [0.2.9] - 2026-03-31
+
+### Added
+- `Legion::Rbac::CapabilityAudit` module: static analysis of extension source code to detect dangerous patterns (`system`, `exec`, `Open3`, backticks, `eval`, `Net::HTTP`, `Faraday`, `File.write`, `FileUtils`) and map them to required capabilities (`shell_execute`, `code_eval`, `network_outbound`, `filesystem_write`). Blocks extensions with undeclared capabilities in enforce mode, warns in warn mode. Configurable via `rbac.capability_audit` settings.
+- `Legion::Rbac::CapabilityAudit::AuditResult` value object with `blocked?`, `undeclared`, `detected_capabilities`, `declared_capabilities`, and `to_h` conversion.
+- `Legion::Rbac::CapabilityRegistry` module: thread-safe registry tracking which extensions have which capabilities. `register`, `for_extension`, `extensions_with`, `audit_result_for`, `all`, `registered?`, `clear!` methods.
+- `Legion::Rbac::PolicyEngine.evaluate_capability`: runtime RBAC gating for capabilities — checks if a principal's roles grant or deny a specific capability, with deny-always-wins semantics and dry-run support.
+- `Legion::Rbac::Role#capability_allowed?`: per-role capability check (denial takes precedence over grant).
+- `capability_grants` and `capability_denials` fields on all four built-in roles: admin (all granted), supervisor (shell + network + filesystem, code_eval denied), worker (network + filesystem, shell + eval denied), governance-observer (all denied).
+- `Legion::Rbac.audit_extension`: convenience method that audits an extension and registers it in the CapabilityRegistry.
+- `Legion::Rbac.authorize_capability!`: raises `AccessDenied` when a principal lacks the required capability.
+- `rbac.capability_audit` settings: `enabled` (default true), `mode` (enforce/warn), `undeclared_policy` (block).
+- 43 new specs (159 total) covering all three phases of the capability enforcement system.
+
 ## [0.2.8] - 2026-03-28
 
 ### Added

data/CLAUDE.md

@@ -2,7 +2,7 @@
 
 **Parent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
 **GitHub**: https://github.com/LegionIO/legion-rbac
-**Version**: 0.2.2
+**Version**: 0.2.7
 
 Optional RBAC gem for LegionIO. Vault-style flat policy model with deny-always-wins semantics.
 

data/Gemfile

@@ -9,5 +9,6 @@ group :test do
   gem 'rspec'
   gem 'rspec_junit_formatter'
   gem 'rubocop'
+  gem 'rubocop-legion'
   gem 'simplecov'
 end

data/README.md

@@ -2,7 +2,7 @@
 
 Role-based access control for LegionIO, following Vault-style flat policy patterns.
 
-**Version**: 0.2.2
+**Version**: 0.2.9
 
 ## Features
 
@@ -53,6 +53,36 @@ principal.profile       # => { first_name: "Jane", last_name: "Doe", ... }
 Legion::Rbac.authorize_execution!(principal: principal, runner_class: 'Legion::Extensions::LexHttp::Runners::Request', function: :get)
 ```
 
+### Capability Audit (Extension Security)
+
+Audit an extension's source code for dangerous patterns and enforce capability declarations:
+
+```ruby
+result = Legion::Rbac.audit_extension(
+  extension_name: 'lex-codegen',
+  source_path: '/path/to/lex-codegen/lib',
+  declared_capabilities: [:shell_execute, :filesystem_write]
+)
+result.blocked?               # => false (all capabilities declared)
+result.detected_capabilities  # => [:shell_execute, :filesystem_write]
+
+# Query the capability registry
+Legion::Rbac::CapabilityRegistry.for_extension('lex-codegen')
+# => [:filesystem_write, :shell_execute]
+
+Legion::Rbac::CapabilityRegistry.extensions_with(:shell_execute)
+# => ["lex-codegen", "lex-exec"]
+```
+
+### Capability Authorization
+
+Check if a principal's role allows a specific capability:
+
+```ruby
+Legion::Rbac.authorize_capability!(principal: principal, capability: :shell_execute, extension_name: 'lex-codegen')
+# Raises AccessDenied if the principal's role denies shell_execute
+```
+
 ### Dry-Run Check
 
 ```ruby

data/legion-rbac.gemspec

@@ -27,5 +27,6 @@ Gem::Specification.new do |spec|
   }
 
   spec.add_dependency 'legion-json', '>= 1.2.0'
+  spec.add_dependency 'legion-logging', '>= 1.5.0'
   spec.add_dependency 'legion-settings', '>= 1.3.12'
 end

data/lib/legion/rbac/capability_audit.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'legion/logging'
+
+module Legion
+  module Rbac
+    module CapabilityAudit
+      extend Legion::Logging::Helper
+
+      PATTERN_TO_CAPABILITY = {
+        /\bKernel\.system\b|\bsystem\s*\(/     => :shell_execute,
+        /\bKernel\.exec\b|\bexec\s*\(/         => :shell_execute,
+        /\bOpen3\b/                            => :shell_execute,
+        /`[^`]+`/                              => :shell_execute,
+        /\bIO\.popen\b/                        => :shell_execute,
+        /\bKernel\.eval\b|\beval\s*\(/         => :code_eval,
+        /\bNet::HTTP\b/                        => :network_outbound,
+        /\bFaraday\b/                          => :network_outbound,
+        /\bHTTParty\b/                         => :network_outbound,
+        /\bFile\.(write|open|delete|rename)\b/ => :filesystem_write,
+        /\bFileUtils\b/                        => :filesystem_write
+      }.freeze
+
+      class AuditResult
+        attr_reader :extension_name, :detected_capabilities, :declared_capabilities,
+                    :undeclared, :allowed, :reason
+
+        def initialize(extension_name:, detected:, declared:, allowed:, reason: nil)
+          @extension_name = extension_name
+          @detected_capabilities = detected.uniq.sort
+          @declared_capabilities = declared.map(&:to_sym).uniq.sort
+          @undeclared = (@detected_capabilities - @declared_capabilities).sort
+          @allowed = allowed
+          @reason = reason
+        end
+
+        def blocked?
+          !@allowed
+        end
+
+        def to_h
+          hash = {
+            extension_name:        @extension_name,
+            allowed:               @allowed,
+            detected_capabilities: @detected_capabilities,
+            declared_capabilities: @declared_capabilities,
+            undeclared:            @undeclared
+          }
+          hash[:reason] = @reason if @reason
+          hash
+        end
+      end
+
+      class << self
+        def audit(extension_name:, source_path:, declared_capabilities: [])
+          log.info(
+            "RBAC capability_audit start extension=#{extension_name} source_path=#{source_path} " \
+            "declared=#{Array(declared_capabilities).size}"
+          )
+          unless enabled?
+            result = skip_result(extension_name, 'capability audit disabled')
+            log.info("RBAC capability_audit skipped extension=#{extension_name} reason=#{result.reason}")
+            return result
+          end
+
+          unless source_path && Dir.exist?(source_path.to_s)
+            result = skip_result(extension_name, 'no source path')
+            log.info("RBAC capability_audit skipped extension=#{extension_name} reason=#{result.reason}")
+            return result
+          end
+
+          detected = scan_source(source_path)
+          declared_syms = Array(declared_capabilities).map(&:to_sym)
+          undeclared = (detected.uniq - declared_syms)
+
+          result = if undeclared.empty?
+                     AuditResult.new(
+                       extension_name: extension_name,
+                       detected:       detected,
+                       declared:       declared_syms,
+                       allowed:        true
+                     )
+                   else
+                     handle_undeclared(extension_name, detected, declared_syms, undeclared)
+                   end
+          log.info(
+            "RBAC capability_audit extension=#{extension_name} allowed=#{result.allowed} " \
+            "detected=#{result.detected_capabilities.size} undeclared=#{result.undeclared.size}"
+          )
+          result
+        rescue StandardError => e
+          handle_exception(
+            e,
+            level:          :error,
+            operation:      'rbac.capability_audit.audit',
+            extension_name: extension_name,
+            source_path:    source_path
+          )
+          raise
+        end
+
+        def enabled?
+          settings = capability_audit_settings
+          settings[:enabled] != false
+        end
+
+        def mode
+          settings = capability_audit_settings
+          (settings[:mode] || 'enforce').to_s
+        end
+
+        private
+
+        def scan_source(source_path)
+          capabilities = []
+          files = Dir.glob(File.join(source_path, '**', '*.rb'))
+          files.each do |file|
+            File.foreach(file) do |line|
+              PATTERN_TO_CAPABILITY.each do |pattern, capability|
+                capabilities << capability if line.match?(pattern)
+              end
+            end
+          end
+          log.debug("RBAC capability_audit scanned source_path=#{source_path} files=#{files.size}")
+          capabilities.uniq
+        end
+
+        def handle_undeclared(extension_name, detected, declared, undeclared)
+          if mode == 'warn'
+            log_warning(extension_name, undeclared)
+            AuditResult.new(
+              extension_name: extension_name,
+              detected:       detected,
+              declared:       declared,
+              allowed:        true,
+              reason:         "undeclared capabilities (warn mode): #{undeclared.join(', ')}"
+            )
+          else
+            log.warn("CapabilityAudit: #{extension_name} blocked for undeclared capabilities: #{undeclared.join(', ')}")
+            AuditResult.new(
+              extension_name: extension_name,
+              detected:       detected,
+              declared:       declared,
+              allowed:        false,
+              reason:         "undeclared capabilities: #{undeclared.join(', ')}"
+            )
+          end
+        end
+
+        def log_warning(extension_name, undeclared)
+          log.warn("CapabilityAudit: #{extension_name} uses undeclared capabilities: #{undeclared.join(', ')}")
+        end
+
+        def skip_result(extension_name, reason)
+          log.debug("RBAC capability_audit skip_result extension=#{extension_name} reason=#{reason}")
+          AuditResult.new(
+            extension_name: extension_name,
+            detected:       [],
+            declared:       [],
+            allowed:        true,
+            reason:         reason
+          )
+        end
+
+        def capability_audit_settings
+          return {} unless defined?(Legion::Settings)
+
+          Legion::Settings[:rbac]&.dig(:capability_audit) || {}
+        end
+      end
+    end
+  end
+end

data/lib/legion/rbac/capability_registry.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require 'legion/logging'
+require 'monitor'
+
+module Legion
+  module Rbac
+    module CapabilityRegistry
+      class << self
+        include Legion::Logging::Helper
+
+        def register(extension_name, capabilities:, audit_result: nil)
+          mon.synchronize do
+            entries[extension_name.to_s] = {
+              capabilities:  Array(capabilities).map(&:to_sym).uniq,
+              audit_result:  audit_result,
+              registered_at: Time.now
+            }
+          end
+          log.info("RBAC capability_registry register extension=#{extension_name} count=#{Array(capabilities).uniq.size}")
+        end
+
+        def for_extension(extension_name)
+          capabilities = mon.synchronize do
+            entry = entries[extension_name.to_s]
+            entry ? entry[:capabilities].dup : []
+          end
+          log.debug("RBAC capability_registry for_extension extension=#{extension_name} count=#{capabilities.size}")
+          capabilities
+        end
+
+        def extensions_with(capability)
+          cap_sym = capability.to_sym
+          extensions = mon.synchronize do
+            entries.select { |_, entry| entry[:capabilities].include?(cap_sym) }.keys
+          end
+          log.debug("RBAC capability_registry extensions_with capability=#{capability} count=#{extensions.size}")
+          extensions
+        end
+
+        def audit_result_for(extension_name)
+          audit_result = mon.synchronize do
+            entry = entries[extension_name.to_s]
+            entry&.dig(:audit_result)
+          end
+          log.debug("RBAC capability_registry audit_result_for extension=#{extension_name} present=#{!audit_result.nil?}")
+          audit_result
+        end
+
+        def all
+          registry = mon.synchronize do
+            entries.each_with_object({}) do |(extension_name, entry), copy|
+              copy[extension_name] = {
+                capabilities:  entry[:capabilities].dup,
+                audit_result:  entry[:audit_result],
+                registered_at: entry[:registered_at]
+              }
+            end
+          end
+          log.debug("RBAC capability_registry all count=#{registry.size}")
+          registry
+        end
+
+        def registered?(extension_name)
+          registered = mon.synchronize { entries.key?(extension_name.to_s) }
+          log.debug("RBAC capability_registry registered extension=#{extension_name} value=#{registered}")
+          registered
+        end
+
+        def clear!
+          mon.synchronize { @entries = {} }
+          log.info('RBAC capability_registry cleared')
+        end
+
+        private
+
+        def entries
+          @entries ||= {}
+        end
+
+        def mon
+          @mon ||= Monitor.new
+        end
+      end
+    end
+  end
+end

data/lib/legion/rbac/config_loader.rb

@@ -1,21 +1,32 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
 require 'legion/rbac/role'
 
 module Legion
   module Rbac
     module ConfigLoader
+      extend Legion::Logging::Helper
+
       def self.load_roles(roles_config = nil)
         roles_config ||= Legion::Settings[:rbac][:roles]
-        roles_config.each_with_object({}) do |(name, config), index|
+        roles = roles_config.each_with_object({}) do |(name, config), index|
           index[name.to_sym] = Role.new(
-            name:        name,
-            description: config[:description] || '',
-            permissions: config[:permissions] || [],
-            deny:        config[:deny] || [],
-            cross_team:  config[:cross_team] || false
+            name:               name,
+            description:        config[:description] || '',
+            permissions:        config[:permissions] || [],
+            deny:               config[:deny] || [],
+            cross_team:         config[:cross_team] || false,
+            capability_grants:  config[:capability_grants] || [],
+            capability_denials: config[:capability_denials] || []
           )
+          log.debug("RBAC role loaded name=#{name} permissions=#{config[:permissions]&.size || 0} deny=#{config[:deny]&.size || 0}")
         end
+        log.info("RBAC roles loaded count=#{roles.size}")
+        roles
+      rescue StandardError => e
+        handle_exception(e, level: :error, operation: 'rbac.config_loader.load_roles')
+        raise
       end
     end
   end

data/lib/legion/rbac/entra_claims_mapper.rb

@@ -1,41 +1,79 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
+
 module Legion
   module Rbac
     module EntraClaimsMapper
+      extend Legion::Logging::Helper
+
       DEFAULT_ROLE_MAP = {
         'Legion.Admin'      => 'admin',
         'Legion.Supervisor' => 'supervisor',
         'Legion.Worker'     => 'worker',
         'Legion.Observer'   => 'governance-observer'
       }.freeze
+      DEFAULT_TEAM_KEYS = %i[legion_team extension_legion_team tid].freeze
 
       module_function
 
-      def map_claims(entra_claims, role_map: DEFAULT_ROLE_MAP, group_map: {}, default_role: 'worker')
+      def map_claims(entra_claims, role_map: DEFAULT_ROLE_MAP, group_map: {}, default_role: 'worker',
+                     team_keys: DEFAULT_TEAM_KEYS, team_map: nil)
+        roles = resolve_roles(entra_claims, role_map: role_map, group_map: group_map)
+        used_default_role = roles.empty?
+        roles << default_role if used_default_role
+        team = resolve_team(entra_claims, team_keys: team_keys, team_map: team_map)
+
+        claims = {
+          sub:   claim_value(entra_claims, :oid, :sub),
+          name:  claim_value(entra_claims, :name, :preferred_username),
+          roles: roles.to_a,
+          team:  team,
+          scope: 'human'
+        }
+        log.info(
+          "RBAC entra_claims map sub=#{claims[:sub]} roles=#{claims[:roles].size} " \
+          "team=#{claims[:team]} default_role=#{used_default_role}"
+        )
+        claims
+      rescue StandardError => e
+        handle_exception(e, level: :error, operation: 'rbac.entra_claims_mapper.map_claims')
+        raise
+      end
+
+      def resolve_roles(entra_claims, role_map:, group_map:)
         roles = Set.new
 
-        Array(entra_claims[:roles] || entra_claims['roles']).each do |entra_role|
+        Array(claim_value(entra_claims, :roles)).each do |entra_role|
           legion_role = role_map[entra_role]
           roles << legion_role if legion_role
         end
 
-        Array(entra_claims[:groups] || entra_claims['groups']).each do |group_oid|
+        Array(claim_value(entra_claims, :groups)).each do |group_oid|
           legion_role = group_map[group_oid]
           roles << legion_role if legion_role
         end
 
-        roles << default_role if roles.empty?
+        roles
+      end
+
+      def resolve_team(entra_claims, team_keys:, team_map:)
+        raw_team = claim_value(entra_claims, *Array(team_keys))
+        return raw_team if raw_team.nil? || team_map.nil? || team_map.empty?
 
-        {
-          sub:   entra_claims[:oid] || entra_claims[:sub] || entra_claims['oid'] || entra_claims['sub'],
-          name:  entra_claims[:name] || entra_claims[:preferred_username] ||
-            entra_claims['name'] || entra_claims['preferred_username'],
-          roles: roles.to_a,
-          team:  entra_claims[:tid] || entra_claims['tid'],
-          scope: 'human'
-        }
+        team_map[raw_team] || team_map[raw_team.to_s] || team_map[raw_team.to_sym]
       end
+
+      def claim_value(claims, *keys)
+        keys.each do |key|
+          value = claims[key] || claims[key.to_s]
+          return value unless value.nil?
+        end
+
+        nil
+      end
+
+      private :resolve_roles, :resolve_team, :claim_value
     end
   end
 end

data/lib/legion/rbac/kerberos_claims_mapper.rb

@@ -1,43 +1,141 @@
 # frozen_string_literal: true
 
+require 'legion/logging'
+
 module Legion
   module Rbac
     module KerberosClaimsMapper
+      extend Legion::Logging::Helper
+
       DEFAULT_ROLE = 'worker'
+      DEFAULT_TEAM_KEYS = %i[team legion_team].freeze
 
       module_function
 
-      def map(principal:, groups:, role_map: {}, default_role: DEFAULT_ROLE, **profile)
+      def map(principal:, groups:, role_map: {}, default_role: DEFAULT_ROLE, team_keys: DEFAULT_TEAM_KEYS,
+              team_map: nil, **profile)
         parts = principal.split('@', 2)
         username = parts.first
         realm = parts.length > 1 ? parts.last : nil
         roles = Array(groups).filter_map { |g| role_map[g] }.uniq
-        roles = [default_role] if roles.empty?
+        used_default_role = roles.empty?
+        roles = [default_role] if used_default_role
+        team = resolve_team(profile, team_keys: team_keys, team_map: team_map)
 
-        {
+        claims = {
           sub:            username,
           samaccountname: username,
           ad_fqdn:        realm&.downcase,
           roles:          roles,
           scope:          'human',
           auth_method:    'kerberos',
-          **profile
+          **profile,
+          team:           team
         }.compact
+        log.info(
+          "RBAC kerberos_claims map principal=#{username} roles=#{claims[:roles].size} " \
+          "default_role=#{used_default_role} realm=#{claims[:ad_fqdn]} team=#{claims[:team] || 'none'}"
+        )
+        claims
+      rescue StandardError => e
+        handle_exception(e, level: :error, operation: 'rbac.kerberos_claims_mapper.map', principal: principal)
+        raise
       end
 
       def map_with_fallback(principal:, groups: nil, fallback: :entra, role_map: {},
                             default_role: DEFAULT_ROLE, **profile)
+        profile, team_resolution = extract_team_resolution(profile)
         if groups&.any?
-          map(principal: principal, groups: groups, role_map: role_map, default_role: default_role, **profile)
+          claims = mapped_claims(
+            principal:       principal,
+            groups:          groups,
+            role_map:        role_map,
+            default_role:    default_role,
+            team_resolution: team_resolution,
+            profile:         profile
+          )
+          path = 'groups'
         elsif fallback == :entra && defined?(Legion::Rbac::EntraClaimsMapper)
-          entra_claims = { sub: principal, preferred_username: principal }
-          result = EntraClaimsMapper.map_claims(entra_claims)
-          result&.merge(auth_method: 'kerberos') || map(principal: principal, groups: [],
-                                                        role_map: role_map, default_role: default_role)
+          claims = entra_fallback_claims(
+            principal:       principal,
+            role_map:        role_map,
+            default_role:    default_role,
+            team_resolution: team_resolution,
+            profile:         profile
+          )
+          path = 'entra'
         else
-          map(principal: principal, groups: [], role_map: role_map, default_role: default_role, **profile)
+          claims = mapped_claims(
+            principal:       principal,
+            groups:          [],
+            role_map:        role_map,
+            default_role:    default_role,
+            team_resolution: team_resolution,
+            profile:         profile
+          )
+          path = 'default_role'
         end
+        log.info("RBAC kerberos_claims fallback principal=#{principal} path=#{path}")
+        claims
+      rescue StandardError => e
+        handle_exception(
+          e,
+          level:     :error,
+          operation: 'rbac.kerberos_claims_mapper.map_with_fallback',
+          principal: principal,
+          fallback:  fallback
+        )
+        raise
+      end
+
+      def resolve_team(profile, team_keys:, team_map:)
+        Array(team_keys).each do |key|
+          value = profile[key] || profile[key.to_s]
+          return value if value && (team_map.nil? || team_map.empty?)
+          return team_map[value] || team_map[value.to_s] || team_map[value.to_sym] if value
+        end
+        nil
+      end
+
+      def extract_team_resolution(profile)
+        sanitized_profile = profile.dup
+        team_resolution = {
+          team_keys: sanitized_profile.delete(:team_keys) || DEFAULT_TEAM_KEYS,
+          team_map:  sanitized_profile.delete(:team_map)
+        }
+        [sanitized_profile, team_resolution]
+      end
+
+      def mapped_claims(principal:, groups:, role_map:, default_role:, team_resolution:, profile:)
+        map(
+          principal:    principal,
+          groups:       groups,
+          role_map:     role_map,
+          default_role: default_role,
+          **team_resolution,
+          **profile
+        )
       end
+
+      def entra_fallback_claims(principal:, role_map:, default_role:, team_resolution:, profile:)
+        entra_claims = { sub: principal, preferred_username: principal, **profile }.compact
+        result = EntraClaimsMapper.map_claims(
+          entra_claims,
+          role_map:     role_map,
+          default_role: default_role,
+          **team_resolution
+        )
+        result&.merge(**profile, auth_method: 'kerberos', team: result[:team]) || mapped_claims(
+          principal:       principal,
+          groups:          [],
+          role_map:        role_map,
+          default_role:    default_role,
+          team_resolution: team_resolution,
+          profile:         profile
+        )
+      end
+
+      private :resolve_team, :extract_team_resolution, :mapped_claims, :entra_fallback_claims
     end
   end
 end