lex-microsoft_teams 0.5.3 → 0.5.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c23c0559f6761c3c19f3aea4a372e7bc4c07e0c271795cca4d8ac73a984cac4
-  data.tar.gz: affd2bdc5020080b320816044999b23403e463290cdabdbb625bc9bf831ffb8e
+  metadata.gz: 5dd2ecc48c7eda33072b23d32d9a08947b43d51aaeba49b6b4eb46fb410e8065
+  data.tar.gz: ec8b561ede2e96afe790aad56ecc02c3491117ea26e3bbd2e78a480d214a58d2
 SHA512:
-  metadata.gz: a2de35d93f2e6377c8eb1f078df5093c676c575fe1a65bc70ce454bd0ba94261821d771df585209d780624bb037f9a21c12a3bf729a2cff306b73628487994ab
-  data.tar.gz: 6e739d4ab5d13bd78230860dd62920e9921138c89062afa9f113158bf1a14764727981ec666b22bb62d2dd40ef911e9c85f4399f46a1398a27bf0d5f544dff77
+  metadata.gz: 786b4d6f2b4e3cce9fee5d61d96cb2c89f31080628d19c5e146976e9eaf3ecb6e4e8eaf76854493cfa37e6dba89721c0e6dca42e8dd657bbaac67ad84b195cf6
+  data.tar.gz: 82fc1cf2c2f31b81e7f640b5edc00be53cc976733bb7c33f3d3a68648991ad0a6979cfb2eb43f57584c48aeb7dd90542ac787e056fc44938216b7b7b9bbed41a

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## [0.5.5] - 2026-03-19
+
+### Added
+- `Hooks::Auth` hook class with `mount '/callback'` for OAuth redirect via expanded hooks system
+- `Runners::Auth#auth_callback` method handling OAuth callback with HTML response and event emission
+- OAuth callback now routes through `Ingress.run` for RBAC and audit support
+
+### Changed
+- OAuth callback URL moves from hardcoded `/api/oauth/microsoft_teams/callback` to `/api/hooks/lex/microsoft_teams/auth/callback`
+
+## [0.5.4] - 2026-03-19
+
+### Added
+- `TokenCache#authenticated?` predicate for runtime delegated token state
+- `TokenCache#previously_authenticated?` predicate for persistent auth history
+- `AuthValidator` actor (Once): validates and restores delegated tokens on boot
+- `TokenRefresher` actor (Every, 15min configurable): keeps delegated tokens fresh
+- Automatic browser re-auth when previously authenticated user's token expires
+- `refresh_interval` config key at `settings[:microsoft_teams][:auth][:delegated]`
+
 ## [0.5.3] - 2026-03-19
 
 ### Added

data/CLAUDE.md

@@ -10,7 +10,7 @@ Legion Extension that connects LegionIO to Microsoft Teams via Graph API and Bot
 
 **GitHub**: https://github.com/LegionIO/lex-microsoft_teams
 **License**: MIT
-**Version**: 0.5.2
+**Version**: 0.5.4
 
 ## Architecture
 
@@ -36,7 +36,9 @@ Legion::Extensions::MicrosoftTeams
 │   ├── CacheSync             # Every 5min: incremental ingest of new messages
 │   ├── DirectChatPoller      # Every 5s: polls bot DM chats via Graph API
 │   ├── ObservedChatPoller    # Every 30s: polls subscribed human conversations (compliance-gated)
-│   └── MessageProcessor      # Subscription: consumes AMQP queue, routes by mode
+│   ├── MessageProcessor      # Subscription: consumes AMQP queue, routes by mode
+│   ├── AuthValidator         # Once: validates/restores delegated tokens on boot (2s delay)
+│   └── TokenRefresher        # Every 15min (configurable): keeps delegated tokens fresh
 ├── Transport/
 │   ├── Exchanges/Messages    # teams.messages topic exchange
 │   ├── Queues/MessagesProcess # teams.messages.process durable queue
@@ -50,7 +52,7 @@ Legion::Extensions::MicrosoftTeams
 │   ├── HighWaterMark     # Per-chat message dedup via legion-cache (with in-memory fallback)
 │   ├── PromptResolver    # Layered system prompt resolution (settings -> mode -> per-conversation)
 │   ├── SessionManager    # Multi-turn LLM session lifecycle with lex-memory persistence
-│   ├── TokenCache        # In-memory OAuth token cache with pre-expiry refresh (app + delegated slots)
+│   ├── TokenCache        # In-memory OAuth token cache with pre-expiry refresh (app + delegated slots, authenticated?/previously_authenticated? predicates)
 │   ├── SubscriptionRegistry # Conversation observation subscriptions (in-memory + lex-memory)
 │   ├── BrowserAuth       # Delegated OAuth orchestrator (PKCE, headless detection, browser launch)
 │   └── CallbackServer    # Ephemeral TCP server for OAuth redirect callback
@@ -68,6 +70,18 @@ Tokens stored in Vault (`legionio/microsoft_teams/delegated_token`) with configu
 
 Key files: `Helpers::BrowserAuth` (orchestrator), `Helpers::CallbackServer` (ephemeral TCP), `Runners::Auth` (authorize_url, exchange_code, refresh_delegated_token), `Helpers::TokenCache` (delegated slot).
 
+## Token Lifecycle (v0.5.4)
+
+Automatic delegated token management: validate on boot, refresh on a timer, re-authenticate via browser when a previously authenticated user's token expires.
+
+- **AuthValidator** (Once actor, 2s delay): Loads token from Vault/local file on boot, attempts refresh. If refresh fails and user previously authenticated (`previously_authenticated?` — local file exists), fires BrowserAuth. Silent for users who never opted in.
+- **TokenRefresher** (Every actor, 15min default): Guards with `authenticated?` (live token in memory). Refreshes and persists on each tick. On failure, same re-auth logic as AuthValidator.
+- **TokenCache predicates**: `authenticated?` = live token in `@delegated_cache`. `previously_authenticated?` = local token file exists on disk. This distinction controls auto re-auth (returning users only) vs silence (never-authenticated users).
+
+Configuration: `settings[:microsoft_teams][:auth][:delegated][:refresh_interval]` (default 900 seconds).
+
+Design doc: `docs/plans/2026-03-19-teams-token-lifecycle-design.md`
+
 ## AI Bot (v0.2.0)
 
 Two operating modes, both using polling (Graph API) with AMQP-based message routing:
@@ -104,6 +118,8 @@ microsoft_teams:
     tenant_id: "..."
     client_id: "..."
     client_secret: "vault://secret/teams/client_secret"
+    delegated:
+      refresh_interval: 900    # seconds (TokenRefresher interval)
   bot:
     bot_id: "28:your-bot-id"
     direct_poll_interval: 5      # seconds
@@ -197,7 +213,7 @@ Optional framework dependencies (guarded with `defined?`, not in gemspec):
 
 ```bash
 bundle install
-bundle exec rspec     # 185 specs (as of v0.5.2)
+bundle exec rspec     # 209 specs (as of v0.5.4)
 bundle exec rubocop   # Clean
 ```
 

data/docs/plans/2026-03-19-teams-token-lifecycle-design.md

@@ -0,0 +1,120 @@
+# Teams Token Lifecycle Design
+
+## Summary
+
+Add automatic delegated token management to lex-microsoft_teams: validate on boot, refresh on a timer, and re-authenticate via browser when a previously authenticated user's token expires.
+
+## Problem
+
+Currently, delegated tokens require manual `legion auth teams` invocation. If a token expires between restarts (or the refresh token dies), nothing recovers it. Pollers silently fail because `cached_delegated_token` returns nil.
+
+## Approach
+
+Two new actors + TokenCache enhancements. Follows the existing actor conventions (CacheBulkIngest is Once, DirectChatPoller is Every).
+
+## Components
+
+### TokenCache Enhancements
+
+Two new public methods on `Helpers::TokenCache`:
+
+- `authenticated?` — returns true when `@delegated_cache` is non-nil (live token in memory)
+- `previously_authenticated?` — returns true when the local token file exists on disk (user opted in before)
+
+The distinction: `previously_authenticated?` means "user said yes before" (file exists). `authenticated?` means "we have a live token right now." This controls whether auto re-auth fires (only for returning users) vs staying silent (never-authenticated users).
+
+### AuthValidator Actor (Once)
+
+`Actor::AuthValidator < Legion::Extensions::Actors::Once`
+
+Runs once on boot with a 2-second delay. Sequence:
+
+1. Create TokenCache instance
+2. Call `token_cache.load_from_vault` (tries Vault, falls back to local file)
+3. If loaded: try `cached_delegated_token` (triggers internal refresh if expired)
+   - Refresh succeeds: log info "Teams delegated auth restored"
+   - Refresh fails + `previously_authenticated?`: log warning, fire BrowserAuth
+   - Refresh fails + not previously authenticated: silent (user never opted in)
+4. If nothing loaded: check `previously_authenticated?`
+   - True: log warning, fire BrowserAuth (file corrupt or unloadable)
+   - False: log debug "No Teams delegated auth configured" — silent
+
+Does NOT touch the app token (client_credentials). That is handled lazily by `cached_graph_token` in the pollers.
+
+### TokenRefresher Actor (Every)
+
+`Actor::TokenRefresher < Legion::Extensions::Actors::Every`
+
+Runs every 15 minutes (configurable). Each tick:
+
+1. Guard: `return unless token_cache.authenticated?`
+2. Call `cached_delegated_token` (internally refreshes if within 60s of expiry)
+3. If token returned: `save_to_vault` (persists to local file + optional Vault). Done.
+4. If nil (refresh failed):
+   - `previously_authenticated?` true: log warning, fire BrowserAuth
+   - Otherwise: do nothing (delegated_cache already nil)
+
+`run_now?` = false (AuthValidator handles the initial check).
+
+### BrowserAuth Trigger
+
+Both actors use the same private `attempt_browser_reauth` method:
+
+1. Read tenant_id, client_id, scopes from settings
+2. Log warning: "Delegated token expired, opening browser for re-authentication..."
+3. Create `BrowserAuth.new(...)` and call `authenticate`
+4. On success: `store_delegated_token` + `save_to_vault`
+5. On failure: log error, return false
+
+BrowserAuth already detects headless environments (no DISPLAY/WAYLAND) and falls back to device code flow. No special handling needed.
+
+Both actors define this method privately. No shared module — it is ~20 lines, used in two places, and a premature abstraction would add complexity for no gain.
+
+### Shared TokenCache Instance
+
+AuthValidator and TokenRefresher each create their own TokenCache instance. This is fine because the local file is the source of truth. AuthValidator loads on boot, TokenRefresher refreshes and saves back to the file on each tick.
+
+## Configuration
+
+Settings path: `Legion::Settings[:microsoft_teams][:auth][:delegated]`
+
+New key:
+
+| Key | Type | Default | Purpose |
+|-----|------|---------|---------|
+| `refresh_interval` | Integer (seconds) | 900 | TokenRefresher polling interval |
+
+Existing keys unchanged: `refresh_buffer`, `scopes`, `vault_path`, `local_token_path`.
+
+## Testing
+
+### TokenCache Specs
+- `authenticated?` returns false with no cache, true after store
+- `previously_authenticated?` returns false with no file, true after save_to_local
+
+### AuthValidator Specs
+- Loads token and refreshes successfully (log info)
+- Loads token, refresh fails, previously authed -> triggers browser reauth
+- Loads token, refresh fails, never authed -> silent
+- No token file exists -> silent
+
+### TokenRefresher Specs
+- Skips when not authenticated
+- Refreshes successfully and saves
+- Refresh fails, previously authed -> triggers browser reauth
+
+### Actor Patterns
+- Stub base classes with `$LOADED_FEATURES` injection + `described_class.allocate`
+- Stub TokenCache and BrowserAuth (no real network calls)
+
+## Files Changed
+
+| File | Change |
+|------|--------|
+| `helpers/token_cache.rb` | Add `authenticated?`, `previously_authenticated?` |
+| `actors/auth_validator.rb` | New file |
+| `actors/token_refresher.rb` | New file |
+| `spec/.../helpers/token_cache_spec.rb` | Add 4 specs |
+| `spec/.../actors/auth_validator_spec.rb` | New file |
+| `spec/.../actors/token_refresher_spec.rb` | New file |
+| `microsoft_teams.rb` | Require new actor files |

data/docs/plans/2026-03-19-teams-token-lifecycle-implementation.md

@@ -0,0 +1,679 @@
+# Teams Token Lifecycle Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add automatic delegated token validation on boot, periodic refresh, and browser re-auth for previously authenticated users.
+
+**Architecture:** Two new actors (AuthValidator/Once, TokenRefresher/Every) plus two new methods on TokenCache. AuthValidator loads tokens on startup and recovers expired sessions. TokenRefresher keeps tokens fresh on a configurable 15-minute interval. Both trigger BrowserAuth for re-auth when a previously authenticated user's token cannot be refreshed.
+
+**Tech Stack:** Ruby, RSpec, lex-microsoft_teams actor/helper conventions
+
+---
+
+### Task 1: Add `authenticated?` and `previously_authenticated?` to TokenCache
+
+**Files:**
+- Modify: `lib/legion/extensions/microsoft_teams/helpers/token_cache.rb:38-63`
+- Test: `spec/legion/extensions/microsoft_teams/helpers/token_cache_spec.rb`
+
+**Step 1: Write the failing tests**
+
+Add to the end of `token_cache_spec.rb`, before the final `end`:
+
+```ruby
+describe '#authenticated?' do
+  it 'returns false when no delegated token is cached' do
+    expect(cache.authenticated?).to be false
+  end
+
+  it 'returns true when a delegated token is stored' do
+    cache.store_delegated_token(
+      access_token: 'tok', refresh_token: 'ref',
+      expires_in: 3600, scopes: 'scope1'
+    )
+    expect(cache.authenticated?).to be true
+  end
+
+  it 'returns false after clearing delegated token' do
+    cache.store_delegated_token(
+      access_token: 'tok', refresh_token: 'ref',
+      expires_in: 3600, scopes: 'scope1'
+    )
+    cache.clear_delegated_token!
+    expect(cache.authenticated?).to be false
+  end
+end
+
+describe '#previously_authenticated?' do
+  it 'returns false when no local file exists' do
+    expect(cache.previously_authenticated?).to be false
+  end
+
+  it 'returns true after save_to_local' do
+    cache.store_delegated_token(
+      access_token: 'tok', refresh_token: 'ref',
+      expires_in: 3600, scopes: 'scope1'
+    )
+    cache.save_to_local
+    expect(cache.previously_authenticated?).to be true
+  end
+end
+```
+
+**Step 2: Run tests to verify they fail**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rspec spec/legion/extensions/microsoft_teams/helpers/token_cache_spec.rb -v`
+Expected: FAIL — `NoMethodError: undefined method 'authenticated?'`
+
+**Step 3: Write minimal implementation**
+
+Add these two methods to `token_cache.rb` after `clear_delegated_token!` (around line 63), before the `load_from_vault` method:
+
+```ruby
+def authenticated?
+  @mutex.synchronize { !@delegated_cache.nil? }
+end
+
+def previously_authenticated?
+  File.exist?(local_token_path)
+end
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rspec spec/legion/extensions/microsoft_teams/helpers/token_cache_spec.rb -v`
+Expected: All pass (including existing specs)
+
+**Step 5: Run rubocop**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rubocop lib/legion/extensions/microsoft_teams/helpers/token_cache.rb`
+Expected: No offenses
+
+**Step 6: Commit**
+
+```bash
+cd extensions/lex-microsoft_teams
+git add lib/legion/extensions/microsoft_teams/helpers/token_cache.rb spec/legion/extensions/microsoft_teams/helpers/token_cache_spec.rb
+git commit -m "add authenticated? and previously_authenticated? to TokenCache"
+```
+
+---
+
+### Task 2: Create AuthValidator actor
+
+**Files:**
+- Create: `lib/legion/extensions/microsoft_teams/actors/auth_validator.rb`
+- Test: `spec/legion/extensions/microsoft_teams/actors/auth_validator_spec.rb`
+
+**Step 1: Write the spec file**
+
+Create `spec/legion/extensions/microsoft_teams/actors/auth_validator_spec.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+unless defined?(Legion::Extensions::Actors::Once)
+  module Legion
+    module Extensions
+      module Actors
+        class Once; end # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/once' unless $LOADED_FEATURES.include?('legion/extensions/actors/once')
+
+require 'legion/extensions/microsoft_teams/actors/auth_validator'
+
+RSpec.describe Legion::Extensions::MicrosoftTeams::Actor::AuthValidator do
+  subject(:actor) { described_class.allocate }
+
+  let(:token_cache) { instance_double(Legion::Extensions::MicrosoftTeams::Helpers::TokenCache) }
+  let(:browser_auth) { instance_double(Legion::Extensions::MicrosoftTeams::Helpers::BrowserAuth) }
+
+  before do
+    allow(actor).to receive(:token_cache).and_return(token_cache)
+  end
+
+  it 'has a 2 second delay' do
+    expect(actor.delay).to eq(2.0)
+  end
+
+  it 'does not generate tasks' do
+    expect(actor.generate_task?).to be false
+  end
+
+  it 'does not check subtasks' do
+    expect(actor.check_subtask?).to be false
+  end
+
+  describe '#manual' do
+    before do
+      allow(token_cache).to receive(:previously_authenticated?).and_return(false)
+    end
+
+    context 'when token loads and refreshes successfully' do
+      before do
+        allow(token_cache).to receive(:load_from_vault).and_return(true)
+        allow(token_cache).to receive(:cached_delegated_token).and_return('valid-token')
+      end
+
+      it 'logs success and does not trigger browser auth' do
+        expect(actor).not_to receive(:attempt_browser_reauth)
+        actor.manual
+      end
+    end
+
+    context 'when token loads but refresh fails and previously authenticated' do
+      before do
+        allow(token_cache).to receive(:load_from_vault).and_return(true)
+        allow(token_cache).to receive(:cached_delegated_token).and_return(nil)
+        allow(token_cache).to receive(:previously_authenticated?).and_return(true)
+        allow(actor).to receive(:attempt_browser_reauth).and_return(true)
+      end
+
+      it 'triggers browser re-auth' do
+        actor.manual
+        expect(actor).to have_received(:attempt_browser_reauth)
+      end
+    end
+
+    context 'when token loads but refresh fails and never authenticated' do
+      before do
+        allow(token_cache).to receive(:load_from_vault).and_return(true)
+        allow(token_cache).to receive(:cached_delegated_token).and_return(nil)
+        allow(token_cache).to receive(:previously_authenticated?).and_return(false)
+      end
+
+      it 'does not trigger browser re-auth' do
+        expect(actor).not_to receive(:attempt_browser_reauth)
+        actor.manual
+      end
+    end
+
+    context 'when no token file exists' do
+      before do
+        allow(token_cache).to receive(:load_from_vault).and_return(false)
+        allow(token_cache).to receive(:previously_authenticated?).and_return(false)
+      end
+
+      it 'does nothing silently' do
+        expect(actor).not_to receive(:attempt_browser_reauth)
+        actor.manual
+      end
+    end
+
+    context 'when no token loads but previously authenticated' do
+      before do
+        allow(token_cache).to receive(:load_from_vault).and_return(false)
+        allow(token_cache).to receive(:previously_authenticated?).and_return(true)
+        allow(actor).to receive(:attempt_browser_reauth).and_return(true)
+      end
+
+      it 'triggers browser re-auth' do
+        actor.manual
+        expect(actor).to have_received(:attempt_browser_reauth)
+      end
+    end
+  end
+end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rspec spec/legion/extensions/microsoft_teams/actors/auth_validator_spec.rb -v`
+Expected: FAIL — `LoadError: cannot load such file -- legion/extensions/microsoft_teams/actors/auth_validator`
+
+**Step 3: Write the actor**
+
+Create `lib/legion/extensions/microsoft_teams/actors/auth_validator.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MicrosoftTeams
+      module Actor
+        class AuthValidator < Legion::Extensions::Actors::Once
+          def use_runner?     = false
+          def check_subtask?  = false
+          def generate_task?  = false
+
+          def delay
+            2.0
+          end
+
+          def enabled?
+            defined?(Legion::Extensions::MicrosoftTeams::Helpers::TokenCache)
+          rescue StandardError
+            false
+          end
+
+          def token_cache
+            @token_cache ||= Legion::Extensions::MicrosoftTeams::Helpers::TokenCache.new
+          end
+
+          def manual
+            loaded = token_cache.load_from_vault
+
+            if loaded
+              token = token_cache.cached_delegated_token
+              if token
+                log_info('Teams delegated auth restored')
+              elsif token_cache.previously_authenticated?
+                attempt_browser_reauth(token_cache)
+              end
+            elsif token_cache.previously_authenticated?
+              log_warn('Token file found but could not load, attempting re-authentication')
+              attempt_browser_reauth(token_cache)
+            else
+              log_debug('No Teams delegated auth configured, skipping')
+            end
+          rescue StandardError => e
+            log_error("AuthValidator: #{e.message}")
+          end
+
+          private
+
+          def attempt_browser_reauth(tc)
+            settings = teams_auth_settings
+            return false unless settings[:tenant_id] && settings[:client_id]
+
+            log_warn('Delegated token expired, opening browser for re-authentication...')
+
+            scopes = settings.dig(:delegated, :scopes) ||
+                     Legion::Extensions::MicrosoftTeams::Helpers::BrowserAuth::DEFAULT_SCOPES
+            browser_auth = Legion::Extensions::MicrosoftTeams::Helpers::BrowserAuth.new(
+              tenant_id: settings[:tenant_id],
+              client_id: settings[:client_id],
+              scopes:    scopes
+            )
+
+            result = browser_auth.authenticate
+            return false if result[:error]
+
+            body = result[:result]
+            tc.store_delegated_token(
+              access_token:  body['access_token'],
+              refresh_token: body['refresh_token'],
+              expires_in:    body['expires_in'],
+              scopes:        scopes
+            )
+            tc.save_to_vault
+            log_info('Teams delegated auth restored via browser')
+            true
+          rescue StandardError => e
+            log_error("Browser re-auth failed: #{e.message}")
+            false
+          end
+
+          def teams_auth_settings
+            return {} unless defined?(Legion::Settings)
+
+            Legion::Settings.dig(:microsoft_teams, :auth) || {}
+          end
+
+          def log_info(msg)
+            Legion::Logging.info(msg) if defined?(Legion::Logging)
+          end
+
+          def log_warn(msg)
+            Legion::Logging.warn(msg) if defined?(Legion::Logging)
+          end
+
+          def log_debug(msg)
+            Legion::Logging.debug(msg) if defined?(Legion::Logging)
+          end
+
+          def log_error(msg)
+            Legion::Logging.error(msg) if defined?(Legion::Logging)
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rspec spec/legion/extensions/microsoft_teams/actors/auth_validator_spec.rb -v`
+Expected: All pass
+
+**Step 5: Run rubocop**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rubocop lib/legion/extensions/microsoft_teams/actors/auth_validator.rb`
+Expected: No offenses
+
+**Step 6: Commit**
+
+```bash
+cd extensions/lex-microsoft_teams
+git add lib/legion/extensions/microsoft_teams/actors/auth_validator.rb spec/legion/extensions/microsoft_teams/actors/auth_validator_spec.rb
+git commit -m "add AuthValidator actor for boot-time token validation"
+```
+
+---
+
+### Task 3: Create TokenRefresher actor
+
+**Files:**
+- Create: `lib/legion/extensions/microsoft_teams/actors/token_refresher.rb`
+- Test: `spec/legion/extensions/microsoft_teams/actors/token_refresher_spec.rb`
+
+**Step 1: Write the spec file**
+
+Create `spec/legion/extensions/microsoft_teams/actors/token_refresher_spec.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+unless defined?(Legion::Extensions::Actors::Every)
+  module Legion
+    module Extensions
+      module Actors
+        class Every; end # rubocop:disable Lint/EmptyClass
+      end
+    end
+  end
+end
+
+$LOADED_FEATURES << 'legion/extensions/actors/every' unless $LOADED_FEATURES.include?('legion/extensions/actors/every')
+
+require 'legion/extensions/microsoft_teams/actors/token_refresher'
+
+RSpec.describe Legion::Extensions::MicrosoftTeams::Actor::TokenRefresher do
+  subject(:actor) { described_class.allocate }
+
+  let(:token_cache) { instance_double(Legion::Extensions::MicrosoftTeams::Helpers::TokenCache) }
+
+  before do
+    allow(actor).to receive(:token_cache).and_return(token_cache)
+  end
+
+  it 'has a default 900 second interval' do
+    expect(actor.time).to eq(900)
+  end
+
+  it 'does not run immediately on start' do
+    expect(actor.run_now?).to be false
+  end
+
+  it 'does not generate tasks' do
+    expect(actor.generate_task?).to be false
+  end
+
+  it 'does not check subtasks' do
+    expect(actor.check_subtask?).to be false
+  end
+
+  describe '#manual' do
+    context 'when not authenticated' do
+      before do
+        allow(token_cache).to receive(:authenticated?).and_return(false)
+      end
+
+      it 'skips refresh entirely' do
+        expect(token_cache).not_to receive(:cached_delegated_token)
+        actor.manual
+      end
+    end
+
+    context 'when authenticated and refresh succeeds' do
+      before do
+        allow(token_cache).to receive(:authenticated?).and_return(true)
+        allow(token_cache).to receive(:cached_delegated_token).and_return('refreshed-token')
+        allow(token_cache).to receive(:save_to_vault)
+      end
+
+      it 'saves the refreshed token' do
+        actor.manual
+        expect(token_cache).to have_received(:save_to_vault)
+      end
+    end
+
+    context 'when authenticated but refresh fails and previously authenticated' do
+      before do
+        allow(token_cache).to receive(:authenticated?).and_return(true)
+        allow(token_cache).to receive(:cached_delegated_token).and_return(nil)
+        allow(token_cache).to receive(:previously_authenticated?).and_return(true)
+        allow(actor).to receive(:attempt_browser_reauth).and_return(true)
+      end
+
+      it 'triggers browser re-auth' do
+        actor.manual
+        expect(actor).to have_received(:attempt_browser_reauth)
+      end
+    end
+
+    context 'when authenticated but refresh fails and never previously authenticated' do
+      before do
+        allow(token_cache).to receive(:authenticated?).and_return(true)
+        allow(token_cache).to receive(:cached_delegated_token).and_return(nil)
+        allow(token_cache).to receive(:previously_authenticated?).and_return(false)
+      end
+
+      it 'does not trigger browser re-auth' do
+        expect(actor).not_to receive(:attempt_browser_reauth)
+        actor.manual
+      end
+    end
+  end
+end
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rspec spec/legion/extensions/microsoft_teams/actors/token_refresher_spec.rb -v`
+Expected: FAIL — `LoadError: cannot load such file`
+
+**Step 3: Write the actor**
+
+Create `lib/legion/extensions/microsoft_teams/actors/token_refresher.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MicrosoftTeams
+      module Actor
+        class TokenRefresher < Legion::Extensions::Actors::Every
+          DEFAULT_REFRESH_INTERVAL = 900 # 15 minutes
+
+          def runner_class    = Legion::Extensions::MicrosoftTeams::Helpers::TokenCache
+          def runner_function = 'cached_delegated_token'
+          def run_now?        = false
+          def use_runner?     = false
+          def check_subtask?  = false
+          def generate_task?  = false
+
+          def time
+            settings = teams_auth_settings
+            delegated = settings[:delegated]
+            return DEFAULT_REFRESH_INTERVAL unless delegated.is_a?(Hash)
+
+            delegated[:refresh_interval] || DEFAULT_REFRESH_INTERVAL
+          end
+
+          def enabled?
+            defined?(Legion::Extensions::MicrosoftTeams::Helpers::TokenCache)
+          rescue StandardError
+            false
+          end
+
+          def token_cache
+            @token_cache ||= Legion::Extensions::MicrosoftTeams::Helpers::TokenCache.new
+          end
+
+          def manual
+            return unless token_cache.authenticated?
+
+            token = token_cache.cached_delegated_token
+            if token
+              token_cache.save_to_vault
+            elsif token_cache.previously_authenticated?
+              attempt_browser_reauth(token_cache)
+            end
+          rescue StandardError => e
+            log_error("TokenRefresher: #{e.message}")
+          end
+
+          private
+
+          def attempt_browser_reauth(tc)
+            settings = teams_auth_settings
+            return false unless settings[:tenant_id] && settings[:client_id]
+
+            log_warn('Delegated token expired, opening browser for re-authentication...')
+
+            scopes = settings.dig(:delegated, :scopes) ||
+                     Legion::Extensions::MicrosoftTeams::Helpers::BrowserAuth::DEFAULT_SCOPES
+            browser_auth = Legion::Extensions::MicrosoftTeams::Helpers::BrowserAuth.new(
+              tenant_id: settings[:tenant_id],
+              client_id: settings[:client_id],
+              scopes:    scopes
+            )
+
+            result = browser_auth.authenticate
+            return false if result[:error]
+
+            body = result[:result]
+            tc.store_delegated_token(
+              access_token:  body['access_token'],
+              refresh_token: body['refresh_token'],
+              expires_in:    body['expires_in'],
+              scopes:        scopes
+            )
+            tc.save_to_vault
+            log_info('Teams delegated auth restored via browser')
+            true
+          rescue StandardError => e
+            log_error("Browser re-auth failed: #{e.message}")
+            false
+          end
+
+          def teams_auth_settings
+            return {} unless defined?(Legion::Settings)
+
+            Legion::Settings.dig(:microsoft_teams, :auth) || {}
+          end
+
+          def log_info(msg)
+            Legion::Logging.info(msg) if defined?(Legion::Logging)
+          end
+
+          def log_warn(msg)
+            Legion::Logging.warn(msg) if defined?(Legion::Logging)
+          end
+
+          def log_error(msg)
+            Legion::Logging.error(msg) if defined?(Legion::Logging)
+          end
+        end
+      end
+    end
+  end
+end
+```
+
+**Step 4: Run tests to verify they pass**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rspec spec/legion/extensions/microsoft_teams/actors/token_refresher_spec.rb -v`
+Expected: All pass
+
+**Step 5: Run rubocop**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rubocop lib/legion/extensions/microsoft_teams/actors/token_refresher.rb`
+Expected: No offenses
+
+**Step 6: Commit**
+
+```bash
+cd extensions/lex-microsoft_teams
+git add lib/legion/extensions/microsoft_teams/actors/token_refresher.rb spec/legion/extensions/microsoft_teams/actors/token_refresher_spec.rb
+git commit -m "add TokenRefresher actor for periodic delegated token refresh"
+```
+
+---
+
+### Task 4: Wire actors into entry point and run full suite
+
+**Files:**
+- Modify: `lib/legion/extensions/microsoft_teams.rb`
+
+**Step 1: Add requires to the entry point**
+
+In `lib/legion/extensions/microsoft_teams.rb`, the actor files are auto-discovered by the framework (loaded via `Legion::Extensions::Core`). However, to ensure they are available, verify the actors directory is loaded. No explicit require needed — actors are discovered by convention. But if other actors in this extension are explicitly required elsewhere, check that pattern.
+
+Actually, reviewing the codebase: actors are NOT explicitly required in the entry point. They are auto-discovered by the framework via the `Actor` module namespace. The existing actors (CacheBulkIngest, CacheSync, DirectChatPoller, ObservedChatPoller, MessageProcessor) are all loaded this way. No change to `microsoft_teams.rb` is needed.
+
+**Step 2: Run full spec suite**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rspec -v`
+Expected: All specs pass (should be ~200+ now)
+
+**Step 3: Run rubocop on entire repo**
+
+Run: `cd extensions/lex-microsoft_teams && bundle exec rubocop`
+Expected: No offenses
+
+**Step 4: Verify spec count increased**
+
+Expected: 188 (previous) + 5 (TokenCache) + 9 (AuthValidator) + 8 (TokenRefresher) = ~210 specs
+
+**Step 5: Commit integration verification**
+
+No files changed in this step — this is verification only.
+
+---
+
+### Task 5: Bump version and update changelog
+
+**Files:**
+- Modify: `lib/legion/extensions/microsoft_teams/version.rb`
+- Modify: `CHANGELOG.md`
+
+**Step 1: Bump version**
+
+Change version from `0.5.3` to `0.5.4` in `version.rb`.
+
+**Step 2: Update changelog**
+
+Add entry at top of CHANGELOG.md:
+
+```markdown
+## [0.5.4] - 2026-03-19
+
+### Added
+- `TokenCache#authenticated?` predicate for runtime delegated token state
+- `TokenCache#previously_authenticated?` predicate for persistent auth history
+- `AuthValidator` actor (Once): validates and restores delegated tokens on boot
+- `TokenRefresher` actor (Every, 15min configurable): keeps delegated tokens fresh
+- Automatic browser re-auth when previously authenticated user's token expires
+- `refresh_interval` config key at `settings[:microsoft_teams][:auth][:delegated]`
+```
+
+**Step 3: Commit**
+
+```bash
+cd extensions/lex-microsoft_teams
+git add lib/legion/extensions/microsoft_teams/version.rb CHANGELOG.md
+git commit -m "bump version to 0.5.4, update changelog"
+```
+
+---
+
+### Task 6: Push
+
+**Step 1: Push to remote**
+
+```bash
+cd extensions/lex-microsoft_teams && git push
+```

data/lib/legion/extensions/microsoft_teams/actors/auth_validator.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MicrosoftTeams
+      module Actor
+        class AuthValidator < Legion::Extensions::Actors::Once
+          def use_runner?     = false
+          def check_subtask?  = false
+          def generate_task?  = false
+
+          def delay
+            2.0
+          end
+
+          def enabled?
+            defined?(Legion::Extensions::MicrosoftTeams::Helpers::TokenCache)
+          rescue StandardError
+            false
+          end
+
+          def token_cache
+            @token_cache ||= Legion::Extensions::MicrosoftTeams::Helpers::TokenCache.new
+          end
+
+          def manual
+            loaded = token_cache.load_from_vault
+
+            if loaded
+              token = token_cache.cached_delegated_token
+              if token
+                log_info('Teams delegated auth restored')
+              elsif token_cache.previously_authenticated?
+                attempt_browser_reauth(token_cache)
+              end
+            elsif token_cache.previously_authenticated?
+              log_warn('Token file found but could not load, attempting re-authentication')
+              attempt_browser_reauth(token_cache)
+            else
+              log_debug('No Teams delegated auth configured, skipping')
+            end
+          rescue StandardError => e
+            log_error("AuthValidator: #{e.message}")
+          end
+
+          private
+
+          def attempt_browser_reauth(cache)
+            settings = teams_auth_settings
+            return false unless settings[:tenant_id] && settings[:client_id]
+
+            log_warn('Delegated token expired, opening browser for re-authentication...')
+
+            scopes = settings.dig(:delegated, :scopes) ||
+                     Legion::Extensions::MicrosoftTeams::Helpers::BrowserAuth::DEFAULT_SCOPES
+            browser_auth = Legion::Extensions::MicrosoftTeams::Helpers::BrowserAuth.new(
+              tenant_id: settings[:tenant_id],
+              client_id: settings[:client_id],
+              scopes:    scopes
+            )
+
+            result = browser_auth.authenticate
+            return false if result[:error]
+
+            body = result[:result]
+            cache.store_delegated_token(
+              access_token:  body['access_token'],
+              refresh_token: body['refresh_token'],
+              expires_in:    body['expires_in'],
+              scopes:        scopes
+            )
+            cache.save_to_vault
+            log_info('Teams delegated auth restored via browser')
+            true
+          rescue StandardError => e
+            log_error("Browser re-auth failed: #{e.message}")
+            false
+          end
+
+          def teams_auth_settings
+            return {} unless defined?(Legion::Settings)
+
+            Legion::Settings.dig(:microsoft_teams, :auth) || {}
+          end
+
+          def log_info(msg)
+            Legion::Logging.info(msg) if defined?(Legion::Logging)
+          end
+
+          def log_warn(msg)
+            Legion::Logging.warn(msg) if defined?(Legion::Logging)
+          end
+
+          def log_debug(msg)
+            Legion::Logging.debug(msg) if defined?(Legion::Logging)
+          end
+
+          def log_error(msg)
+            Legion::Logging.error(msg) if defined?(Legion::Logging)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/microsoft_teams/actors/token_refresher.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MicrosoftTeams
+      module Actor
+        class TokenRefresher < Legion::Extensions::Actors::Every
+          DEFAULT_REFRESH_INTERVAL = 900
+
+          def runner_class    = Legion::Extensions::MicrosoftTeams::Helpers::TokenCache
+          def runner_function = 'cached_delegated_token'
+          def run_now?        = false
+          def use_runner?     = false
+          def check_subtask?  = false
+          def generate_task?  = false
+
+          def time
+            settings = teams_auth_settings
+            delegated = settings[:delegated]
+            return DEFAULT_REFRESH_INTERVAL unless delegated.is_a?(Hash)
+
+            delegated[:refresh_interval] || DEFAULT_REFRESH_INTERVAL
+          end
+
+          def enabled?
+            defined?(Legion::Extensions::MicrosoftTeams::Helpers::TokenCache)
+          rescue StandardError
+            false
+          end
+
+          def token_cache
+            @token_cache ||= Legion::Extensions::MicrosoftTeams::Helpers::TokenCache.new
+          end
+
+          def manual
+            return unless token_cache.authenticated?
+
+            token = token_cache.cached_delegated_token
+            if token
+              token_cache.save_to_vault
+            elsif token_cache.previously_authenticated?
+              attempt_browser_reauth(token_cache)
+            end
+          rescue StandardError => e
+            log_error("TokenRefresher: #{e.message}")
+          end
+
+          private
+
+          def attempt_browser_reauth(cache)
+            settings = teams_auth_settings
+            return false unless settings[:tenant_id] && settings[:client_id]
+
+            log_warn('Delegated token expired, opening browser for re-authentication...')
+
+            scopes = settings.dig(:delegated, :scopes) ||
+                     Legion::Extensions::MicrosoftTeams::Helpers::BrowserAuth::DEFAULT_SCOPES
+            browser_auth = Legion::Extensions::MicrosoftTeams::Helpers::BrowserAuth.new(
+              tenant_id: settings[:tenant_id],
+              client_id: settings[:client_id],
+              scopes:    scopes
+            )
+
+            result = browser_auth.authenticate
+            return false if result[:error]
+
+            body = result[:result]
+            cache.store_delegated_token(
+              access_token:  body['access_token'],
+              refresh_token: body['refresh_token'],
+              expires_in:    body['expires_in'],
+              scopes:        scopes
+            )
+            cache.save_to_vault
+            log_info('Teams delegated auth restored via browser')
+            true
+          rescue StandardError => e
+            log_error("Browser re-auth failed: #{e.message}")
+            false
+          end
+
+          def teams_auth_settings
+            return {} unless defined?(Legion::Settings)
+
+            Legion::Settings.dig(:microsoft_teams, :auth) || {}
+          end
+
+          def log_info(msg)
+            Legion::Logging.info(msg) if defined?(Legion::Logging)
+          end
+
+          def log_warn(msg)
+            Legion::Logging.warn(msg) if defined?(Legion::Logging)
+          end
+
+          def log_error(msg)
+            Legion::Logging.error(msg) if defined?(Legion::Logging)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -62,6 +62,14 @@ module Legion
             @mutex.synchronize { @delegated_cache = nil }
           end
 
+          def authenticated?
+            @mutex.synchronize { !@delegated_cache.nil? }
+          end
+
+          def previously_authenticated?
+            File.exist?(local_token_path)
+          end
+
           def load_from_vault
             return load_from_local unless defined?(Legion::Crypt)
 

data/lib/legion/extensions/microsoft_teams/hooks/auth.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module MicrosoftTeams
+      module Hooks
+        class Auth < Legion::Extensions::Hooks::Base
+          mount '/callback'
+
+          def route(_headers, _payload)
+            :auth_callback
+          end
+
+          def runner_class
+            'Legion::Extensions::MicrosoftTeams::Runners::Auth'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/microsoft_teams/runners/auth.rb

@@ -107,6 +107,35 @@ module Legion
             { result: response.body }
           end
 
+          def auth_callback(code: nil, state: nil, **)
+            unless code && state
+              return {
+                result:   { error: 'missing_params' },
+                response: { status: 400, content_type: 'text/html',
+                            body: '<html><body><h2>Missing code or state parameter</h2></body></html>' }
+              }
+            end
+
+            Legion::Events.emit('microsoft_teams.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 }
+            }
+          end
+
+          private
+
+          def callback_success_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
+          end
+
           include Legion::Extensions::Helpers::Lex if Legion::Extensions.const_defined?(:Helpers) &&
                                                       Legion::Extensions::Helpers.const_defined?(:Lex)
         end

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

@@ -3,7 +3,7 @@
 module Legion
   module Extensions
     module MicrosoftTeams
-      VERSION = '0.5.3'
+      VERSION = '0.5.5'
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lex-microsoft_teams
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.5
 platform: ruby
 authors:
 - Esity
@@ -71,13 +71,17 @@ files:
 - docs/plans/2026-03-15-meetings-transcripts-design.md
 - docs/plans/2026-03-16-delegated-oauth-browser-flow-design.md
 - docs/plans/2026-03-16-delegated-oauth-browser-flow-plan.md
+- docs/plans/2026-03-19-teams-token-lifecycle-design.md
+- docs/plans/2026-03-19-teams-token-lifecycle-implementation.md
 - lex-microsoft_teams.gemspec
 - lib/legion/extensions/microsoft_teams.rb
+- lib/legion/extensions/microsoft_teams/actors/auth_validator.rb
 - lib/legion/extensions/microsoft_teams/actors/cache_bulk_ingest.rb
 - lib/legion/extensions/microsoft_teams/actors/cache_sync.rb
 - lib/legion/extensions/microsoft_teams/actors/direct_chat_poller.rb
 - lib/legion/extensions/microsoft_teams/actors/message_processor.rb
 - lib/legion/extensions/microsoft_teams/actors/observed_chat_poller.rb
+- lib/legion/extensions/microsoft_teams/actors/token_refresher.rb
 - lib/legion/extensions/microsoft_teams/client.rb
 - lib/legion/extensions/microsoft_teams/helpers/browser_auth.rb
 - lib/legion/extensions/microsoft_teams/helpers/callback_server.rb
@@ -87,6 +91,7 @@ files:
 - lib/legion/extensions/microsoft_teams/helpers/session_manager.rb
 - lib/legion/extensions/microsoft_teams/helpers/subscription_registry.rb
 - lib/legion/extensions/microsoft_teams/helpers/token_cache.rb
+- lib/legion/extensions/microsoft_teams/hooks/auth.rb
 - lib/legion/extensions/microsoft_teams/local_cache/extractor.rb
 - lib/legion/extensions/microsoft_teams/local_cache/record_parser.rb
 - lib/legion/extensions/microsoft_teams/local_cache/sstable_reader.rb