agent-messenger 2.28.0 → 2.29.0

package/src/platforms/instagram/commands/auth.test.ts

@@ -3,6 +3,7 @@ import { afterEach, beforeEach, describe, expect, mock, spyOn, it } from 'bun:te
 const originalConsoleLog = console.log
 import type { Command } from 'commander'
 
+import { InstagramClient } from '../client'
 import { InstagramCredentialManager } from '../credential-manager'
 
 const mockGetAccount = mock(() => Promise.resolve(null))
@@ -10,7 +11,7 @@ const mockListAccounts = mock(() => Promise.resolve([]))
 const mockSetCurrent = mock(() => Promise.resolve(true))
 const mockRemoveAccount = mock(() => Promise.resolve(true))
 
-import { authCommand } from './auth'
+import { authCommand, sanitizePassword } from './auth'
 
 function resetCommandState(cmd: Command): void {
   for (const sub of cmd.commands) {
@@ -216,4 +217,179 @@ describe('auth commands', () => {
       expect(output.error).toContain('missing_account')
     })
   })
+
+  describe('sanitizePassword', () => {
+    it('preserves leading and trailing whitespace', () => {
+      expect(sanitizePassword('  pass word  ')).toBe('  pass word  ')
+      expect(sanitizePassword('\tpw\t')).toBe('\tpw\t')
+    })
+
+    it('preserves internal characters exactly', () => {
+      expect(sanitizePassword('p@$$ w0rd!#')).toBe('p@$$ w0rd!#')
+    })
+
+    it('strips only a trailing carriage return', () => {
+      expect(sanitizePassword('secret\r')).toBe('secret')
+      expect(sanitizePassword('sec\rret')).toBe('sec\rret')
+    })
+
+    it('returns undefined for empty input', () => {
+      expect(sanitizePassword('')).toBeUndefined()
+      expect(sanitizePassword('\r')).toBeUndefined()
+    })
+
+    it('keeps a whitespace-only password (not treated as empty)', () => {
+      expect(sanitizePassword('   ')).toBe('   ')
+    })
+  })
+
+  describe('login-email', () => {
+    it('redeems uid/token non-interactively and saves the account', async () => {
+      const oneClickSpy = spyOn(InstagramClient.prototype, 'oneClickLogin').mockResolvedValue({ userId: '4242' })
+      const setSessionPathSpy = spyOn(InstagramClient.prototype, 'setSessionPath').mockImplementation(() => {})
+      const ensurePathsSpy = spyOn(InstagramCredentialManager.prototype, 'ensureAccountPaths').mockResolvedValue({
+        account_dir: '/tmp/x',
+        session_path: '/tmp/x/session.json',
+      })
+      const setAccountSpy = spyOn(InstagramCredentialManager.prototype, 'setAccount').mockResolvedValue(undefined)
+
+      await authCommand.parseAsync(
+        ['login-email', '--username', 'alice', '--uid', 'ENCODED_UID', '--token', 'NONCE123', '--pretty'],
+        { from: 'user' },
+      )
+
+      expect(oneClickSpy).toHaveBeenCalledWith('ENCODED_UID', 'NONCE123')
+      expect(setAccountSpy).toHaveBeenCalled()
+      const output = JSON.parse(consoleLogSpy.mock.calls[0]![0] as string)
+      expect(output.authenticated).toBe(true)
+      expect(output.username).toBe('alice')
+
+      for (const spy of [oneClickSpy, setSessionPathSpy, ensurePathsSpy, setAccountSpy]) spy.mockRestore()
+    })
+
+    it('parses uid/token from a pasted --link', async () => {
+      const oneClickSpy = spyOn(InstagramClient.prototype, 'oneClickLogin').mockResolvedValue({ userId: '7' })
+      const setSessionPathSpy = spyOn(InstagramClient.prototype, 'setSessionPath').mockImplementation(() => {})
+      const ensurePathsSpy = spyOn(InstagramCredentialManager.prototype, 'ensureAccountPaths').mockResolvedValue({
+        account_dir: '/tmp/x',
+        session_path: '/tmp/x/session.json',
+      })
+      const setAccountSpy = spyOn(InstagramCredentialManager.prototype, 'setAccount').mockResolvedValue(undefined)
+
+      await authCommand.parseAsync(
+        [
+          'login-email',
+          '--username',
+          'bob',
+          '--link',
+          'https://www.instagram.com/_n/web_emaillogin?uid=U1&token=T1&auto_send=0',
+        ],
+        { from: 'user' },
+      )
+
+      expect(oneClickSpy).toHaveBeenCalledWith('U1', 'T1')
+
+      for (const spy of [oneClickSpy, setSessionPathSpy, ensurePathsSpy, setAccountSpy]) spy.mockRestore()
+    })
+
+    it('errors on an invalid --link instead of sending a new email', async () => {
+      const oneClickSpy = spyOn(InstagramClient.prototype, 'oneClickLogin').mockResolvedValue({ userId: '1' })
+      const sendEmailSpy = spyOn(InstagramClient.prototype, 'sendOneClickLoginEmail').mockResolvedValue({
+        sent: true,
+        contactPoint: '',
+      })
+
+      await expect(
+        authCommand.parseAsync(['login-email', '--username', 'alice', '--link', 'not-a-link', '--pretty'], {
+          from: 'user',
+        }),
+      ).rejects.toThrow('process.exit called')
+
+      expect(sendEmailSpy).not.toHaveBeenCalled()
+      expect(oneClickSpy).not.toHaveBeenCalled()
+      const output = JSON.parse(consoleLogSpy.mock.calls[0]![0] as string)
+      expect(output.error).toContain('Invalid login link')
+
+      for (const spy of [oneClickSpy, sendEmailSpy]) spy.mockRestore()
+    })
+
+    it('errors when only --uid is provided without --token', async () => {
+      const sendEmailSpy = spyOn(InstagramClient.prototype, 'sendOneClickLoginEmail').mockResolvedValue({
+        sent: true,
+        contactPoint: '',
+      })
+
+      await expect(
+        authCommand.parseAsync(['login-email', '--username', 'alice', '--uid', 'U1', '--pretty'], { from: 'user' }),
+      ).rejects.toThrow('process.exit called')
+
+      expect(sendEmailSpy).not.toHaveBeenCalled()
+      const output = JSON.parse(consoleLogSpy.mock.calls[0]![0] as string)
+      expect(output.error).toContain('Invalid login link')
+
+      sendEmailSpy.mockRestore()
+    })
+
+    it('treats an explicit empty --link as redeem intent and fails closed', async () => {
+      const oneClickSpy = spyOn(InstagramClient.prototype, 'oneClickLogin').mockResolvedValue({ userId: '1' })
+      const sendEmailSpy = spyOn(InstagramClient.prototype, 'sendOneClickLoginEmail').mockResolvedValue({
+        sent: true,
+        contactPoint: '',
+      })
+
+      await expect(
+        authCommand.parseAsync(['login-email', '--username', 'alice', '--link', '', '--pretty'], { from: 'user' }),
+      ).rejects.toThrow('process.exit called')
+
+      expect(sendEmailSpy).not.toHaveBeenCalled()
+      expect(oneClickSpy).not.toHaveBeenCalled()
+      const output = JSON.parse(consoleLogSpy.mock.calls[0]![0] as string)
+      expect(output.error).toContain('Invalid login link')
+
+      for (const spy of [oneClickSpy, sendEmailSpy]) spy.mockRestore()
+    })
+
+    it('requires --username when redeeming non-interactively', async () => {
+      const oneClickSpy = spyOn(InstagramClient.prototype, 'oneClickLogin').mockResolvedValue({ userId: '1' })
+
+      await expect(
+        authCommand.parseAsync(['login-email', '--uid', 'U1', '--token', 'T1', '--pretty'], { from: 'user' }),
+      ).rejects.toThrow('process.exit called')
+
+      expect(oneClickSpy).not.toHaveBeenCalled()
+      const output = JSON.parse(consoleLogSpy.mock.calls[0]![0] as string)
+      expect(output.error).toContain('--username is required')
+
+      oneClickSpy.mockRestore()
+    })
+  })
+
+  describe('login email fallback', () => {
+    it('non-interactively sends the login email when password login offers it', async () => {
+      const authSpy = spyOn(InstagramClient.prototype, 'authenticate').mockResolvedValue({
+        userId: '',
+        oneClickEmailAvailable: true,
+      })
+      const sendEmailSpy = spyOn(InstagramClient.prototype, 'sendOneClickLoginEmail').mockResolvedValue({
+        sent: true,
+        contactPoint: 'j***@example.com',
+      })
+      const ensurePathsSpy = spyOn(InstagramCredentialManager.prototype, 'ensureAccountPaths').mockResolvedValue({
+        account_dir: '/tmp/x',
+        session_path: '/tmp/x/session.json',
+      })
+
+      await authCommand.parseAsync(['login', '--username', 'alice', '--password', 'wrong', '--pretty'], {
+        from: 'user',
+      })
+
+      expect(sendEmailSpy).toHaveBeenCalledWith('alice')
+      const output = JSON.parse(consoleLogSpy.mock.calls[0]![0] as string)
+      expect(output.one_click_email_available).toBe(true)
+      expect(output.email_sent).toBe(true)
+      expect(output.contact_point).toBe('j***@example.com')
+
+      for (const spy of [authSpy, sendEmailSpy, ensurePathsSpy]) spy.mockRestore()
+    })
+  })
 })

package/src/platforms/instagram/commands/auth.ts

@@ -1,4 +1,3 @@
-import { randomUUID } from 'node:crypto'
 import { mkdir, writeFile } from 'node:fs/promises'
 import { Writable } from 'node:stream'
 
@@ -10,7 +9,7 @@ import { isInteractive } from '@/shared/utils/interactive'
 import { formatOutput } from '@/shared/utils/output'
 import { info, warn, error as stderrError, debug } from '@/shared/utils/stderr'
 
-import { InstagramClient, generateAndroidDeviceId, generateDeviceString } from '../client'
+import { InstagramClient, generateDevice, parseOneClickLoginLink } from '../client'
 import { InstagramCredentialManager } from '../credential-manager'
 import { InstagramTokenExtractor } from '../token-extractor'
 import { createAccountId } from '../types'
@@ -26,6 +25,13 @@ async function promptText(message: string): Promise<string | undefined> {
   }
 }
 
+// Never trim passwords: they may contain leading/trailing spaces. Trimming corrupts them and
+// Instagram rejects the login as bad_password. Only strip the trailing CR some terminals add.
+export function sanitizePassword(raw: string): string | undefined {
+  const password = raw.replace(/\r$/, '')
+  return password.length > 0 ? password : undefined
+}
+
 async function promptHidden(message: string): Promise<string | undefined> {
   const { createInterface } = await import('node:readline/promises')
   const hiddenOutput = new (class extends Writable {
@@ -41,7 +47,7 @@ async function promptHidden(message: string): Promise<string | undefined> {
     process.stdout.write(`${message}: `)
     const answer = await rl.question('')
     process.stdout.write('\n')
-    return answer.trim() || undefined
+    return sanitizePassword(answer)
   } finally {
     hiddenOutput.muted = false
     rl.close()
@@ -187,12 +193,167 @@ async function loginAction(options: LoginOptions): Promise<void> {
       return
     }
 
+    if (result.oneClickEmailAvailable) {
+      if (interactive) {
+        await runEmailLogin(manager, username, options, client)
+      } else {
+        const { contactPoint } = await client.sendOneClickLoginEmail(username)
+        console.log(
+          formatOutput(
+            {
+              one_click_email_available: true,
+              email_sent: true,
+              contact_point: contactPoint,
+              message:
+                'Password login was rejected, but this account can log in by email. A login email was sent. Open the "Login as <username>" link and run "agent-instagram auth login-email --username <username> --link <url>" to finish.',
+            },
+            options.pretty,
+          ),
+        )
+      }
+      return
+    }
+
     await saveAccountAndPrint(manager, accountId, username, result.userId, options.pretty)
   } catch (error) {
     handleError(error as Error)
   }
 }
 
+interface LoginEmailOptions {
+  username?: string
+  link?: string
+  uid?: string
+  token?: string
+  pretty?: boolean
+  debug?: boolean
+}
+
+async function loginEmailAction(options: LoginEmailOptions): Promise<void> {
+  try {
+    const interactive = isInteractive()
+    const manager = new InstagramCredentialManager()
+
+    // Presence (not truthiness) signals redeem intent: an explicit empty --link "" must still
+    // fail closed here rather than falling through to the send-email branch and re-emailing.
+    const redeemAttempted = options.link !== undefined || options.uid !== undefined || options.token !== undefined
+    if (redeemAttempted) {
+      if (!options.username) {
+        console.log(
+          formatOutput({ error: '--username is required when redeeming a login email link.' }, options.pretty),
+        )
+        process.exit(1)
+      }
+      const redeem = resolveOneClickCredentials(options)
+      if (!redeem) {
+        console.log(
+          formatOutput(
+            { error: 'Invalid login link. Provide a valid --link <url>, or both --uid and --token.' },
+            options.pretty,
+          ),
+        )
+        process.exit(1)
+      }
+      await redeemLoginEmail(manager, redeem.uid, redeem.token, options.username, options)
+      return
+    }
+
+    let username = options.username
+    if (!username) {
+      if (!interactive) {
+        console.log(
+          formatOutput(
+            {
+              error:
+                'Username required. Use --username <username> to send the login email, then --link <url> (or --uid and --token) to complete.',
+            },
+            options.pretty,
+          ),
+        )
+        process.exit(1)
+      }
+      username = await promptText('Instagram username')
+      if (!username) {
+        stderrError('Username is required.')
+        process.exit(1)
+      }
+    }
+
+    const client = new InstagramClient(manager)
+    if (options.debug) client.setDebugLog((msg) => debug(`[debug] ${msg}`))
+
+    if (!interactive) {
+      const { contactPoint } = await client.sendOneClickLoginEmail(username)
+      console.log(
+        formatOutput(
+          {
+            email_sent: true,
+            contact_point: contactPoint,
+            message:
+              'Login email sent. Open the "Login as <username>" link and run "agent-instagram auth login-email --username <username> --link <url>" to finish.',
+          },
+          options.pretty,
+        ),
+      )
+      return
+    }
+
+    await runEmailLogin(manager, username, options, client)
+  } catch (error) {
+    handleError(error as Error)
+  }
+}
+
+async function runEmailLogin(
+  manager: InstagramCredentialManager,
+  username: string,
+  options: LoginEmailOptions,
+  client: InstagramClient,
+): Promise<void> {
+  const { contactPoint } = await client.sendOneClickLoginEmail(username)
+
+  info(contactPoint ? `\n  Login email sent to: ${contactPoint}` : '\n  Login email sent.')
+  info('  Open the email, copy the "Login as ..." link, and paste it here.')
+  const link = await promptText('Login link')
+  if (!link) {
+    stderrError('Login link is required.')
+    process.exit(1)
+  }
+
+  const parsed = parseOneClickLoginLink(link)
+  if (!parsed) {
+    stderrError('Could not read uid and token from the pasted link.')
+    process.exit(1)
+  }
+
+  await redeemLoginEmail(manager, parsed.uid, parsed.token, username, options, client)
+}
+
+function resolveOneClickCredentials(options: LoginEmailOptions): { uid: string; token: string } | null {
+  if (options.link) return parseOneClickLoginLink(options.link)
+  if (options.uid && options.token) return { uid: options.uid, token: options.token }
+  return null
+}
+
+async function redeemLoginEmail(
+  manager: InstagramCredentialManager,
+  uid: string,
+  token: string,
+  username: string,
+  options: LoginEmailOptions,
+  existingClient?: InstagramClient,
+): Promise<void> {
+  const client = existingClient ?? new InstagramClient(manager)
+  if (!existingClient && options.debug) client.setDebugLog((msg) => debug(`[debug] ${msg}`))
+
+  const accountId = createAccountId(username)
+  const paths = await manager.ensureAccountPaths(accountId)
+  client.setSessionPath(paths.session_path)
+
+  const result = await client.oneClickLogin(uid, token)
+  await saveAccountAndPrint(manager, accountId, username, result.userId, options.pretty)
+}
+
 async function handleInteractiveChallenge(
   client: InstagramClient,
   manager: InstagramCredentialManager,
@@ -414,6 +575,12 @@ async function extractAction(options: { pretty?: boolean; debug?: boolean; brows
 
     const manager = new InstagramCredentialManager()
 
+    let device = await manager.loadDevice()
+    if (!device) {
+      device = generateDevice()
+      await manager.saveDevice(device)
+    }
+
     for (const extracted of results) {
       const session = {
         cookies: [
@@ -426,14 +593,7 @@ async function extractAction(options: { pretty?: boolean; debug?: boolean; brows
         ]
           .filter(Boolean)
           .join('; '),
-        device: {
-          phone_id: randomUUID(),
-          uuid: randomUUID(),
-          android_device_id: generateAndroidDeviceId(),
-          advertising_id: randomUUID(),
-          client_session_id: randomUUID(),
-          device_string: generateDeviceString(),
-        },
+        device,
         user_id: extracted.ds_user_id,
         mid: extracted.mid,
       }
@@ -530,6 +690,17 @@ export const authCommand = new Command('auth')
       .option('--debug', 'Show raw API responses')
       .action(loginAction),
   )
+  .addCommand(
+    new Command('login-email')
+      .description('Log in via a one-click login email link (no password needed)')
+      .option('--username <username>', 'Instagram username (sends the login email)')
+      .option('--link <url>', 'The "Login as <username>" URL from the email')
+      .option('--uid <uid>', 'uid from the email link (alternative to --link)')
+      .option('--token <token>', 'token from the email link (alternative to --link)')
+      .option('--pretty', 'Pretty print JSON output')
+      .option('--debug', 'Show raw API responses')
+      .action(loginEmailAction),
+  )
   .addCommand(
     new Command('extract')
       .description('Extract Instagram cookies from browser (Chrome, Edge, Arc, Brave)')

package/src/platforms/instagram/credential-manager.test.ts

@@ -274,4 +274,34 @@ describe('InstagramCredentialManager', () => {
       expect(paths.session_path).toBe(join(testConfigDir, 'instagram', 'my-account', 'session.json'))
     })
   })
+
+  describe('device persistence', () => {
+    const device = {
+      phone_id: 'phone-1',
+      uuid: 'uuid-1',
+      android_device_id: 'android-abcdef0123456789',
+      advertising_id: 'adid-1',
+      client_session_id: 'csid-1',
+      device_string: '34/14; 480dpi; 1344x2992; Google/google; Pixel 8 Pro; husky; husky; en_US; 719358530',
+    }
+
+    it('returns null when no device is stored', async () => {
+      const manager = setup()
+      expect(await manager.loadDevice()).toBeNull()
+    })
+
+    it('persists and reloads the same device', async () => {
+      const manager = setup()
+      await manager.saveDevice(device)
+      expect(await manager.loadDevice()).toEqual(device)
+    })
+
+    it('shares one device across accounts (machine-level, not per-account)', async () => {
+      const manager = setup()
+      await manager.saveDevice(device)
+      await manager.setAccount(makeAccount({ account_id: 'a' }))
+      await manager.setAccount(makeAccount({ account_id: 'b' }))
+      expect(await manager.loadDevice()).toEqual(device)
+    })
+  })
 })

package/src/platforms/instagram/credential-manager.ts

@@ -3,17 +3,39 @@ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import { getConfigDir } from '../../shared/utils/config-dir'
-import { createAccountId, type InstagramAccount, type InstagramAccountPaths, type InstagramConfig } from './types'
+import {
+  createAccountId,
+  type InstagramAccount,
+  type InstagramAccountPaths,
+  type InstagramConfig,
+  type InstagramDevice,
+} from './types'
 
 export class InstagramCredentialManager {
   private configDir: string
   private credentialsPath: string
   private instagramRootDir: string
+  private devicePath: string
 
   constructor(configDir?: string) {
     this.configDir = configDir ?? getConfigDir()
     this.credentialsPath = join(this.configDir, 'instagram-credentials.json')
     this.instagramRootDir = join(this.configDir, 'instagram')
+    this.devicePath = join(this.instagramRootDir, 'device.json')
+  }
+
+  async loadDevice(): Promise<InstagramDevice | null> {
+    if (!existsSync(this.devicePath)) return null
+    try {
+      return JSON.parse(await readFile(this.devicePath, 'utf-8')) as InstagramDevice
+    } catch {
+      return null
+    }
+  }
+
+  async saveDevice(device: InstagramDevice): Promise<void> {
+    await mkdir(this.instagramRootDir, { recursive: true })
+    await writeFile(this.devicePath, JSON.stringify(device, null, 2), { mode: 0o600 })
   }
 
   async loadConfig(): Promise<InstagramConfig> {

package/src/platforms/instagram/types.ts

@@ -60,19 +60,22 @@ export interface InstagramMessageSummary {
   media_url?: string
 }
 
+export interface InstagramDevice {
+  phone_id: string
+  uuid: string
+  android_device_id: string
+  advertising_id: string
+  client_session_id: string
+  device_string: string
+}
+
 export interface InstagramSessionState {
   cookies: string
-  device: {
-    phone_id: string
-    uuid: string
-    android_device_id: string
-    advertising_id: string
-    client_session_id: string
-    device_string: string
-  }
+  device: InstagramDevice
   authorization?: string
   user_id?: string
   mid?: string
+  www_claim?: string
   challenge_path?: string
 }
 

package/src/platforms/teams/app-config.ts

@@ -0,0 +1,92 @@
+import type { TeamsAccountType } from './types'
+
+export const TEAMS_DESKTOP_CLIENT_ID = '1fec8e78-bce4-4aaf-ab1b-5451cc387264'
+export const TEAMS_WEB_CLIENT_ID = '5e3ce6c0-2b1f-4285-8d4b-75ee78787346'
+
+export const CONSUMER_TENANT_ID = '9188040d-6c67-4c5b-b112-36a304b66dad'
+// The Microsoft Services (MSA passthrough) tenant. Consumer/MSA tokens for the
+// Skype resource carry this `tid`, so it is a placeholder that still requires
+// tenant discovery before the skype-token exchange.
+export const MICROSOFT_SERVICES_TENANT_ID = 'f8cdef31-a31e-4b4a-93e4-5f571e91255a'
+export const WORK_TENANT_ID = 'organizations'
+
+export const DEVICE_CODE_SCOPE_TEAMS = 'service::api.fl.teams.microsoft.com::MBI_SSL openid profile offline_access'
+export const DEVICE_CODE_SCOPE_SKYPE = 'service::api.fl.spaces.skype.com::MBI_SSL openid profile offline_access'
+export const WORK_DEVICE_CODE_SCOPE_TEAMS = 'https://api.spaces.skype.com/.default openid profile offline_access'
+export const WORK_DEVICE_CODE_SCOPE_SKYPE = 'https://api.spaces.skype.com/.default openid profile offline_access'
+
+export const SUBSTRATE_SEARCH_URL = 'https://substrate.office.com/searchservice/api/v2/query'
+export const TEAMS_WEB_ORIGIN = 'https://teams.microsoft.com'
+export const AAD_SCOPE_SUBSTRATE = 'https://substrate.office.com/.default offline_access'
+export const AAD_SCOPE_GRAPH = 'https://graph.microsoft.com/.default offline_access'
+export const AAD_AUDIENCE_SUBSTRATE = 'https://substrate.office.com'
+export const AAD_AUDIENCE_GRAPH = 'https://graph.microsoft.com'
+
+export const AUTHZ_CONSUMER_URL = 'https://teams.live.com/api/auth/v1.0/authz/consumer'
+export const AUTHZ_WORK_URL = 'https://teams.microsoft.com/api/authsvc/v1.0/authz'
+
+// Control-plane tenant-discovery endpoint. The region segment is not
+// authoritative for this call (it lists every tenant the user belongs to
+// regardless of home region), so we pin the value fossteams uses.
+export const TEAMS_TENANTS_URL = 'https://teams.microsoft.com/api/mt/emea/beta/users/tenants'
+
+export const GET_CREDENTIAL_TYPE_URL = 'https://login.microsoftonline.com/common/GetCredentialType'
+
+export function consumerDeviceCodeUrl(): string {
+  return `https://login.microsoftonline.com/${CONSUMER_TENANT_ID}/oauth2/v2.0/devicecode`
+}
+
+export function consumerTokenUrl(): string {
+  return `https://login.microsoftonline.com/${CONSUMER_TENANT_ID}/oauth2/v2.0/token`
+}
+
+export function organizationsDeviceCodeUrl(): string {
+  return `https://login.microsoftonline.com/${WORK_TENANT_ID}/oauth2/v2.0/devicecode`
+}
+
+export function organizationsTokenUrl(): string {
+  return `https://login.microsoftonline.com/${WORK_TENANT_ID}/oauth2/v2.0/token`
+}
+
+export function tenantTokenUrl(tenantId: string): string {
+  return `https://login.microsoftonline.com/${tenantId}/oauth2/v2.0/token`
+}
+
+export function deviceCodeUrl(accountType: TeamsAccountType): string {
+  return accountType === 'personal' ? consumerDeviceCodeUrl() : organizationsDeviceCodeUrl()
+}
+
+export function deviceCodeTokenUrl(accountType: TeamsAccountType, tenantId?: string): string {
+  if (tenantId) return tenantTokenUrl(tenantId)
+  return accountType === 'personal' ? consumerTokenUrl() : organizationsTokenUrl()
+}
+
+export function deviceCodeTeamsScope(accountType: TeamsAccountType): string {
+  return accountType === 'personal' ? DEVICE_CODE_SCOPE_TEAMS : WORK_DEVICE_CODE_SCOPE_TEAMS
+}
+
+export function deviceCodeSkypeScope(accountType: TeamsAccountType): string {
+  return accountType === 'personal' ? DEVICE_CODE_SCOPE_SKYPE : WORK_DEVICE_CODE_SCOPE_SKYPE
+}
+
+export function authzUrl(accountType: TeamsAccountType): string {
+  return accountType === 'personal' ? AUTHZ_CONSUMER_URL : AUTHZ_WORK_URL
+}
+
+export interface TeamsAppClient {
+  clientId: string
+  source: 'env' | 'builtin'
+}
+
+function parseTrimmed(value: string | undefined): string | undefined {
+  const normalized = value?.trim()
+  return normalized ? normalized : undefined
+}
+
+export function getTeamsAppClientId(accountType: TeamsAccountType = 'personal'): TeamsAppClient {
+  const envClientId = parseTrimmed(process.env.AGENT_TEAMS_CLIENT_ID)
+  if (envClientId) {
+    return { clientId: envClientId, source: 'env' }
+  }
+  return { clientId: accountType === 'work' ? TEAMS_DESKTOP_CLIENT_ID : TEAMS_WEB_CLIENT_ID, source: 'builtin' }
+}