lex-identity 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3681b4b6aab75c906d15647f1f359d19760d42994803b8c89d733480e77eacff
-  data.tar.gz: 4b49caa8730568c80e4e84a8d43f9053d83e6bef70a22730115a63492d7d5a06
+  metadata.gz: 402e57fb1c2fafdaac3bbbfd79ab0cd34d448798fe9f61e14511002845dc3d7c
+  data.tar.gz: 30585e986691ac0bee3bd2111f291fdc4adcef5c6ef83179c16a4e12d3e6eb67
 SHA512:
-  metadata.gz: 527ef0472ad306da82d94ebea24a2b48c0375e164248b322aff1a721897d84f7518eac789852f17af88df14117ddfc9523dd65b42047a84d27af4fb907797d03
-  data.tar.gz: d7e69edd6068f138112c1a685423fc34fd44b8c5d83482c4c4ec8a1179b628955f2043a2e0d43a2b0dc0035b71129f8f56d5d6119dfc69ca64317087a7905849
+  metadata.gz: 87d225ef73a724bcbf18649664670e56ed5eb93c7f5f2312ee19cf70550191c41849a4e25bb303aee50e98b330962269cd2c0c53c3781f5926a5fca89ed047f4
+  data.tar.gz: 798d6de090c2666919a3bc778adb4decaa0c08e586a14d03fc6e781a13ad2d33ecad0cb35f852b41c12d59c830c0f69b248aaddafe54e6b59e96d4800129dc47

data/Gemfile

@@ -4,5 +4,6 @@ source 'https://rubygems.org'
 
 gemspec
 
+gem 'faraday', '~> 2.0'
 gem 'rspec', '~> 3.13'
 gem 'rubocop', '~> 1.75', require: false

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

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/actors/every'
+
+module Legion
+  module Extensions
+    module Identity
+      module Actor
+        class CredentialRefresh < Legion::Extensions::Actors::Every
+          CREDENTIAL_REFRESH_INTERVAL = 21_600 # 6 hours
+
+          def runner_class
+            Legion::Extensions::Identity::Runners::Entra
+          end
+
+          def runner_function
+            'credential_refresh_cycle'
+          end
+
+          def time
+            CREDENTIAL_REFRESH_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/helpers/graph_client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Helpers
+        module GraphClient
+          GRAPH_BASE = 'https://graph.microsoft.com/v1.0'
+
+          module_function
+
+          def connection(token:, base: GRAPH_BASE)
+            require 'faraday'
+            Faraday.new(url: base) do |conn|
+              conn.request :json
+              conn.response :json, content_type: /\bjson$/
+              conn.headers['Authorization'] = "Bearer #{token}"
+              conn.headers['Content-Type'] = 'application/json'
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Helpers
+        module GraphToken
+          TOKEN_ENDPOINT = 'https://login.microsoftonline.com/%<tenant_id>s/oauth2/v2.0/token'
+          GRAPH_SCOPE = 'https://graph.microsoft.com/.default'
+
+          class GraphTokenError < StandardError; end
+
+          module_function
+
+          def fetch(tenant_id:, client_id:, client_secret:)
+            require 'faraday'
+            url = format(TOKEN_ENDPOINT, tenant_id: tenant_id)
+            conn = Faraday.new(url: url) do |c|
+              c.request :url_encoded
+              c.response :json, content_type: /\bjson$/
+            end
+            resp = conn.post('', grant_type: 'client_credentials', client_id: client_id,
+                                 client_secret: client_secret, scope: GRAPH_SCOPE)
+            raise GraphTokenError, resp.body['error_description'] unless resp.success?
+
+            resp.body['access_token']
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Helpers
+        module TokenCache
+          REFRESH_BUFFER = 300
+
+          @mutex = Mutex.new
+          @tokens = {}
+
+          module_function
+
+          def store(worker_id:, token:, expires_in:)
+            @mutex.synchronize do
+              @tokens[worker_id] = {
+                access_token: token,
+                expires_at:   Time.now + expires_in,
+                acquired_at:  Time.now
+              }
+            end
+          end
+
+          def fetch(worker_id:)
+            @mutex.synchronize do
+              entry = @tokens[worker_id]
+              return nil unless entry
+              return nil if Time.now >= entry[:expires_at]
+
+              entry
+            end
+          end
+
+          def approaching_expiry?(worker_id:, buffer: REFRESH_BUFFER)
+            @mutex.synchronize do
+              entry = @tokens[worker_id]
+              return true unless entry
+
+              (entry[:expires_at] - Time.now) < buffer
+            end
+          end
+
+          def clear(worker_id:)
+            @mutex.synchronize { @tokens.delete(worker_id) }
+          end
+
+          def clear_all
+            @mutex.synchronize { @tokens.clear }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -77,23 +77,47 @@ module Legion
 
           # Sync the worker's owner from Entra app ownership.
           # Requires: Application.Read.All or Directory.Read.All (read-only)
+          # Falls back to local record when Graph API credentials unavailable.
           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
+            entra_object_id = worker[:entra_object_id]
+            return { synced: false, worker_id: worker_id, error: 'no entra_object_id', source: :local } unless entra_object_id
 
-            Legion::Logging.debug "[identity:entra] sync_owner: worker=#{worker_id} current_owner=#{worker[:owner_msid]}"
+            creds = resolve_graph_credentials
+            unless creds
+              Legion::Logging.debug "[identity:entra] sync_owner fallback to local: worker=#{worker_id}"
+              return { synced: true, worker_id: worker_id, source: :local,
+                       owner_msid: worker[:owner_msid], synced_at: Time.now.utc }
+            end
 
-            {
-              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
-            }
+            token = Helpers::GraphToken.fetch(**creds)
+            conn = Helpers::GraphClient.connection(token: token)
+            resp = conn.get("applications/#{entra_object_id}/owners")
+
+            unless resp.success?
+              Legion::Logging.warn "[identity:entra] graph owner sync failed: #{resp.status}"
+              return { synced: false, worker_id: worker_id, source: :local, owner_msid: worker[:owner_msid] }
+            end
+
+            owners = resp.body['value'] || []
+            graph_owner_msid = owners.first&.dig('id')
+            changed = graph_owner_msid && graph_owner_msid != worker[:owner_msid].to_s
+
+            if changed && defined?(Legion::Data::Model::DigitalWorker)
+              Legion::Data::Model::DigitalWorker.where(worker_id: worker_id).update(owner_msid: graph_owner_msid)
+              if defined?(Legion::Events)
+                Legion::Events.emit('worker.owner_changed', { worker_id: worker_id, old: worker[:owner_msid],
+                                                              new: graph_owner_msid })
+              end
+            end
+
+            { synced: true, source: :graph_api, worker_id: worker_id,
+              owner_msid: graph_owner_msid || worker[:owner_msid], changed: !changed.nil?, synced_at: Time.now.utc }
+          rescue Helpers::GraphToken::GraphTokenError, Faraday::Error => e
+            Legion::Logging.warn "[identity:entra] graph sync error: #{e.message}"
+            { synced: false, worker_id: worker_id, source: :local, error: e.message }
           end
 
           # Transfer ownership of a digital worker to a new human.
@@ -140,6 +164,7 @@ module Legion
           # 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.
+          # Falls back to local-only scan when Graph API credentials unavailable.
           def check_orphans(**)
             return { orphans: [], checked: 0, source: :unavailable } unless defined?(Legion::Data) && defined?(Legion::Data::Model::DigitalWorker)
 
@@ -147,30 +172,151 @@ module Legion
             orphans = []
             skipped = 0
 
+            creds = resolve_graph_credentials
+            conn = nil
+            if creds
+              token = Helpers::GraphToken.fetch(**creds)
+              conn = Helpers::GraphClient.connection(token: token)
+            end
+
             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)
+              next unless conn
+
+              orphan_reason = check_worker_orphan_status(conn, worker)
+              if orphan_reason
+                orphans << worker
+                auto_pause_orphan(worker, reason: orphan_reason)
+              end
+            rescue Faraday::Error => e
+              Legion::Logging.warn "[identity:entra] graph error scanning #{worker.worker_id}: #{e.message}"
             end
 
-            Legion::Logging.debug "[identity:entra] orphan check: scanned #{active_workers.size} active workers, skipped #{skipped} system workers"
+            source = conn ? :graph_api : :local
+            Legion::Logging.debug "[identity:entra] orphan check (#{source}): scanned #{active_workers.size}, skipped #{skipped}"
 
             {
-              orphans:    orphans.map { |w| { worker_id: w.worker_id, owner_msid: w.owner_msid, reason: :pending_entra_validation } },
+              orphans:    orphans.map { |w| { worker_id: w.worker_id, owner_msid: w.owner_msid, reason: :entra_orphan } },
               checked:    active_workers.size - skipped,
               skipped:    skipped,
-              source:     :local,
+              source:     source,
               checked_at: Time.now.utc
             }
+          rescue Helpers::GraphToken::GraphTokenError => e
+            Legion::Logging.warn "[identity:entra] orphan check token error: #{e.message}"
+            { orphans: [], checked: 0, source: :local, error: e.message, checked_at: Time.now.utc }
+          end
+
+          # Map Entra security group OIDs to Legion governance roles
+          def resolve_governance_roles(groups:, **)
+            group_map = Legion::Settings.dig(:rbac, :entra, :group_map) || {}
+            default_role = Legion::Settings.dig(:rbac, :entra, :default_role) || 'governance-observer'
+            matched = Array(groups).filter_map { |oid| group_map[oid] }.uniq
+            matched = [default_role] if matched.empty?
+            { success: true, groups: groups, roles: matched }
+          end
+
+          def refresh_access_token(worker_id:, force: false, **)
+            require_relative '../helpers/token_cache'
+
+            unless force
+              cached = Helpers::TokenCache.fetch(worker_id: worker_id)
+              if cached && !Helpers::TokenCache.approaching_expiry?(worker_id: worker_id)
+                return { refreshed: false, worker_id: worker_id, source: :cache, expires_at: cached[:expires_at] }
+              end
+            end
+
+            secret = Helpers::VaultSecrets.read_client_secret(worker_id: worker_id)
+            return { refreshed: false, worker_id: worker_id, error: 'vault_unavailable' } unless secret
+
+            tenant_id = resolve_tenant_id
+            return { refreshed: false, worker_id: worker_id, error: 'no_tenant_id' } unless tenant_id
+
+            scope = Legion::Settings.dig(:identity, :entra, :token_scope) || 'https://graph.microsoft.com/.default'
+            url = "https://login.microsoftonline.com/#{tenant_id}/oauth2/v2.0/token"
+
+            require 'faraday'
+            resp = Faraday.post(url, {
+                                  grant_type:    'client_credentials',
+                                  client_id:     secret[:client_id] || secret[:entra_app_id],
+                                  client_secret: secret[:client_secret],
+                                  scope:         scope
+                                })
+
+            unless resp.success?
+              Legion::Logging.warn "[identity] token refresh failed for #{worker_id}: #{resp.status}"
+              return { refreshed: false, worker_id: worker_id, error: 'token_request_failed' }
+            end
+
+            body = Legion::JSON.load(resp.body)
+            expires_in = body[:expires_in]&.to_i || 3600
+            Helpers::TokenCache.store(worker_id: worker_id, token: body[:access_token], expires_in: expires_in)
+
+            { refreshed: true, worker_id: worker_id, expires_at: Time.now + expires_in }
+          rescue StandardError => e
+            Legion::Logging.warn "[identity] token refresh error: #{e.message}"
+            { refreshed: false, worker_id: worker_id, error: e.message }
+          end
+
+          def rotate_client_secret(worker_id:, dry_run: false, **)
+            rotation_enabled = Legion::Settings.dig(:identity, :entra, :rotation_enabled)
+            buffer_days = Legion::Settings.dig(:identity, :entra, :rotation_buffer_days) || 30
+
+            secret = Helpers::VaultSecrets.read_client_secret(worker_id: worker_id)
+            return { rotated: false, worker_id: worker_id, error: 'vault_unavailable' } unless secret
+
+            expires_at = secret[:client_secret_expires_at]
+            return { rotated: false, worker_id: worker_id, action_required: false, reason: 'no_expiry_tracked' } unless expires_at
+
+            days_remaining = (Time.parse(expires_at.to_s) - Time.now) / 86_400
+            unless days_remaining < buffer_days
+              return { rotated: false, worker_id: worker_id, action_required: false,
+                       days_remaining: days_remaining.round(1) }
+            end
+
+            unless rotation_enabled
+              Legion::Logging.warn "[identity] credential expiring for #{worker_id} in #{days_remaining.round(1)} days"
+              if defined?(Legion::Events)
+                Legion::Events.emit('worker.credential_expiry_warning', {
+                                      worker_id: worker_id, days_remaining: days_remaining.round(1)
+                                    })
+              end
+              return { rotated: false, worker_id: worker_id, action_required: true,
+                       days_remaining: days_remaining.round(1) }
+            end
+
+            return { rotated: false, worker_id: worker_id, dry_run: true, would_rotate: true } if dry_run
+
+            # Graph API rotation would go here when permission is granted
+            { rotated: false, worker_id: worker_id, error: 'graph_api_rotation_not_implemented' }
+          end
+
+          def credential_refresh_cycle(**)
+            return { workers_checked: 0, error: 'data_unavailable' } unless defined?(Legion::Data::Model::DigitalWorker)
+
+            workers = Legion::Data::Model::DigitalWorker.where(lifecycle_state: 'active').all
+            results = { workers_checked: 0, refreshed: 0, warned: 0 }
+
+            workers.each do |worker|
+              next if system_placeholder?(worker.entra_app_id, worker.worker_id)
+
+              results[:workers_checked] += 1
+
+              token_result = refresh_access_token(worker_id: worker.worker_id)
+              results[:refreshed] += 1 if token_result[:refreshed]
+
+              rotation_result = rotate_client_secret(worker_id: worker.worker_id)
+              results[:warned] += 1 if rotation_result[:action_required]
+            end
+
+            results
+          rescue StandardError => e
+            Legion::Logging.warn "[identity] credential refresh cycle error: #{e.message}"
+            { workers_checked: 0, error: e.message }
           end
 
           private
@@ -200,6 +346,35 @@ module Legion
             nil
           end
 
+          def resolve_graph_credentials
+            tenant_id = resolve_tenant_id
+            return nil unless tenant_id
+
+            secret = Helpers::VaultSecrets.read_client_secret(worker_id: 'legion/identity')
+            return nil unless secret && secret[:client_id] && secret[:client_secret]
+
+            { tenant_id: tenant_id, client_id: secret[:client_id], client_secret: secret[:client_secret] }
+          rescue StandardError
+            nil
+          end
+
+          def check_worker_orphan_status(conn, worker)
+            # Check if the Entra app registration still exists
+            if worker.respond_to?(:entra_object_id) && worker.entra_object_id
+              app_resp = conn.get("applications/#{worker.entra_object_id}")
+              return :entra_app_deleted unless app_resp.success?
+            end
+
+            # Check if the owner account is still active
+            if worker.owner_msid
+              user_resp = conn.get("users/#{worker.owner_msid}")
+              return :owner_deleted unless user_resp.success?
+              return :owner_disabled if user_resp.body['accountEnabled'] == false
+            end
+
+            nil
+          end
+
           def auto_pause_orphan(worker, reason:)
             worker.update(lifecycle_state: 'paused', updated_at: Time.now.utc)
 

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module Identity
-      VERSION = '0.2.0'
+      VERSION = '0.4.0'
     end
   end
 end

data/spec/legion/extensions/identity/helpers/graph_client_spec.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/identity/helpers/graph_client'
+
+RSpec.describe Legion::Extensions::Identity::Helpers::GraphClient do
+  describe '.connection' do
+    it 'returns a Faraday connection with bearer token' do
+      conn = described_class.connection(token: 'test-token')
+      expect(conn).to be_a(Faraday::Connection)
+      expect(conn.headers['Authorization']).to eq('Bearer test-token')
+    end
+
+    it 'uses custom base URL when provided' do
+      conn = described_class.connection(token: 'tok', base: 'https://custom.api.com')
+      expect(conn.url_prefix.to_s).to eq('https://custom.api.com/')
+    end
+  end
+end

data/spec/legion/extensions/identity/helpers/graph_token_spec.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/identity/helpers/graph_token'
+
+RSpec.describe Legion::Extensions::Identity::Helpers::GraphToken do
+  describe '.fetch' do
+    it 'raises GraphTokenError on failure' do
+      stub_request = instance_double(Faraday::Response, success?: false,
+                                                        body:     { 'error_description' => 'invalid_client' })
+      conn = instance_double(Faraday::Connection)
+      allow(conn).to receive(:post).and_return(stub_request)
+      allow(Faraday).to receive(:new).and_return(conn)
+
+      expect do
+        described_class.fetch(tenant_id: 't1', client_id: 'c1', client_secret: 's1')
+      end.to raise_error(described_class::GraphTokenError, 'invalid_client')
+    end
+
+    it 'returns access_token on success' do
+      stub_request = instance_double(Faraday::Response, success?: true,
+                                                        body:     { 'access_token' => 'tok-123' })
+      conn = instance_double(Faraday::Connection)
+      allow(conn).to receive(:post).and_return(stub_request)
+      allow(Faraday).to receive(:new).and_return(conn)
+
+      token = described_class.fetch(tenant_id: 't1', client_id: 'c1', client_secret: 's1')
+      expect(token).to eq('tok-123')
+    end
+  end
+end

data/spec/legion/extensions/identity/helpers/token_cache_spec.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'legion/extensions/identity/helpers/token_cache'
+
+RSpec.describe Legion::Extensions::Identity::Helpers::TokenCache do
+  before { described_class.clear_all }
+  after { described_class.clear_all }
+
+  describe '.store and .fetch' do
+    it 'stores and retrieves a token' do
+      described_class.store(worker_id: 'w1', token: 'abc', expires_in: 3600)
+      entry = described_class.fetch(worker_id: 'w1')
+      expect(entry[:access_token]).to eq('abc')
+    end
+
+    it 'returns nil for unknown worker' do
+      expect(described_class.fetch(worker_id: 'unknown')).to be_nil
+    end
+
+    it 'returns nil for expired token' do
+      described_class.store(worker_id: 'w1', token: 'abc', expires_in: -1)
+      expect(described_class.fetch(worker_id: 'w1')).to be_nil
+    end
+  end
+
+  describe '.approaching_expiry?' do
+    it 'returns true when no token exists' do
+      expect(described_class.approaching_expiry?(worker_id: 'w1')).to be true
+    end
+
+    it 'returns true when token is within buffer' do
+      described_class.store(worker_id: 'w1', token: 'abc', expires_in: 100)
+      expect(described_class.approaching_expiry?(worker_id: 'w1', buffer: 200)).to be true
+    end
+
+    it 'returns false when token has plenty of time' do
+      described_class.store(worker_id: 'w1', token: 'abc', expires_in: 3600)
+      expect(described_class.approaching_expiry?(worker_id: 'w1', buffer: 300)).to be false
+    end
+  end
+
+  describe '.clear' do
+    it 'removes a specific worker token' do
+      described_class.store(worker_id: 'w1', token: 'abc', expires_in: 3600)
+      described_class.clear(worker_id: 'w1')
+      expect(described_class.fetch(worker_id: 'w1')).to be_nil
+    end
+  end
+end

data/spec/legion/extensions/identity/runners/entra_spec.rb

@@ -44,6 +44,7 @@ RSpec.describe Legion::Extensions::Identity::Runners::Entra do
 
     scope_double = double('Scope')
     allow(scope_double).to receive(:all).and_return(active_all)
+    allow(scope_double).to receive(:update)
 
     model_double = double('DigitalWorker model')
     allow(model_double).to receive(:first).and_return(worker_double)
@@ -238,24 +239,112 @@ RSpec.describe Legion::Extensions::Identity::Runners::Entra do
   end
 
   # ---------------------------------------------------------------------------
-  # sync_owner
+  # refresh_access_token
   # ---------------------------------------------------------------------------
 
-  describe '#sync_owner' do
-    context 'when the worker exists' do
-      it 'returns synced: true with current owner info from local record' do
-        stub_data_model(build_model_double)
+  describe '#refresh_access_token' do
+    let(:vault_secrets_mod) do
+      Module.new do
+        def self.read_client_secret(worker_id:) # rubocop:disable Lint/UnusedMethodArgument
+          { client_id: 'app-id', client_secret: 'secret-val' }
+        end
+      end
+    end
 
-        result = client.sync_owner(worker_id: 'worker-abc')
+    before do
+      require 'legion/extensions/identity/helpers/token_cache'
+      Legion::Extensions::Identity::Helpers::TokenCache.clear_all
+      stub_const('Legion::Extensions::Identity::Helpers::VaultSecrets', vault_secrets_mod)
+      allow(client).to receive(:resolve_tenant_id).and_return('tenant-123')
+    end
 
-        expect(result[:synced]).to be true
-        expect(result[:worker_id]).to eq('worker-abc')
-        expect(result[:owner_msid]).to eq('alice@example.com')
-        expect(result[:source]).to eq(:local)
-        expect(result[:synced_at]).to be_a(Time)
+    after { Legion::Extensions::Identity::Helpers::TokenCache.clear_all }
+
+    it 'returns cached token when available and not expiring' do
+      Legion::Extensions::Identity::Helpers::TokenCache.store(worker_id: 'w1', token: 'cached', expires_in: 3600)
+      result = client.refresh_access_token(worker_id: 'w1')
+      expect(result[:refreshed]).to be false
+      expect(result[:source]).to eq(:cache)
+    end
+
+    it 'returns error when vault unavailable' do
+      vault_nil = Module.new do
+        def self.read_client_secret(**) = nil
+      end
+      stub_const('Legion::Extensions::Identity::Helpers::VaultSecrets', vault_nil)
+      result = client.refresh_access_token(worker_id: 'w1')
+      expect(result[:error]).to eq('vault_unavailable')
+    end
+
+    it 'returns error when no tenant_id' do
+      allow(client).to receive(:resolve_tenant_id).and_return(nil)
+      result = client.refresh_access_token(worker_id: 'w1')
+      expect(result[:error]).to eq('no_tenant_id')
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # rotate_client_secret
+  # ---------------------------------------------------------------------------
+
+  describe '#rotate_client_secret' do
+    before do
+      stub_const('Legion::Settings', Class.new do
+        def self.dig(*keys)
+          map = {
+            %i[identity entra rotation_enabled]     => false,
+            %i[identity entra rotation_buffer_days] => 30
+          }
+          map[keys]
+        end
+
+        def self.[](_key) = {}
+      end)
+    end
+
+    it 'returns no action when no expiry tracked' do
+      vault_mod = Module.new do
+        def self.read_client_secret(**) = { client_secret: 'val' }
+      end
+      stub_const('Legion::Extensions::Identity::Helpers::VaultSecrets', vault_mod)
+
+      result = client.rotate_client_secret(worker_id: 'w1')
+      expect(result[:action_required]).to be false
+      expect(result[:reason]).to eq('no_expiry_tracked')
+    end
+
+    it 'emits warning when rotation not enabled and secret expiring' do
+      vault_mod = Module.new do
+        def self.read_client_secret(**)
+          { client_secret: 'val', client_secret_expires_at: (Time.now + (86_400 * 10)).iso8601 }
+        end
       end
+      stub_const('Legion::Extensions::Identity::Helpers::VaultSecrets', vault_mod)
+
+      result = client.rotate_client_secret(worker_id: 'w1')
+      expect(result[:action_required]).to be true
+      expect(result[:days_remaining]).to be_within(0.5).of(10.0)
     end
 
+    it 'returns no action when secret has plenty of time' do
+      vault_mod = Module.new do
+        def self.read_client_secret(**)
+          { client_secret: 'val', client_secret_expires_at: (Time.now + (86_400 * 60)).iso8601 }
+        end
+      end
+      stub_const('Legion::Extensions::Identity::Helpers::VaultSecrets', vault_mod)
+
+      result = client.rotate_client_secret(worker_id: 'w1')
+      expect(result[:action_required]).to be false
+      expect(result[:days_remaining]).to be > 30
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # sync_owner
+  # ---------------------------------------------------------------------------
+
+  describe '#sync_owner' do
     context 'when the worker does not exist' do
       it 'returns synced: false with error' do
         model_double = double('DigitalWorker model')
@@ -268,6 +357,61 @@ RSpec.describe Legion::Extensions::Identity::Runners::Entra do
         expect(result[:error]).to eq('worker not found')
       end
     end
+
+    context 'when credentials are unavailable' do
+      it 'falls back to local source' do
+        stub_data_model(build_model_double)
+        allow(client).to receive(:resolve_graph_credentials).and_return(nil)
+
+        result = client.sync_owner(worker_id: 'worker-abc')
+
+        expect(result[:synced]).to be true
+        expect(result[:source]).to eq(:local)
+        expect(result[:owner_msid]).to eq('alice@example.com')
+      end
+    end
+
+    context 'when Graph API call succeeds' do
+      before do
+        stub_data_model(build_model_double)
+        allow(client).to receive(:resolve_graph_credentials)
+          .and_return({ tenant_id: 't', client_id: 'c', client_secret: 's' })
+
+        graph_token = Legion::Extensions::Identity::Helpers::GraphToken
+        allow(graph_token).to receive(:fetch).and_return('token')
+
+        @conn = instance_double(Faraday::Connection)
+        allow(Legion::Extensions::Identity::Helpers::GraphClient).to receive(:connection).and_return(@conn)
+      end
+
+      it 'returns source: :graph_api on success' do
+        allow(@conn).to receive(:get)
+          .and_return(double(success?: true, body: { 'value' => [{ 'id' => 'owner-123' }] }))
+
+        result = client.sync_owner(worker_id: 'worker-abc')
+        expect(result[:source]).to eq(:graph_api)
+        expect(result[:synced]).to be true
+      end
+
+      it 'returns source: :local when Graph API call fails' do
+        allow(@conn).to receive(:get).and_return(double(success?: false, status: 403))
+
+        result = client.sync_owner(worker_id: 'worker-abc')
+        expect(result[:synced]).to be false
+        expect(result[:source]).to eq(:local)
+      end
+    end
+
+    context 'when worker has no entra_object_id' do
+      it 'returns error with source: :local' do
+        worker_no_obj = worker_record.merge(entra_object_id: nil)
+        stub_data_model(build_model_double(worker_hash: worker_no_obj))
+
+        result = client.sync_owner(worker_id: 'worker-abc')
+        expect(result[:synced]).to be false
+        expect(result[:error]).to eq('no entra_object_id')
+      end
+    end
   end
 
   # ---------------------------------------------------------------------------
@@ -378,6 +522,7 @@ RSpec.describe Legion::Extensions::Identity::Runners::Entra do
     context 'when there are no active workers' do
       it 'returns empty orphans list with checked count of 0' do
         stub_data_model(build_model_double(active_all: []))
+        allow(client).to receive(:resolve_graph_credentials).and_return(nil)
 
         result = client.check_orphans
 
@@ -388,11 +533,12 @@ RSpec.describe Legion::Extensions::Identity::Runners::Entra do
       end
     end
 
-    context 'when there are active workers' do
-      it 'returns the count of workers scanned and an empty orphans list (pending Entra validation)' do
+    context 'when credentials are unavailable' do
+      it 'returns source: :local with workers scanned' do
         active_worker = double('DigitalWorker', worker_id: 'worker-abc', owner_msid: 'alice@example.com',
                                                 entra_app_id: 'entra-app-abc')
         stub_data_model(build_model_double(active_all: [active_worker]))
+        allow(client).to receive(:resolve_graph_credentials).and_return(nil)
 
         result = client.check_orphans
 
@@ -401,5 +547,109 @@ RSpec.describe Legion::Extensions::Identity::Runners::Entra do
         expect(result[:source]).to eq(:local)
       end
     end
+
+    context 'when Graph API detects orphan (app deleted)' do
+      it 'auto-pauses the orphaned worker' do
+        active_worker = double('DigitalWorker', worker_id: 'worker-abc', owner_msid: 'alice@example.com',
+                                                entra_app_id: 'entra-app-abc', entra_object_id: 'obj-456')
+        allow(active_worker).to receive(:update)
+        stub_data_model(build_model_double(active_all: [active_worker]))
+
+        allow(client).to receive(:resolve_graph_credentials)
+          .and_return({ tenant_id: 't', client_id: 'c', client_secret: 's' })
+        allow(Legion::Extensions::Identity::Helpers::GraphToken).to receive(:fetch).and_return('token')
+
+        conn = instance_double(Faraday::Connection)
+        allow(Legion::Extensions::Identity::Helpers::GraphClient).to receive(:connection).and_return(conn)
+        allow(conn).to receive(:get).with('applications/obj-456').and_return(double(success?: false))
+
+        result = client.check_orphans
+        expect(result[:orphans].size).to eq(1)
+        expect(result[:source]).to eq(:graph_api)
+      end
+    end
+
+    context 'when one worker errors during scan' do
+      it 'continues scanning remaining workers' do
+        w1 = double('DigitalWorker', worker_id: 'w1', owner_msid: 'a@x.com',
+                                     entra_app_id: 'app1', entra_object_id: 'obj1')
+        w2 = double('DigitalWorker', worker_id: 'w2', owner_msid: 'b@x.com',
+                                     entra_app_id: 'app2', entra_object_id: 'obj2')
+        stub_data_model(build_model_double(active_all: [w1, w2]))
+
+        allow(client).to receive(:resolve_graph_credentials)
+          .and_return({ tenant_id: 't', client_id: 'c', client_secret: 's' })
+        allow(Legion::Extensions::Identity::Helpers::GraphToken).to receive(:fetch).and_return('token')
+
+        conn = instance_double(Faraday::Connection)
+        allow(Legion::Extensions::Identity::Helpers::GraphClient).to receive(:connection).and_return(conn)
+        allow(conn).to receive(:get).with('applications/obj1').and_raise(Faraday::ConnectionFailed, 'timeout')
+        allow(conn).to receive(:get).with('applications/obj2').and_return(double(success?: true))
+        allow(conn).to receive(:get).with('users/b@x.com').and_return(double(success?: true, body: { 'accountEnabled' => true }))
+
+        result = client.check_orphans
+        expect(result[:checked]).to eq(2)
+      end
+    end
+  end
+
+  # ---------------------------------------------------------------------------
+  # resolve_governance_roles
+  # ---------------------------------------------------------------------------
+
+  describe '#resolve_governance_roles' do
+    let(:group_map) do
+      {
+        '00000000-0000-0000-0000-000000000001' => 'admin',
+        '00000000-0000-0000-0000-000000000002' => 'governance-council',
+        '00000000-0000-0000-0000-000000000003' => 'owner'
+      }
+    end
+
+    before do
+      stub_const('Legion::Settings', Class.new do
+        def self.dig(*keys)
+          map = {
+            %i[rbac entra group_map]    => {
+              '00000000-0000-0000-0000-000000000001' => 'admin',
+              '00000000-0000-0000-0000-000000000002' => 'governance-council',
+              '00000000-0000-0000-0000-000000000003' => 'owner'
+            },
+            %i[rbac entra default_role] => 'governance-observer'
+          }
+          map[keys]
+        end
+
+        def self.[](_key) = {}
+      end)
+    end
+
+    it 'returns matched role for known group OID' do
+      result = client.resolve_governance_roles(groups: ['00000000-0000-0000-0000-000000000001'])
+      expect(result[:success]).to be true
+      expect(result[:roles]).to eq(['admin'])
+    end
+
+    it 'returns all matched roles for multiple groups' do
+      result = client.resolve_governance_roles(
+        groups: %w[00000000-0000-0000-0000-000000000001 00000000-0000-0000-0000-000000000002]
+      )
+      expect(result[:roles]).to contain_exactly('admin', 'governance-council')
+    end
+
+    it 'returns default_role when no groups match' do
+      result = client.resolve_governance_roles(groups: ['unknown-oid'])
+      expect(result[:roles]).to eq(['governance-observer'])
+    end
+
+    it 'returns default_role when groups is nil' do
+      result = client.resolve_governance_roles(groups: nil)
+      expect(result[:roles]).to eq(['governance-observer'])
+    end
+
+    it 'returns default_role when groups is empty' do
+      result = client.resolve_governance_roles(groups: [])
+      expect(result[:roles]).to eq(['governance-observer'])
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-identity
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Esity
@@ -48,10 +48,14 @@ files:
 - Gemfile
 - lex-identity.gemspec
 - lib/legion/extensions/identity.rb
+- lib/legion/extensions/identity/actors/credential_refresh.rb
 - lib/legion/extensions/identity/actors/orphan_check.rb
 - lib/legion/extensions/identity/client.rb
 - lib/legion/extensions/identity/helpers/dimensions.rb
 - lib/legion/extensions/identity/helpers/fingerprint.rb
+- lib/legion/extensions/identity/helpers/graph_client.rb
+- lib/legion/extensions/identity/helpers/graph_token.rb
+- lib/legion/extensions/identity/helpers/token_cache.rb
 - lib/legion/extensions/identity/helpers/vault_secrets.rb
 - lib/legion/extensions/identity/local_migrations/20260316000030_create_fingerprint.rb
 - lib/legion/extensions/identity/runners/entra.rb
@@ -61,6 +65,9 @@ files:
 - spec/legion/extensions/identity/client_spec.rb
 - spec/legion/extensions/identity/helpers/dimensions_spec.rb
 - spec/legion/extensions/identity/helpers/fingerprint_spec.rb
+- spec/legion/extensions/identity/helpers/graph_client_spec.rb
+- spec/legion/extensions/identity/helpers/graph_token_spec.rb
+- spec/legion/extensions/identity/helpers/token_cache_spec.rb
 - spec/legion/extensions/identity/runners/entra_spec.rb
 - spec/legion/extensions/identity/runners/identity_spec.rb
 - spec/local_persistence_spec.rb