lex-identity 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3681b4b6aab75c906d15647f1f359d19760d42994803b8c89d733480e77eacff
+  data.tar.gz: 4b49caa8730568c80e4e84a8d43f9053d83e6bef70a22730115a63492d7d5a06
+SHA512:
+  metadata.gz: 527ef0472ad306da82d94ebea24a2b48c0375e164248b322aff1a721897d84f7518eac789852f17af88df14117ddfc9523dd65b42047a84d27af4fb907797d03
+  data.tar.gz: d7e69edd6068f138112c1a685423fc34fd44b8c5d83482c4c4ec8a1179b628955f2043a2e0d43a2b0dc0035b71129f8f56d5d6119dfc69ca64317087a7905849

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rspec', '~> 3.13'
+gem 'rubocop', '~> 1.75', require: false

data/lex-identity.gemspec

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/identity/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-identity'
+  spec.version       = Legion::Extensions::Identity::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Identity'
+  spec.description   = 'Human partner identity modeling and behavioral entropy for brain-modeled agentic AI'
+  spec.homepage      = 'https://github.com/LegionIO/lex-identity'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/LegionIO/lex-identity'
+  spec.metadata['documentation_uri'] = 'https://github.com/LegionIO/lex-identity'
+  spec.metadata['changelog_uri'] = 'https://github.com/LegionIO/lex-identity'
+  spec.metadata['bug_tracker_uri'] = 'https://github.com/LegionIO/lex-identity/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('{lib,spec}/**/*') + %w[lex-identity.gemspec Gemfile]
+  end
+  spec.require_paths = ['lib']
+  spec.add_development_dependency 'sequel',  '>= 5.70'
+  spec.add_development_dependency 'sqlite3', '>= 2.0'
+end

data/lib/legion/extensions/identity/actors/orphan_check.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Identity
+      module Actor
+        # Periodic orphan detection: scans active workers for disabled Entra apps
+        # or inactive owners. Runs every 4 hours by default.
+        # Requires legion-data for worker records.
+        class OrphanCheck < Legion::Extensions::Actors::Every
+          ORPHAN_CHECK_INTERVAL = 14_400 # 4 hours in seconds
+
+          def runner_class
+            Legion::Extensions::Identity::Runners::Entra
+          end
+
+          def runner_function
+            'check_orphans'
+          end
+
+          def time
+            ORPHAN_CHECK_INTERVAL
+          end
+
+          def enabled?
+            defined?(Legion::Data) && Legion::Settings[:data][:connected] != false
+          rescue StandardError
+            false
+          end
+
+          def use_runner?
+            false
+          end
+
+          def check_subtask?
+            false
+          end
+
+          def generate_task?
+            false
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/identity/helpers/dimensions'
+require 'legion/extensions/identity/helpers/fingerprint'
+require 'legion/extensions/identity/runners/identity'
+
+module Legion
+  module Extensions
+    module Identity
+      class Client
+        include Runners::Identity
+
+        def initialize(**)
+          @identity_fingerprint = Helpers::Fingerprint.new
+        end
+
+        private
+
+        attr_reader :identity_fingerprint
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Helpers
+        module Dimensions
+          # The 6 behavioral dimensions that constitute identity
+          IDENTITY_DIMENSIONS = %i[
+            communication_cadence
+            vocabulary_patterns
+            emotional_response
+            decision_patterns
+            contextual_consistency
+            temporal_patterns
+          ].freeze
+
+          # Entropy thresholds (from tick-loop-spec Phase 4)
+          HIGH_ENTROPY_THRESHOLD = 0.70
+          LOW_ENTROPY_THRESHOLD  = 0.20
+          OPTIMAL_ENTROPY_RANGE  = (0.20..0.70)
+
+          # EMA alpha for dimension updates
+          OBSERVATION_ALPHA = 0.1
+
+          module_function
+
+          def new_identity_model
+            IDENTITY_DIMENSIONS.to_h do |dim|
+              [dim, { mean: 0.5, variance: 0.1, observations: 0, last_observed: nil }]
+            end
+          end
+
+          def compute_entropy(observations, model)
+            return 0.5 if observations.empty?
+
+            divergences = IDENTITY_DIMENSIONS.filter_map do |dim|
+              obs = observations[dim]
+              next unless obs
+
+              baseline = model[dim]
+              next 0.0 unless baseline && baseline[:observations].positive?
+
+              # Weighted divergence from established baseline
+              (obs - baseline[:mean]).abs / [baseline[:variance].to_f, 0.1].max
+            end
+
+            return 0.5 if divergences.empty?
+
+            raw = divergences.sum / divergences.size
+            clamp(raw / 3.0) # normalize: divergence of 3.0 stddevs = entropy 1.0
+          end
+
+          def classify_entropy(entropy)
+            if entropy > HIGH_ENTROPY_THRESHOLD
+              :high_entropy
+            elsif entropy < LOW_ENTROPY_THRESHOLD
+              :low_entropy
+            else
+              :normal
+            end
+          end
+
+          def clamp(value, min = 0.0, max = 1.0)
+            value.clamp(min, max)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,166 @@
+# 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

@@ -0,0 +1,76 @@
+# 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

@@ -0,0 +1,20 @@
+# 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

@@ -0,0 +1,223 @@
+# 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