lex-identity 0.2.0 → 0.3.0

data/lib/legion/extensions/identity/helpers/fingerprint.rb

@@ -1,166 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-require 'time'
-
-module Legion
-  module Extensions
-    module Identity
-      module Helpers
-        class Fingerprint
-          attr_reader :model, :observation_count, :entropy_history
-
-          def initialize
-            @model = Dimensions.new_identity_model
-            @observation_count = 0
-            @entropy_history = []
-            load_from_local
-          end
-
-          def observe(dimension, value)
-            return unless Dimensions::IDENTITY_DIMENSIONS.include?(dimension)
-
-            dim = @model[dimension]
-            dim[:observations] += 1
-            @observation_count += 1
-
-            alpha = Dimensions::OBSERVATION_ALPHA
-            old_mean = dim[:mean]
-            dim[:mean] = (alpha * value) + ((1.0 - alpha) * old_mean)
-            deviation = (value - dim[:mean]).abs
-            dim[:variance] = (alpha * deviation) + ((1.0 - alpha) * dim[:variance])
-            dim[:last_observed] = Time.now.utc
-          end
-
-          def observe_all(observations)
-            observations.each { |dim, value| observe(dim, value) }
-          end
-
-          def current_entropy(observations = {})
-            entropy = Dimensions.compute_entropy(observations, @model)
-            @entropy_history << { entropy: entropy, at: Time.now.utc }
-            @entropy_history.shift while @entropy_history.size > 200
-            entropy
-          end
-
-          def entropy_trend(window: 10)
-            recent = @entropy_history.last(window)
-            return :stable if recent.size < 2
-
-            values = recent.map { |e| e[:entropy] }
-            first_half = values[0...(values.size / 2)]
-            second_half = values[(values.size / 2)..]
-
-            diff = (second_half.sum / second_half.size) - (first_half.sum / first_half.size)
-            if diff > 0.1
-              :rising
-            elsif diff < -0.1
-              :falling
-            else
-              :stable
-            end
-          end
-
-          def maturity
-            if @observation_count < 10
-              :nascent
-            elsif @observation_count < 100
-              :developing
-            elsif @observation_count < 1000
-              :established
-            else
-              :mature
-            end
-          end
-
-          def to_h
-            {
-              model:                @model,
-              observation_count:    @observation_count,
-              maturity:             maturity,
-              entropy_history_size: @entropy_history.size
-            }
-          end
-
-          def save_to_local
-            return unless local_available?
-
-            db = Legion::Data::Local.connection
-
-            @model.each do |dimension, data|
-              existing = db[:identity_fingerprint].where(dimension: dimension.to_s).first
-              row = {
-                dimension:     dimension.to_s,
-                mean:          data[:mean],
-                variance:      data[:variance],
-                observations:  data[:observations],
-                last_observed: data[:last_observed]
-              }
-              if existing
-                db[:identity_fingerprint].where(dimension: dimension.to_s).update(row)
-              else
-                db[:identity_fingerprint].insert(row)
-              end
-            end
-
-            history_json = ::JSON.generate(@entropy_history.map { |e| { entropy: e[:entropy], at: e[:at].iso8601 } })
-            meta = db[:identity_meta].first
-            if meta
-              db[:identity_meta].where(id: meta[:id]).update(
-                observation_count: @observation_count,
-                entropy_history:   history_json
-              )
-            else
-              db[:identity_meta].insert(
-                observation_count: @observation_count,
-                entropy_history:   history_json
-              )
-            end
-
-            true
-          rescue StandardError => e
-            Legion::Logging.warn "lex-identity: save_to_local failed: #{e.message}" if defined?(Legion::Logging)
-            false
-          end
-
-          def load_from_local
-            return unless local_available?
-
-            db = Legion::Data::Local.connection
-
-            db[:identity_fingerprint].each do |row|
-              dim = row[:dimension].to_sym
-              next unless @model.key?(dim)
-
-              @model[dim][:mean]          = row[:mean].to_f
-              @model[dim][:variance]      = row[:variance].to_f
-              @model[dim][:observations]  = row[:observations].to_i
-              @model[dim][:last_observed] = row[:last_observed]
-            end
-
-            meta = db[:identity_meta].first
-            if meta
-              @observation_count = meta[:observation_count].to_i
-              raw = meta[:entropy_history]
-              if raw && !raw.empty?
-                parsed = ::JSON.parse(raw)
-                @entropy_history = parsed.map { |e| { entropy: e['entropy'].to_f, at: Time.parse(e['at']) } }
-              end
-            end
-
-            true
-          rescue StandardError => e
-            Legion::Logging.warn "lex-identity: load_from_local failed: #{e.message}" if defined?(Legion::Logging)
-            false
-          end
-
-          private
-
-          def local_available?
-            defined?(Legion::Data::Local) && Legion::Data::Local.connected?
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/identity/helpers/vault_secrets.rb

@@ -1,76 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Identity
-      module Helpers
-        # Vault secret path conventions for Digital Worker Entra ID credentials.
-        #
-        # Secrets are stored in Vault KV v2 under a well-known path:
-        #   secret/data/legion/workers/{worker_id}/entra
-        #
-        # Legion uses legion-crypt for Vault access. If Vault is not connected,
-        # methods return nil/false gracefully.
-        module VaultSecrets
-          VAULT_PATH_PREFIX = 'secret/data/legion/workers'
-
-          def self.secret_path(worker_id)
-            "#{VAULT_PATH_PREFIX}/#{worker_id}/entra"
-          end
-
-          # Store Entra app client_secret in Vault.
-          # Returns true on success, false if Vault is unavailable.
-          def self.store_client_secret(worker_id:, client_secret:, entra_app_id: nil)
-            return false unless vault_available?
-
-            path = secret_path(worker_id)
-            data = { client_secret: client_secret }
-            data[:entra_app_id] = entra_app_id if entra_app_id
-
-            Legion::Crypt.write(path, data)
-            Legion::Logging.info "[identity:vault] stored Entra credentials for worker=#{worker_id}"
-            true
-          rescue StandardError => e
-            Legion::Logging.error "[identity:vault] failed to store credentials for worker=#{worker_id}: #{e.message}"
-            false
-          end
-
-          # Read Entra app client_secret from Vault.
-          # Returns the secret hash on success, nil if unavailable or not found.
-          def self.read_client_secret(worker_id:)
-            return nil unless vault_available?
-
-            path = secret_path(worker_id)
-            result = Legion::Crypt.read(path)
-            result&.dig(:data, :data) || result&.dig(:data)
-          rescue StandardError => e
-            Legion::Logging.error "[identity:vault] failed to read credentials for worker=#{worker_id}: #{e.message}"
-            nil
-          end
-
-          # Delete Entra app credentials from Vault (used during worker termination).
-          # Returns true on success, false if Vault is unavailable.
-          def self.delete_client_secret(worker_id:)
-            return false unless vault_available?
-
-            path = secret_path(worker_id)
-            Legion::Crypt.delete(path)
-            Legion::Logging.info "[identity:vault] deleted Entra credentials for worker=#{worker_id}"
-            true
-          rescue StandardError => e
-            Legion::Logging.error "[identity:vault] failed to delete credentials for worker=#{worker_id}: #{e.message}"
-            false
-          end
-
-          def self.vault_available?
-            defined?(Legion::Crypt) &&
-              defined?(Legion::Settings) &&
-              Legion::Settings[:crypt][:vault][:connected] == true
-          rescue StandardError
-            false
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/identity/local_migrations/20260316000030_create_fingerprint.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-Sequel.migration do
-  change do
-    create_table(:identity_fingerprint) do
-      primary_key :id
-      String :dimension, null: false, unique: true
-      Float :mean, default: 0.0
-      Float :variance, default: 0.0
-      Integer :observations, default: 0
-      DateTime :last_observed
-    end
-
-    create_table(:identity_meta) do
-      primary_key :id
-      Integer :observation_count, default: 0
-      String :entropy_history, text: true
-    end
-  end
-end

data/lib/legion/extensions/identity/runners/entra.rb

@@ -1,223 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Identity
-      module Runners
-        # Entra ID Application identity integration for Digital Workers.
-        #
-        # Permission model:
-        #   - Entra app CREATION is done by the human owner (requires Application.ReadWrite.All
-        #     which Legion does not have and should not have)
-        #   - Legion gets Application.Read.All or Directory.Read.All for read operations
-        #   - OIDC token validation uses the public JWKS endpoint (no special permission)
-        #   - Write operations (transfer ownership, disable apps) update the Legion DB
-        #     and emit events; the human completes the Entra side manually
-        module Entra
-          GRAPH_API_BASE = 'https://graph.microsoft.com/v1.0'
-          ENTRA_JWKS_URL_TEMPLATE = 'https://login.microsoftonline.com/%<tenant_id>s/discovery/v2.0/keys'
-          ENTRA_ISSUER_TEMPLATE = 'https://login.microsoftonline.com/%<tenant_id>s/v2.0'
-
-          # Validate a worker's identity by checking its Entra app registration exists
-          # and its OIDC token is valid.
-          # OIDC validation uses the public JWKS endpoint — no Graph API permission needed.
-          def validate_worker_identity(worker_id:, entra_app_id: nil, token: nil, tenant_id: nil, **)
-            worker = find_worker(worker_id)
-            return { valid: false, error: 'worker not found' } unless worker
-
-            app_id = entra_app_id || worker[:entra_app_id]
-            return { valid: false, error: 'no entra_app_id' } unless app_id
-
-            # If a token is provided and legion-crypt has JWKS support, validate it
-            if token && defined?(Legion::Crypt::JWT) && Legion::Crypt::JWT.respond_to?(:verify_with_jwks)
-              tid = tenant_id || resolve_tenant_id
-              return { valid: false, error: 'no tenant_id configured' } unless tid
-
-              jwks_url = format(ENTRA_JWKS_URL_TEMPLATE, tenant_id: tid)
-              issuer = format(ENTRA_ISSUER_TEMPLATE, tenant_id: tid)
-
-              claims = Legion::Crypt::JWT.verify_with_jwks(
-                token,
-                jwks_url: jwks_url,
-                issuers:  [issuer],
-                audience: app_id
-              )
-
-              Legion::Logging.debug "[identity:entra] token validated: worker=#{worker_id} sub=#{claims[:sub]}"
-
-              return {
-                valid:        true,
-                worker_id:    worker_id,
-                entra_app_id: app_id,
-                owner_msid:   worker[:owner_msid],
-                lifecycle:    worker[:lifecycle_state],
-                claims:       claims,
-                validated_at: Time.now.utc
-              }
-            end
-
-            # No token provided — return identity info without token validation
-            Legion::Logging.debug "[identity:entra] validate (no token): worker=#{worker_id} entra_app=#{app_id}"
-
-            {
-              valid:        true,
-              worker_id:    worker_id,
-              entra_app_id: app_id,
-              owner_msid:   worker[:owner_msid],
-              lifecycle:    worker[:lifecycle_state],
-              validated_at: Time.now.utc
-            }
-          rescue Legion::Crypt::JWT::ExpiredTokenError => e
-            { valid: false, error: 'token_expired', message: e.message }
-          rescue Legion::Crypt::JWT::InvalidTokenError => e
-            { valid: false, error: 'token_invalid', message: e.message }
-          rescue Legion::Crypt::JWT::Error => e
-            { valid: false, error: 'token_error', message: e.message }
-          end
-
-          # Sync the worker's owner from Entra app ownership.
-          # Requires: Application.Read.All or Directory.Read.All (read-only)
-          def sync_owner(worker_id:, **)
-            worker = find_worker(worker_id)
-            return { synced: false, error: 'worker not found' } unless worker
-
-            # TODO: With Application.Read.All, call:
-            # GET #{GRAPH_API_BASE}/applications/#{worker[:entra_object_id]}/owners
-            # Parse owner MSID from response, update local record
-
-            Legion::Logging.debug "[identity:entra] sync_owner: worker=#{worker_id} current_owner=#{worker[:owner_msid]}"
-
-            {
-              synced:     true,
-              worker_id:  worker_id,
-              owner_msid: worker[:owner_msid],
-              source:     :local, # will be :graph_api when read permission granted
-              synced_at:  Time.now.utc
-            }
-          end
-
-          # Transfer ownership of a digital worker to a new human.
-          # Updates the Legion DB record and emits an audit event.
-          # The Entra app ownership change must be done by the human owner
-          # (requires Application.ReadWrite.All which Legion intentionally does not have).
-          def transfer_ownership(worker_id:, new_owner_msid:, transferred_by:, reason: nil, **)
-            worker = find_worker(worker_id)
-            return { transferred: false, error: 'worker not found' } unless worker
-
-            old_owner = worker[:owner_msid]
-            return { transferred: false, error: 'same owner' } if old_owner == new_owner_msid
-
-            # Update local record — this is the Legion side of the transfer
-            if defined?(Legion::Data) && defined?(Legion::Data::Model::DigitalWorker)
-              dw = Legion::Data::Model::DigitalWorker.first(worker_id: worker_id)
-              dw&.update(owner_msid: new_owner_msid, updated_at: Time.now.utc)
-            end
-
-            # Entra app ownership change requires Application.ReadWrite.All.
-            # Legion does not have this permission by design — the human owner
-            # must update Entra app ownership separately via Azure Portal or CLI.
-
-            audit = {
-              event:                 :ownership_transferred,
-              worker_id:             worker_id,
-              from_owner:            old_owner,
-              to_owner:              new_owner_msid,
-              transferred_by:        transferred_by,
-              reason:                reason,
-              entra_action_required: 'update Entra app ownership via Azure Portal or az CLI',
-              at:                    Time.now.utc
-            }
-
-            Legion::Events.emit('worker.ownership_transferred', audit) if defined?(Legion::Events)
-            Legion::Logging.info "[identity:entra] ownership transferred (Legion DB): worker=#{worker_id} " \
-                                 "from=#{old_owner} to=#{new_owner_msid} by=#{transferred_by}"
-            Legion::Logging.warn '[identity:entra] Entra app ownership must be updated manually (requires Application.ReadWrite.All)'
-
-            { transferred: true }.merge(audit)
-          end
-
-          # Scan for orphaned workers: Entra apps that are disabled or owners no longer active.
-          # Requires: Application.Read.All or Directory.Read.All (read-only)
-          # Orphan REMEDIATION (disabling apps) requires human action since Legion
-          # does not have Application.ReadWrite.All.
-          def check_orphans(**)
-            return { orphans: [], checked: 0, source: :unavailable } unless defined?(Legion::Data) && defined?(Legion::Data::Model::DigitalWorker)
-
-            active_workers = Legion::Data::Model::DigitalWorker.where(lifecycle_state: 'active').all
-            orphans = []
-            skipped = 0
-
-            active_workers.each do |worker|
-              # Skip auto-registered extension workers without real Entra apps
-              if system_placeholder?(worker.entra_app_id, worker.worker_id)
-                skipped += 1
-                next
-              end
-
-              # TODO: With Application.Read.All, check:
-              # GET #{GRAPH_API_BASE}/applications/#{entra_object_id} — is app disabled?
-              # GET #{GRAPH_API_BASE}/users/#{owner_msid} — is owner active?
-              # If either is disabled/deleted:
-              #   orphans << worker
-              #   auto_pause_orphan(worker, reason: :entra_app_disabled)
-            end
-
-            Legion::Logging.debug "[identity:entra] orphan check: scanned #{active_workers.size} active workers, skipped #{skipped} system workers"
-
-            {
-              orphans:    orphans.map { |w| { worker_id: w.worker_id, owner_msid: w.owner_msid, reason: :pending_entra_validation } },
-              checked:    active_workers.size - skipped,
-              skipped:    skipped,
-              source:     :local,
-              checked_at: Time.now.utc
-            }
-          end
-
-          private
-
-          def find_worker(worker_id)
-            if defined?(Legion::Data) && defined?(Legion::Data::Model::DigitalWorker)
-              worker = Legion::Data::Model::DigitalWorker.first(worker_id: worker_id)
-              return worker.to_hash if worker
-            end
-            nil
-          end
-
-          def system_placeholder?(entra_app_id, worker_id)
-            return true if entra_app_id.nil? || entra_app_id == 'system'
-            return true if entra_app_id == worker_id
-            return true if entra_app_id.start_with?('lex-')
-
-            false
-          end
-
-          def resolve_tenant_id
-            if defined?(Legion::Settings) &&
-               Legion::Settings[:identity]&.dig(:entra, :tenant_id)
-              return Legion::Settings[:identity][:entra][:tenant_id]
-            end
-
-            nil
-          end
-
-          def auto_pause_orphan(worker, reason:)
-            worker.update(lifecycle_state: 'paused', updated_at: Time.now.utc)
-
-            if defined?(Legion::Events)
-              Legion::Events.emit('worker.orphan_detected', {
-                                    worker_id:   worker.worker_id,
-                                    owner_msid:  worker.owner_msid,
-                                    reason:      reason,
-                                    action:      :auto_paused,
-                                    remediation: 'disable or reassign Entra app via Azure Portal',
-                                    at:          Time.now.utc
-                                  })
-            end
-
-            Legion::Logging.warn "[identity:entra] orphan detected: worker=#{worker.worker_id} reason=#{reason} — auto-paused"
-          end
-        end
-      end
-    end
-  end
-end

data/lib/legion/extensions/identity/runners/identity.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-module Legion
-  module Extensions
-    module Identity
-      module Runners
-        module Identity
-          include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
-                                                      Legion::Extensions::Helpers.const_defined?(:Lex)
-
-          def observe_behavior(dimension:, value:, **)
-            fingerprint = identity_fingerprint
-            fingerprint.observe(dimension, value)
-
-            Legion::Logging.debug "[identity] observe: dim=#{dimension} val=#{value.round(2)} " \
-                                  "obs=#{fingerprint.observation_count} maturity=#{fingerprint.maturity}"
-            {
-              dimension:         dimension,
-              recorded:          true,
-              observation_count: fingerprint.observation_count,
-              maturity:          fingerprint.maturity
-            }
-          end
-
-          def observe_all(observations:, **)
-            fingerprint = identity_fingerprint
-            fingerprint.observe_all(observations)
-
-            Legion::Logging.debug "[identity] observe_all: dims=#{observations.keys.join(',')} " \
-                                  "obs=#{fingerprint.observation_count} maturity=#{fingerprint.maturity}"
-            {
-              dimensions_observed: observations.keys,
-              observation_count:   fingerprint.observation_count,
-              maturity:            fingerprint.maturity
-            }
-          end
-
-          def check_entropy(observations: {}, **)
-            fingerprint = identity_fingerprint
-            entropy = fingerprint.current_entropy(observations)
-            classification = Helpers::Dimensions.classify_entropy(entropy)
-            trend = fingerprint.entropy_trend
-
-            result = {
-              entropy:        entropy,
-              classification: classification,
-              trend:          trend,
-              in_range:       Helpers::Dimensions::OPTIMAL_ENTROPY_RANGE.cover?(entropy)
-            }
-
-            case classification
-            when :high_entropy
-              result[:warning] = :possible_impersonation_or_drift
-              result[:action] = :enter_caution_mode
-              Legion::Logging.warn "[identity] high entropy detected: #{entropy.round(3)} trend=#{trend} - possible impersonation"
-            when :low_entropy
-              result[:warning] = :possible_automation
-              result[:action] = :trigger_verification
-              Legion::Logging.warn "[identity] low entropy detected: #{entropy.round(3)} trend=#{trend} - possible automation"
-            else
-              Legion::Logging.debug "[identity] entropy check: #{entropy.round(3)} classification=#{classification} trend=#{trend}"
-            end
-
-            result
-          end
-
-          def identity_status(**)
-            fingerprint = identity_fingerprint
-            Legion::Logging.debug "[identity] status: maturity=#{fingerprint.maturity} observations=#{fingerprint.observation_count}"
-            fingerprint.to_h
-          end
-
-          def identity_maturity(**)
-            { maturity: identity_fingerprint.maturity }
-          end
-
-          private
-
-          def identity_fingerprint
-            @identity_fingerprint ||= Helpers::Fingerprint.new
-          end
-        end
-      end
-    end
-  end
-end

data/spec/legion/extensions/identity/actors/orphan_check_spec.rb

@@ -1,104 +0,0 @@
-# frozen_string_literal: true
-
-# Stub the framework actor base class since legionio gem is not available in test
-module Legion
-  module Extensions
-    module Actors
-      class Every # rubocop:disable Lint/EmptyClass
-      end
-    end
-  end
-end
-
-# Intercept the require in the actor file so it doesn't fail
-$LOADED_FEATURES << 'legion/extensions/actors/every'
-
-require 'legion/extensions/identity/actors/orphan_check'
-
-RSpec.describe Legion::Extensions::Identity::Actor::OrphanCheck do
-  subject(:actor) { described_class.new }
-
-  describe 'ORPHAN_CHECK_INTERVAL' do
-    it 'is 14400 seconds (4 hours)' do
-      expect(described_class::ORPHAN_CHECK_INTERVAL).to eq(14_400)
-    end
-  end
-
-  describe '#runner_class' do
-    it 'returns the Entra module' do
-      expect(actor.runner_class).to eq(Legion::Extensions::Identity::Runners::Entra)
-    end
-  end
-
-  describe '#runner_function' do
-    it 'returns check_orphans' do
-      expect(actor.runner_function).to eq('check_orphans')
-    end
-  end
-
-  describe '#time' do
-    it 'returns 14400 seconds using the constant' do
-      expect(actor.time).to eq(Legion::Extensions::Identity::Actor::OrphanCheck::ORPHAN_CHECK_INTERVAL)
-    end
-
-    it 'returns 14400' do
-      expect(actor.time).to eq(14_400)
-    end
-  end
-
-  describe '#use_runner?' do
-    it 'returns false' do
-      expect(actor.use_runner?).to be false
-    end
-  end
-
-  describe '#check_subtask?' do
-    it 'returns false' do
-      expect(actor.check_subtask?).to be false
-    end
-  end
-
-  describe '#generate_task?' do
-    it 'returns false' do
-      expect(actor.generate_task?).to be false
-    end
-  end
-
-  describe '#enabled?' do
-    context 'when Legion::Data is not defined' do
-      it 'returns false' do
-        hide_const('Legion::Data') if defined?(Legion::Data)
-        expect(actor.enabled?).to be_falsey
-      end
-    end
-
-    context 'when Legion::Data is defined and data is connected' do
-      it 'returns truthy' do
-        stub_const('Legion::Data', Module.new)
-        stub_const('Legion::Settings', Class.new)
-        settings_double = { connected: true }
-        allow(Legion::Settings).to receive(:[]).with(:data).and_return(settings_double)
-        expect(actor.enabled?).to be_truthy
-      end
-    end
-
-    context 'when Legion::Data is defined but connected is false' do
-      it 'returns false' do
-        stub_const('Legion::Data', Module.new)
-        stub_const('Legion::Settings', Class.new)
-        settings_double = { connected: false }
-        allow(Legion::Settings).to receive(:[]).with(:data).and_return(settings_double)
-        expect(actor.enabled?).to be false
-      end
-    end
-
-    context 'when Legion::Settings raises an error' do
-      it 'returns false' do
-        stub_const('Legion::Data', Module.new)
-        stub_const('Legion::Settings', Class.new)
-        allow(Legion::Settings).to receive(:[]).with(:data).and_raise(StandardError)
-        expect(actor.enabled?).to be false
-      end
-    end
-  end
-end