legionio 1.7.19 → 1.7.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2114c2b32ae4dbc1650bef546391f6abb1499a0b9d96d577739503c47caba79
-  data.tar.gz: 1e95267b23de0b635ffb32c9f745f58fe0bac63aa7d806a6581e3557b9b1aad6
+  metadata.gz: ba8e945b1c999e0c815583388817c35bc019134994745682a774afb6e645db1f
+  data.tar.gz: d21bf7aea3328dda51f7139ed36632b31f16e5c57bef938a9eb2f9f000c2c21e
 SHA512:
-  metadata.gz: 56c140c38d73a16c97574b405c4f27bdb91de199758692e76aecd0ec55afad66acab08fc011cf31a658df408cfcf8506e5e2971f4fbe92a4276e8856153a7481
-  data.tar.gz: 903faf2b78e2f27e1176e03558138f58ee9e6bdfcc34ac3f61c8c933424a0f7a0c641ba97d38d27c527b41cad93c9d8f69bffb64fed8a032a5d1aeb2bd6cb5ff
+  metadata.gz: c5ef0de86e4ea0a8e92fc7433af4e36bb8b7088737142abcfa5edcaad3769ede8acf0205e2b8478e80cc4376052e6cb3ef3df384b2cf2c39abdc8205fd965a68
+  data.tar.gz: 389cf7d22ac2db9e44489c4118cbef323d0d92d9242b4ec0e8a4c7ed141425497249a6832b2cf1bbecdc9e6666d65251978fac36f299175195d2eefa8fb6e190

data/.rubocop.yml

@@ -3,6 +3,9 @@ AllCops:
   NewCops: enable
   SuggestExtensions: false
 
+Style/RedundantConstantBase:
+  Enabled: false
+
 Layout/LineLength:
   Max: 160
   Exclude:

data/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 ## [Unreleased]
 
+## [1.7.20] - 2026-04-06
+### Added
+- `Legion::Mode` module with `LEGACY_MAP`, ENV/Settings fallback chain, `agent?`/`worker?`/`infra?`/`lite?` predicates
+- `Legion.instance_id` — UUID computed at load time, ENV override via `LEGIONIO_INSTANCE_ID`
+- `Legion::Identity::Process` singleton — process identity with `bind!`, `bind_fallback!`, `queue_prefix` per-mode, `AtomicReference` thread safety
+- `Legion::Identity::Request` — per-request immutable identity with `from_env`, `from_auth_context`, `to_caller_hash`, `to_rbac_principal`
+- `Legion::Identity::Lease` — credential lease value object with `expired?`, `stale?` (50% TTL), `ttl_seconds`, `valid?`
+- `Legion::Identity::LeaseRenewer` — background thread per provider, 50% TTL renewal, cooperative shutdown (no `Thread#kill`)
+- `Legion::Identity::Broker` — provider management with groups cache (60s TTL, single-flight CAS), `token_for`, `credentials_for`, `shutdown`
+- `Legion::Identity::Middleware` — Rack middleware bridging `legion.auth` to `legion.principal` (`Identity::Request`)
+- `setup_identity` boot step 9 — parallel provider resolution via `Concurrent::Promises`, fallback to `ENV['USER']`
+- Extension publish suppression — defers `LexRegister.publish` until identity resolves, `flush_pending_registrations!`
+- Identity provider auto-registration during phased extension load (`identity_provider?` duck-type check)
+- `GET /api/identity/audit` route with principal and duration filtering
+- `legion doctor` checks: `ApiBindCheck` (non-loopback without auth), `ModeCheck` (no explicit process.mode)
+
+### Changed
+- `Readiness.status` upgraded to `Concurrent::Hash` for thread safety; `:identity` added to `COMPONENTS`
+- `READONLY_SECTIONS` extended with `:identity`, `:rbac`, `:api`
+- Default API bind changed from `0.0.0.0` to `127.0.0.1`
+- `ProcessRole` delegates `.current` to `Mode.current`; added `:agent` and `:infra` role entries
+- `lite_mode?` delegates to `Mode.lite?`
+- Reload path adds `Identity::Process.refresh_credentials` after transport reconnect
+- Shutdown adds cooperative `Identity::Broker.shutdown` and JWKS background refresh stop
+
 ## [1.7.19] - 2026-04-06
 
 ### Added

data/lib/legion/api/default_settings.rb

@@ -9,7 +9,7 @@ module Legion
         {
           enabled:         true,
           port:            4567,
-          bind:            '0.0.0.0',
+          bind:            '127.0.0.1',
           puma:            puma_defaults,
           bind_retries:    3,
           bind_retry_wait: 2,

data/lib/legion/api/identity_audit.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module IdentityAudit
+        def self.registered(app)
+          app.helpers IdentityAuditHelpers
+
+          app.get '/api/identity/audit' do
+            halt 503, json_error('unavailable', 'audit records not available') unless defined?(Legion::Data::Model::AuditRecord)
+
+            dataset = Legion::Data::Model::AuditRecord.where(entity_type: 'identity')
+
+            principal = params[:principal]
+            dataset = dataset.where(Sequel.lit("metadata->>'principal' = ?", principal)) if principal
+
+            since = params[:since]
+            if since
+              duration = parse_since_duration(since)
+              dataset = dataset.where { created_at >= Time.now - duration } if duration
+            end
+
+            records = dataset.order(Sequel.desc(:created_at)).limit(100).all
+            json_collection(records.map do |r|
+              { id: r.id, action: r.action, entity_type: r.entity_type, metadata: r.parsed_metadata, created_at: r.created_at }
+            end)
+          end
+        end
+
+        module IdentityAuditHelpers
+          def parse_since_duration(value)
+            return nil unless value.is_a?(String)
+
+            case value
+            when /\A(\d+)h\z/ then Regexp.last_match(1).to_i * 3600
+            when /\A(\d+)m\z/ then Regexp.last_match(1).to_i * 60
+            when /\A(\d+)s\z/ then Regexp.last_match(1).to_i
+            when /\A(\d+)d\z/ then Regexp.last_match(1).to_i * 86_400
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/api/settings.rb

@@ -5,7 +5,7 @@ module Legion
     module Routes
       module Settings
         SENSITIVE_KEYS = %i[password secret token key cert private_key api_key].freeze
-        READONLY_SECTIONS = %i[crypt transport].freeze
+        READONLY_SECTIONS = %i[crypt transport identity rbac api].freeze
 
         def self.registered(app)
           app.get '/api/settings' do

data/lib/legion/api.rb

@@ -60,6 +60,7 @@ require_relative 'api/tbi_patterns'
 require_relative 'api/webhooks'
 require_relative 'api/tenants'
 require_relative 'api/inbound_webhooks'
+require_relative 'api/identity_audit'
 require_relative 'api/graphql' if defined?(GraphQL)
 
 module Legion
@@ -216,6 +217,7 @@ module Legion
     register Routes::Webhooks
     register Routes::Tenants
     register Routes::InboundWebhooks
+    register Routes::IdentityAudit
     register Routes::GraphQL if defined?(Routes::GraphQL)
 
     use Legion::API::Middleware::RequestLogger

data/lib/legion/cli/doctor/api_bind_check.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Legion
+  module CLI
+    class Doctor
+      class ApiBindCheck
+        LOOPBACK_BINDS = %w[127.0.0.1 ::1 localhost].freeze
+
+        def name
+          'API bind address'
+        end
+
+        def run
+          return skip_result unless defined?(Legion::Settings)
+
+          api_settings = Legion::Settings[:api]
+          return skip_result unless api_settings.is_a?(Hash)
+
+          bind = api_settings[:bind]
+          return skip_result if bind.nil?
+
+          if LOOPBACK_BINDS.include?(bind)
+            Result.new(
+              name:    name,
+              status:  :pass,
+              message: "API bound to loopback (#{bind})"
+            )
+          elsif api_settings.dig(:auth, :enabled) == true
+            Result.new(
+              name:    name,
+              status:  :pass,
+              message: "API bound to #{bind} with auth enabled"
+            )
+          else
+            Result.new(
+              name:         name,
+              status:       :warn,
+              message:      "API bound to non-loopback address (#{bind}) without explicit auth configuration",
+              prescription: "Set api.auth.enabled: true or change api.bind to '127.0.0.1'"
+            )
+          end
+        end
+
+        private
+
+        def skip_result
+          Result.new(
+            name:    name,
+            status:  :pass,
+            message: 'API settings not loaded'
+          )
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli/doctor/mode_check.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Legion
+  module CLI
+    class Doctor
+      class ModeCheck
+        def name
+          'Process mode'
+        end
+
+        def run
+          unless defined?(Legion::Settings)
+            return Result.new(
+              name:    name,
+              status:  :pass,
+              message: 'Settings not loaded'
+            )
+          end
+
+          explicit_mode = Legion::Settings.dig(:process, :mode) || Legion::Settings[:mode]
+
+          if explicit_mode
+            Result.new(
+              name:    name,
+              status:  :pass,
+              message: "Explicit process mode configured: #{explicit_mode}"
+            )
+          else
+            Result.new(
+              name:         name,
+              status:       :warn,
+              message:      'No explicit process.mode configured (defaulting to agent)',
+              prescription: 'Set {"process": {"mode": "agent"}} in settings to prepare for Phase 9 default change to worker'
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/cli/doctor_command.rb

@@ -17,6 +17,8 @@ module Legion
       autoload :PidCheck,         'legion/cli/doctor/pid_check'
       autoload :PermissionsCheck, 'legion/cli/doctor/permissions_check'
       autoload :TlsCheck,         'legion/cli/doctor/tls_check'
+      autoload :ApiBindCheck,     'legion/cli/doctor/api_bind_check'
+      autoload :ModeCheck,        'legion/cli/doctor/mode_check'
 
       def self.exit_on_failure?
         true
@@ -37,6 +39,8 @@ module Legion
         PidCheck
         PermissionsCheck
         TlsCheck
+        ApiBindCheck
+        ModeCheck
       ].freeze
 
       # Weights: security > connectivity > convenience

data/lib/legion/extensions.rb

@@ -22,6 +22,7 @@ module Legion
         @actors = []
         @running_instances = Concurrent::Array.new
         @loaded_extensions = []
+        @pending_registrations = Concurrent::Array.new
 
         find_extensions
 
@@ -106,6 +107,21 @@ module Legion
         Legion::Logging.info "Successfully shut down all actors (#{(Time.now - shutdown_start).round(1)}s)"
       end
 
+      def flush_pending_registrations!
+        return if @pending_registrations.nil? || @pending_registrations.empty?
+
+        registrations = @pending_registrations
+        count = registrations.size
+        @pending_registrations = nil
+
+        registrations.each do |registration|
+          registration.publish
+        rescue StandardError => e
+          Legion::Logging.warn "[Extensions] flush registration failed: #{e.message}" if defined?(Legion::Logging)
+        end
+        Legion::Logging.info "[Extensions] flushed #{count} pending registrations" if defined?(Legion::Logging)
+      end
+
       def pause_actors
         @running_instances&.each do |inst|
           timer = inst.instance_variable_get(:@timer)
@@ -253,8 +269,15 @@ module Legion
         has_logger = extension.respond_to?(:log)
         extension.autobuild
 
+        register_identity_provider(extension, entry) if identity_provider?(extension)
+
         require 'legion/transport/messages/lex_register'
-        Legion::Transport::Messages::LexRegister.new(function: 'save', opts: extension.runners).publish
+        registration = Legion::Transport::Messages::LexRegister.new(function: 'save', opts: extension.runners)
+        if @pending_registrations
+          @pending_registrations << registration
+        else
+          registration.publish
+        end
 
         register_capabilities(entry[:gem_name], extension.runners) if extension.respond_to?(:runners)
         write_lex_cli_manifest(entry, extension)
@@ -405,6 +428,39 @@ module Legion
 
       private
 
+      def identity_provider?(extension)
+        extension.respond_to?(:provider_name) &&
+          extension.respond_to?(:provider_type) &&
+          extension.respond_to?(:facing)
+      end
+
+      def register_identity_provider(extension, entry)
+        return unless defined?(Legion::Data) && Legion::Data.connected?
+        return unless defined?(Legion::Data::Model::IdentityProvider)
+
+        name = extension.provider_name.to_s
+        attrs = {
+          provider_type: extension.provider_type.to_s,
+          facing:        extension.facing.to_s,
+          priority:      extension.respond_to?(:priority) ? extension.priority : 100,
+          trust_weight:  extension.respond_to?(:trust_weight) ? extension.trust_weight : 50,
+          capabilities:  extension.respond_to?(:capabilities) ? Array(extension.capabilities).map(&:to_s) : [],
+          source:        'gem',
+          enabled:       true
+        }
+
+        existing = Legion::Data::Model::IdentityProvider.where(name: name).first
+        if existing
+          diverged = attrs.any? { |k, v| existing.send(k).to_s != v.to_s }
+          Legion::Logging.info "[identity][provider] name=#{name} source=db/gem diverged=#{diverged}" if defined?(Legion::Logging)
+        else
+          Legion::Data::Model::IdentityProvider.insert_conflict(target: :name, update: attrs).insert(attrs.merge(name: name))
+          Legion::Logging.info "[identity][provider] name=#{name} registered" if defined?(Legion::Logging)
+        end
+      rescue StandardError => e
+        Legion::Logging.warn "[identity][provider] registration failed for #{entry[:gem_name]}: #{e.message}" if defined?(Legion::Logging)
+      end
+
       def write_lex_cli_manifest(entry, extension)
         require 'legion/cli/lex_cli_manifest'
 

data/lib/legion/identity/broker.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Legion
+  module Identity
+    module Broker
+      GROUPS_CACHE_TTL = 60
+
+      class << self
+        def token_for(provider_name)
+          renewer = renewers[provider_name.to_sym]
+          return nil unless renewer
+
+          lease = renewer.current_lease
+          lease&.valid? ? lease.token : nil
+        end
+
+        def credentials_for(provider_name, service: nil)
+          renewer = renewers[provider_name.to_sym]
+          return nil unless renewer
+
+          lease = renewer.current_lease
+          return nil unless lease&.valid?
+
+          { token: lease.token, provider: provider_name.to_sym, service: service, lease: lease }
+        end
+
+        def register_provider(provider_name, provider:, lease:)
+          name = provider_name.to_sym
+          renewers[name]&.stop!
+          renewers[name] = LeaseRenewer.new(
+            provider_name: name,
+            provider:      provider,
+            lease:         lease
+          )
+        end
+
+        def authenticated?
+          Identity::Process.resolved?
+        end
+
+        def groups
+          cached = @groups_cache&.get
+          return cached[:groups] if cached && (Time.now - cached[:fetched_at]) < GROUPS_CACHE_TTL
+
+          if @groups_fetch_in_progress.make_true
+            begin
+              fetched = fetch_groups
+              @groups_cache.set({ groups: fetched, fetched_at: Time.now })
+              fetched
+            ensure
+              @groups_fetch_in_progress.make_false
+            end
+          else
+            loop do
+              current = @groups_cache&.get
+              return current[:groups] if current
+
+              break unless @groups_fetch_in_progress.true?
+
+              sleep(0.01)
+            end
+
+            cached ? cached[:groups] : []
+          end
+        end
+
+        def invalidate_groups_cache!
+          @groups_cache.set(nil)
+        end
+
+        def emails
+          process_state = Identity::Process.identity_hash
+          metadata = process_state[:metadata] || {}
+          Array(metadata[:emails])
+        end
+
+        def providers
+          renewers.keys
+        end
+
+        def leases
+          renewers.transform_values { |r| r.current_lease&.to_h }
+        end
+
+        def shutdown
+          renewers.each_value do |r|
+            r.stop!
+          rescue Exception # rubocop:disable Lint/RescueException
+            nil
+          end
+          renewers.clear
+        end
+
+        def reset!
+          shutdown
+          @groups_cache = Concurrent::AtomicReference.new(nil)
+          @groups_fetch_in_progress = Concurrent::AtomicBoolean.new(false)
+        end
+
+        private
+
+        def renewers
+          @renewers ||= Concurrent::Hash.new
+        end
+
+        def fetch_groups
+          process_groups = Identity::Process.identity_hash[:groups]
+          return process_groups if process_groups && !process_groups.empty?
+
+          return db_groups if db_available?
+
+          []
+        end
+
+        def db_groups
+          return [] unless defined?(Legion::Data) && Legion::Data.respond_to?(:connected?) && Legion::Data.connected?
+
+          model = begin
+            Legion::Data::Model::IdentityGroupMembership
+          rescue StandardError
+            nil
+          end
+          return [] unless model
+
+          principal_id = Identity::Process.id
+          memberships = model.where(principal_id: principal_id, status: 'active').all
+          memberships.filter_map do |m|
+            m.group.name
+          rescue StandardError
+            nil
+          end
+        rescue StandardError => e
+          log_warn("Broker.db_groups failed: #{e.message}")
+          []
+        end
+
+        def db_available?
+          defined?(Legion::Data) &&
+            Legion::Data.respond_to?(:connected?) &&
+            Legion::Data.connected?
+        end
+
+        def log_warn(message)
+          if defined?(Legion::Logging) && Legion::Logging.respond_to?(:warn)
+            Legion::Logging.warn("[Identity::Broker] #{message}")
+          else
+            $stderr.puts "[Identity::Broker] #{message}" # rubocop:disable Style/StderrPuts
+          end
+        end
+      end
+
+      # Initialize atomics at module definition time
+      @groups_cache = Concurrent::AtomicReference.new(nil)
+      @groups_fetch_in_progress = Concurrent::AtomicBoolean.new(false)
+    end
+  end
+end

data/lib/legion/identity/lease.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Legion
+  module Identity
+    class Lease
+      attr_reader :provider, :credential, :lease_id, :expires_at, :renewable, :issued_at, :metadata
+
+      def initialize(provider:, credential:, lease_id: nil, expires_at: nil, renewable: false, issued_at: nil, metadata: {}) # rubocop:disable Metrics/ParameterLists
+        @provider = provider
+        @credential = credential
+        @lease_id = lease_id
+        @expires_at = expires_at
+        @renewable = renewable
+        @issued_at = issued_at || Time.now
+        @metadata = metadata.freeze
+      end
+
+      def token
+        credential
+      end
+
+      def expired?
+        return false if expires_at.nil?
+
+        Time.now >= expires_at
+      end
+
+      def stale?
+        return false if expires_at.nil? || issued_at.nil?
+
+        elapsed = Time.now - issued_at
+        total = expires_at - issued_at
+        return false if total <= 0
+
+        elapsed >= (total * 0.5)
+      end
+
+      def ttl_seconds
+        return nil if expires_at.nil?
+
+        remaining = expires_at - Time.now
+        remaining.negative? ? 0 : remaining.to_i
+      end
+
+      def valid?
+        !credential.nil? && !expired?
+      end
+
+      def to_h
+        {
+          provider:   provider,
+          lease_id:   lease_id,
+          expires_at: expires_at&.iso8601,
+          renewable:  renewable,
+          issued_at:  issued_at&.iso8601,
+          ttl:        ttl_seconds,
+          valid:      valid?,
+          metadata:   metadata
+        }
+      end
+    end
+  end
+end

data/lib/legion/identity/lease_renewer.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module Legion
+  module Identity
+    class LeaseRenewer
+      attr_reader :provider_name
+
+      BACKOFF_SLEEP  = 5
+      MIN_SLEEP      = 1
+      DEFAULT_SLEEP  = 60
+
+      def initialize(provider_name:, provider:, lease:)
+        @provider_name = provider_name
+        @provider      = provider
+        @lease         = Concurrent::AtomicReference.new(lease)
+        @stop          = Concurrent::AtomicBoolean.new(false)
+        @thread        = Thread.new { run_loop }
+        @thread.name   = "lease-renewer-#{provider_name}"
+        @thread.abort_on_exception = false
+      end
+
+      def current_lease
+        @lease.get
+      end
+
+      def stop!
+        @stop.make_true
+        @thread&.wakeup rescue nil # rubocop:disable Style/RescueModifier
+        @thread&.join(5)
+      end
+
+      def alive?
+        @thread&.alive? || false
+      end
+
+      private
+
+      def run_loop
+        until @stop.true?
+          lease      = @lease.get
+          sleep_time = compute_sleep(lease)
+          interruptible_sleep(sleep_time)
+          break if @stop.true?
+
+          renew
+        end
+      end
+
+      def renew
+        new_lease = @provider.provide_token
+        @lease.set(new_lease) if new_lease&.valid?
+      rescue StandardError => e
+        log_renewal_failure(e)
+        interruptible_sleep(BACKOFF_SLEEP)
+      end
+
+      def compute_sleep(lease)
+        return DEFAULT_SLEEP if lease.nil? || lease.expires_at.nil? || lease.issued_at.nil?
+
+        remaining      = lease.expires_at - Time.now
+        half_remaining = remaining / 2.0
+        [half_remaining, MIN_SLEEP].max
+      end
+
+      def interruptible_sleep(seconds)
+        deadline = Time.now + seconds
+        sleep([1, deadline - Time.now].min) while Time.now < deadline && !@stop.true?
+      end
+
+      def log_renewal_failure(error)
+        message = "[LeaseRenewer][#{@provider_name}] renewal failed: #{error.message}"
+        if defined?(Legion::Logging) && Legion::Logging.respond_to?(:warn)
+          Legion::Logging.warn(message)
+        else
+          $stderr.puts message # rubocop:disable Style/StderrPuts
+        end
+      end
+    end
+  end
+end

data/lib/legion/identity/middleware.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Legion
+  module Identity
+    class Middleware
+      SKIP_PATHS     = %w[/api/health /api/ready /api/openapi.json /metrics].freeze
+      LOOPBACK_BINDS = %w[127.0.0.1 ::1 localhost].freeze
+
+      def initialize(app, require_auth: false)
+        @app          = app
+        @require_auth = require_auth
+      end
+
+      def call(env)
+        return @app.call(env) if skip_path?(env['PATH_INFO'])
+
+        # Bridge from existing auth middleware
+        auth_claims  = env['legion.auth']
+        auth_method  = env['legion.auth_method']
+
+        env['legion.principal'] = if auth_claims
+                                    build_request(auth_claims, auth_method)
+                                  elsif @require_auth
+                                    # Auth middleware already handled 401 for protected paths;
+                                    # this is a safety net for any path that slipped through.
+                                    nil
+                                  else
+                                    # No auth required (loopback bind, lite mode, etc.).
+                                    # Set a system-level principal so audit trails always have an identity.
+                                    system_principal
+                                  end
+
+        @app.call(env)
+      end
+
+      # Returns whether the API should require authentication.
+      # Skips auth for lite mode and loopback binds (local dev / CI).
+      def self.require_auth?(bind:, mode:)
+        return false if mode == :lite
+        return false if LOOPBACK_BINDS.include?(bind)
+
+        true
+      end
+
+      private
+
+      def skip_path?(path)
+        SKIP_PATHS.any? { |p| path.start_with?(p) }
+      end
+
+      def build_request(claims, method)
+        Identity::Request.from_auth_context({
+                                              sub:    claims[:sub] || claims[:worker_id] || claims[:owner_msid],
+                                              name:   claims[:name] || claims[:sub],
+                                              kind:   determine_kind(claims, method),
+                                              groups: Array(claims[:roles] || claims[:groups]),
+                                              source: method&.to_sym
+                                            })
+      end
+
+      def determine_kind(claims, method)
+        return :service if claims[:scope] == 'worker' || claims[:worker_id]
+        return :human   if method == 'kerberos' || claims[:scope] == 'human'
+
+        :human
+      end
+
+      def system_principal
+        @system_principal ||= Identity::Request.new(
+          principal_id:   'system:local',
+          canonical_name: 'system',
+          kind:           :service,
+          groups:         [],
+          source:         :local
+        )
+      end
+    end
+  end
+end

data/lib/legion/identity/process.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'socket'
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/atomic/atomic_boolean'
+
+module Legion
+  module Identity
+    module Process
+      EMPTY_STATE = {
+        id:             nil,
+        canonical_name: nil,
+        kind:           nil,
+        persistent:     false,
+        groups:         [].freeze,
+        metadata:       {}.freeze
+      }.freeze
+
+      class << self
+        def id
+          state = @state.get
+          state[:id] || Legion.instance_id
+        end
+
+        def canonical_name
+          state = @state.get
+          state[:canonical_name] || 'anonymous'
+        end
+
+        def kind
+          @state.get[:kind]
+        end
+
+        def mode
+          Legion::Mode.current
+        end
+
+        def queue_prefix
+          name = canonical_name
+          case mode
+          when :worker then "worker.#{name}.#{Legion.instance_id}"
+          when :infra  then "infra.#{name}.#{safe_hostname}"
+          when :lite   then "lite.#{name}.#{Legion.instance_id}"
+          else              "agent.#{name}.#{safe_hostname}"
+          end
+        end
+
+        def resolved?
+          @resolved.true?
+        end
+
+        def persistent?
+          @state.get[:persistent] == true
+        end
+
+        def identity_hash
+          {
+            id:             id,
+            canonical_name: canonical_name,
+            kind:           kind,
+            mode:           mode,
+            queue_prefix:   queue_prefix,
+            resolved:       resolved?,
+            persistent:     persistent?,
+            groups:         @state.get[:groups] || [],
+            metadata:       @state.get[:metadata] || {}
+          }
+        end
+
+        def bind!(provider, identity_hash)
+          @provider = provider
+          @state.set({
+                       id:             identity_hash[:id],
+                       canonical_name: identity_hash[:canonical_name],
+                       kind:           identity_hash[:kind],
+                       persistent:     identity_hash.fetch(:persistent, true),
+                       groups:         Array(identity_hash[:groups]).compact.freeze,
+                       metadata:       identity_hash[:metadata].is_a?(Hash) ? identity_hash[:metadata].dup.freeze : {}.freeze
+                     })
+          @resolved.make_true
+        end
+
+        def bind_fallback!
+          user = ENV.fetch('USER', 'anonymous')
+          @state.set({
+                       id:             nil,
+                       canonical_name: user,
+                       kind:           :human,
+                       persistent:     false,
+                       groups:         [].freeze,
+                       metadata:       {}.freeze
+                     })
+          @resolved.make_false
+        end
+
+        def refresh_credentials
+          return unless defined?(@provider) && @provider.respond_to?(:refresh)
+
+          @provider.refresh
+        end
+
+        def reset!
+          @state    = Concurrent::AtomicReference.new(EMPTY_STATE.dup)
+          @resolved = Concurrent::AtomicBoolean.new(false)
+          @provider = nil
+        end
+
+        private
+
+        def safe_hostname
+          ::Socket.gethostname.downcase
+                  .gsub(/[^a-z0-9]+/, '-')
+                  .gsub(/\A-+|-+\z/, '')
+        end
+      end
+
+      # Initialize atomics at module definition time
+      reset!
+    end
+  end
+end

data/lib/legion/identity/request.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Identity
+    class Request
+      attr_reader :principal_id, :canonical_name, :kind, :groups, :source, :metadata
+
+      def initialize(principal_id:, canonical_name:, kind:, groups: [], source: nil, metadata: {}) # rubocop:disable Metrics/ParameterLists
+        @principal_id   = principal_id
+        @canonical_name = canonical_name
+        @kind           = kind
+        @groups         = groups.freeze
+        @source         = source
+        @metadata       = metadata.freeze
+        freeze
+      end
+
+      # Reads the already-resolved identity from the Rack env (set by middleware).
+      # Returns nil when the key is absent.
+      def self.from_env(env)
+        env['legion.principal']
+      end
+
+      # Builds a Request from a parsed auth claims hash with symbol keys:
+      #   { sub:, name:, preferred_username:, kind:, groups:, source: }
+      def self.from_auth_context(claims_hash)
+        raw_name = claims_hash[:name] || claims_hash[:preferred_username] || ''
+        canonical = raw_name.to_s.strip.downcase.gsub('.', '-')
+
+        new(
+          principal_id:   claims_hash[:sub],
+          canonical_name: canonical,
+          kind:           claims_hash[:kind] || :human,
+          groups:         claims_hash[:groups] || [],
+          source:         claims_hash[:source]
+        )
+      end
+
+      def identity_hash
+        {
+          principal_id:   principal_id,
+          canonical_name: canonical_name,
+          kind:           kind,
+          groups:         groups,
+          source:         source
+        }
+      end
+
+      # Maps to RBAC principal format.
+      # :service workers are represented as :worker in RBAC.
+      def to_rbac_principal
+        {
+          identity: canonical_name,
+          type:     kind == :service ? :worker : kind
+        }
+      end
+
+      # Pipeline-compatible caller hash (matches legion-llm pipeline format).
+      def to_caller_hash
+        {
+          requested_by: {
+            id:         principal_id,
+            identity:   canonical_name,
+            type:       kind,
+            credential: source
+          }
+        }
+      end
+    end
+  end
+end

data/lib/legion/mode.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Legion
+  module Mode
+    LEGACY_MAP = { full: :agent, api: :worker, router: :worker, worker: :worker, lite: :lite }.freeze
+
+    class << self
+      def current
+        raw = ENV['LEGION_MODE'] ||
+              settings_dig(:mode) ||
+              settings_dig(:process, :mode) ||
+              legacy_role
+        normalize(raw)
+      end
+
+      def agent?
+        current == :agent
+      end
+
+      def worker?
+        current == :worker
+      end
+
+      def infra?
+        current == :infra
+      end
+
+      def lite?
+        current == :lite
+      end
+
+      private
+
+      def normalize(raw)
+        return :agent if raw.nil?
+
+        sym = raw.to_s.downcase.strip.to_sym
+        return sym if %i[agent worker infra lite].include?(sym)
+
+        LEGACY_MAP.fetch(sym, :agent)
+      end
+
+      def legacy_role
+        settings_dig(:process, :role)
+      end
+
+      def fetch_setting_value(container, key)
+        value = container[key]
+        return value unless value.nil?
+
+        alternate_key = case key
+                        when Symbol then key.to_s
+                        when String then key.to_sym
+                        end
+        return value if alternate_key.nil?
+
+        container[alternate_key]
+      end
+
+      def settings_dig(*keys)
+        return nil unless defined?(Legion::Settings) && Legion::Settings.respond_to?(:[])
+
+        result = Legion::Settings
+        keys.each do |k|
+          return nil unless result.respond_to?(:[])
+
+          result = fetch_setting_value(result, k)
+          return nil if result.nil? && keys.last != k
+        end
+        result
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/legion/process_role.rb

@@ -4,10 +4,12 @@ module Legion
   module ProcessRole
     ROLES = {
       full:   { transport: true,  cache: true, data: true,  extensions: true,  api: true,  llm: true,  gaia: true,  crypt: true, supervision: true  },
+      agent:  { transport: true,  cache: true, data: true,  extensions: true,  api: true,  llm: true,  gaia: true,  crypt: true, supervision: true  },
       api:    { transport: true,  cache: true, data: true,  extensions: false, api: true,  llm: false, gaia: false, crypt: true, supervision: false },
       worker: { transport: true,  cache: true, data: true,  extensions: true,  api: false, llm: true,  gaia: true,  crypt: true, supervision: true  },
       router: { transport: true,  cache: true, data: false, extensions: true,  api: false, llm: false, gaia: false, crypt: true, supervision: false },
-      lite:   { transport: true,  cache: true, data: true,  extensions: true,  api: true,  llm: true,  gaia: true,  crypt: false, supervision: true }
+      lite:   { transport: true,  cache: true, data: true,  extensions: true,  api: true,  llm: true,  gaia: true,  crypt: false, supervision: true },
+      infra:  { transport: true,  cache: true, data: true,  extensions: true,  api: true,  llm: true,  gaia: true,  crypt: true, supervision: true }
     }.freeze
 
     def self.resolve(role_name)
@@ -21,7 +23,7 @@ module Legion
 
     def self.current
       settings = begin
-        Legion::Settings[:process]
+        defined?(Legion::Settings) ? Legion::Settings[:process] : nil
       rescue StandardError => e
         Legion::Logging.debug "ProcessRole#current failed to read process settings: #{e.message}" if defined?(Legion::Logging)
         nil

data/lib/legion/readiness.rb

@@ -1,13 +1,15 @@
 # frozen_string_literal: true
 
+require 'concurrent'
+
 module Legion
   module Readiness
-    COMPONENTS = %i[settings crypt transport cache data rbac llm apollo gaia extensions api].freeze
+    COMPONENTS = %i[settings crypt transport cache data rbac llm apollo gaia identity extensions api].freeze
     DRAIN_TIMEOUT = 5
 
     class << self
       def status
-        @status ||= {}
+        @status ||= Concurrent::Hash.new
       end
 
       def mark_ready(component)
@@ -43,7 +45,7 @@ module Legion
       end
 
       def reset
-        @status = {}
+        @status = nil
       end
 
       def to_h

data/lib/legion/service.rb

@@ -3,6 +3,7 @@
 require 'timeout'
 require 'legion/logging'
 require_relative 'readiness'
+require_relative 'mode'
 require_relative 'process_role'
 
 module Legion
@@ -149,6 +150,9 @@ module Legion
         setup_generated_functions
       end
 
+      # Identity resolution — after extensions so lex-identity-* providers are loaded
+      setup_identity if transport
+
       register_core_tools
 
       Legion::Gaia.registry&.rediscover if gaia && defined?(Legion::Gaia) && Legion::Gaia.started?
@@ -204,8 +208,7 @@ module Legion
     end
 
     def lite_mode?
-      ENV['LEGION_MODE'] == 'lite' ||
-        Legion::Settings[:mode].to_s == 'lite'
+      Legion::Mode.lite?
     end
 
     def setup_data
@@ -344,6 +347,12 @@ module Legion
         log.info "Starting Legion API on #{bind}:#{port}"
       end
 
+      # Mount identity middleware — bridges legion.auth to legion.principal
+      if defined?(Legion::Identity::Middleware)
+        require_auth = Legion::Identity::Middleware.require_auth?(bind: bind, mode: Legion::Mode.current)
+        Legion::API.use Legion::Identity::Middleware, require_auth: require_auth
+      end
+
       @api_thread = Thread.new do
         retries = 0
         max_retries = api_settings[:bind_retries]
@@ -427,6 +436,45 @@ module Legion
       log.info 'Legion::Transport connected'
     end
 
+    def setup_identity
+      require_relative 'identity/process'
+      require_relative 'identity/broker'
+      require_relative 'identity/lease'
+      require_relative 'identity/lease_renewer'
+      require_relative 'identity/request'
+      require_relative 'identity/middleware'
+
+      # Resolve identity from available providers (Phase 4 adds real providers)
+      resolved = resolve_identity_providers
+      unless resolved
+        Legion::Identity::Process.bind_fallback!
+        log.info "[Identity] fallback identity: #{Legion::Identity::Process.canonical_name}"
+      end
+
+      # Re-resolve secrets for any identity-scoped lease:// refs (task 2.25)
+      Legion::Settings.resolve_secrets! if Legion::Settings.respond_to?(:resolve_secrets!)
+
+      # Fire-and-forget JWKS prefetch
+      jwks_url = Legion::Settings.dig(:identity, :jwks_endpoint) || Legion::Settings.dig(:crypt, :jwt, :jwks_endpoint)
+      if jwks_url && defined?(Legion::Crypt::JwksClient)
+        Legion::Crypt::JwksClient.prefetch!(jwks_url)
+        Legion::Crypt::JwksClient.start_background_refresh!(jwks_url)
+      end
+
+      log.info "[Identity] resolved=#{Legion::Identity::Process.resolved?} mode=#{Legion::Mode.current} queue_prefix=#{Legion::Identity::Process.queue_prefix}"
+    rescue StandardError => e
+      handle_exception(e, level: :warn, operation: 'service.setup_identity')
+      Legion::Identity::Process.bind_fallback! if defined?(Legion::Identity::Process) && !Legion::Identity::Process.resolved?
+    ensure
+      Legion::Readiness.mark_ready(:identity)
+      begin
+        Legion::Extensions.flush_pending_registrations! if defined?(Legion::Extensions) &&
+                                                           Legion::Extensions.respond_to?(:flush_pending_registrations!)
+      rescue StandardError => e
+        handle_exception(e, level: :warn, operation: 'service.setup_identity.flush_pending_registrations')
+      end
+    end
+
     def setup_logging_transport # rubocop:disable Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
       return unless defined?(Legion::Transport::Connection)
       return unless Legion::Transport::Connection.session_open?
@@ -610,7 +658,7 @@ module Legion
       handle_exception(e, level: :warn, operation: 'service.shutdown_api')
     end
 
-    def shutdown # rubocop:disable Metrics/CyclomaticComplexity
+    def shutdown # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       log.info('Legion::Service.shutdown was called')
       @shutdown = true
       Legion::Settings[:client][:shutting_down] = true
@@ -658,6 +706,17 @@ module Legion
       shutdown_component('Cache') { Legion::Cache.shutdown }
       Legion::Readiness.mark_not_ready(:cache)
 
+      # Identity: cooperative shutdown of Broker (stops all LeaseRenewer threads)
+      if defined?(Legion::Identity::Broker)
+        shutdown_component('Identity::Broker') { Legion::Identity::Broker.shutdown }
+        Legion::Readiness.mark_not_ready(:identity)
+      end
+
+      # Stop JWKS background refresh
+      if defined?(Legion::Crypt::JwksClient) && Legion::Crypt::JwksClient.respond_to?(:stop_background_refresh!)
+        Legion::Crypt::JwksClient.stop_background_refresh!
+      end
+
       teardown_logging_transport
       shutdown_component('Transport') { Legion::Transport::Connection.shutdown }
       Legion::Readiness.mark_not_ready(:transport)
@@ -718,6 +777,8 @@ module Legion
       teardown_logging_transport
       setup_logging_transport
 
+      Legion::Identity::Process.refresh_credentials if defined?(Legion::Identity::Process)
+
       require 'legion/cache' unless defined?(Legion::Cache)
       Legion::Cache.setup
       Legion::Readiness.mark_ready(:cache)
@@ -735,6 +796,8 @@ module Legion
       load_extensions
       Legion::Readiness.mark_ready(:extensions)
 
+      Legion::Extensions.flush_pending_registrations! if defined?(Legion::Extensions) && Legion::Extensions.respond_to?(:flush_pending_registrations!)
+
       register_core_tools
 
       Legion::Crypt.cs
@@ -895,6 +958,72 @@ module Legion
 
     private
 
+    def resolve_identity_providers
+      # Phase 4 adds lex-identity-* providers. For now, check if any are loaded.
+      return false unless defined?(Legion::Extensions)
+
+      providers = find_identity_providers
+      return false if providers.empty?
+
+      # Parallel resolution with 5s per-provider timeout (NO Timeout.timeout — uses future.value)
+      pool = Concurrent::FixedThreadPool.new([providers.size, 4].min)
+      futures = providers.map do |provider|
+        Concurrent::Promises.future_on(pool, provider, &:resolve)
+      end
+
+      winner_pair = providers.zip(futures).find do |_provider, future|
+        result = begin
+          future.value(5) # 5s timeout per provider
+        rescue StandardError => e
+          handle_exception(e, level: :debug, operation: 'service.resolve_identity_providers.future')
+          nil
+        end
+        result.is_a?(Hash) && result[:canonical_name]
+      end
+
+      if winner_pair
+        provider, future = winner_pair
+        identity = future.value
+        Legion::Identity::Process.bind!(provider, identity)
+        log.info "[Identity] resolved via #{provider.class.name}: #{identity[:canonical_name]}"
+        true
+      else
+        false
+      end
+    rescue StandardError => e
+      handle_exception(e, level: :warn, operation: 'service.resolve_identity_providers')
+      false
+    ensure
+      pool&.shutdown
+      pool&.kill unless pool&.wait_for_termination(2)
+    end
+
+    def find_identity_providers
+      return [] unless defined?(Legion::Extensions)
+
+      collect_identity_providers(Legion::Extensions)
+    end
+
+    def collect_identity_providers(namespace, visited = Set.new)
+      return [] unless namespace.is_a?(Module)
+      return [] if visited.include?(namespace.object_id)
+
+      visited.add(namespace.object_id)
+      providers = []
+
+      namespace.constants(false).each do |const_name|
+        mod = namespace.const_get(const_name, false)
+        next unless mod.is_a?(Module)
+
+        providers << mod if mod.respond_to?(:resolve) && mod.respond_to?(:provider_name)
+        providers.concat(collect_identity_providers(mod, visited))
+      rescue StandardError
+        next
+      end
+
+      providers
+    end
+
     def bootstrap_log_level(cli_level)
       cli_level = nil if cli_level.respond_to?(:empty?) && cli_level.empty?
       return cli_level if cli_level

data/lib/legion/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Legion
-  VERSION = '1.7.19'
+  VERSION = '1.7.20'
 end

data/lib/legion.rb

@@ -6,6 +6,7 @@ require 'securerandom'
 require 'legion/version'
 require 'legion/logging'
 require 'legion/events'
+require 'legion/mode'
 require 'legion/ingress'
 require 'legion/process'
 require 'legion/service'
@@ -18,6 +19,12 @@ module Legion
   autoload :Leader,  'legion/leader'
   autoload :Prompts, 'legion/prompts'
 
+  @instance_id = ENV.fetch('LEGIONIO_INSTANCE_ID') { SecureRandom.uuid }.downcase.strip.gsub(/[^a-z0-9-]/, '')
+
+  def self.instance_id
+    @instance_id
+  end
+
   attr_reader :service
 
   def self.start

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legionio
 version: !ruby/object:Gem::Version
-  version: 1.7.19
+  version: 1.7.20
 platform: ruby
 authors:
 - Esity
@@ -490,6 +490,7 @@ files:
 - lib/legion/api/graphql/types/task_type.rb
 - lib/legion/api/graphql/types/worker_type.rb
 - lib/legion/api/helpers.rb
+- lib/legion/api/identity_audit.rb
 - lib/legion/api/inbound_webhooks.rb
 - lib/legion/api/knowledge.rb
 - lib/legion/api/lex_dispatch.rb
@@ -641,11 +642,13 @@ files:
 - lib/legion/cli/do_command.rb
 - lib/legion/cli/docs_command.rb
 - lib/legion/cli/doctor.rb
+- lib/legion/cli/doctor/api_bind_check.rb
 - lib/legion/cli/doctor/bundle_check.rb
 - lib/legion/cli/doctor/cache_check.rb
 - lib/legion/cli/doctor/config_check.rb
 - lib/legion/cli/doctor/database_check.rb
 - lib/legion/cli/doctor/extensions_check.rb
+- lib/legion/cli/doctor/mode_check.rb
 - lib/legion/cli/doctor/permissions_check.rb
 - lib/legion/cli/doctor/pid_check.rb
 - lib/legion/cli/doctor/rabbitmq_check.rb
@@ -841,6 +844,12 @@ files:
 - lib/legion/graph/exporter.rb
 - lib/legion/guardrails.rb
 - lib/legion/helpers/context.rb
+- lib/legion/identity/broker.rb
+- lib/legion/identity/lease.rb
+- lib/legion/identity/lease_renewer.rb
+- lib/legion/identity/middleware.rb
+- lib/legion/identity/process.rb
+- lib/legion/identity/request.rb
 - lib/legion/ingress.rb
 - lib/legion/isolation.rb
 - lib/legion/leader.rb
@@ -848,6 +857,7 @@ files:
 - lib/legion/lock.rb
 - lib/legion/memory/consolidator.rb
 - lib/legion/metrics.rb
+- lib/legion/mode.rb
 - lib/legion/notebook/generator.rb
 - lib/legion/notebook/parser.rb
 - lib/legion/notebook/renderer.rb