lex-identity-entra 0.5.4 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a50147c3bd7a673e611e5191168b9ade2fe468041ad2b320fccba89dc267a999
-  data.tar.gz: a0889be0de3da89dedae7360058f0463ae8570a735b5f759750f74bf0e720974
+  metadata.gz: e7076abeb6fcf3e837854a909a38bbe46ab78ff6dd8372fb0df53d507484170e
+  data.tar.gz: 6d9347e6aedc921ee6c16fc8a2004d0eb986e15eb8faf150a3a26787363e0d04
 SHA512:
-  metadata.gz: bf3ff78771dc93dea6cb326c1577d6421382575e714eb4ef25ae67ca07cbeceab37f5b616dd9a611eea85e3ff31d868964878f85409ced0e8688510d3231e8d8
-  data.tar.gz: 74f7b159ecc89ba0e306273e3e6438b81d8cb1ad09c52d5e2f9c1fb1d6cf4de95e06de62317c8253c8a69b9bfd9cb365ca5785ffede017d0e365dfbfd9502e61
+  metadata.gz: 6245ce699161036398ccfb11d141587f0188ebabe38944862fe693fcf7f6210c935cf4a493119de46d1b0b42691aa69a5f6459c2f0e11dc2d39b81bde8dad706
+  data.tar.gz: 0b2a7fae7d074dc4fe580f7289c79105ca6761227b6bbbd7045844d4e75b0fb0be90a4c46f92af04fd2ff4a112fa86a3dd12440f1cb6b805d2174cd52b809999

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.6.1] - 2026-10-19
+### Fixed
+- **Browser tab storm**: `Delegated::Actor::TokenRefresher` opened a new login tab on every 15-minute tick once the refresh token went bad (about 50 tabs overnight). It now respects `browser_auth.auto_authenticate`, and every interactive attempt goes through the new `Helpers::InteractiveAuthGuard`, which provides:
+  - single-flight per process (Mutex) and across processes (`flock` lock file)
+  - exponential backoff after an unanswered automatic attempt (30 min, doubling up to 6 h), then a pause after `max_auto_attempts` (3) until the user signs in manually. State persists across restarts.
+  - skipping automatic attempts while the macOS screen is locked or the user is idle (`ioreg`)
+  - a single warning telling the user to run `legionio auth teams`
+- **Refresh loop**: `TokenManager.refresh_token` now negative-caches failures per refresh token. Permanent OAuth errors (`invalid_grant`, `interaction_required`, ...) are not retried until a new token is saved, and transient errors back off from 30 s to 15 min. Previously the broker's `LeaseRenewer` called `provide_token` about once a second and every call re-POSTed the dead refresh token and logged a warning.
+- `AuthValidator` no longer opens a browser for an expired token when `auto_authenticate` is false. It logs the re-auth hint instead.
+- `browser_auth.callback_timeout` is now honored. It was hard-coded to 120 s. The hook listener is removed on timeout.
+
+### Changed
+- The OAuth callback page (local callback server and API hook route) now reads "LegionIO — Microsoft Teams / Entra sign-in complete. You can close this tab." There is a matching failure page that shows the provider error and the `legionio auth teams` hint. Provider errors such as `access_denied` now surface immediately instead of waiting for the timeout. The local server returns 404 for unrelated requests like `/favicon.ico` instead of consuming the callback.
+
+## [0.6.0] - 2026-09-25
+### Changed
+- **Breaking**: Vault token persistence is now opt-in in both directions. New per-pattern settings `identity.entra.<pattern>.token.vault_read_enabled` and `vault_write_enabled`, both defaulting to `false`. With the defaults, Entra tokens are never read from or written to Vault. Set the flags explicitly to restore 0.5.x Vault behavior (each direction is independent).
+- **Breaking**: Removed local disk token persistence (`~/.legionio/tokens/entra_<qualifier>.json`) and its `local_token_path` setting. Tokens are held in-memory by default and in Vault only when explicitly opted in — nothing is ever written to disk. In the default configuration tokens no longer survive a process restart: re-auth via `auto_authenticate` or `legion lex exec entra auth login`.
+- Upgrades from 0.5.x: tokens that exist only in Vault are not read by default (expect a one-time re-auth, or set `vault_read_enabled: true`), and stale on-disk token files are no longer read or written.
+
 ## [0.5.4] - 2026-08-04
 ### Fixed
 - Stop writing delegated Entra tokens to bootstrap Vault paths. Token persistence now uses only the canonical `users/<identity>/entra/<qualifier>/auth` Vault path and falls back to local disk until a canonical identity is available.

data/README.md

@@ -7,7 +7,7 @@ and workload identity authentication patterns.
 ## Features
 
 - **Delegated auth** — OAuth2 PKCE browser flow with local callback server; device-code fallback
-- **Token persistence** — Vault-first (`kv/data/users/<identity>/entra/<qualifier>/auth`), disk fallback, in-memory fallback; disk file deleted once Vault write succeeds
+- **Token persistence** — in-memory by default; Vault (`kv/data/users/<identity>/entra/<qualifier>/auth`) reading and writing are separate opt-ins via `vault_read_enabled` / `vault_write_enabled`. Tokens are never written to local disk
 - **Scope fingerprinting** — MD5 fingerprint of active scopes stored with token; any scope change forces re-authentication on next boot
 - **Identity integration** — `AuthValidator` upgrades `Legion::Identity::Process` via `Resolver.upgrade!` and registers with `Legion::Identity::Broker` for cross-extension token access
 - **Application credentials** — client credentials flow for service-to-service auth
@@ -33,9 +33,17 @@ identity:
       client_id: "your-client-id"
     delegated:
       browser_auth:
-        auto_authenticate: false   # set true to open browser automatically at boot
+        auto_authenticate: false   # set true to open browser automatically (boot + token refresher)
         callback_timeout: 120
+        # Guard for automatic (actor-initiated) sign-in:
+        backoff_base_seconds: 1800      # wait after an unanswered tab; doubles each time
+        backoff_max_seconds: 21600
+        max_auto_attempts: 3            # then stop opening tabs until you sign in manually
+        skip_when_screen_locked: true   # macOS: never open tabs while the screen is locked
+        skip_when_idle_seconds: 900     # macOS: skip if no keyboard/mouse input for this long (0 = off)
       token:
+        vault_read_enabled: false   # set true to read the token from Vault
+        vault_write_enabled: false  # set true to write the token to Vault
         refresh_buffer: 60
         refresh_interval: 900
       scopes:
@@ -61,6 +69,21 @@ legion lex exec entra auth status
 The `AuthValidator` actor fires 9 seconds after boot. If `auto_authenticate: true` is set,
 it opens a browser window automatically. Otherwise trigger login via the CLI.
 
+Interactive sign-in is protected by `Helpers::InteractiveAuthGuard`:
+
+- **Single-flight**: only one browser/device-code attempt runs at a time, per process (mutex) and across
+  processes (`flock` on `~/.legionio/run/entra_browser_auth.lock`).
+- **Backoff**: when an automatic attempt times out, the next one waits `backoff_base_seconds` (default 30 min),
+  doubling up to `backoff_max_seconds`. After `max_auto_attempts` unanswered tabs, automatic sign-in pauses
+  until you sign in manually (`legionio auth teams` or `legion lex exec entra auth login`). Backoff state is
+  kept in `~/.legionio/run/entra_browser_auth_state.json` (no secrets), so restarting the daemon does not
+  reopen a tab right away.
+- **Presence**: on macOS, automatic attempts are skipped while the screen is locked or the user is idle.
+- **No refresh storms**: a refresh token that Microsoft rejects (`invalid_grant` and similar) is not retried
+  until a new token is saved, and transient refresh errors back off from 30 s up to 15 min. One warning tells
+  you how to sign in again.
+- `TokenRefresher` only opens a browser when `auto_authenticate: true`.
+
 ### Accessing tokens from another extension
 
 ```ruby
@@ -98,11 +121,10 @@ identity:
 
 ## Token storage
 
-| Backend | Path | Priority |
-|---------|------|----------|
-| HashiCorp Vault | `kv/data/users/<identity>/entra/delegated/auth` | 1 (preferred) |
-| Local disk | `~/.legionio/tokens/entra_delegated.json` | 2 (fallback, deleted when Vault succeeds) |
-| Memory | In-process store | 3 (runtime fallback) |
+| Backend | Path | When used |
+|---------|------|-----------|
+| HashiCorp Vault | `kv/data/users/<identity>/entra/delegated/auth` | Only when opted in: `vault_read_enabled` / `vault_write_enabled` (both default `false`) |
+| Memory | In-process store | Default persistence; tokens are never written to local disk |
 
 ## Identity provider contract
 

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

@@ -32,10 +32,11 @@ module Legion
                 category_overrides: {}
               },
               token:   {
-                vault_path:       nil,
-                local_token_path: nil,
-                refresh_buffer:   60,
-                refresh_interval: 2700
+                vault_read_enabled:  false,
+                vault_write_enabled: false,
+                vault_path:          nil,
+                refresh_buffer:      60,
+                refresh_interval:    2700
               }
             }
           end

data/lib/legion/extensions/identity/entra/delegated/actors/auth_validator.rb

@@ -38,11 +38,15 @@ module Legion
                   raw_data = stored_token_data
                   log.warn('Entra delegated token expired but refresh_token available — refresh may be stuck') if raw_data && raw_data[:refresh_token]
                   if Legion::Extensions::Identity::Entra::Helpers::TokenManager.scope_fingerprint_stale?(:delegated)
-                    log.info('Entra delegated scope fingerprint changed, re-authenticating to acquire updated scopes')
+                    log.info('Entra delegated scope fingerprint changed, re-authentication needed to acquire updated scopes')
                   else
-                    log.info('Entra delegated token file found but expired, attempting re-auth')
+                    log.info('Entra delegated token found but expired, re-authentication needed')
+                  end
+                  if auto_authenticate?
+                    attempt_browser_reauth
+                  else
+                    Legion::Extensions::Identity::Entra::Helpers::InteractiveAuthGuard.notify_reauth_required('token_expired')
                   end
-                  attempt_browser_reauth
                 elsif auto_authenticate?
                   log.info('auto_authenticate enabled, opening browser for initial auth')
                   attempt_browser_reauth
@@ -67,12 +71,14 @@ module Legion
                 browser = Legion::Extensions::Identity::Entra::Helpers::BrowserAuth.new(
                   tenant_id: auth_settings[:tenant_id],
                   client_id: auth_settings[:client_id],
-                  scopes:    scopes
+                  scopes:    scopes,
+                  automatic: true
                 )
 
                 result = browser.authenticate
                 if result[:error]
-                  log.error("Browser auth error: #{result[:error]} - #{result[:description]}")
+                  log.debug("[entra][auth_validator] action=reauth_incomplete error=#{result[:error]} reason=#{result[:reason]}")
+                  log.error("Browser auth error: #{result[:error]} - #{result[:description]}") unless result[:error] == 'auth_skipped'
                   return false
                 end
 
@@ -139,8 +145,7 @@ module Legion
               end
 
               def previously_authenticated?
-                path = Legion::Extensions::Identity::Entra::Helpers::TokenManager.local_path(:delegated)
-                File.exist?(path)
+                !stored_token_data.nil?
               end
 
               def stored_token_data

data/lib/legion/extensions/identity/entra/delegated/actors/token_refresher.rb

@@ -45,19 +45,29 @@ module Legion
                 if refreshed && !Legion::Extensions::Identity::Entra::Helpers::TokenManager.expired?(refreshed)
                   Legion::Extensions::Identity::Entra::Client.reset!(pattern: :delegated)
                   log.info('Delegated token refreshed successfully')
-                else
-                  log.warn('Delegated token refresh failed, attempting browser re-auth')
+                elsif auto_authenticate?
+                  log.info('Delegated token refresh failed, attempting automatic browser re-auth')
                   attempt_browser_reauth
+                else
+                  log.debug('[entra][token_refresher] action=reauth_skipped reason=auto_authenticate_disabled')
+                  auth_guard.notify_reauth_required('token_refresh_failed')
                 end
               rescue StandardError => e
-                log.error("Delegated TokenRefresher: #{e.message}")
+                handle_exception(e, level: :error, operation: 'entra.delegated.token_refresher.manual')
               end
 
               private
 
+              def auto_authenticate?
+                Legion::Settings.dig(:identity, :entra, :delegated, :browser_auth, :auto_authenticate) == true
+              end
+
+              def auth_guard
+                Legion::Extensions::Identity::Entra::Helpers::InteractiveAuthGuard
+              end
+
               def stored_raw_data
                 Legion::Extensions::Identity::Entra::Helpers::TokenManager.from_vault_data(:delegated) ||
-                  Legion::Extensions::Identity::Entra::Helpers::TokenManager.from_local_data(:delegated) ||
                   Legion::Extensions::Identity::Entra::Helpers::TokenManager.from_memory(:delegated)
               end
 
@@ -69,12 +79,16 @@ module Legion
                 browser = Legion::Extensions::Identity::Entra::Helpers::BrowserAuth.new(
                   tenant_id: auth_settings[:tenant_id],
                   client_id: auth_settings[:client_id],
-                  scopes:    scopes
+                  scopes:    scopes,
+                  automatic: true
                 )
 
                 result = browser.authenticate
                 body = result&.dig(:result)
-                return unless body&.dig(:access_token)
+                unless body&.dig(:access_token)
+                  log.debug("[entra][token_refresher] action=reauth_incomplete error=#{result&.dig(:error)} reason=#{result&.dig(:reason)}")
+                  return
+                end
 
                 Legion::Extensions::Identity::Entra::Helpers::TokenManager.save_token(
                   :delegated,
@@ -88,7 +102,7 @@ module Legion
                 Legion::Extensions::Identity::Entra::Client.reset!(pattern: :delegated)
                 log.info('Delegated auth restored via browser re-auth')
               rescue StandardError => e
-                log.error("Delegated browser re-auth failed: #{e.message}")
+                handle_exception(e, level: :error, operation: 'entra.delegated.token_refresher.attempt_browser_reauth')
               end
             end
           end

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

@@ -2,6 +2,7 @@
 
 require 'faraday'
 require 'legion/extensions/identity/entra/helpers/scopes'
+require 'legion/extensions/identity/entra/helpers/callback_page'
 
 module Legion
   module Extensions
@@ -108,24 +109,25 @@ module Legion
                 { error: 'request_failed', description: e.message }
               end
 
-              def auth_callback(code: nil, state: nil, **)
+              def auth_callback(code: nil, state: nil, error: nil, error_description: nil, **)
+                if error
+                  log.warn("Login.auth_callback: provider returned error=#{error}")
+                  emit_oauth_callback(state: state, error: error, error_description: error_description)
+                  return { result:   { error: error },
+                           response: callback_response(400, callback_failure_html(error, error_description)) }
+                end
+
                 unless code && state
                   log.warn('Login.auth_callback: missing code or state parameter')
-                  return {
-                    result:   { error: 'missing_params' },
-                    response: { status: 400, content_type: 'text/html',
-                                body: '<html><body><h2>Missing code or state parameter</h2></body></html>' }
-                  }
+                  return { result:   { error: 'missing_params' },
+                           response: callback_response(400, callback_failure_html('missing_params',
+                                                                                  'The sign-in response was missing the code or state parameter.')) }
                 end
 
                 log.info('Login.auth_callback: OAuth callback received')
-                Legion::Events.emit('identity.entra.oauth.callback', code: code, state: state) if defined?(Legion::Events)
-
-                {
-                  result:   { authenticated: true, code: code, state: state },
-                  response: { status: 200, content_type: 'text/html',
-                              body: callback_success_html }
-                }
+                emit_oauth_callback(code: code, state: state)
+                { result:   { authenticated: true, code: code, state: state },
+                  response: callback_response(200, callback_success_html) }
               end
               alias handle auth_callback
 
@@ -156,21 +158,22 @@ module Legion
                 body
               end
 
+              def emit_oauth_callback(**payload)
+                return unless defined?(Legion::Events)
+
+                Legion::Events.emit('identity.entra.oauth.callback', **payload.compact)
+              end
+
+              def callback_response(status, body)
+                { status: status, content_type: 'text/html; charset=utf-8', body: body }
+              end
+
+              def callback_failure_html(error, description)
+                Legion::Extensions::Identity::Entra::Helpers::CallbackPage.failure_html(error, description)
+              end
+
               def callback_success_html
-                <<~HTML
-                  <html><body style="font-family:sans-serif;text-align:center;padding:40px;">
-                  <h2>Authentication complete</h2>
-                  <p>Closing in <span id="t">10</span> seconds&hellip;</p>
-                  <script>
-                    var s = 10;
-                    var i = setInterval(function() {
-                      s--;
-                      document.getElementById('t').textContent = s;
-                      if (s <= 0) { clearInterval(i); window.close(); }
-                    }, 1000);
-                  </script>
-                  </body></html>
-                HTML
+                Legion::Extensions::Identity::Entra::Helpers::CallbackPage.success_html
               end
 
               include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&

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

@@ -35,15 +35,22 @@ module Legion
                 category_overrides: {}
               },
               token:        {
-                vault_path:       nil,
-                local_token_path: nil,
-                refresh_buffer:   60,
-                refresh_interval: 900
+                vault_read_enabled:  false,
+                vault_write_enabled: false,
+                vault_path:          nil,
+                refresh_buffer:      60,
+                refresh_interval:    900
               },
               browser_auth: {
-                auto_authenticate:  false,
-                force_local_server: false,
-                callback_timeout:   120
+                auto_authenticate:       false,
+                force_local_server:      false,
+                callback_timeout:        120,
+                # Automatic (actor-initiated) sign-in guard; see Helpers::InteractiveAuthGuard
+                backoff_base_seconds:    1800,
+                backoff_max_seconds:     21_600,
+                max_auto_attempts:       3,
+                skip_when_screen_locked: true,
+                skip_when_idle_seconds:  900
               }
             }
           end

data/lib/legion/extensions/identity/entra/helpers/account_discovery.rb

@@ -16,19 +16,13 @@ module Legion
             include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
                                                         Legion::Extensions::Helpers.const_defined?(:Lex, false)
 
-            # Returns an array of qualifier symbols for which tokens exist locally.
+            # Returns an array of qualifier symbols for which tokens exist in-process.
             def discovered_qualifiers
-              (local_qualifiers + broker_qualifiers).uniq
+              (memory_qualifiers + broker_qualifiers).uniq
             end
 
-            def local_qualifiers
-              return [] unless File.directory?(Legion::Extensions::Identity::Entra::Helpers::TokenManager::TOKEN_DIR)
-
-              Dir.glob(File.join(Legion::Extensions::Identity::Entra::Helpers::TokenManager::TOKEN_DIR, 'entra_*.json')).filter_map do |path|
-                basename = File.basename(path, '.json')
-                match = basename.match(/\Aentra_(.+)\z/)
-                match[1].to_sym if match
-              end
+            def memory_qualifiers
+              Legion::Extensions::Identity::Entra::Helpers::TokenManager.memory_store.keys
             end
 
             def broker_qualifiers

data/lib/legion/extensions/identity/entra/helpers/browser_auth.rb

@@ -6,6 +6,7 @@ require 'securerandom'
 require 'faraday'
 
 require 'legion/extensions/identity/entra/helpers/callback_server'
+require 'legion/extensions/identity/entra/helpers/interactive_auth_guard'
 require 'legion/extensions/identity/entra/delegated/runners/login'
 
 module Legion
@@ -23,26 +24,40 @@ module Legion
 
             attr_reader :tenant_id, :client_id, :scopes
 
-            def initialize(tenant_id:, client_id:, scopes: self.class.default_scopes, auth: nil, force_local_server: false, **)
+            DEFAULT_CALLBACK_TIMEOUT = 120
+
+            # automatic: true marks a background (actor-initiated) attempt. Those are
+            # subject to InteractiveAuthGuard backoff/suspension and screen-lock/idle
+            # checks; user-initiated attempts (CLI) only get single-flight protection.
+            def initialize(tenant_id:, client_id:, scopes: self.class.default_scopes, auth: nil, force_local_server: false,
+                           automatic: false, **)
               @tenant_id = tenant_id
               @client_id = client_id
               @scopes = scopes
               @auth = auth || Object.new.extend(Legion::Extensions::Identity::Entra::Delegated::Runners::Login)
               @force_local_server = force_local_server
-              log.debug("BrowserAuth initialized: tenant=#{tenant_id} client=#{client_id} force_local=#{force_local_server}")
+              @automatic = automatic
+              log.debug("BrowserAuth initialized: tenant=#{tenant_id} client=#{client_id} force_local=#{force_local_server} automatic=#{automatic}")
               log.info("BrowserAuth scopes: #{@scopes}")
             end
 
             def authenticate
-              if gui_available?
-                log.info('BrowserAuth: GUI available, using browser auth')
-                authenticate_browser
-              else
-                log.info('BrowserAuth: no GUI detected, using device code flow')
-                authenticate_device_code
+              InteractiveAuthGuard.run(automatic: @automatic) do
+                if gui_available?
+                  log.info('BrowserAuth: GUI available, using browser auth')
+                  authenticate_browser
+                else
+                  log.info('BrowserAuth: no GUI detected, using device code flow')
+                  authenticate_device_code
+                end
               end
             end
 
+            def callback_timeout
+              value = Legion::Settings.dig(:identity, :entra, :delegated, :browser_auth, :callback_timeout).to_i
+              value.positive? ? value : DEFAULT_CALLBACK_TIMEOUT
+            end
+
             def api_hook_available?
               return false if @force_local_server
               return false unless defined?(Legion::API) && defined?(Legion::Events)
@@ -143,8 +158,9 @@ module Legion
                 return authenticate_device_code
               end
 
-              log.debug('BrowserAuth: waiting for callback (timeout=120s)')
-              mutex.synchronize { cv.wait(mutex, 120) unless result_holder[:result] }
+              log.debug("BrowserAuth: waiting for callback (timeout=#{callback_timeout}s)")
+              mutex.synchronize { cv.wait(mutex, callback_timeout) unless result_holder[:result] }
+              Legion::Events.off('identity.entra.oauth.callback', listener) unless result_holder[:result]
               exchange_callback(result_holder[:result], state: state, verifier: verifier, callback_uri: callback_uri)
             end
 
@@ -163,8 +179,8 @@ module Legion
                 return authenticate_device_code
               end
 
-              log.debug('BrowserAuth: waiting for callback on local server (timeout=120s)')
-              result = server.wait_for_callback(timeout: 120)
+              log.debug("BrowserAuth: waiting for callback on local server (timeout=#{callback_timeout}s)")
+              result = server.wait_for_callback(timeout: callback_timeout)
               exchange_callback(result, state: state, verifier: verifier, callback_uri: callback_uri)
             ensure
               server&.shutdown
@@ -172,6 +188,11 @@ module Legion
             end
 
             def exchange_callback(result, state:, verifier:, callback_uri:)
+              if result && result[:error] && !result[:code]
+                log.error("BrowserAuth: OAuth callback returned error=#{result[:error]}")
+                return { error: result[:error].to_s, description: result[:error_description] }
+              end
+
               unless result && result[:code]
                 log.error('BrowserAuth: OAuth callback timed out or missing code')
                 return { error: 'timeout', description: 'No callback received within timeout' }

data/lib/legion/extensions/identity/entra/helpers/callback_page.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Legion
+  module Extensions
+    module Identity
+      module Entra
+        module Helpers
+          # HTML returned to the browser by the OAuth redirect (local callback
+          # server and the API hook route). Keeps the wording in one place so the
+          # user always knows which app the tab belongs to.
+          module CallbackPage
+            module_function
+
+            TITLE = 'LegionIO — Microsoft Teams / Entra sign-in'
+
+            def success_html
+              render(heading: 'LegionIO — Microsoft Teams / Entra sign-in complete',
+                     message: 'You can close this tab.', color: '#107c10', icon: '✔')
+            end
+
+            def failure_html(reason = nil, description = nil)
+              detail = [reason, description].compact.map { |v| CGI.escapeHTML(v.to_s) }.reject(&:empty?).join(': ')
+              detail_html = detail.empty? ? '' : "<p class=\"detail\">#{detail}</p>"
+              render(heading: 'LegionIO &mdash; Microsoft Teams / Entra sign-in failed',
+                     message: 'You can close this tab. To try again, run <code>legionio auth teams</code>.',
+                     color: '#a4262c', icon: '&#10008;', extra: detail_html)
+            end
+
+            def render(heading:, message:, color:, icon:, extra: '')
+              <<~HTML
+                <!DOCTYPE html>
+                <html lang="en"><head><meta charset="utf-8"><title>#{TITLE}</title>
+                <style>
+                  body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;text-align:center;padding:48px;color:#323130}
+                  .icon{font-size:48px;color:#{color}} h1{font-size:22px;color:#{color}} .detail{color:#605e5c;font-size:13px}
+                  code{background:#f3f2f1;padding:2px 6px;border-radius:3px}
+                </style></head>
+                <body><div class="icon">#{icon}</div><h1>#{heading}</h1><p>#{message}</p>#{extra}</body></html>
+              HTML
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/entra/helpers/callback_server.rb

@@ -2,6 +2,7 @@
 
 require 'socket'
 require 'uri'
+require 'legion/extensions/identity/entra/helpers/callback_page'
 
 module Legion
   module Extensions
@@ -12,11 +13,6 @@ module Legion
             include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers, false) &&
                                                         Legion::Extensions::Helpers.const_defined?(:Lex, false)
 
-            RESPONSE_HTML = <<~HTML
-              <html><body style="font-family:sans-serif;text-align:center;padding:40px;">
-              <h2>Authentication complete</h2><p>You can close this window.</p></body></html>
-            HTML
-
             attr_reader :port
 
             def initialize
@@ -60,9 +56,9 @@ module Legion
                 client = @server.accept
                 request_line = client.gets
                 drain_headers(client)
-                capture_callback(request_line) if request_line&.include?('/callback?')
-
-                client.print "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\nConnection: close\r\n\r\n#{RESPONSE_HTML}"
+                status, body = handle_request(request_line)
+                client.print "HTTP/1.1 #{status}\r\nContent-Type: text/html; charset=utf-8\r\n" \
+                             "Content-Length: #{body.bytesize}\r\nConnection: close\r\n\r\n#{body}"
                 client.close
               end
             rescue IOError # rubocop:disable Legion/RescueLogging/NoCapture
@@ -79,17 +75,34 @@ module Legion
               line = client.gets until line.nil? || line.strip.empty?
             end
 
-            def capture_callback(request_line)
-              query = request_line.split[1].split('?', 2).last
+            # Returns [status_line, html]. Only /callback?... completes the flow;
+            # anything else (favicon, probes) gets a 404 and keeps listening.
+            def handle_request(request_line)
+              target = request_line.to_s.split[1].to_s
+              return ['404 Not Found', 'Not Found'] unless target.start_with?('/callback?')
+
+              params = capture_callback(target)
+              if params['code']
+                ['200 OK', CallbackPage.success_html]
+              else
+                ['400 Bad Request', CallbackPage.failure_html(params['error'] || 'missing_code', params['error_description'])]
+              end
+            end
+
+            def capture_callback(target)
+              query = target.split('?', 2).last
               params = URI.decode_www_form(query).to_h
 
               @mutex.synchronize do
                 @result = {
-                  code:  params['code'],
-                  state: params['state']
-                }
+                  code:              params['code'],
+                  state:             params['state'],
+                  error:             params['error'],
+                  error_description: params['error_description']
+                }.compact
                 @cv.broadcast
               end
+              params
             end
 
             def log_debug(message)

data/lib/legion/extensions/identity/entra/helpers/interactive_auth_guard.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'open3'
+require 'rbconfig'
+
+module Legion
+  module Extensions
+    module Identity
+      module Entra
+        module Helpers
+          # Guards interactive (browser / device-code) sign-in so background actors
+          # can never stack up login tabs:
+          #
+          # * single-flight: one attempt at a time per process (Mutex) and across
+          #   processes (flock on a lock file)
+          # * exponential backoff after an unanswered automatic attempt, and a
+          #   hard stop after +max_auto_attempts+ until the user signs in manually
+          #   (any successful TokenManager.save_token(:delegated) resets the guard)
+          # * optional skip while the macOS screen is locked or the user is idle
+          # * one clear warning telling the user how to re-authenticate
+          #
+          # Backoff state is persisted (no secrets) so a daemon restart does not
+          # immediately reopen a tab.
+          module InteractiveAuthGuard
+            extend self
+            include Legion::Logging::Helper
+            include Legion::JSON::Helper
+
+            REAUTH_HINT = 'Run `legionio auth teams` to sign in to Microsoft Teams / Entra again.'
+            DEFAULTS = {
+              backoff_base_seconds:    1800,
+              backoff_max_seconds:     21_600,
+              max_auto_attempts:       3,
+              skip_when_screen_locked: true,
+              skip_when_idle_seconds:  900
+            }.freeze
+            RUN_DIR = File.join(Dir.home, '.legionio', 'run')
+            SUCCESS_KEYS = %i[access_token].freeze
+
+            MUTEX = Mutex.new
+            STATE_MUTEX = Mutex.new
+
+            # Runs the block as an interactive sign-in attempt.
+            #
+            # automatic: true  -> background actor; subject to backoff, suspension, screen lock/idle
+            # automatic: false -> user asked for it (CLI); only single-flight applies
+            #
+            # Returns the block's result, or { error:, description: } when skipped.
+            def run(automatic: false, &)
+              if automatic
+                skip = automatic_skip_reason
+                return skipped(skip) if skip
+              end
+
+              return busy('in_process') unless MUTEX.try_lock
+
+              begin
+                with_process_lock { record_outcome(yield, automatic: automatic) }
+              ensure
+                MUTEX.unlock
+              end
+            end
+
+            def in_flight?
+              MUTEX.locked?
+            end
+
+            # Clears backoff/suspension. Called after any successful delegated sign-in.
+            def reset!(reason: 'success')
+              STATE_MUTEX.synchronize do
+                state = current_state
+                had_state = state[:failures].to_i.positive? || state[:suspended] || state[:notified]
+                next unless had_state
+
+                @state = blank_state
+                persist_state
+                log.info("[entra][auth_guard] action=reset reason=#{reason}")
+              end
+            end
+
+            def state
+              STATE_MUTEX.synchronize { current_state.dup }
+            end
+
+            # Logs a single warning (once per process until the next successful
+            # sign-in) telling the user how to re-authenticate.
+            def notify_reauth_required(reason)
+              STATE_MUTEX.synchronize do
+                state = current_state
+                if state[:notified]
+                  log.debug("[entra][auth_guard] action=notify_suppressed reason=#{reason}")
+                  return false
+                end
+
+                state[:notified] = reason.to_s
+                persist_state
+              end
+              log.warn("Microsoft Teams / Entra sign-in required (#{reason}). #{REAUTH_HINT}")
+              true
+            end
+
+            def screen_locked?
+              return false unless darwin?
+
+              out, status = Open3.capture2('/usr/sbin/ioreg', '-n', 'Root', '-d1')
+              status.success? && out.include?('"CGSSessionScreenIsLocked"=Yes')
+            rescue StandardError => e
+              handle_exception(e, level: :debug, operation: 'entra.auth_guard.screen_locked?')
+              false
+            end
+
+            # Seconds since the last keyboard/mouse input (macOS only), or nil.
+            def idle_seconds
+              return nil unless darwin?
+
+              out, status = Open3.capture2('/usr/sbin/ioreg', '-c', 'IOHIDSystem', '-d', '4')
+              return nil unless status.success?
+
+              match = out.match(/"HIDIdleTime"\s*=\s*(\d+)/)
+              match ? match[1].to_i / 1_000_000_000 : nil
+            rescue StandardError => e
+              handle_exception(e, level: :debug, operation: 'entra.auth_guard.idle_seconds')
+              nil
+            end
+
+            def lock_path
+              setting(:lock_path) || File.join(RUN_DIR, 'entra_browser_auth.lock')
+            end
+
+            def state_path
+              setting(:state_path) || File.join(RUN_DIR, 'entra_browser_auth_state.json')
+            end
+
+            # Test helper: forget in-memory state so it is re-read from disk.
+            def reload!
+              STATE_MUTEX.synchronize do
+                @state = nil
+                @state_mtime = nil
+              end
+            end
+
+            private
+
+            def automatic_skip_reason
+              state = self.state
+              if state[:suspended]
+                log.debug("[entra][auth_guard] action=skip reason=suspended failures=#{state[:failures]}")
+                return 'suspended'
+              end
+
+              retry_at = state[:next_attempt_at]
+              if retry_at && Time.now.to_i < retry_at
+                log.debug("[entra][auth_guard] action=skip reason=backoff retry_in=#{retry_at - Time.now.to_i}s")
+                return 'backoff'
+              end
+
+              if config[:skip_when_screen_locked] && screen_locked?
+                log.debug('[entra][auth_guard] action=skip reason=screen_locked')
+                return 'screen_locked'
+              end
+
+              idle_limit = config[:skip_when_idle_seconds].to_i
+              if idle_limit.positive?
+                idle = idle_seconds
+                if idle && idle >= idle_limit
+                  log.debug("[entra][auth_guard] action=skip reason=user_idle idle=#{idle}s limit=#{idle_limit}s")
+                  return 'user_idle'
+                end
+              end
+
+              nil
+            end
+
+            def with_process_lock
+              path = lock_path
+              FileUtils.mkdir_p(File.dirname(path))
+              File.open(path, File::RDWR | File::CREAT, 0o600) do |file|
+                unless file.flock(File::LOCK_EX | File::LOCK_NB)
+                  holder = file.read.to_s.strip
+                  return busy('other_process', holder: holder)
+                end
+
+                begin
+                  file.truncate(0)
+                  file.write(::Process.pid.to_s)
+                  file.flush
+                  log.debug("[entra][auth_guard] action=lock_acquired path=#{path} pid=#{::Process.pid}")
+                  yield
+                ensure
+                  file.truncate(0)
+                  file.flock(File::LOCK_UN)
+                end
+              end
+            end
+
+            def record_outcome(result, automatic:)
+              if success?(result)
+                reset!
+              elsif automatic
+                record_failure(result)
+              end
+              result
+            end
+
+            def success?(result)
+              return false unless result.is_a?(Hash)
+
+              body = result[:result]
+              body.is_a?(Hash) && SUCCESS_KEYS.all? { |k| body[k] || body[k.to_s] }
+            end
+
+            def record_failure(result)
+              error = result.is_a?(Hash) ? (result[:error] || 'no_token') : 'no_token'
+              cfg = config
+              warning = nil
+              STATE_MUTEX.synchronize do
+                state = current_state
+                state[:failures] = state[:failures].to_i + 1
+                state[:last_error] = error.to_s
+                state[:last_attempt_at] = Time.now.to_i
+                if state[:failures] >= cfg[:max_auto_attempts].to_i
+                  state[:suspended] = true
+                  state[:next_attempt_at] = nil
+                  warning = "Automatic Microsoft Teams / Entra browser sign-in paused after #{state[:failures]} " \
+                            "unanswered attempts (last error: #{error}). No more login tabs will be opened. #{REAUTH_HINT}"
+                else
+                  delay = backoff_delay(state[:failures], cfg)
+                  state[:next_attempt_at] = Time.now.to_i + delay
+                  warning = "Microsoft Teams / Entra browser sign-in was not completed (#{error}). " \
+                            "Will retry automatically in #{format_duration(delay)} " \
+                            "(attempt #{state[:failures]}/#{cfg[:max_auto_attempts]}). #{REAUTH_HINT}"
+                end
+                state[:notified] = 'auto_auth_failed'
+                persist_state
+              end
+              log.warn(warning)
+            end
+
+            def backoff_delay(failures, cfg)
+              base = cfg[:backoff_base_seconds].to_i
+              max = cfg[:backoff_max_seconds].to_i
+              [base * (2**(failures - 1)), max].min
+            end
+
+            def format_duration(seconds)
+              return "#{seconds}s" if seconds < 120
+              return "#{seconds / 60} minutes" if seconds < 7200
+
+              "#{(seconds / 3600.0).round(1)} hours"
+            end
+
+            def skipped(reason)
+              notify_reauth_required('automatic sign-in deferred') if %w[screen_locked user_idle].include?(reason)
+              { error: 'auth_skipped', reason: reason,
+                description: "interactive sign-in skipped (#{reason}). #{REAUTH_HINT}" }
+            end
+
+            def busy(scope, holder: nil)
+              log.info("[entra][auth_guard] action=skip reason=in_progress scope=#{scope} holder=#{holder}")
+              { error: 'auth_in_progress', reason: scope,
+                description: "another Microsoft sign-in is already in progress#{" (pid #{holder})" unless holder.to_s.empty?}" }
+            end
+
+            # Re-reads the state file when another process (e.g. `legionio entra login`)
+            # changed it, so a sign-in elsewhere clears this daemon's backoff.
+            def current_state
+              mtime = state_file_mtime
+              if @state.nil? || (mtime && mtime != @state_mtime)
+                notified = @state&.dig(:notified)
+                @state = load_state
+                @state[:notified] ||= notified if @state[:failures].to_i.positive? || @state[:suspended]
+                @state_mtime = mtime
+              end
+              @state
+            end
+
+            def state_file_mtime
+              path = state_path
+              File.exist?(path) ? File.mtime(path) : nil
+            end
+
+            def blank_state
+              { failures: 0, suspended: false, next_attempt_at: nil, last_error: nil,
+                last_attempt_at: nil, notified: nil }
+            end
+
+            def load_state
+              path = state_path
+              return blank_state unless File.exist?(path)
+
+              raw = json_load(File.read(path))
+              return blank_state unless raw.is_a?(Hash)
+
+              # :notified is per-process so each daemon start logs the hint once.
+              blank_state.merge(raw.transform_keys(&:to_sym).slice(*blank_state.keys).except(:notified))
+            rescue StandardError => e
+              handle_exception(e, level: :warn, operation: 'entra.auth_guard.load_state', path: path)
+              blank_state
+            end
+
+            def persist_state
+              path = state_path
+              FileUtils.mkdir_p(File.dirname(path))
+              File.write(path, json_dump(@state.except(:notified)))
+              File.chmod(0o600, path)
+              @state_mtime = state_file_mtime
+            rescue StandardError => e
+              handle_exception(e, level: :warn, operation: 'entra.auth_guard.persist_state', path: path)
+            end
+
+            def config
+              DEFAULTS.to_h { |key, default| [key, setting(key).nil? ? default : setting(key)] }
+            end
+
+            def setting(key)
+              Legion::Settings.dig(:identity, :entra, :delegated, :browser_auth, key)
+            rescue StandardError => e
+              handle_exception(e, level: :debug, operation: 'entra.auth_guard.setting', key: key)
+              nil
+            end
+
+            def darwin?
+              RbConfig::CONFIG['host_os'].include?('darwin')
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/entra/helpers/token_manager.rb

@@ -2,8 +2,8 @@
 
 require 'concurrent'
 require 'digest'
-require 'fileutils'
 require 'time'
+require 'legion/extensions/identity/entra/helpers/interactive_auth_guard'
 
 module Legion
   module Extensions
@@ -16,14 +16,26 @@ module Legion
             include Legion::Settings::Helper
             include Legion::JSON::Helper
 
-            TOKEN_DIR = File.join(Dir.home, '.legionio', 'tokens')
             REFRESH_BUFFER = 60
             MEMORY_STORE = Concurrent::Hash.new
+            # Negative cache for failed refresh attempts, keyed by qualifier. Without it
+            # every caller (LeaseRenewer polls once a second once the lease expires)
+            # re-POSTs a dead refresh_token to Microsoft and logs a warning each time.
+            REFRESH_FAILURES = Concurrent::Hash.new
+            REFRESH_BACKOFF_BASE = 30
+            REFRESH_BACKOFF_MAX = 900
+            # OAuth errors meaning the refresh_token will never work again; stop
+            # retrying until a new token is saved (user signs in again).
+            PERMANENT_REFRESH_ERRORS = %w[invalid_grant interaction_required invalid_client unauthorized_client].freeze
 
             def memory_store
               MEMORY_STORE
             end
 
+            def refresh_failures
+              REFRESH_FAILURES
+            end
+
             def load_token(qualifier = :delegated)
               log.debug("TokenManager.load_token: qualifier=#{qualifier}")
               data = token_data(qualifier, refresh: true)
@@ -34,20 +46,7 @@ module Legion
 
             def token_data(qualifier = :delegated, refresh: true)
               log.debug("TokenManager.token_data: qualifier=#{qualifier} refresh=#{refresh}")
-              vault_data = from_vault_data(qualifier)
-              other_data = vault_data || from_local_data(qualifier) || from_memory(qualifier)
-              if other_data && !vault_data && vault_available? && canonical_name_available?
-                log.info("TokenManager.token_data: backfilling #{qualifier} token to vault")
-                backfill_saved = save_to_vault(qualifier, access_token:      other_data[:access_token],
-                                                          refresh_token:     other_data[:refresh_token],
-                                                          expires_at:        other_data[:expires_at],
-                                                          scopes:            other_data[:scopes],
-                                                          tenant_id:         other_data[:tenant_id],
-                                                          client_id:         other_data[:client_id],
-                                                          scope_fingerprint: other_data[:scope_fingerprint])
-                delete_local(qualifier) if backfill_saved
-              end
-              data = other_data
+              data = from_vault_data(qualifier) || from_memory(qualifier)
               return nil unless data
 
               if scope_fingerprint_stale?(qualifier, data)
@@ -68,20 +67,14 @@ module Legion
             def save_token(qualifier, access_token:, refresh_token: nil, expires_at: nil,
                            expires_in: nil, scopes: nil, tenant_id: nil, client_id: nil)
               log.debug("TokenManager.save_token: qualifier=#{qualifier} expires_in=#{expires_in}")
+              clear_refresh_failure(qualifier)
+              Helpers::InteractiveAuthGuard.reset!(reason: 'token_saved') if qualifier.to_sym == :delegated && access_token
               expires_at ||= Time.now + expires_in.to_i if expires_in
               fingerprint = current_scope_fingerprint(qualifier)
-              vault_saved = save_to_vault(qualifier, access_token: access_token, refresh_token: refresh_token,
-                                                     expires_at: expires_at, scopes: scopes,
-                                                     tenant_id: tenant_id, client_id: client_id,
-                                                     scope_fingerprint: fingerprint)
-              if vault_saved
-                delete_local(qualifier)
-              else
-                save_to_local(qualifier, access_token: access_token, refresh_token: refresh_token,
-                                         expires_at: expires_at, scopes: scopes,
-                                         tenant_id: tenant_id, client_id: client_id,
-                                         scope_fingerprint: fingerprint)
-              end
+              save_to_vault(qualifier, access_token: access_token, refresh_token: refresh_token,
+                                            expires_at: expires_at, scopes: scopes,
+                                            tenant_id: tenant_id, client_id: client_id,
+                                            scope_fingerprint: fingerprint)
               save_to_memory(qualifier, access_token: access_token, refresh_token: refresh_token,
                                         expires_at: expires_at, scopes: scopes,
                                         tenant_id: tenant_id, client_id: client_id,
@@ -89,6 +82,7 @@ module Legion
             end
 
             def from_vault_data(qualifier)
+              return nil unless vault_read_enabled?(qualifier)
               return nil unless vault_available? && canonical_name_available?
 
               read_vault_token(qualifier, vault_path(qualifier))
@@ -106,20 +100,9 @@ module Legion
               nil
             end
 
-            def from_local_data(qualifier)
-              path = local_path(qualifier)
-              return nil unless File.exist?(path)
-
-              log.debug("TokenManager.from_local_data: reading #{path}")
-              normalize_token_data(json_load(File.read(path)))
-            rescue StandardError => e
-              handle_exception(e, level: :warn, operation: 'token_manager.from_local_data',
-                                  qualifier: qualifier, path: path)
-              nil
-            end
-
             def save_to_vault(qualifier, access_token:, refresh_token:, expires_at:,
                               scopes: nil, tenant_id: nil, client_id: nil, scope_fingerprint: nil)
+              return unless vault_write_enabled?(qualifier)
               return unless vault_available?
               return unless canonical_name_available?
 
@@ -144,38 +127,6 @@ module Legion
               nil
             end
 
-            def save_to_local(qualifier, access_token:, refresh_token:, expires_at:,
-                              scopes: nil, tenant_id: nil, client_id: nil, scope_fingerprint: nil)
-              path = local_path(qualifier)
-              log.debug("TokenManager.save_to_local: writing #{path}")
-              FileUtils.mkdir_p(File.dirname(path))
-              File.write(path, json_dump({
-                                           access_token:      access_token,
-                                           refresh_token:     refresh_token,
-                                           expires_at:        expires_at&.utc&.iso8601,
-                                           scopes:            scopes,
-                                           tenant_id:         tenant_id,
-                                           client_id:         client_id,
-                                           scope_fingerprint: scope_fingerprint
-                                         }))
-              File.chmod(0o600, path)
-              log.debug('TokenManager.save_to_local: success')
-            rescue StandardError => e
-              handle_exception(e, level: :warn, operation: 'token_manager.save_to_local',
-                                  qualifier: qualifier, path: path)
-              nil
-            end
-
-            def delete_local(qualifier)
-              path = local_path(qualifier)
-              return unless File.exist?(path)
-
-              File.delete(path)
-              log.info("TokenManager.delete_local: removed #{path} (vault is authoritative)")
-            rescue StandardError => e
-              handle_exception(e, level: :warn, operation: 'token_manager.delete_local', qualifier: qualifier)
-            end
-
             def from_memory(qualifier)
               data = TokenManager.memory_store[qualifier.to_sym]
               return nil unless data
@@ -204,7 +155,7 @@ module Legion
             end
 
             def scope_fingerprint_stale?(qualifier, data = nil)
-              data ||= from_local_data(qualifier) || from_memory(qualifier)
+              data ||= from_memory(qualifier)
               return false unless data
 
               stored = data[:scope_fingerprint]
@@ -227,19 +178,17 @@ module Legion
                 return nil
               end
 
-              runner = Object.new.extend(Legion::Extensions::Identity::Entra::Delegated::Runners::Login)
-              result = runner.refresh_delegated_token(
+              return nil if refresh_suppressed?(qualifier, refresh)
+
+              result = login_runner.refresh_delegated_token(
                 tenant_id:     auth[:tenant_id],
                 client_id:     auth[:client_id],
                 refresh_token: refresh,
                 scope:         auth[:scopes] || Legion::Extensions::Identity::Entra::Helpers::Scopes.resolve(pattern: :delegated)
               )
-              body = result[:result]
+              body = result[:result] || {}
               access_token = fetch_key(body, :access_token)
-              unless access_token
-                log.warn("TokenManager.refresh_token: refresh failed for #{qualifier}, no access_token in response")
-                return nil
-              end
+              return record_refresh_response_failure(qualifier, refresh, result, body) unless access_token
 
               log.info("TokenManager.refresh_token: successfully refreshed token for #{qualifier}")
               save_token(qualifier,
@@ -253,9 +202,69 @@ module Legion
             rescue StandardError => e
               handle_exception(e, level: :error, operation: 'token_manager.refresh_token',
                                   qualifier: qualifier)
+              record_refresh_failure(qualifier, refresh, e.class.name, e.message) if refresh
               nil
             end
 
+            def login_runner
+              Object.new.extend(Legion::Extensions::Identity::Entra::Delegated::Runners::Login)
+            end
+
+            def record_refresh_response_failure(qualifier, refresh, result, body)
+              error = fetch_key(body, :error) || result[:error] || 'no_access_token'
+              record_refresh_failure(qualifier, refresh, error, fetch_key(body, :error_description) || result[:description])
+              nil
+            end
+
+            def refresh_suppressed?(qualifier, refresh)
+              entry = refresh_failures[qualifier.to_sym]
+              return false unless entry
+              return false unless entry[:fingerprint] == refresh_fingerprint(refresh)
+
+              if entry[:permanent]
+                log.debug("[entra][token_manager] action=refresh_skipped qualifier=#{qualifier} reason=permanent error=#{entry[:error]}")
+                return true
+              end
+
+              remaining = entry[:retry_at] - Time.now
+              return false unless remaining.positive?
+
+              log.debug("[entra][token_manager] action=refresh_skipped qualifier=#{qualifier} reason=backoff " \
+                        "retry_in=#{remaining.round}s failures=#{entry[:failures]}")
+              true
+            end
+
+            def record_refresh_failure(qualifier, refresh, error, description = nil)
+              key = qualifier.to_sym
+              fingerprint = refresh_fingerprint(refresh)
+              previous = refresh_failures[key]
+              previous = nil unless previous && previous[:fingerprint] == fingerprint
+              failures = (previous&.dig(:failures) || 0) + 1
+              permanent = PERMANENT_REFRESH_ERRORS.include?(error.to_s)
+              delay = [REFRESH_BACKOFF_BASE * (2**(failures - 1)), REFRESH_BACKOFF_MAX].min
+              refresh_failures[key] = { fingerprint: fingerprint, failures: failures, error: error.to_s,
+                                        permanent: permanent, retry_at: Time.now + delay }
+
+              if permanent && !previous&.dig(:permanent)
+                log.warn("TokenManager.refresh_token: refresh token for #{qualifier} was rejected (#{error}: #{description}). " \
+                         'Not retrying until you sign in again.')
+                Helpers::InteractiveAuthGuard.notify_reauth_required('refresh_token_rejected') if key == :delegated
+              elsif failures == 1
+                log.warn("TokenManager.refresh_token: refresh failed for #{qualifier} (#{error}), backing off #{delay}s")
+              else
+                log.debug("[entra][token_manager] action=refresh_failed qualifier=#{qualifier} error=#{error} " \
+                          "failures=#{failures} retry_in=#{delay}s permanent=#{permanent}")
+              end
+            end
+
+            def clear_refresh_failure(qualifier)
+              refresh_failures.delete(qualifier.to_sym)
+            end
+
+            def refresh_fingerprint(refresh)
+              Digest::SHA256.hexdigest(refresh.to_s)[0, 16]
+            end
+
             def from_broker(qualifier)
               return nil unless defined?(Legion::Identity::Broker)
 
@@ -280,6 +289,14 @@ module Legion
               !load_token(qualifier).nil?
             end
 
+            def vault_read_enabled?(qualifier)
+              Legion::Settings.dig(:identity, :entra, qualifier.to_sym, :token, :vault_read_enabled)
+            end
+
+            def vault_write_enabled?(qualifier)
+              Legion::Settings.dig(:identity, :entra, qualifier.to_sym, :token, :vault_write_enabled)
+            end
+
             def vault_available?
               defined?(Legion::Crypt) &&
                 Legion::Crypt.respond_to?(:vault_connected?) &&
@@ -296,14 +313,6 @@ module Legion
               "users/#{Legion::Identity::Process.canonical_name}/entra/#{qualifier}/auth"
             end
 
-            def local_path(qualifier)
-              auth = settings_auth
-              pattern_settings = auth[qualifier.to_sym]
-              return File.expand_path(pattern_settings[:local_token_path]) if pattern_settings.is_a?(Hash) && pattern_settings[:local_token_path]
-
-              File.join(TOKEN_DIR, "entra_#{qualifier}.json")
-            end
-
             def settings_auth
               identity_entra = Legion::Settings.dig(:identity, :entra) || {}
               auth = identity_entra[:auth].is_a?(Hash) ? identity_entra[:auth].dup : identity_entra.dup

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

@@ -28,10 +28,11 @@ module Legion
                 category_overrides: {}
               },
               token:     {
-                vault_path:       nil,
-                local_token_path: nil,
-                refresh_buffer:   60,
-                refresh_interval: 2700
+                vault_read_enabled:  false,
+                vault_write_enabled: false,
+                vault_path:          nil,
+                refresh_buffer:      60,
+                refresh_interval:    2700
               }
             }
           end

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Identity
       module Entra
-        VERSION = '0.5.4'
+        VERSION = '0.6.1'
       end
     end
   end

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

@@ -29,10 +29,11 @@ module Legion
                 category_overrides: {}
               },
               token:          {
-                vault_path:       nil,
-                local_token_path: nil,
-                refresh_buffer:   60,
-                refresh_interval: 2700
+                vault_read_enabled:  false,
+                vault_write_enabled: false,
+                vault_path:          nil,
+                refresh_buffer:      60,
+                refresh_interval:    2700
               }
             }
           end

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

@@ -12,6 +12,8 @@ require_relative 'entra/version'
 require_relative 'entra/helpers/scopes'
 require_relative 'entra/helpers/scope_registry'
 require_relative 'entra/helpers/scope_gate'
+require_relative 'entra/helpers/interactive_auth_guard'
+require_relative 'entra/helpers/callback_page'
 require_relative 'entra/helpers/token_manager'
 require_relative 'entra/helpers/graph_client'
 require_relative 'entra/helpers/account_discovery'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-identity-entra
 version: !ruby/object:Gem::Version
-  version: 0.5.4
+  version: 0.6.1
 platform: ruby
 authors:
 - Esity
@@ -129,8 +129,10 @@ files:
 - lib/legion/extensions/identity/entra/delegated/scopes.rb
 - lib/legion/extensions/identity/entra/helpers/account_discovery.rb
 - lib/legion/extensions/identity/entra/helpers/browser_auth.rb
+- lib/legion/extensions/identity/entra/helpers/callback_page.rb
 - lib/legion/extensions/identity/entra/helpers/callback_server.rb
 - lib/legion/extensions/identity/entra/helpers/graph_client.rb
+- lib/legion/extensions/identity/entra/helpers/interactive_auth_guard.rb
 - lib/legion/extensions/identity/entra/helpers/scope_gate.rb
 - lib/legion/extensions/identity/entra/helpers/scope_registry.rb
 - lib/legion/extensions/identity/entra/helpers/scopes.rb