legion-rbac 0.2.9 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: db6027eb10e80db5c7fce237a53e1640036d4d30e73e2e468029054843df5c4f
-  data.tar.gz: dd520f3dc81753b13bb29bf41bd664bbb0acdd789697a50649f93f77c68d3655
+  metadata.gz: 222914812dd7014e897e4aa3a6311ea7b4e8062c74ad1c532774f2f3c9e06fca
+  data.tar.gz: 30b265cf04e23b6456f839d5aeeeb47792751d3580f92b2085709b9f786388b5
 SHA512:
-  metadata.gz: e56a6e0e93987b829f04ca89c907753d893ec9d6907d7cf8f29d011b92b82906b249abac00fe3951142589b6ba8cbd8308fe0fd57b9d5974c708e00b744585f3
-  data.tar.gz: 5d47a2e7805ae8fcd242c1a7bcf2f916063adf8517831ec06b198f77c145b4734eaa9b36d4ce8450eebe17d5ff47c852abd8288ae9da9f6e115780f9bb152f45
+  metadata.gz: 5e9e541ca68dffe258a0766c0dbf58069faf39475ca94db674f38b8d33430dc04a14bf75b360ce1dc72807361a7d67f9bfff558541e3287ddf51a7325bf0a416
+  data.tar.gz: c327b53c9b782f461fc163aef47118c075f3367b9aa60585080faab7ebdf43c57092e580c86ea454a22c0ed5ecbd298a3027c442cc327988edd2dfe812047cb9

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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

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

@@ -1,8 +1,12 @@
 # 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,
@@ -49,24 +53,50 @@ module Legion
 
       class << self
         def audit(extension_name:, source_path:, declared_capabilities: [])
-          return skip_result(extension_name, 'capability audit disabled') unless enabled?
+          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
 
-          return skip_result(extension_name, 'no source path') unless source_path && Dir.exist?(source_path.to_s)
+          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)
 
-          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
+          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?
@@ -83,13 +113,15 @@ module Legion
 
         def scan_source(source_path)
           capabilities = []
-          Dir.glob(File.join(source_path, '**', '*.rb')).each do |file|
+          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
 
@@ -104,6 +136,7 @@ module Legion
               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,
@@ -115,14 +148,11 @@ module Legion
         end
 
         def log_warning(extension_name, undeclared)
-          return unless defined?(Legion::Logging)
-
-          Legion::Logging.warn(
-            "CapabilityAudit: #{extension_name} uses undeclared capabilities: #{undeclared.join(', ')}"
-          )
+          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:       [],

data/lib/legion/rbac/capability_registry.rb

@@ -1,11 +1,14 @@
 # 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] = {
@@ -14,39 +17,59 @@ module Legion
               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)
-          mon.synchronize do
+          capabilities = mon.synchronize do
             entry = entries[extension_name.to_s]
-            entry ? entry[:capabilities] : []
+            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
-          mon.synchronize do
+          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)
-          mon.synchronize do
+          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
-          mon.synchronize { entries.dup }
+          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)
-          mon.synchronize { entries.key?(extension_name.to_s) }
+          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

data/lib/legion/rbac/config_loader.rb

@@ -1,13 +1,16 @@
 # 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] || '',
@@ -17,7 +20,13 @@ module Legion
             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