agent-messenger 2.28.0 → 2.29.1

package/src/platforms/teams/token-provider.test.ts

@@ -0,0 +1,227 @@
+import { afterAll, afterEach, describe, expect, it, mock } from 'bun:test'
+import { rmSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { TeamsCredentialManager } from './credential-manager'
+import { TeamsTokenProvider } from './token-provider'
+import { TeamsAuthCapabilityError } from './types'
+
+const TENANT_ID = '11111111-1111-1111-1111-111111111111'
+const USER_ID = '22222222-2222-2222-2222-222222222222'
+const CLIENT_ID = '1fec8e78-bce4-4aaf-ab1b-5451cc387264'
+const SUBSTRATE_AUD = 'https://substrate.office.com'
+const GRAPH_AUD = 'https://graph.microsoft.com'
+const originalFetch = globalThis.fetch
+const testDirs: string[] = []
+
+interface FetchCall {
+  url: string
+  init: RequestInit
+  body: URLSearchParams
+}
+
+interface TokenResponseConfig {
+  aud: string
+  refreshToken: string
+  expiresIn?: number
+  marker?: string
+}
+
+function setup(): TeamsCredentialManager {
+  const dir = join(import.meta.dir, `.test-teams-provider-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  testDirs.push(dir)
+  return new TeamsCredentialManager(dir)
+}
+
+async function seedDeviceAccount(manager: TeamsCredentialManager, refreshToken = 'old-refresh'): Promise<void> {
+  await manager.setDeviceCodeAccount({
+    accountType: 'work',
+    token: 'skype-token',
+    tokenExpiresAt: '2100-01-01T00:00:00Z',
+    aadRefreshToken: refreshToken,
+    aadClientId: CLIENT_ID,
+    teams: {},
+    currentTeam: null,
+  })
+}
+
+async function seedPersonalDeviceAccount(
+  manager: TeamsCredentialManager,
+  refreshToken = 'personal-refresh',
+): Promise<void> {
+  await manager.setDeviceCodeAccount({
+    accountType: 'personal',
+    token: 'personal-skype-token',
+    tokenExpiresAt: '2100-01-01T00:00:00Z',
+    aadRefreshToken: refreshToken,
+    aadClientId: CLIENT_ID,
+    teams: {},
+    currentTeam: null,
+  })
+}
+
+function createJwt(aud: string, marker = 'token'): string {
+  const header = Buffer.from(JSON.stringify({ alg: 'none', typ: 'JWT' })).toString('base64url')
+  const payload = Buffer.from(
+    JSON.stringify({ aud, tid: TENANT_ID, oid: USER_ID, exp: Math.floor(Date.now() / 1000) + 3600, jti: marker }),
+  ).toString('base64url')
+  return `${header}.${payload}.signature`
+}
+
+function bodyParams(body: BodyInit | null | undefined): URLSearchParams {
+  if (body instanceof URLSearchParams) return body
+  if (typeof body === 'string') return new URLSearchParams(body)
+  return new URLSearchParams()
+}
+
+function headerValue(init: RequestInit, name: string): string | undefined {
+  const headers = init.headers
+  if (headers instanceof Headers) return headers.get(name) ?? undefined
+  if (Array.isArray(headers)) {
+    const pair = headers.find(([key]) => key.toLowerCase() === name.toLowerCase())
+    return pair?.[1]
+  }
+  return headers?.[name]
+}
+
+function mockTokenResponses(responses: TokenResponseConfig[]): { calls: FetchCall[] } {
+  const calls: FetchCall[] = []
+  const queue = [...responses]
+  globalThis.fetch = mock((input: string | URL | Request, init?: RequestInit) => {
+    const requestInit = init ?? {}
+    calls.push({ url: String(input), init: requestInit, body: bodyParams(requestInit.body) })
+    const next = queue.shift()
+    if (!next) {
+      return Promise.resolve(new Response(JSON.stringify({ error: 'no_mock_response' }), { status: 500 }))
+    }
+    return Promise.resolve(
+      new Response(
+        JSON.stringify({
+          access_token: createJwt(next.aud, next.marker),
+          refresh_token: next.refreshToken,
+          expires_in: next.expiresIn ?? 3600,
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      ),
+    )
+  }) as typeof fetch
+  return { calls }
+}
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+})
+
+afterAll(() => {
+  for (const dir of testDirs) rmSync(dir, { recursive: true, force: true })
+})
+
+describe('TeamsTokenProvider', () => {
+  it('refresh-exchanges substrate tokens with Origin and persists rotated refresh tokens', async () => {
+    const manager = setup()
+    await seedDeviceAccount(manager)
+    const { calls } = mockTokenResponses([{ aud: SUBSTRATE_AUD, refreshToken: 'rotated-refresh' }])
+
+    const provider = new TeamsTokenProvider(manager)
+    const token = await provider.getSubstrateToken()
+
+    expect(token).toContain('.signature')
+    expect(calls[0].url).toContain('/organizations/oauth2/v2.0/token')
+    expect(calls[0].body.get('grant_type')).toBe('refresh_token')
+    expect(calls[0].body.get('client_id')).toBe(CLIENT_ID)
+    expect(calls[0].body.get('refresh_token')).toBe('old-refresh')
+    expect(calls[0].body.get('scope')).toBe('https://substrate.office.com/.default offline_access')
+    expect(headerValue(calls[0].init, 'Origin')).toBe('https://teams.microsoft.com')
+
+    const config = await manager.loadConfig()
+    expect(config?.accounts.work?.aad_refresh_token).toBe('rotated-refresh')
+  })
+
+  it('throws when the acquired token audience does not match the requested audience', async () => {
+    const manager = setup()
+    await seedDeviceAccount(manager)
+    mockTokenResponses([{ aud: GRAPH_AUD, refreshToken: 'rotated-refresh' }])
+
+    const provider = new TeamsTokenProvider(manager)
+    await expect(provider.getSubstrateToken()).rejects.toThrow(/audience/i)
+  })
+
+  it('throws TeamsAuthCapabilityError for cookie-only credentials', async () => {
+    const manager = setup()
+    await manager.setToken('skype-token', 'work', '2100-01-01T00:00:00Z')
+
+    const provider = new TeamsTokenProvider(manager)
+    await expect(provider.getSubstrateToken()).rejects.toThrow(TeamsAuthCapabilityError)
+    await expect(provider.getSubstrateToken()).rejects.toThrow(/auth login/)
+  })
+
+  it('uses the in-memory cache until the five-minute refresh buffer', async () => {
+    const manager = setup()
+    await seedDeviceAccount(manager)
+    const { calls } = mockTokenResponses([{ aud: SUBSTRATE_AUD, refreshToken: 'rotated-refresh', marker: 'cached' }])
+
+    const provider = new TeamsTokenProvider(manager)
+    const first = await provider.getSubstrateToken()
+    const second = await provider.getSubstrateToken()
+
+    expect(second).toBe(first)
+    expect(calls).toHaveLength(1)
+  })
+
+  it('refreshes cached tokens inside the five-minute buffer', async () => {
+    const manager = setup()
+    await seedDeviceAccount(manager)
+    const { calls } = mockTokenResponses([
+      { aud: SUBSTRATE_AUD, refreshToken: 'near-expiry-refresh', expiresIn: 299, marker: 'near-expiry' },
+      { aud: SUBSTRATE_AUD, refreshToken: 'fresh-refresh', expiresIn: 3600, marker: 'fresh' },
+    ])
+
+    const provider = new TeamsTokenProvider(manager)
+    const first = await provider.getSubstrateToken()
+    const second = await provider.getSubstrateToken()
+
+    expect(second).not.toBe(first)
+    expect(calls).toHaveLength(2)
+    const config = await manager.loadConfig()
+    expect(config?.accounts.work?.aad_refresh_token).toBe('fresh-refresh')
+  })
+
+  it('does not reuse bearer tokens across bound accounts', async () => {
+    const manager = setup()
+    await seedDeviceAccount(manager, 'work-refresh')
+    await seedPersonalDeviceAccount(manager, 'personal-refresh')
+    const { calls } = mockTokenResponses([
+      { aud: SUBSTRATE_AUD, refreshToken: 'work-rotated-refresh', marker: 'work-token' },
+      { aud: SUBSTRATE_AUD, refreshToken: 'personal-rotated-refresh', marker: 'personal-token' },
+    ])
+
+    const provider = new TeamsTokenProvider(manager)
+    const workToken = await provider.bindAccount('work').getSubstrateToken()
+    const personalToken = await provider.bindAccount('personal').getSubstrateToken()
+
+    expect(personalToken).not.toBe(workToken)
+    expect(calls).toHaveLength(2)
+    expect(calls[0].body.get('refresh_token')).toBe('work-refresh')
+    expect(calls[1].body.get('refresh_token')).toBe('personal-refresh')
+  })
+
+  it('restores tenant/user identity on a cached bearer hit after switching accounts back', async () => {
+    const manager = setup()
+    await seedDeviceAccount(manager, 'work-refresh')
+    await seedPersonalDeviceAccount(manager, 'personal-refresh')
+    mockTokenResponses([
+      { aud: SUBSTRATE_AUD, refreshToken: 'work-rotated', marker: 'work-token' },
+      { aud: SUBSTRATE_AUD, refreshToken: 'personal-rotated', marker: 'personal-token' },
+    ])
+
+    const provider = new TeamsTokenProvider(manager)
+    // work mints + caches (identity set), personal switch resets identity,
+    // then work again is served from cache and must re-restore identity
+    await provider.bindAccount('work').getSubstrateToken()
+    await provider.bindAccount('personal').getSubstrateToken()
+    await provider.bindAccount('work').getSubstrateToken()
+
+    expect(await provider.getTenantId()).toBe(TENANT_ID)
+    expect(await provider.getUserId()).toBe(USER_ID)
+  })
+})

package/src/platforms/teams/token-provider.ts

@@ -0,0 +1,284 @@
+import {
+  AAD_AUDIENCE_GRAPH,
+  AAD_AUDIENCE_SUBSTRATE,
+  AAD_SCOPE_GRAPH,
+  AAD_SCOPE_SUBSTRATE,
+  consumerTokenUrl,
+  getTeamsAppClientId,
+  organizationsTokenUrl,
+  TEAMS_WEB_ORIGIN,
+} from './app-config'
+import { TeamsCredentialManager } from './credential-manager'
+import type { TeamsAccount, TeamsAccountType } from './types'
+import { TeamsAuthCapabilityError, TeamsError } from './types'
+
+export type TokenAudience = 'skype' | 'substrate' | 'graph'
+
+type BearerAudience = Exclude<TokenAudience, 'skype'>
+
+interface CachedToken {
+  accessToken: string
+  expiresAt: number
+  aud: string
+  tenantId?: string
+  userId?: string
+}
+
+type CacheKey = TokenAudience | `${TeamsAccountType}:${BearerAudience}`
+
+interface CurrentAccountContext {
+  accountType: TeamsAccountType
+  account: TeamsAccount
+}
+
+interface BearerAudienceConfig {
+  scope: string
+  aud: string
+}
+
+interface JwtClaims {
+  aud?: string
+  tid?: string
+  oid?: string
+  exp?: number
+  [key: string]: unknown
+}
+
+const REFRESH_BUFFER_MS = 5 * 60 * 1000
+const DEFAULT_ACCESS_TOKEN_TTL_SEC = 3600
+
+const BEARER_AUDIENCES: Record<BearerAudience, BearerAudienceConfig> = {
+  substrate: { scope: AAD_SCOPE_SUBSTRATE, aud: AAD_AUDIENCE_SUBSTRATE },
+  graph: { scope: AAD_SCOPE_GRAPH, aud: AAD_AUDIENCE_GRAPH },
+}
+
+export class TeamsTokenProvider {
+  private cache: Map<CacheKey, CachedToken> = new Map()
+  private tenantId?: string
+  private userId?: string
+  private boundAccountType?: TeamsAccountType
+  private lastAccountType?: TeamsAccountType
+
+  constructor(private credManager: TeamsCredentialManager = new TeamsCredentialManager()) {}
+
+  bindAccount(accountType: TeamsAccountType): this {
+    this.boundAccountType = accountType
+    return this
+  }
+
+  async getSkypeToken(): Promise<string> {
+    const cached = this.getCached('skype')
+    if (cached) return cached.accessToken
+
+    const cred = await this.credManager.getTokenWithExpiry()
+    if (!cred?.token) {
+      throw new TeamsError(
+        'No Teams credentials found. Run `agent-teams auth login` or `agent-teams auth extract`.',
+        'no_credentials',
+      )
+    }
+
+    const expiresAt = cred.tokenExpiresAt ? new Date(cred.tokenExpiresAt).getTime() : Number.POSITIVE_INFINITY
+    if (expiresAt <= Date.now()) {
+      throw new TeamsError('Token has expired. Run "auth login" or "auth extract" to refresh.', 'token_expired')
+    }
+
+    this.cache.set('skype', { accessToken: cred.token, expiresAt, aud: 'skype' })
+    return cred.token
+  }
+
+  async getSubstrateToken(): Promise<string> {
+    return this.getBearerToken('substrate')
+  }
+
+  async getGraphToken(): Promise<string> {
+    return this.getBearerToken('graph')
+  }
+
+  async getTenantId(): Promise<string> {
+    await this.ensureIdentity()
+    if (!this.tenantId) {
+      throw new TeamsError(
+        'Microsoft token did not include a tenant id needed for Teams search.',
+        'aad_identity_missing',
+      )
+    }
+    return this.tenantId
+  }
+
+  async getUserId(): Promise<string> {
+    await this.ensureIdentity()
+    if (!this.userId) {
+      throw new TeamsError('Microsoft token did not include a user id needed for Teams search.', 'aad_identity_missing')
+    }
+    return this.userId
+  }
+
+  private getCached(key: CacheKey): CachedToken | undefined {
+    const cached = this.cache.get(key)
+    if (!cached) return undefined
+    return cached.expiresAt - Date.now() > REFRESH_BUFFER_MS ? cached : undefined
+  }
+
+  private async getBearerToken(audience: BearerAudience): Promise<string> {
+    const current = await this.getCurrentAccount()
+    this.resetIdentityIfAccountChanged(current.accountType)
+    const cacheKey: CacheKey = `${current.accountType}:${audience}`
+    const cached = this.getCached(cacheKey)
+    if (cached) {
+      // a cache hit after an account switch reset our identity, so restore the
+      // tenant/user claims captured when this token was minted
+      this.tenantId = cached.tenantId ?? this.tenantId
+      this.userId = cached.userId ?? this.userId
+      return cached.accessToken
+    }
+
+    if (!current.account.aad_refresh_token) {
+      throw new TeamsAuthCapabilityError()
+    }
+
+    const clientId = current.account.aad_client_id ?? getTeamsAppClientId(current.accountType).clientId
+    const config = BEARER_AUDIENCES[audience]
+    const token = await this.refreshBearerToken({
+      accountType: current.accountType,
+      clientId,
+      refreshToken: current.account.aad_refresh_token,
+      audience,
+      config,
+    })
+
+    this.cache.set(cacheKey, token)
+    return token.accessToken
+  }
+
+  private async refreshBearerToken(params: {
+    accountType: TeamsAccountType
+    clientId: string
+    refreshToken: string
+    audience: BearerAudience
+    config: BearerAudienceConfig
+  }): Promise<CachedToken> {
+    const response = await fetch(tokenUrlForAccount(params.accountType), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Origin: TEAMS_WEB_ORIGIN,
+      },
+      body: new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: params.clientId,
+        refresh_token: params.refreshToken,
+        scope: params.config.scope,
+      }),
+    })
+
+    const body = (await response.json().catch(() => ({}))) as Record<string, unknown>
+    if (!response.ok) {
+      throw new TeamsError(
+        `Microsoft token refresh failed: ${describeAadError(body, response.status)}`,
+        'aad_refresh_failed',
+      )
+    }
+
+    const accessToken = stringField(body, 'access_token')
+    if (!accessToken) {
+      throw new TeamsError('Microsoft token refresh response did not include an access token.', 'aad_access_missing')
+    }
+
+    const claims = decodeJwt(accessToken)
+    if (claims.aud !== params.config.aud) {
+      throw new TeamsError(
+        `Microsoft token audience mismatch: expected ${params.config.aud}, got ${claims.aud ?? 'missing'}.`,
+        'aad_audience_mismatch',
+      )
+    }
+
+    this.tenantId = claims.tid ?? this.tenantId
+    this.userId = claims.oid ?? this.userId
+
+    const rotatedRefreshToken = stringField(body, 'refresh_token')
+    if (rotatedRefreshToken) {
+      await this.credManager.updateAadRefreshToken(params.accountType, rotatedRefreshToken, params.clientId)
+    }
+
+    const expiresIn = numberField(body, 'expires_in') ?? DEFAULT_ACCESS_TOKEN_TTL_SEC
+    return {
+      accessToken,
+      expiresAt: Date.now() + expiresIn * 1000,
+      aud: params.config.aud,
+      tenantId: claims.tid,
+      userId: claims.oid,
+    }
+  }
+
+  private async getCurrentAccount(): Promise<CurrentAccountContext> {
+    const config = await this.credManager.loadConfig()
+    if (!config) {
+      throw new TeamsError(
+        'No Teams credentials found. Run `agent-teams auth login` or `agent-teams auth extract`.',
+        'no_credentials',
+      )
+    }
+    const accountKey = this.boundAccountType ?? TeamsCredentialManager.accountOverride ?? config.current_account
+    if (accountKey !== 'work' && accountKey !== 'personal') {
+      throw new TeamsError(
+        'No active Teams account selected. Run `agent-teams auth switch-account`.',
+        'no_current_account',
+      )
+    }
+    const account = config.accounts[accountKey]
+    if (!account) {
+      throw new TeamsError(
+        'No active Teams account selected. Run `agent-teams auth switch-account`.',
+        'no_current_account',
+      )
+    }
+    return { accountType: accountKey, account }
+  }
+
+  private resetIdentityIfAccountChanged(accountType: TeamsAccountType): void {
+    if (this.lastAccountType === accountType) return
+    this.tenantId = undefined
+    this.userId = undefined
+    this.lastAccountType = accountType
+  }
+
+  private async ensureIdentity(): Promise<void> {
+    if (this.tenantId && this.userId) return
+    await this.getSubstrateToken()
+  }
+}
+
+function tokenUrlForAccount(accountType: TeamsAccountType): string {
+  return accountType === 'personal' ? consumerTokenUrl() : organizationsTokenUrl()
+}
+
+function decodeJwt(token: string): JwtClaims {
+  const payload = token.split('.')[1]
+  if (!payload) {
+    throw new TeamsError('Microsoft token response was not a JWT.', 'aad_token_invalid')
+  }
+  const decoded = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as Record<string, unknown>
+  return {
+    ...decoded,
+    aud: typeof decoded.aud === 'string' ? decoded.aud : undefined,
+    tid: typeof decoded.tid === 'string' ? decoded.tid : undefined,
+    oid: typeof decoded.oid === 'string' ? decoded.oid : undefined,
+    exp: typeof decoded.exp === 'number' ? decoded.exp : undefined,
+  }
+}
+
+function stringField(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key]
+  return typeof value === 'string' ? value : undefined
+}
+
+function numberField(record: Record<string, unknown>, key: string): number | undefined {
+  const value = record[key]
+  return typeof value === 'number' ? value : undefined
+}
+
+function describeAadError(body: Record<string, unknown>, status: number): string {
+  const desc = body.error_description ?? body.error
+  return typeof desc === 'string' ? desc.split('\n')[0] : `HTTP ${status}`
+}

package/src/platforms/teams/trouter.test.ts

@@ -0,0 +1,174 @@
+import { expect, it } from 'bun:test'
+import { gzipSync } from 'node:zlib'
+
+import {
+  buildActivityFrame,
+  buildAuthenticateFrame,
+  buildEventAck,
+  buildPingFrame,
+  buildRequestAck,
+  buildWebSocketUrl,
+  decodeMessageBody,
+  extractChatId,
+  isMessageLossFrame,
+  isThreadConversation,
+  parseMentions,
+  parseRequestFrame,
+  type TrouterInfo,
+} from './trouter'
+
+const info: TrouterInfo = {
+  socketio: 'https://pub-ent-test.trouter.teams.microsoft.com:443/',
+  surl: 'https://pub-ent-test.trouter.teams.microsoft.com:3443/v4/f/HASH/',
+  connectparams: { sr: 'abc', issuer: 'prod-2', sig: 'xyz' },
+}
+
+it('buildWebSocketUrl targets the socket.io v1 websocket path', () => {
+  const url = buildWebSocketUrl(info, 'SESSION123', 'endpoint-uuid')
+  expect(url.startsWith(`${info.socketio}socket.io/1/websocket/SESSION123?`)).toBe(true)
+  expect(url).toContain('epid=endpoint-uuid')
+  expect(url).toContain('sr=abc')
+  expect(url).toContain('auth=true')
+})
+
+it('buildAuthenticateFrame embeds the Bearer id_token and connectparams', () => {
+  const frame = buildAuthenticateFrame(info, 'ID_TOKEN')
+  expect(frame.startsWith('5:::')).toBe(true)
+  const payload = JSON.parse(frame.slice(4))
+  expect(payload.name).toBe('user.authenticate')
+  expect(payload.args[0].headers.Authorization).toBe('Bearer ID_TOKEN')
+  expect(payload.args[0].connectparams).toEqual(info.connectparams)
+})
+
+it('buildActivityFrame and buildPingFrame use the sequence number', () => {
+  expect(buildActivityFrame(3)).toBe('5:3::{"name":"user.activity","args":[{"state":"active"}]}')
+  expect(buildPingFrame(7)).toBe('5:7::{"name":"ping"}')
+})
+
+it('buildRequestAck returns a 200 ack for the request id', () => {
+  const ack = buildRequestAck(42)
+  expect(ack.startsWith('3:::')).toBe(true)
+  expect(JSON.parse(ack.slice(4))).toEqual({ id: 42, status: 200, body: '' })
+})
+
+it('buildEventAck acks numbered event frames and ignores others', () => {
+  expect(buildEventAck('5:12::{"name":"trouter.message_loss"}')).toBe('6:12::')
+  expect(buildEventAck('5:9+::{"name":"x"}')).toBe('6:9::')
+  expect(buildEventAck('1::')).toBeNull()
+  expect(buildEventAck('6:::1["pong"]')).toBeNull()
+})
+
+it('parseRequestFrame parses 3::: frames and rejects others', () => {
+  const frame = '3:::{"id":1,"method":"POST","url":"/v4/f/HASH/messaging","body":"{}"}'
+  const parsed = parseRequestFrame(frame)
+  expect(parsed?.id).toBe(1)
+  expect(parsed?.url).toBe('/v4/f/HASH/messaging')
+  expect(parseRequestFrame('5:1::{}')).toBeNull()
+  expect(parseRequestFrame('3:::not-json')).toBeNull()
+})
+
+it('parseRequestFrame rejects frames without a numeric id', () => {
+  expect(parseRequestFrame('3:::{"url":"/x/messaging"}')).toBeNull()
+  expect(parseRequestFrame('3:::{"id":"abc"}')).toBeNull()
+  expect(parseRequestFrame('3:::"just-a-string"')).toBeNull()
+  expect(parseRequestFrame('3:::null')).toBeNull()
+})
+
+it('isMessageLossFrame detects trouter.message_loss events', () => {
+  expect(isMessageLossFrame('5:2::{"name":"trouter.message_loss","args":[{}]}')).toBe(true)
+  expect(isMessageLossFrame('5:1::{"name":"trouter.connected","args":[{}]}')).toBe(false)
+  expect(isMessageLossFrame('1::')).toBe(false)
+})
+
+it('extractChatId pulls the conversation id from a link', () => {
+  expect(extractChatId('https://notifications.skype.net/v1/users/ME/conversations/19:uni01_abc@thread.v2')).toBe(
+    '19:uni01_abc@thread.v2',
+  )
+  expect(extractChatId('https://x/conversations/19:uni01_abc@thread.v2/messages/123')).toBe('19:uni01_abc@thread.v2')
+  expect(extractChatId(undefined)).toBeNull()
+  expect(extractChatId('no-conversation-here')).toBeNull()
+})
+
+it('decodeMessageBody parses plain JSON bodies', () => {
+  const body = JSON.stringify({ resourceType: 'NewMessage', resource: { id: '1' } })
+  expect(decodeMessageBody({}, body)).toEqual({ resourceType: 'NewMessage', resource: { id: '1' } })
+})
+
+it('decodeMessageBody inflates gzip+base64 bodies', () => {
+  const inner = JSON.stringify({ resourceType: 'NewMessage' })
+  const gzipped = gzipSync(Buffer.from(inner)).toString('base64')
+  const decoded = decodeMessageBody({ 'X-Microsoft-Skype-Content-Encoding': 'gzip' }, gzipped)
+  expect(decoded).toEqual({ resourceType: 'NewMessage' })
+})
+
+it('decodeMessageBody unwraps nested cp (gzip+base64) payloads', () => {
+  const inner = JSON.stringify({ resourceType: 'NewMessage', resource: { content: 'hi' } })
+  const cp = gzipSync(Buffer.from(inner)).toString('base64')
+  const decoded = decodeMessageBody({}, JSON.stringify({ cp }))
+  expect(decoded).toEqual({ resourceType: 'NewMessage', resource: { content: 'hi' } })
+})
+
+it('decodeMessageBody unwraps nested gp (base64) payloads', () => {
+  const inner = JSON.stringify({ resourceType: 'NewMessage' })
+  const gp = Buffer.from(inner).toString('base64')
+  const decoded = decodeMessageBody({}, JSON.stringify({ gp }))
+  expect(decoded).toEqual({ resourceType: 'NewMessage' })
+})
+
+it('isThreadConversation flags @thread ids and rejects 1:1 conversations', () => {
+  expect(isThreadConversation('19:abc@thread.tacv2')).toBe(true)
+  expect(isThreadConversation('19:abc@thread.v2')).toBe(true)
+  expect(isThreadConversation('19:uni01_abc@unq.gbl.spaces')).toBe(false)
+  expect(isThreadConversation('8:orgid:user@oneToOne.skype')).toBe(false)
+})
+
+it('parseMentions prefers the authoritative properties.mentions array', () => {
+  const properties = {
+    mentions: [
+      { itemid: '0', mri: '8:orgid:aaa', mentionType: 'person', displayName: 'Alice' },
+      { itemid: '1', mri: '8:orgid:bbb', mentionType: 'person', displayName: 'Bob' },
+    ],
+  }
+  const content =
+    '<span itemtype="http://schema.skype.com/Mention" itemscope itemid="0">Alice</span> ' +
+    '<span itemtype="http://schema.skype.com/Mention" itemscope itemid="1">Bob</span> hi'
+  expect(parseMentions(properties, content)).toEqual([
+    { id: '0', mri: '8:orgid:aaa', displayName: 'Alice' },
+    { id: '1', mri: '8:orgid:bbb', displayName: 'Bob' },
+  ])
+})
+
+it('parseMentions accepts JSON-stringified properties and mentions', () => {
+  const properties = JSON.stringify({
+    mentions: JSON.stringify([{ itemid: '0', mri: '8:orgid:aaa', displayName: 'Alice' }]),
+  })
+  expect(parseMentions(properties, '')).toEqual([{ id: '0', mri: '8:orgid:aaa', displayName: 'Alice' }])
+})
+
+it('parseMentions keeps tag mentions', () => {
+  const properties = { mentions: [{ itemid: '0', mri: 'tag:eng', mentionType: 'tag', displayName: 'Engineering' }] }
+  expect(parseMentions(properties, '')).toEqual([{ id: '0', mri: 'tag:eng', displayName: 'Engineering' }])
+})
+
+it('parseMentions falls back to content spans when properties are absent', () => {
+  const content =
+    '<readonly class="skipProofing" itemtype="http://schema.skype.com/Mention" contenteditable="false">' +
+    '<span itemtype="http://schema.skype.com/Mention" itemscope itemid="0">Alice</span></readonly> hi'
+  expect(parseMentions(undefined, content)).toEqual([{ id: '0', displayName: 'Alice' }])
+})
+
+it('parseMentions skips property entries missing itemid', () => {
+  const properties = {
+    mentions: [
+      { mri: '8:orgid:aaa', displayName: 'Alice' },
+      { itemid: '1', displayName: 'Bob' },
+    ],
+  }
+  expect(parseMentions(properties, '')).toEqual([{ id: '1', mri: undefined, displayName: 'Bob' }])
+})
+
+it('parseMentions returns an empty array for malformed data', () => {
+  expect(parseMentions('not-json', '')).toEqual([])
+  expect(parseMentions({ mentions: 'not-json' }, '')).toEqual([])
+  expect(parseMentions(null, 'plain text with no mentions')).toEqual([])
+})