lex-microsoft_teams 0.5.2 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04b94ffb46a95a36eb66ec477890cdde5fe1c438cd1e4e6b93ecd1759a7d36d4
-  data.tar.gz: 22010f036440e7e63e03c55c432ef22e2ecee592adb7d124cc55bc7444201ec6
+  metadata.gz: 050cf6a6703c4b6ee4d636980ee7843a3bc34b27c533d0d1cab0325c9903ca02
+  data.tar.gz: ffb0ca49267fc2f64b1a27c10f25e45099e2d2450839b3ddf8984efe21572d6b
 SHA512:
-  metadata.gz: 1ab613f4985c7131d7c748802b6b2ae0239e88d8e1f73ae375912d2a5bdfe05755fdd9d0592bce9cccbba3a48796868a727df8ea109d308d08aa408703cf665e
-  data.tar.gz: ae176b71bf531f00831483b8a77c610165ceb65350f03bfbe2407eb587c7c348f06adb24d5c53179efd20441707095f80586f95429a6001482fd4652e5c8f811
+  metadata.gz: 9f93cdb1ff43c5ff3829f71de8aedca04086cf1a8efed385441a8d0920d39c7a429718e3de6035f734021921d3583ed2004648dc97bd47982cb75d6258baebc7
+  data.tar.gz: 50327854fc1dad382f923be114d6b2c413666070f2e8cffb14c35cd467d73519654bdc7bb372fb370ed743e834d438ea4ce25663b7826c0f56a0f6bdd1b6953f

data/.gitignore

@@ -10,6 +10,6 @@
 # rspec failure tracking
 .rspec_status
 
-# local credentials
+# local credentials and test scripts
 .env
-test_device_code.rb
+test_*.rb

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [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
+- `user_path` helper in `Helpers::Client` for Graph API `/me/` vs `/users/{id}/` flexibility
+- `user_id: 'me'` default on all meeting, transcript, presence, chat, and team runner methods
+- `user_id:` parameter on `Client` constructor for application-permission workflows
+
+### Fixed
+- RecordParser 3-byte varint decoding: added missing `& 0x7F` mask on third byte
+- MessageProcessor actor namespace: `Actors` to `Actor` for consistency with all other actors
+- `Client#authenticate!` nil guard preventing `NoMethodError` on failed token acquisition
+- CallbackServer error handling: separate `IOError` (shutdown) from unexpected errors
+- SubscriptionRegistry now calls `load` on initialization to restore persisted subscriptions
+- Device code polling: collapsed duplicate case branches for cleaner error handling
+
+### Removed
+- Dead `transport.rb` file (never required by any code path)
+- Dead `.tap` block in CacheSync `args` method
+- Dead `conversation_overrides` TODO stub in PromptResolver (simplified to nil return)
+
+### Changed
+- `strip_html` in CacheIngest moved from public to private
+- Token cache spec cleanup: atomic file operations, `Process.pid` over `$$`
+
 ## [0.5.2] - 2026-03-18
 
 ### Fixed

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.1
+**Version**: 0.5.2
 
 ## Architecture
 
@@ -197,7 +197,7 @@ Optional framework dependencies (guarded with `defined?`, not in gemspec):
 
 ```bash
 bundle install
-bundle exec rspec     # 185 specs (as of v0.5.1)
+bundle exec rspec     # 185 specs (as of v0.5.2)
 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 |