agent-messenger 2.8.0 → 2.10.0

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

@@ -1,6 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
 
+import * as jose from 'node-jose'
+
 import { WebexClient } from './client'
+import { WebexEncryptionService } from './encryption'
 import { WebexError } from './types'
 
 describe('WebexClient', () => {
@@ -56,6 +59,17 @@ describe('WebexClient', () => {
       await expect(new WebexClient().login({ token: '' })).rejects.toThrow(WebexError)
       await expect(new WebexClient().login({ token: '' })).rejects.toThrow('Token is required')
     })
+
+    test('accepts deviceUrl and tokenType', async () => {
+      const client = await new WebexClient().login({
+        token: 'test-token',
+        deviceUrl: 'https://wdm-r.wbx2.com/wdm/api/v1/devices/dev-1',
+        tokenType: 'extracted',
+      })
+      expect(client).toBeInstanceOf(WebexClient)
+      expect((client as any).deviceUrl).toBe('https://wdm-r.wbx2.com/wdm/api/v1/devices/dev-1')
+      expect((client as any).tokenType).toBe('extracted')
+    })
   })
 
   describe('testAuth', () => {
@@ -84,6 +98,59 @@ describe('WebexClient', () => {
       const client = await new WebexClient().login({ token: 'bad-token' })
       await expect(client.testAuth()).rejects.toThrow(WebexError)
     })
+
+    test('falls back to internal API when public API fails for extracted tokens', async () => {
+      // given - public API rejects, internal API succeeds
+      mockResponse({ message: 'Unauthorized' }, 401)
+      fetchResponses.push(
+        new Response(JSON.stringify({ id: 'conv-1', activities: { items: [] } }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+      )
+
+      const client = await new WebexClient().login({
+        token: 'extracted-token',
+        deviceUrl: 'https://wdm-r.wbx2.com/wdm/api/v1/devices/dev-1',
+        tokenType: 'extracted',
+      })
+
+      // when
+      const person = await client.testAuth()
+
+      // then - succeeds via internal API
+      expect(fetchCalls.length).toBe(2)
+      expect(fetchCalls[0].url).toBe('https://webexapis.com/v1/people/me')
+      expect(fetchCalls[1].url).toContain('conv-r.wbx2.com/conversation/api/v1/conversations')
+      expect(person).toBeTruthy()
+    })
+
+    test('throws when both public and internal APIs fail for extracted tokens', async () => {
+      // given - both APIs reject
+      mockResponse({ message: 'Unauthorized' }, 401)
+      fetchResponses.push(
+        new Response(JSON.stringify({ message: 'Unauthorized' }), {
+          status: 401,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+      )
+
+      const client = await new WebexClient().login({
+        token: 'bad-extracted-token',
+        deviceUrl: 'https://wdm-r.wbx2.com/wdm/api/v1/devices/dev-1',
+        tokenType: 'extracted',
+      })
+
+      await expect(client.testAuth()).rejects.toThrow(WebexError)
+    })
+
+    test('does not use internal API fallback for non-extracted tokens', async () => {
+      mockResponse({ message: 'Unauthorized' }, 401)
+
+      const client = await new WebexClient().login({ token: 'bad-token' })
+      await expect(client.testAuth()).rejects.toThrow(WebexError)
+      expect(fetchCalls.length).toBe(1)
+    })
   })
 
   describe('listSpaces', () => {
@@ -402,10 +469,11 @@ describe('WebexClient', () => {
     })
 
     const createExtractedClient = async () => {
-      const client = await new WebexClient().login({ token: 'extracted-token' })
-      ;(client as any).deviceUrl = TEST_DEVICE_URL
-      ;(client as any).tokenType = 'extracted'
-      return client
+      return new WebexClient().login({
+        token: 'extracted-token',
+        deviceUrl: TEST_DEVICE_URL,
+        tokenType: 'extracted',
+      })
     }
 
     describe('sendMessage', () => {
@@ -419,7 +487,7 @@ describe('WebexClient', () => {
         expect(fetchCalls[0].options?.method).toBe('POST')
       })
 
-      test('body has verb, object type, displayName, and content', async () => {
+      test('body has verb, object type, and displayName (no content for plain text)', async () => {
         mockResponse(mockActivity('Hello world'))
 
         const client = await createExtractedClient()
@@ -429,7 +497,7 @@ describe('WebexClient', () => {
         expect(body.verb).toBe('post')
         expect(body.object.objectType).toBe('comment')
         expect(body.object.displayName).toBe('Hello world')
-        expect(body.object.content).toBe('Hello world')
+        expect(body.object.content).toBeUndefined()
       })
 
       test('body has target with decoded conv UUID and conversation type', async () => {
@@ -488,7 +556,7 @@ describe('WebexClient', () => {
         expect(body.object.markdown).toBeUndefined()
       })
 
-      test('markdown option does not affect plain text messages', async () => {
+      test('plain text messages omit content field', async () => {
         mockResponse(mockActivity('Hello world'))
 
         const client = await createExtractedClient()
@@ -496,7 +564,7 @@ describe('WebexClient', () => {
 
         const body = JSON.parse(fetchCalls[0].options?.body as string)
         expect(body.object.displayName).toBe('Hello world')
-        expect(body.object.content).toBe('Hello world')
+        expect(body.object.content).toBeUndefined()
       })
     })
 
@@ -620,8 +688,11 @@ describe('WebexClient', () => {
     })
 
     describe('editMessage', () => {
+      const mockEditActivity = (text: string, parentId = 'activity-123') =>
+        mockActivity(text, { parent: { id: parentId, type: 'edit' } })
+
       test('posts activity with verb post and parent edit reference', async () => {
-        mockResponse(mockActivity('Edited text'))
+        mockResponse(mockEditActivity('Edited text'))
 
         const client = await createExtractedClient()
         await client.editMessage('activity-123', TEST_ROOM_ID, 'Edited text')
@@ -631,8 +702,8 @@ describe('WebexClient', () => {
         expect(body.parent).toEqual({ id: 'activity-123', type: 'edit' })
       })
 
-      test('body has object with comment type and new text', async () => {
-        mockResponse(mockActivity('Edited text'))
+      test('plain text edit populates both displayName and content to avoid auto-tombstone', async () => {
+        mockResponse(mockEditActivity('Edited text'))
 
         const client = await createExtractedClient()
         await client.editMessage('activity-123', TEST_ROOM_ID, 'Edited text')
@@ -643,8 +714,18 @@ describe('WebexClient', () => {
         expect(body.object.content).toBe('Edited text')
       })
 
+      test('clientTempId uses -edit suffix to match Webex web client format', async () => {
+        mockResponse(mockEditActivity('Edited text'))
+
+        const client = await createExtractedClient()
+        await client.editMessage('activity-123', TEST_ROOM_ID, 'Edited text')
+
+        const body = JSON.parse(fetchCalls[0].options?.body as string)
+        expect(body.clientTempId).toMatch(/^tmp-\d+-edit$/)
+      })
+
       test('target has decoded conv UUID', async () => {
-        mockResponse(mockActivity('Edited text'))
+        mockResponse(mockEditActivity('Edited text'))
 
         const client = await createExtractedClient()
         await client.editMessage('activity-123', TEST_ROOM_ID, 'Edited text')
@@ -654,7 +735,7 @@ describe('WebexClient', () => {
       })
 
       test('markdown option converts content to HTML and strips displayName', async () => {
-        mockResponse(mockActivity('italic text'))
+        mockResponse(mockEditActivity('italic text'))
 
         const client = await createExtractedClient()
         await client.editMessage('activity-123', TEST_ROOM_ID, '_italic text_', { markdown: true })
@@ -664,6 +745,69 @@ describe('WebexClient', () => {
         expect(body.object.content).toBe('<em>italic text</em>')
         expect(body.object.markdown).toBeUndefined()
       })
+
+      test('tolerates responses that omit parent (minimal success shape)', async () => {
+        mockResponse(mockActivity('Edited text'))
+
+        const client = await createExtractedClient()
+        const message = await client.editMessage('activity-123', TEST_ROOM_ID, 'Edited text')
+        expect(message.id).toBe('activity-123')
+      })
+
+      test('throws when server returns activity linked to a different parent', async () => {
+        mockResponse(mockEditActivity('Edited text', 'activity-999'))
+
+        const client = await createExtractedClient()
+        await expect(client.editMessage('activity-123', TEST_ROOM_ID, 'Edited text')).rejects.toThrow(/Edit rejected/)
+      })
+    })
+
+    describe('encrypted send and edit', () => {
+      const TEST_KEY_URI = 'kms://kms-aore.wbx2.com/keys/test-key-id'
+
+      const decodeJweHeader = (jwe: string): Record<string, unknown> => {
+        const [header = ''] = jwe.split('.')
+        const padded = header + '='.repeat((4 - (header.length % 4)) % 4)
+        return JSON.parse(Buffer.from(padded, 'base64url').toString('utf8')) as Record<string, unknown>
+      }
+
+      const createEncryptedClient = async () => {
+        const keystore = jose.JWK.createKeyStore()
+        const key = await keystore.generate('oct', 256, { alg: 'A256GCM' })
+        const rawKeys = new Map<string, string>([[TEST_KEY_URI, JSON.stringify({ jwk: key.toJSON(true) })]])
+        const service = new WebexEncryptionService(rawKeys)
+        const client = await createExtractedClient()
+        ;(client as unknown as { encryption: WebexEncryptionService }).encryption = service
+        return client
+      }
+
+      test('plain text send omits content field on encrypted path (preserves prior fix)', async () => {
+        mockResponse({ id: TEST_CONV_UUID, defaultActivityEncryptionKeyUrl: TEST_KEY_URI })
+        mockResponse(mockActivity('Hello world'))
+
+        const client = await createEncryptedClient()
+        await client.sendMessage(TEST_ROOM_ID, 'Hello world')
+
+        const body = JSON.parse(fetchCalls[1].options?.body as string)
+        expect(body.object.content).toBeUndefined()
+        expect(body.object.displayName.startsWith('eyJ')).toBe(true)
+        expect(body.encryptionKeyUrl).toBe(TEST_KEY_URI)
+      })
+
+      test('plain text edit encrypts both displayName and content with kid in JWE header', async () => {
+        mockResponse({ id: TEST_CONV_UUID, defaultActivityEncryptionKeyUrl: TEST_KEY_URI })
+        mockResponse(mockActivity('Edited text', { parent: { id: 'activity-123', type: 'edit' } }))
+
+        const client = await createEncryptedClient()
+        await client.editMessage('activity-123', TEST_ROOM_ID, 'Edited text')
+
+        const body = JSON.parse(fetchCalls[1].options?.body as string)
+        expect(body.object.displayName.startsWith('eyJ')).toBe(true)
+        expect(body.object.content.startsWith('eyJ')).toBe(true)
+        expect(body.encryptionKeyUrl).toBe(TEST_KEY_URI)
+        expect(decodeJweHeader(body.object.displayName).kid).toBe(TEST_KEY_URI)
+        expect(decodeJweHeader(body.object.content).kid).toBe(TEST_KEY_URI)
+      })
     })
 
     describe('sendDirectMessage', () => {

package/src/platforms/webex/client.ts

@@ -21,12 +21,14 @@ export class WebexClient {
   private globalRateLimitUntil: number = 0
   private encryption: WebexEncryptionService | null = null
 
-  async login(credentials?: { token: string }): Promise<this> {
+  async login(credentials?: { token: string; deviceUrl?: string; tokenType?: string }): Promise<this> {
     if (credentials) {
       if (!credentials.token) {
         throw new WebexError('Token is required', 'missing_token')
       }
       this.token = credentials.token
+      if (credentials.deviceUrl !== undefined) this.deviceUrl = credentials.deviceUrl
+      if (credentials.tokenType !== undefined) this.tokenType = credentials.tokenType
       return this
     }
 
@@ -161,9 +163,28 @@ export class WebexClient {
   }
 
   async testAuth(): Promise<WebexPerson> {
+    if (this.useInternalAPI) {
+      try {
+        return await this.request<WebexPerson>('GET', '/people/me')
+      } catch (err) {
+        const isAuthError = err instanceof WebexError && (err.code === 'http_401' || err.code === 'http_403')
+        if (!isAuthError) throw err
+        await this.testAuthInternal()
+        return { id: '', emails: [], displayName: '', orgId: '', type: 'person', created: '' } as WebexPerson
+      }
+    }
     return this.request<WebexPerson>('GET', '/people/me')
   }
 
+  private async testAuthInternal(): Promise<void> {
+    if (!this.deviceUrl) {
+      throw new WebexError('No device URL available for internal API validation', 'no_device_url')
+    }
+    await this.internalRequest<InternalConversation>(
+      '/conversations?participantsLimit=0&activitiesLimit=0&conversationsLimit=1',
+    )
+  }
+
   async listSpaces(options?: { type?: string; max?: number }): Promise<WebexSpace[]> {
     const params = new URLSearchParams()
     if (options?.type) params.set('type', options.type)
@@ -248,10 +269,15 @@ export class WebexClient {
   private async buildEncryptedObject(
     convUuid: string,
     text: string,
-    options?: { markdown?: boolean },
+    options?: { markdown?: boolean; forEdit?: boolean },
   ): Promise<{ object: Record<string, string>; encryptionKeyUrl?: string }> {
     const displayName = options?.markdown ? stripMarkdown(text) : text
-    const content = options?.markdown ? markdownToHtml(text) : text
+    let content: string | undefined
+    if (options?.markdown) {
+      content = markdownToHtml(text)
+    } else if (options?.forEdit) {
+      content = text
+    }
 
     if (this.encryption) {
       const conv = await this.internalRequest<InternalConversation>(
@@ -260,21 +286,25 @@ export class WebexClient {
       const keyUri = conv.defaultActivityEncryptionKeyUrl
       if (keyUri) {
         const encryptedDisplayName = await this.encryption.encryptText(keyUri, displayName)
-        const encryptedContent = await this.encryption.encryptText(keyUri, content)
-        if (encryptedDisplayName && encryptedContent) {
-          return {
-            object: {
-              objectType: 'comment',
-              displayName: encryptedDisplayName,
-              content: encryptedContent,
-            },
-            encryptionKeyUrl: keyUri,
+        const encryptedContent = content ? await this.encryption.encryptText(keyUri, content) : undefined
+        if (encryptedDisplayName) {
+          const object: Record<string, string> = {
+            objectType: 'comment',
+            displayName: encryptedDisplayName,
+          }
+          if (encryptedContent) {
+            object.content = encryptedContent
           }
+          return { object, encryptionKeyUrl: keyUri }
         }
       }
     }
 
-    return { object: { objectType: 'comment', displayName, content } }
+    const object: Record<string, string> = { objectType: 'comment', displayName }
+    if (content) {
+      object.content = content
+    }
+    return { object }
   }
 
   private async sendMessageInternal(
@@ -349,6 +379,11 @@ export class WebexClient {
     if (this.useInternalAPI) {
       const activity = await this.internalRequest<InternalActivity>(`/activities/${messageId}`)
       const convId = activity.target?.id ?? ''
+      // Internal API responses don't carry the cluster shard (e.g. `us-west-2_r`) the
+      // public roomId encoding requires. The `unknown` placeholder is a sentinel — it
+      // round-trips through other internal API calls because they decode only the
+      // conversation UUID suffix. Callers that need a public-API-safe roomId should
+      // obtain it from `listSpaces()` or pass it through from a prior `sendMessage`.
       const roomId = convId ? Buffer.from(`ciscospark://urn:TEAM:unknown/ROOM/${convId}`).toString('base64') : ''
       return this.activityToMessage(activity, roomId)
     }
@@ -381,14 +416,17 @@ export class WebexClient {
   ): Promise<WebexMessage> {
     if (this.useInternalAPI) {
       const convUuid = this.decodeConvUuid(roomId)
-      const { object, encryptionKeyUrl } = await this.buildEncryptedObject(convUuid, text, options)
+      const { object, encryptionKeyUrl } = await this.buildEncryptedObject(convUuid, text, {
+        ...options,
+        forEdit: true,
+      })
 
       const activity: Record<string, unknown> = {
         verb: 'post',
         object,
         target: { id: convUuid, objectType: 'conversation' },
         parent: { id: messageId, type: 'edit' },
-        clientTempId: `tmp-${Date.now()}`,
+        clientTempId: `tmp-${Date.now()}-edit`,
       }
 
       if (encryptionKeyUrl) {
@@ -399,6 +437,16 @@ export class WebexClient {
         method: 'POST',
         body: JSON.stringify(activity),
       })
+
+      // Tolerate responses that omit `parent` (server may return minimal shape) —
+      // only fail on an explicit mismatch between the echoed parent and the edited id.
+      if (result.parent && result.parent.id !== messageId) {
+        throw new WebexError(
+          `Edit rejected: server linked the new activity ${result.id} to ${result.parent.id} instead of ${messageId}.`,
+          'edit_failed',
+        )
+      }
+
       return this.activityToMessage(result, roomId)
     }
     const body = options?.markdown ? { roomId, markdown: text } : { roomId, text }
@@ -443,6 +491,7 @@ interface InternalActivity {
     encryptionKeyUrl?: string
   }
   target?: { id: string; encryptionKeyUrl?: string }
+  parent?: { id: string; type: string }
   published: string
   encryptionKeyUrl?: string
 }

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

@@ -3,7 +3,9 @@ import * as childProcess from 'node:child_process'
 
 import { WebexClient } from '../client'
 import { WebexCredentialManager } from '../credential-manager'
-import { loginAction, logoutAction, statusAction } from './auth'
+import { WebexTokenExtractor } from '../token-extractor'
+import { WebexError } from '../types'
+import { extractAction, loginAction, logoutAction, statusAction } from './auth'
 
 describe('auth commands', () => {
   let consoleSpy: ReturnType<typeof spyOn>
@@ -208,6 +210,125 @@ describe('auth commands', () => {
     })
   })
 
+  describe('extractAction', () => {
+    test('passes deviceUrl and tokenType to client.login', async () => {
+      protoSpy(WebexTokenExtractor.prototype, 'extract').mockResolvedValue({
+        accessToken: 'extracted-token-at-least-twenty-chars',
+        refreshToken: 'refresh-token',
+        expiresAt: Date.now() + 3600000,
+        deviceUrl: 'https://wdm-r.wbx2.com/wdm/api/v1/devices/test-device-id',
+        userId: 'user-1',
+      })
+      const loginSpy = protoSpy(WebexClient.prototype, 'login').mockResolvedValue(new WebexClient())
+      protoSpy(WebexClient.prototype, 'testAuth').mockResolvedValue(mockPerson)
+      protoSpy(WebexCredentialManager.prototype, 'saveConfig').mockResolvedValue(undefined)
+
+      await extractAction({ pretty: false })
+
+      expect(loginSpy).toHaveBeenCalledWith({
+        token: 'extracted-token-at-least-twenty-chars',
+        deviceUrl: 'https://wdm-r.wbx2.com/wdm/api/v1/devices/test-device-id',
+        tokenType: 'extracted',
+      })
+    })
+
+    test('attempts refresh when token is expired', async () => {
+      protoSpy(WebexTokenExtractor.prototype, 'extract').mockResolvedValue({
+        accessToken: 'expired-token-at-least-twenty-chars-',
+        refreshToken: 'valid-refresh-token',
+        expiresAt: Date.now() - 7200000,
+      })
+      const refreshSpy = protoSpy(WebexCredentialManager.prototype, 'refreshToken').mockResolvedValue({
+        accessToken: 'refreshed-token-at-least-twenty-ch',
+        refreshToken: 'new-refresh',
+        expiresAt: Date.now() + 3600000,
+      })
+      const loginSpy = protoSpy(WebexClient.prototype, 'login').mockResolvedValue(new WebexClient())
+      protoSpy(WebexClient.prototype, 'testAuth').mockResolvedValue(mockPerson)
+      protoSpy(WebexCredentialManager.prototype, 'saveConfig').mockResolvedValue(undefined)
+
+      await extractAction({ pretty: false })
+
+      expect(refreshSpy).toHaveBeenCalled()
+      expect(loginSpy).toHaveBeenCalledWith(expect.objectContaining({ token: 'refreshed-token-at-least-twenty-ch' }))
+      const lastCall = consoleSpy.mock.calls[consoleSpy.mock.calls.length - 1][0] as string
+      const output = JSON.parse(lastCall)
+      expect(output.authenticated).toBe(true)
+      expect(output.refreshed).toBe(true)
+    })
+
+    test('reports expired token with actionable hint when refresh fails', async () => {
+      protoSpy(WebexTokenExtractor.prototype, 'extract').mockResolvedValue({
+        accessToken: 'expired-token-at-least-twenty-chars-',
+        refreshToken: 'bad-refresh-token',
+        expiresAt: Date.now() - 7200000,
+      })
+      protoSpy(WebexCredentialManager.prototype, 'refreshToken').mockResolvedValue(null)
+      protoSpy(WebexClient.prototype, 'login').mockResolvedValue(new WebexClient())
+      protoSpy(WebexClient.prototype, 'testAuth').mockRejectedValue(new WebexError('Unauthorized', 'http_401'))
+      const exitSpy = protoSpy(process, 'exit').mockImplementation(() => undefined as never)
+
+      await extractAction({ pretty: false })
+
+      const lastCall = consoleSpy.mock.calls[consoleSpy.mock.calls.length - 1][0] as string
+      const output = JSON.parse(lastCall)
+      expect(output.error).toContain('expired')
+      expect(output.hint).toContain('web.webex.com')
+      expect(output.hint).toContain('not webex.com')
+      expect(exitSpy).toHaveBeenCalledWith(1)
+    })
+
+    test('rethrows non-auth errors even when token is expired', async () => {
+      protoSpy(WebexTokenExtractor.prototype, 'extract').mockResolvedValue({
+        accessToken: 'expired-token-at-least-twenty-chars-',
+        refreshToken: 'bad-refresh-token',
+        expiresAt: Date.now() - 7200000,
+      })
+      protoSpy(WebexCredentialManager.prototype, 'refreshToken').mockResolvedValue(null)
+      protoSpy(WebexClient.prototype, 'login').mockResolvedValue(new WebexClient())
+      protoSpy(WebexClient.prototype, 'testAuth').mockRejectedValue(new Error('Network error'))
+      protoSpy(process, 'exit').mockImplementation(() => undefined as never)
+
+      await extractAction({ pretty: false })
+
+      const lastCall = consoleErrorSpy.mock.calls[consoleErrorSpy.mock.calls.length - 1]?.[0] as string | undefined
+      if (lastCall) {
+        const output = JSON.parse(lastCall)
+        expect(output.error).toContain('Network error')
+      }
+    })
+
+    test('rethrows non-expiry auth errors', async () => {
+      protoSpy(WebexTokenExtractor.prototype, 'extract').mockResolvedValue({
+        accessToken: 'valid-token-at-least-twenty-chars-xx',
+        expiresAt: Date.now() + 3600000,
+      })
+      protoSpy(WebexClient.prototype, 'login').mockResolvedValue(new WebexClient())
+      protoSpy(WebexClient.prototype, 'testAuth').mockRejectedValue(new Error('Network error'))
+      protoSpy(process, 'exit').mockImplementation(() => undefined as never)
+
+      await extractAction({ pretty: false })
+
+      const lastCall = consoleErrorSpy.mock.calls[consoleErrorSpy.mock.calls.length - 1]?.[0] as string | undefined
+      if (lastCall) {
+        const output = JSON.parse(lastCall)
+        expect(output.error).toContain('Network error')
+      }
+    })
+
+    test('outputs no token found when extract returns null', async () => {
+      protoSpy(WebexTokenExtractor.prototype, 'extract').mockResolvedValue(null)
+      const exitSpy = protoSpy(process, 'exit').mockImplementation(() => undefined as never)
+
+      await extractAction({ pretty: false })
+
+      const lastCall = consoleSpy.mock.calls[consoleSpy.mock.calls.length - 1][0] as string
+      const output = JSON.parse(lastCall)
+      expect(output.error).toContain('No Webex token found')
+      expect(exitSpy).toHaveBeenCalledWith(1)
+    })
+  })
+
   describe('logoutAction', () => {
     test('clears credentials when authenticated', async () => {
       protoSpy(WebexCredentialManager.prototype, 'loadConfig').mockResolvedValue({

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

@@ -8,6 +8,7 @@ import { getWebexAppCredentials } from '../app-config'
 import { WebexClient } from '../client'
 import { WebexCredentialManager } from '../credential-manager'
 import { WebexTokenExtractor } from '../token-extractor'
+import { WebexError } from '../types'
 
 interface ResolvedCredentials {
   clientId: string
@@ -142,7 +143,8 @@ export async function statusAction(options: { pretty?: boolean }): Promise<void>
 
 export async function extractAction(options: { pretty?: boolean; debug?: boolean }): Promise<void> {
   try {
-    const extractor = new WebexTokenExtractor(undefined, options.debug ? (msg) => debug(`[debug] ${msg}`) : undefined)
+    const debugLog = options.debug ? (msg: string) => debug(`[debug] ${msg}`) : undefined
+    const extractor = new WebexTokenExtractor(undefined, debugLog)
 
     if (options.debug) {
       debug('[debug] Searching browser profiles for Webex tokens...')
@@ -155,7 +157,7 @@ export async function extractAction(options: { pretty?: boolean; debug?: boolean
         formatOutput(
           {
             error:
-              'No Webex token found in any browser. Make sure you are logged in to web.webex.com in Chrome, Edge, Arc, or Brave.',
+              'No Webex token found in any browser. Make sure you are logged in at https://web.webex.com (not webex.com) in Chrome, Edge, Arc, or Brave.',
             hint: 'Run "auth login" for OAuth Device Grant flow, or --debug for more info.',
           },
           options.pretty,
@@ -165,30 +167,83 @@ export async function extractAction(options: { pretty?: boolean; debug?: boolean
       return
     }
 
-    const client = await new WebexClient().login({ token: extracted.accessToken })
-    const person = await client.testAuth()
+    const isExpired = extracted.expiresAt != null && extracted.expiresAt > 0 && extracted.expiresAt < Date.now()
+    if (isExpired && options.debug) {
+      const agoMs = Date.now() - extracted.expiresAt!
+      const agoHours = Math.round(agoMs / 3_600_000)
+      debugLog?.(`Token expired ${agoHours > 0 ? `${agoHours}h ago` : 'recently'}.`)
+    }
+
+    let activeToken = extracted.accessToken
+    let refreshedConfig: { accessToken: string; refreshToken: string; expiresAt: number } | null = null
+
+    if (isExpired && extracted.refreshToken) {
+      debugLog?.('Attempting token refresh...')
+      const credManager = new WebexCredentialManager()
+      const { clientId, clientSecret } = getWebexAppCredentials()
+      refreshedConfig = await credManager.refreshToken(extracted.refreshToken, clientId, clientSecret)
+      if (refreshedConfig) {
+        debugLog?.('Token refreshed successfully.')
+        activeToken = refreshedConfig.accessToken
+      } else {
+        debugLog?.('Token refresh failed. Will attempt validation with expired token.')
+      }
+    }
+
+    const client = await new WebexClient().login({
+      token: activeToken,
+      deviceUrl: extracted.deviceUrl,
+      tokenType: 'extracted',
+    })
+
+    let person: { id: string; displayName: string; emails: string[] } | null = null
+    try {
+      const result = await client.testAuth()
+      if (result.id) {
+        person = { id: result.id, displayName: result.displayName, emails: result.emails }
+      }
+    } catch (authError) {
+      const isAuthFailure =
+        authError instanceof WebexError && (authError.code === 'http_401' || authError.code === 'http_403')
+      if (isExpired && isAuthFailure) {
+        console.log(
+          formatOutput(
+            {
+              error: 'Extracted browser token is expired and could not be refreshed.',
+              hint: 'Log in at https://web.webex.com (not webex.com) in your browser, then run "auth extract" again. Or use "auth login" for OAuth Device Grant flow.',
+            },
+            options.pretty,
+          ),
+        )
+        process.exit(1)
+        return
+      }
+      throw authError
+    }
 
     const credManager = new WebexCredentialManager()
     await credManager.saveConfig({
-      accessToken: extracted.accessToken,
-      refreshToken: extracted.refreshToken ?? '',
-      expiresAt: extracted.expiresAt ?? 0,
+      accessToken: activeToken,
+      refreshToken: refreshedConfig?.refreshToken ?? extracted.refreshToken ?? '',
+      expiresAt: refreshedConfig?.expiresAt ?? extracted.expiresAt ?? 0,
       tokenType: 'extracted',
       deviceUrl: extracted.deviceUrl,
       userId: extracted.userId,
       encryptionKeys: extracted.encryptionKeys ? Object.fromEntries(extracted.encryptionKeys) : undefined,
     })
 
-    console.log(
-      formatOutput(
-        {
-          user: { id: person.id, displayName: person.displayName, emails: person.emails },
-          authenticated: true,
-          tokenType: 'extracted',
-        },
-        options.pretty,
-      ),
-    )
+    const output: Record<string, unknown> = {
+      authenticated: true,
+      tokenType: 'extracted',
+    }
+    if (refreshedConfig) {
+      output['refreshed'] = true
+    }
+    if (person) {
+      output['user'] = person
+    }
+
+    console.log(formatOutput(output, options.pretty))
   } catch (error) {
     handleError(error as Error)
   }