lex-identity-entra 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea7d2caf79ed2c6025cbad1ee6daae0a5f5250aada92cf26f42c71bf8e849680
-  data.tar.gz: 3f7afe033551273e7ebe6345c40e24f824529b0f4df79a1f3e7677002dcb006c
+  metadata.gz: e7076abeb6fcf3e837854a909a38bbe46ab78ff6dd8372fb0df53d507484170e
+  data.tar.gz: 6d9347e6aedc921ee6c16fc8a2004d0eb986e15eb8faf150a3a26787363e0d04
 SHA512:
-  metadata.gz: 55af5175673b2d9371c0e1d8b8ff03479299e7425b8f6f79b88b941e2b31bcb44069f026bcae90d898a87a7a6511b69a2c0618279ed73b1ac6631369d9733db2
-  data.tar.gz: fc672dfff7aa30a9325b7046752f5cdefe737f39b5e8bb69066657c0873d2f8ae600bf758a2ad42fcc382cb5a47467090e074931581486124e89eb52b66dd53b
+  metadata.gz: 6245ce699161036398ccfb11d141587f0188ebabe38944862fe693fcf7f6210c935cf4a493119de46d1b0b42691aa69a5f6459c2f0e11dc2d39b81bde8dad706
+  data.tar.gz: 0b2a7fae7d074dc4fe580f7289c79105ca6761227b6bbbd7045844d4e75b0fb0be90a4c46f92af04fd2ff4a112fa86a3dd12440f1cb6b805d2174cd52b809999

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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).

data/README.md

@@ -33,8 +33,14 @@ 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
@@ -63,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

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
 

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

@@ -45,16 +45,27 @@ 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_memory(:delegated)
@@ -68,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,
@@ -87,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

@@ -42,9 +42,15 @@ module Legion
                 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/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

@@ -3,6 +3,7 @@
 require 'concurrent'
 require 'digest'
 require 'time'
+require 'legion/extensions/identity/entra/helpers/interactive_auth_guard'
 
 module Legion
   module Extensions
@@ -17,11 +18,24 @@ module Legion
 
             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)
@@ -53,6 +67,8 @@ 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)
               save_to_vault(qualifier, access_token: access_token, refresh_token: refresh_token,
@@ -162,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,
@@ -188,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)
 

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

@@ -4,7 +4,7 @@ module Legion
   module Extensions
     module Identity
       module Entra
-        VERSION = '0.6.0'
+        VERSION = '0.6.1'
       end
     end
   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.6.0
+  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