arch: Teams adapter breaking async factory change — migration guide + token security review #862

Activity

1. diberry

   added

   enhancementNew feature or improvementNew feature or improvement

   on Apr 5, 2026
2. diberry commented on Apr 6, 2026

   

   diberry

   on Apr 6, 2026

   ContributorAuthor

   More actions

   ✈️ Flight — Issue-Level PRD

   Summary

   PR #768 changed createCommunicationAdapter from sync to async with no migration guide, deprecation period, or token security hardening. This PRD covers the migration guide for the breaking change and addresses four token security gaps (no tenant isolation, no revoke mechanism, no auth timeout, stale token reuse).

   Problem Statement

   • Breaking change: Existing code calling createCommunicationAdapter synchronously will break with no guidance
   • Token security: Module-level cached auth token has no tenant isolation — wrong tenant in multi-tenant deployments
   • No revoke: Tokens persist indefinitely with no logout mechanism
   • No timeout: Device-code auth flow could hang indefinitely on failed auth
   • Stale tokens: Token not cleared on auth error — invalid token reused on retry

   Proposed Approach

   Phase 1 — Migration Guide + Deprecation (P0)

   • Document the sync→async breaking change with before/after code examples
   • Add runtime deprecation warning if sync call pattern is detected (if feasible)
   • Update CHANGELOG and any samples that use the sync API
   • Add migration section to docs/ or UPGRADING.md

   Phase 2 — Token Security Hardening (P1)

   • Tenant-scoped token cache: key tokens by tenant ID, not global singleton
   • Explicit revoke() method on the adapter for logout/cleanup
   • Device-code timeout guard: 15-minute max, configurable, clear error on timeout
   • Clear token on auth error — force re-auth on next call

   Phase 3 — Multi-Tenant Testing (P2)

   • Integration tests: two tenants, verify tokens are isolated
   • Timeout test: device-code flow with simulated timeout
   • Token lifecycle test: auth → error → clear → re-auth

   Acceptance Criteria

   • Migration guide published with sync→async examples and codemods
   • CHANGELOG updated for the breaking change
   • Token cache is tenant-scoped (keyed by tenant ID)
   • revoke() method implemented and documented
   • Device-code flow has configurable timeout (default 15 min)
   • Stale tokens cleared on auth error
   • Multi-tenant integration test passes
   • Timeout integration test passes

   Architecture Notes

   • Token cache lives in packages/squad-sdk/src/platform/comms-teams.ts
   • Related to test(sdk): Add integration tests for Teams adapter class methods #772 (Teams adapter integration tests) and fix(sdk): Log warning when icacls fails on Windows token permission hardening #770 (icacls warning) — all three address Teams adapter quality gaps from PR feat(sdk): Add Teams communication adapter #768
   • Phase 1 migration guide should ship before the next minor release
3. diberry

   added 2 commits that reference this issue on Apr 7, 2026

   fix(sdk): Teams adapter token security + migration guide

   ...

   This issue will close once commit 0335a57 is merged into the 'dev' branch.

   0335a57

   fix(sdk): Teams adapter token security + migration guide

   ...

   This issue will close once commit 032df44 is merged into the 'dev' branch.

   032df44
4. diberry commented on Apr 10, 2026

   

   diberry

   on Apr 10, 2026

   ContributorAuthor

   More actions

   🔒 On hold — focusing on low-touch and medium-touch issues first.
5. bradygaster

   closed this as completedin #906on Apr 12, 2026