agent-messenger 2.22.0 → 2.23.0

package/src/platforms/webex/password-login.ts

@@ -0,0 +1,332 @@
+import { createHash, randomBytes } from 'node:crypto'
+
+import { WebexError } from './types'
+
+export const WEB_CLIENT_ID = 'C64ab04639eefee4798f58e7bc3fe01d47161be0d97ff0d31e040a6ffe66d7f0a'
+export const WEB_CLIENT_SECRET = 'f4261a01a4111b3b3b1710583073cae9cd7104517e7f78800c43d01eea133782'
+
+const REDIRECT_URI = 'https://web.webex.com'
+const DEFAULT_IDBROKER_HOST = 'https://idbroker.webex.com'
+const SCOPE =
+  'webexsquare:get_conversation Identity:SCIM identity:things_read spark:kms spark:people_read spark:people_write spark:organizations_read spark:rooms_read spark:rooms_write spark:memberships_read spark:calls_read spark:calls_write webexsquare:admin'
+const U2C_URL = 'https://u2c.svc.webex.com/u2c/api/v1/limited/catalog'
+const MAX_REDIRECTS = 12
+
+export interface PasswordLoginOptions {
+  idbrokerHost?: string
+}
+
+export interface PasswordLoginResult {
+  accessToken: string
+  refreshToken: string
+  expiresAt: number
+  deviceUrl: string
+  userId: string
+}
+
+interface TokenResponse {
+  access_token: string
+  refresh_token: string
+  expires_in: number
+  refresh_token_expires_in?: number
+  scope?: string
+  token_type?: string
+}
+
+interface U2CDiscovery {
+  idbrokerHost: string
+  wdmHost?: string
+}
+
+interface RedirectResult {
+  response: Response
+  url: string
+}
+
+export async function loginWithPassword(
+  email: string,
+  password: string,
+  options?: PasswordLoginOptions,
+): Promise<PasswordLoginResult> {
+  const normalizedEmail = email.toLowerCase()
+  const emailHash = sha256Hex(normalizedEmail)
+  const discovery = await discoverU2C(emailHash)
+  const idbrokerHost = normalizeOrigin(options?.idbrokerHost ?? discovery.idbrokerHost)
+  const pkce = createPkcePair()
+  const state = base64url(Buffer.from(JSON.stringify({ csrf_token: crypto.randomUUID(), emailhash: emailHash })))
+  const cookieJar = new CookieJar()
+
+  const authorizeUrl = `${idbrokerHost}/idb/oauth2/v1/authorize?${new URLSearchParams({
+    response_type: 'code',
+    cisKeepMeSignedInOption: '1',
+    state,
+    cisService: 'webex',
+    emailHash,
+    code_challenge: pkce.challenge,
+    code_challenge_method: 'S256',
+    client_id: WEB_CLIENT_ID,
+    redirect_uri: REDIRECT_URI,
+    scope: SCOPE,
+  }).toString()}`
+
+  const authorizeResult = await followRedirects(authorizeUrl, { method: 'GET' }, cookieJar)
+  const clusterHost = new URL(authorizeResult.url).origin
+  // Reject before touching credentials: if authorize redirected off Webex (an SSO
+  // IdP), posting IDToken1/IDToken2 here would leak the password to that host.
+  if (!isWebexHost(new URL(clusterHost).host)) {
+    throw new WebexError('SSO/IdP login is not supported for headless password login', 'sso_required')
+  }
+  const loginPageHtml = await authorizeResult.response.text()
+  const fields = parseInputFields(loginPageHtml)
+  fields.set('IDToken0', '')
+  fields.set('IDToken1', email)
+  fields.set('IDToken2', password)
+  fields.set('IDButton', 'Sign In')
+  fields.set('loginid', email)
+
+  const loginBody = new URLSearchParams()
+  for (const [key, value] of fields) loginBody.set(key, value)
+
+  const loginResult = await followRedirects(
+    `${clusterHost}/idb/UI/Login`,
+    {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: loginBody.toString(),
+    },
+    cookieJar,
+  )
+  const code = getAuthorizationCode(loginResult.url)
+
+  if (code === null) {
+    await throwLoginFailure(loginResult)
+    throw new WebexError('Login failed: invalid credentials or unexpected response', 'login_failed')
+  }
+
+  const token = await exchangeCode(clusterHost, code, pkce.verifier)
+  const device = await registerDevice(discovery.wdmHost, token.access_token)
+
+  return {
+    accessToken: token.access_token,
+    refreshToken: token.refresh_token,
+    expiresAt: Date.now() + token.expires_in * 1000,
+    deviceUrl: device.deviceUrl,
+    userId: device.userId,
+  }
+}
+
+export function createPkcePair(verifier?: string): { verifier: string; challenge: string } {
+  const resolvedVerifier = verifier ?? base64url(randomBytes(64))
+  return {
+    verifier: resolvedVerifier,
+    challenge: base64url(createHash('sha256').update(resolvedVerifier).digest()),
+  }
+}
+
+async function discoverU2C(emailHash: string): Promise<U2CDiscovery> {
+  try {
+    const url = `${U2C_URL}?${new URLSearchParams({ format: 'hostmap', emailhash: emailHash }).toString()}`
+    const response = await fetch(url)
+    if (!response.ok) return { idbrokerHost: DEFAULT_IDBROKER_HOST }
+    const catalog = (await response.json()) as { serviceLinks?: Record<string, string> }
+    // Match the exact `idbroker` serviceLink key: a substring scan would wrongly
+    // pick `idbroker-guest`, routing login to a cluster the user has no account on.
+    const links = catalog.serviceLinks ?? {}
+    return {
+      idbrokerHost: typeof links.idbroker === 'string' ? normalizeOrigin(links.idbroker) : DEFAULT_IDBROKER_HOST,
+      wdmHost: typeof links.wdm === 'string' ? normalizeOrigin(links.wdm) : undefined,
+    }
+  } catch {
+    return { idbrokerHost: DEFAULT_IDBROKER_HOST }
+  }
+}
+
+async function exchangeCode(clusterHost: string, code: string, verifier: string): Promise<TokenResponse> {
+  const response = await fetch(`${clusterHost}/idb/oauth2/v1/access_token`, {
+    method: 'POST',
+    headers: {
+      Authorization: `Basic ${Buffer.from(`${WEB_CLIENT_ID}:${WEB_CLIENT_SECRET}`).toString('base64')}`,
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+    body: new URLSearchParams({
+      grant_type: 'authorization_code',
+      redirect_uri: REDIRECT_URI,
+      code,
+      code_verifier: verifier,
+      self_contained_token: 'true',
+    }).toString(),
+  })
+
+  if (!response.ok) {
+    throw new WebexError(`Token exchange failed: HTTP ${response.status}`, 'token_exchange_failed')
+  }
+
+  const token = (await response.json()) as Partial<TokenResponse>
+  if (!token.access_token || !token.refresh_token || typeof token.expires_in !== 'number') {
+    throw new WebexError('Token exchange failed: incomplete response', 'token_exchange_failed')
+  }
+
+  return token as TokenResponse
+}
+
+async function registerDevice(
+  wdmHost: string | undefined,
+  accessToken: string,
+): Promise<{ deviceUrl: string; userId: string }> {
+  // deviceUrl is required: without it WebexClient falls back to the plaintext
+  // public API instead of the internal KMS-encrypted path password tokens need.
+  if (!wdmHost) {
+    throw new WebexError('Webex device registration service was not found in the catalog', 'device_registration_failed')
+  }
+
+  const response = await fetch(`${normalizeOrigin(wdmHost)}/wdm/api/v1/devices`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${accessToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      deviceName: 'agent-messenger',
+      name: 'agent-messenger',
+      deviceType: 'UNKNOWN',
+      model: 'agent-messenger',
+      localizedModel: 'agent-messenger',
+      systemName: 'agent-messenger',
+      systemVersion: '1.0',
+    }),
+  })
+  if (!response.ok) {
+    throw new WebexError(`Webex device registration failed: HTTP ${response.status}`, 'device_registration_failed')
+  }
+  const data = (await response.json()) as { url?: string; userId?: string }
+  if (!data.url || !data.userId) {
+    throw new WebexError('Webex device registration returned an incomplete device', 'device_registration_failed')
+  }
+  return { deviceUrl: data.url, userId: data.userId }
+}
+
+async function followRedirects(url: string, init: RequestInit, cookieJar: CookieJar): Promise<RedirectResult> {
+  let currentUrl = url
+  let response = await fetchWithCookies(currentUrl, init, cookieJar)
+  let redirects = 0
+
+  while (isRedirect(response) && redirects++ < MAX_REDIRECTS) {
+    const location = response.headers.get('location')
+    if (!location) break
+    currentUrl = new URL(location, currentUrl).toString()
+    if (currentUrl.startsWith(REDIRECT_URI) && /[?&]code=/.test(currentUrl)) {
+      return { response, url: currentUrl }
+    }
+    response = await fetchWithCookies(currentUrl, { method: 'GET' }, cookieJar)
+  }
+
+  return { response, url: currentUrl }
+}
+
+async function fetchWithCookies(url: string, init: RequestInit, cookieJar: CookieJar): Promise<Response> {
+  const headers = new Headers(init.headers)
+  // Only attach/store session cookies on Webex hosts so a redirect to an external
+  // IdP (SSO) never receives the Webex session cookies.
+  const isWebex = isWebexHost(new URL(url).host)
+  const cookie = cookieJar.header()
+  if (cookie && isWebex) headers.set('Cookie', cookie)
+  const response = await fetch(url, { ...init, redirect: 'manual', headers })
+  if (isWebex) cookieJar.apply(response)
+  return response
+}
+
+function parseInputFields(html: string): Map<string, string> {
+  const fields = new Map<string, string>()
+  for (const input of html.match(/<input[^>]*>/gi) ?? []) {
+    const attrs = parseAttributes(input)
+    const name = attrs.get('name')
+    if (name && !fields.has(name)) {
+      fields.set(name, decodeEntities(attrs.get('value') ?? ''))
+    }
+  }
+  return fields
+}
+
+function parseAttributes(tag: string): Map<string, string> {
+  const attrs = new Map<string, string>()
+  const attrPattern = /([:\w-]+)\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/g
+  let match = attrPattern.exec(tag)
+  while (match) {
+    const rawValue = match[2]
+    const value = rawValue.startsWith('"') || rawValue.startsWith("'") ? rawValue.slice(1, -1) : rawValue
+    attrs.set(match[1], decodeEntities(value))
+    match = attrPattern.exec(tag)
+  }
+  return attrs
+}
+
+function decodeEntities(value: string): string {
+  return value
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex: string) => String.fromCodePoint(parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, decimal: string) => String.fromCodePoint(parseInt(decimal, 10)))
+    .replace(/&amp;/g, '&')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+}
+
+async function throwLoginFailure(loginResult: RedirectResult): Promise<never> {
+  const finalHost = new URL(loginResult.url).host
+  if (!isWebexHost(finalHost)) {
+    throw new WebexError('SSO/IdP login is not supported for headless password login', 'sso_required')
+  }
+
+  const html = await loginResult.response.text()
+  if (/verification code|passcode|one-time|security code|\bOTP\b|\bMFA\b/i.test(html)) {
+    throw new WebexError('Account requires MFA; headless password login is not supported', 'mfa_required')
+  }
+
+  throw new WebexError('Login failed: invalid credentials or unexpected response', 'login_failed')
+}
+
+function getAuthorizationCode(url: string): string | null {
+  const code = new URL(url).searchParams.get('code')
+  return code ? decodeURIComponent(code) : null
+}
+
+function isRedirect(response: Response): boolean {
+  return response.status >= 300 && response.status < 400
+}
+
+function isWebexHost(host: string): boolean {
+  return host === 'webex.com' || host.endsWith('.webex.com') || host === 'wbx2.com' || host.endsWith('.wbx2.com')
+}
+
+function normalizeOrigin(value: string): string {
+  return new URL(value).origin
+}
+
+function sha256Hex(value: string): string {
+  return createHash('sha256').update(value).digest('hex')
+}
+
+function base64url(buffer: Buffer): string {
+  return buffer.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+class CookieJar {
+  private cookies = new Map<string, string>()
+
+  apply(response: Response): void {
+    for (const cookie of getSetCookies(response.headers)) {
+      const [pair] = cookie.split(';')
+      const index = pair.indexOf('=')
+      if (index > 0) this.cookies.set(pair.slice(0, index).trim(), pair.slice(index + 1).trim())
+    }
+  }
+
+  header(): string {
+    return [...this.cookies.entries()].map(([key, value]) => `${key}=${value}`).join('; ')
+  }
+}
+
+function getSetCookies(headers: Headers): string[] {
+  const headersWithSetCookie = headers as Headers & { getSetCookie?: () => string[] }
+  const cookies = headersWithSetCookie.getSetCookie?.()
+  if (cookies?.length) return cookies
+  const single = headers.get('set-cookie')
+  return single ? [single] : []
+}

package/src/platforms/webex/types.test.ts

@@ -266,6 +266,22 @@ it('WebexConfigSchema validates config with tokenType manual', () => {
   }
 })
 
+it('WebexConfigSchema validates config with tokenType password', () => {
+  const result = WebexConfigSchema.safeParse({
+    accessToken: 'test',
+    refreshToken: 'test',
+    expiresAt: 1234567890,
+    tokenType: 'password',
+    deviceUrl: 'https://wdm-test.wbx2.com/wdm/api/v1/devices/device-1',
+    userId: 'user-1',
+    encryptionKeys: {},
+  })
+  expect(result.success).toBe(true)
+  if (result.success) {
+    expect(result.data.tokenType).toBe('password')
+  }
+})
+
 it('WebexConfigSchema rejects invalid tokenType', () => {
   const result = WebexConfigSchema.safeParse({
     accessToken: 'test',

package/src/platforms/webex/types.ts

@@ -55,7 +55,7 @@ export interface WebexConfig {
   expiresAt: number
   clientId?: string
   clientSecret?: string
-  tokenType?: 'oauth' | 'manual' | 'extracted'
+  tokenType?: 'oauth' | 'manual' | 'extracted' | 'password'
   deviceUrl?: string
   userId?: string
   encryptionKeys?: Record<string, string>
@@ -126,7 +126,7 @@ export const WebexConfigSchema = z.object({
   expiresAt: z.number(),
   clientId: z.string().optional(),
   clientSecret: z.string().optional(),
-  tokenType: z.enum(['oauth', 'manual', 'extracted']).optional(),
+  tokenType: z.enum(['oauth', 'manual', 'extracted', 'password']).optional(),
   deviceUrl: z.string().optional(),
   userId: z.string().optional(),
   encryptionKeys: z.record(z.string(), z.string()).optional(),

package/src/platforms/{webexbot → webex}/wdm-discovery.ts

@@ -1,6 +1,6 @@
 import type { FetchFunction, FetchRequest, FetchResponse } from 'webex-message-handler'
 
-import { WebexBotError } from './types'
+import { WebexError } from './types'
 
 const U2C_CATALOG_URL = 'https://u2c.wbx2.com/u2c/api/v1/catalog?format=hostmap'
 const HARDCODED_WDM_DEVICES_URL = 'https://wdm-a.wbx2.com/wdm/api/v1/devices'
@@ -14,13 +14,13 @@ const HARDCODED_WDM_DEVICES_URL = 'https://wdm-a.wbx2.com/wdm/api/v1/devices'
 export async function discoverWdmDevicesUrl(token: string): Promise<string> {
   const response = await fetch(U2C_CATALOG_URL, { headers: { Authorization: `Bearer ${token}` } })
   if (!response.ok) {
-    throw new WebexBotError(`Failed to discover Webex WDM cluster: HTTP ${response.status}`, 'wdm_discovery_failed')
+    throw new WebexError(`Failed to discover Webex WDM cluster: HTTP ${response.status}`, 'wdm_discovery_failed')
   }
 
   const catalog = (await response.json()) as { serviceLinks?: { wdm?: string } }
   const wdm = catalog.serviceLinks?.wdm
   if (!wdm) {
-    throw new WebexBotError('Webex U2C catalog did not include serviceLinks.wdm', 'wdm_discovery_failed')
+    throw new WebexError('Webex U2C catalog did not include serviceLinks.wdm', 'wdm_discovery_failed')
   }
 
   return `${wdm.replace(/\/$/, '')}/devices`

package/src/platforms/webexbot/client.test.ts

@@ -1,5 +1,6 @@
-import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, it, spyOn } from 'bun:test'
 
+import { toRestId } from '../webex/id-normalizer'
 import { WebexBotClient } from './client'
 
 describe('WebexBotClient', () => {
@@ -195,4 +196,127 @@ describe('WebexBotClient', () => {
       expect(result.filename).toBe('passwd')
     })
   })
+
+  describe('room cluster resolution', () => {
+    const roomUuid = '12345678-1234-1234-1234-1234567890ab'
+    const usRoomId = toRestId(roomUuid, 'ROOM')
+    const clusteredRoomId = Buffer.from(`ciscospark://urn:TEAM:us-west-2_r/ROOM/${roomUuid}`).toString('base64url')
+
+    const isRoomsList = (url: string) => new URL(url).pathname === '/v1/rooms'
+
+    const clusteredId = (uuid: string) =>
+      Buffer.from(`ciscospark://urn:TEAM:us-west-2_r/ROOM/${uuid}`).toString('base64url')
+
+    const mockRoomsPage = (items: unknown[], nextCursor?: string) => {
+      const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+      if (nextCursor) headers.Link = `<https://webexapis.com/v1/rooms?max=1000&before=${nextCursor}>; rel="next"`
+      fetchResponses.push(new Response(JSON.stringify({ items }), { status: 200, headers }))
+    }
+
+    it('rewrites a us-cluster roomId to the real urn:TEAM id before sending', async () => {
+      // given a non-default-cluster room only reachable via its clustered id
+      mockResponse({ items: [{ id: clusteredRoomId, title: 'Team', type: 'group' }] })
+      mockResponse({ id: 'msg-1', roomId: clusteredRoomId, roomType: 'group' })
+
+      // when sending to the us-flattened id the listener emitted
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await client.sendMessage(usRoomId, 'hello')
+
+      // then the lookup runs and the send targets the corrected clustered id
+      expect(isRoomsList(fetchCalls[0].url)).toBe(true)
+      const body = JSON.parse(fetchCalls[1].options?.body as string)
+      expect(body.roomId).toBe(clusteredRoomId)
+    })
+
+    it('routes listMemberships through the corrected clustered id', async () => {
+      mockResponse({ items: [{ id: clusteredRoomId, type: 'group' }] })
+      mockResponse({ items: [{ id: 'm1', roomId: clusteredRoomId, personId: 'p1' }] })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await client.listMemberships(usRoomId)
+
+      const membershipsUrl = new URL(fetchCalls[1].url)
+      expect(membershipsUrl.pathname).toBe('/v1/memberships')
+      expect(membershipsUrl.searchParams.get('roomId')).toBe(clusteredRoomId)
+    })
+
+    it('routes listMessages and its space lookup through the corrected clustered id', async () => {
+      mockResponse({ items: [{ id: clusteredRoomId, type: 'group' }] })
+      mockResponse({ id: clusteredRoomId, title: 'Team', type: 'group' })
+      mockResponse({ items: [{ id: 'msg-1', roomId: clusteredRoomId, roomType: 'group' }] })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await client.listMessages(usRoomId, { max: 5 })
+
+      expect(fetchCalls[1].url).toBe(`https://webexapis.com/v1/rooms/${clusteredRoomId}`)
+      const messagesUrl = new URL(fetchCalls[2].url)
+      expect(messagesUrl.searchParams.get('roomId')).toBe(clusteredRoomId)
+    })
+
+    it('passes an already-clustered roomId through without a lookup', async () => {
+      mockResponse({ id: 'msg-1', roomId: clusteredRoomId, roomType: 'group' })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await client.sendMessage(clusteredRoomId, 'hi')
+
+      expect(fetchCalls).toHaveLength(1)
+      expect(new URL(fetchCalls[0].url).pathname).toBe('/v1/messages')
+      expect(JSON.parse(fetchCalls[0].options?.body as string).roomId).toBe(clusteredRoomId)
+    })
+
+    it('caches the resolution so repeated calls trigger one room lookup', async () => {
+      mockResponse({ items: [{ id: clusteredRoomId, type: 'group' }] })
+      mockResponse({ id: 'msg-1', roomId: clusteredRoomId })
+      mockResponse({ id: 'msg-2', roomId: clusteredRoomId })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await client.sendMessage(usRoomId, 'a')
+      await client.sendMessage(usRoomId, 'b')
+
+      expect(fetchCalls.filter((c) => isRoomsList(c.url))).toHaveLength(1)
+    })
+
+    it('follows Link pages until the room is found on a later page', async () => {
+      // given the matching room is only on the second page
+      mockRoomsPage([{ id: clusteredId('00000000-0000-0000-0000-000000000000'), type: 'group' }], 'cursor1')
+      mockRoomsPage([{ id: clusteredRoomId, type: 'group' }])
+      mockResponse({ id: 'msg-1', roomId: clusteredRoomId, roomType: 'group' })
+
+      // when sending to a room not present on the first page
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await client.sendMessage(usRoomId, 'hi')
+
+      // then the second page is fetched via the Link cursor and the send targets the match
+      expect(isRoomsList(fetchCalls[0].url)).toBe(true)
+      expect(isRoomsList(fetchCalls[1].url)).toBe(true)
+      expect(fetchCalls[1].url).toContain('before=cursor1')
+      expect(JSON.parse(fetchCalls[2].options?.body as string).roomId).toBe(clusteredRoomId)
+    })
+
+    it('stops paging once the room is found and does not fetch later pages', async () => {
+      // given a first page that already contains the match but still advertises a next page
+      mockRoomsPage([{ id: clusteredRoomId, type: 'group' }], 'cursor1')
+      mockResponse({ id: 'msg-1', roomId: clusteredRoomId, roomType: 'group' })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await client.sendMessage(usRoomId, 'hi')
+
+      // then only the first page is fetched (a second page fetch would hit the unmocked response and throw)
+      expect(fetchCalls.filter((c) => isRoomsList(c.url))).toHaveLength(1)
+      expect(JSON.parse(fetchCalls[1].options?.body as string).roomId).toBe(clusteredRoomId)
+    })
+
+    it('fails open to the un-clustered id and warns when no room matches', async () => {
+      const warnSpy = spyOn(console, 'warn').mockImplementation(() => {})
+      mockResponse({ items: [] })
+      mockResponse({ id: 'msg-1', roomId: usRoomId })
+
+      const client = await new WebexBotClient().login({ token: 'bot-token' })
+      await expect(client.sendMessage(usRoomId, 'x')).resolves.toBeDefined()
+
+      expect(JSON.parse(fetchCalls[1].options?.body as string).roomId).toBe(usRoomId)
+      expect(warnSpy).toHaveBeenCalled()
+      warnSpy.mockRestore()
+    })
+  })
 })

package/src/platforms/webexbot/client.ts

@@ -2,10 +2,33 @@ import { WebexClient } from '../webex/client'
 import type { WebexMembership, WebexMessage, WebexPerson, WebexSpace } from '../webex/types'
 import { WebexBotError } from './types'
 
+interface DecodedWebexId {
+  cluster: string
+  type: string
+  uuid: string
+}
+
+// Webex REST ids are base64(url) of `ciscospark://<cluster>/<TYPE>/<uuid>`; the
+// cluster correction needs all three parts, not just the <uuid> `fromRestId` returns.
+function decodeWebexId(restId: string): DecodedWebexId | null {
+  if (!restId) return null
+  const decoded = Buffer.from(restId, 'base64').toString('utf-8')
+  const match = decoded.match(/^ciscospark:\/\/([^/]+)\/([^/]+)\/(.+)$/)
+  if (!match) return null
+  return { cluster: match[1], type: match[2], uuid: match[3] }
+}
+
 export class WebexBotClient {
   private client = new WebexClient()
   private token: string | null = null
 
+  // The listener flattens room ids to `ciscospark://us/ROOM/<uuid>`, but team/group
+  // rooms live on `ciscospark://urn:TEAM:<cluster>/ROOM/<uuid>` — a cluster the bare
+  // uuid cannot recover. Cache the real clustered id per uuid and dedupe concurrent
+  // lookups so a burst of calls triggers a single `listSpaces`.
+  private clusteredRoomIds = new Map<string, string>()
+  private roomIdLookups = new Map<string, Promise<string>>()
+
   async login(credentials?: { token: string }): Promise<this> {
     if (credentials) {
       if (!credentials.token) {
@@ -41,7 +64,7 @@ export class WebexBotClient {
   }
 
   async getSpace(spaceId: string): Promise<WebexSpace> {
-    return this.client.getSpace(spaceId)
+    return this.client.getSpace(await this.resolveRoomId(spaceId))
   }
 
   async sendMessage(
@@ -49,7 +72,7 @@ export class WebexBotClient {
     text: string,
     options?: { markdown?: boolean; parentId?: string; files?: string[] },
   ): Promise<WebexMessage> {
-    return this.client.sendMessage(roomId, text, options)
+    return this.client.sendMessage(await this.resolveRoomId(roomId), text, options)
   }
 
   async sendDirectMessage(personEmail: string, text: string, options?: { markdown?: boolean }): Promise<WebexMessage> {
@@ -57,16 +80,21 @@ export class WebexBotClient {
   }
 
   async listMessages(roomId: string, options?: { max?: number; parentId?: string }): Promise<WebexMessage[]> {
-    const space = await this.client.getSpace(roomId)
+    const resolvedRoomId = await this.resolveRoomId(roomId)
+    const space = await this.client.getSpace(resolvedRoomId)
     const messageOptions = space.type === 'group' ? { ...options, mentionedPeople: 'me' } : options
-    return this.client.listMessages(roomId, messageOptions)
+    return this.client.listMessages(resolvedRoomId, messageOptions)
   }
 
   async listReplies(roomId: string, parentId: string, options?: { max?: number }): Promise<WebexMessage[]> {
-    return this.client.listMessages(roomId, { ...options, parentId })
+    return this.client.listMessages(await this.resolveRoomId(roomId), { ...options, parentId })
   }
 
   async getMessage(messageId: string): Promise<WebexMessage> {
+    // MESSAGE ids carry their parent room's cluster, which the bare-UUID normalizer
+    // also flattens to `us`. Correcting that needs the room context, which a lone
+    // messageId does not provide; room-keyed calls (the reported failures) are
+    // corrected via resolveRoomId instead.
     return this.client.getMessage(messageId)
   }
 
@@ -80,7 +108,7 @@ export class WebexBotClient {
     text: string,
     options?: { markdown?: boolean },
   ): Promise<WebexMessage> {
-    return this.client.editMessage(messageId, roomId, text, options)
+    return this.client.editMessage(messageId, await this.resolveRoomId(roomId), text, options)
   }
 
   async listPeople(options?: { email?: string; displayName?: string; max?: number }): Promise<WebexPerson[]> {
@@ -96,7 +124,7 @@ export class WebexBotClient {
   }
 
   async listMemberships(roomId: string, options?: { max?: number }): Promise<WebexMembership[]> {
-    return this.client.listMemberships(roomId, options)
+    return this.client.listMemberships(await this.resolveRoomId(roomId), options)
   }
 
   async uploadFile(
@@ -104,10 +132,53 @@ export class WebexBotClient {
     file: { content: Blob; filename: string },
     options?: { text?: string; markdown?: boolean; parentId?: string },
   ): Promise<WebexMessage> {
-    return this.client.uploadFile(roomId, file, options)
+    return this.client.uploadFile(await this.resolveRoomId(roomId), file, options)
   }
 
   async downloadContent(contentRef: string): Promise<{ data: ArrayBuffer; filename: string; contentType: string }> {
     return this.client.downloadContent(contentRef)
   }
+
+  private async resolveRoomId(roomId: string): Promise<string> {
+    const decoded = decodeWebexId(roomId)
+    // Already cluster-qualified or undecodable: nothing to correct.
+    if (!decoded || decoded.cluster.startsWith('urn:')) return roomId
+
+    const { uuid } = decoded
+    const cached = this.clusteredRoomIds.get(uuid)
+    if (cached) return cached
+
+    const inFlight = this.roomIdLookups.get(uuid)
+    if (inFlight) return inFlight
+
+    const lookup = this.lookupRoomId(uuid, roomId)
+    this.roomIdLookups.set(uuid, lookup)
+    try {
+      return await lookup
+    } finally {
+      this.roomIdLookups.delete(uuid)
+    }
+  }
+
+  private async lookupRoomId(uuid: string, fallback: string): Promise<string> {
+    try {
+      // Page through every room the bot belongs to (largest page size, following
+      // `Link` pages), stopping as soon as the trailing UUID matches.
+      for await (const room of this.client.iterateSpaces({ max: 1000 })) {
+        if (decodeWebexId(room.id)?.uuid === uuid) {
+          this.clusteredRoomIds.set(uuid, room.id)
+          return room.id
+        }
+      }
+    } catch {
+      // Network/auth failure: fail open to the un-corrected id rather than block the call.
+      return fallback
+    }
+
+    console.warn(
+      `[webexbot] Could not resolve clustered room id for ${uuid}; falling back to the un-clustered id. ` +
+        'Room-scoped calls may fail if this room lives on a non-default Webex cluster.',
+    )
+    return fallback
+  }
 }