agent-messenger 2.34.0 → 2.36.0

package/src/platforms/kakaotalk/auth/oauth-refresh.test.ts

@@ -0,0 +1,225 @@
+import { describe, expect, it, mock } from 'bun:test'
+
+import { KakaoOAuthRefreshError, refreshKakaoOAuthToken } from './oauth-refresh'
+
+const HEX_DEVICE_UUID = 'a'.repeat(64)
+const credentials = {
+  accessToken: 'access-secret',
+  refreshToken: 'refresh-secret',
+  deviceUuid: HEX_DEVICE_UUID,
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+function captureError(promise: Promise<unknown>): Promise<KakaoOAuthRefreshError> {
+  return promise.then(
+    () => {
+      throw new Error('Expected refresh to fail')
+    },
+    (error: unknown) => {
+      expect(error).toBeInstanceOf(KakaoOAuthRefreshError)
+      return error as KakaoOAuthRefreshError
+    },
+  )
+}
+
+function expectSecretsRedacted(error: Error, ...secrets: string[]): void {
+  const rendered = `${String(error)}\n${error.stack ?? ''}\n${JSON.stringify(error)}`
+  for (const secret of secrets) {
+    expect(rendered).not.toContain(secret)
+  }
+}
+
+describe('refreshKakaoOAuthToken', () => {
+  it('sends the Android sub-device refresh request and returns rotated tokens', async () => {
+    const fetchImpl = mock(async () =>
+      jsonResponse({
+        status: 0,
+        access_token: 'new-access',
+        refresh_token: 'new-refresh',
+        token_type: 'bearer',
+        expires_in: 3600,
+      }),
+    )
+
+    const result = await refreshKakaoOAuthToken(credentials, {
+      fetchImpl,
+      requestId: () => 'request-id',
+    })
+
+    expect(result).toEqual({
+      accessToken: 'new-access',
+      refreshToken: 'new-refresh',
+      tokenType: 'bearer',
+      expiresIn: 3600,
+    })
+    expect(fetchImpl).toHaveBeenCalledTimes(1)
+
+    const [url, init] = fetchImpl.mock.calls[0] as unknown as [string, RequestInit]
+    expect(url).toBe('https://katalk.kakao.com/android/account/oauth2_token.json')
+    expect(init.method).toBe('POST')
+    expect(init.headers).toEqual({
+      A: 'android/25.9.2/ko',
+      Authorization: `access-secret-${HEX_DEVICE_UUID}`,
+      'User-Agent': 'KT/25.9.2 An/13 ko',
+      'Accept-Language': 'ko',
+      'Content-Type': 'application/json; charset=utf-8',
+      C: 'request-id',
+      Connection: 'Close',
+    })
+    expect(JSON.parse(String(init.body))).toEqual({
+      access_token: credentials.accessToken,
+      refresh_token: credentials.refreshToken,
+      grant_type: 'refresh_token',
+    })
+    expect(init.signal).toBeInstanceOf(AbortSignal)
+  })
+
+  it('derives the Android device id for a non-hex UUID', async () => {
+    const fetchImpl = mock(async () => jsonResponse({ status: 0, access_token: 'new-access' }))
+
+    await refreshKakaoOAuthToken({ ...credentials, deviceUuid: 'device-uuid' }, { fetchImpl })
+
+    const [, init] = fetchImpl.mock.calls[0] as unknown as [string, RequestInit]
+    expect(init.headers).toMatchObject({
+      Authorization: 'access-secret-db214b8bbba42ef7a5fbc4c1bbba91305178ade87b29f1378f55b69fc04caac5',
+    })
+  })
+
+  it('preserves the input refresh token when Kakao does not rotate it', async () => {
+    const fetchImpl = mock(async () => jsonResponse({ status: 0, access_token: 'new-access' }))
+
+    await expect(refreshKakaoOAuthToken(credentials, { fetchImpl })).resolves.toEqual({
+      accessToken: 'new-access',
+      refreshToken: credentials.refreshToken,
+      tokenType: undefined,
+      expiresIn: undefined,
+    })
+  })
+
+  it('rejects missing credentials before making a request', async () => {
+    const fetchImpl = mock(async () => jsonResponse({ status: 0, access_token: 'unused' }))
+
+    const error = await captureError(refreshKakaoOAuthToken({ ...credentials, refreshToken: '' }, { fetchImpl }))
+
+    expect(error).toMatchObject({ code: 'refresh_credentials_missing' })
+    expect(fetchImpl).not.toHaveBeenCalled()
+  })
+
+  it('classifies a Kakao rejection with safe status metadata', async () => {
+    const fetchImpl = mock(async () =>
+      jsonResponse({ status: -950, message: 'rejected', raw: 'raw-response-secret' }, 401),
+    )
+
+    const error = await captureError(refreshKakaoOAuthToken(credentials, { fetchImpl }))
+
+    expect(error).toMatchObject({ code: 'refresh_rejected', serverStatus: -950, httpStatus: 401 })
+    expectSecretsRedacted(error, credentials.accessToken, credentials.refreshToken, 'raw-response-secret')
+  })
+
+  it('classifies an HTTP failure without a Kakao status', async () => {
+    const fetchImpl = mock(async () => jsonResponse({ message: 'unavailable' }, 503))
+
+    const error = await captureError(refreshKakaoOAuthToken(credentials, { fetchImpl }))
+
+    expect(error).toMatchObject({ code: 'refresh_http_error', httpStatus: 503 })
+    expect(error.serverStatus).toBeUndefined()
+  })
+
+  it('rejects a malformed successful response without exposing the body', async () => {
+    const fetchImpl = mock(async () => jsonResponse({ status: 0, access_token: '', raw: 'do-not-log' }))
+
+    const error = await captureError(refreshKakaoOAuthToken(credentials, { fetchImpl }))
+
+    expect(error).toMatchObject({ code: 'refresh_malformed_response', httpStatus: 200 })
+    expectSecretsRedacted(error, credentials.accessToken, credentials.refreshToken, 'do-not-log')
+  })
+
+  it('rejects a non-JSON response without exposing its text', async () => {
+    const fetchImpl = mock(async () => new Response('body-secret', { status: 200 }))
+
+    const error = await captureError(refreshKakaoOAuthToken(credentials, { fetchImpl }))
+
+    expect(error).toMatchObject({ code: 'refresh_malformed_response', httpStatus: 200 })
+    expectSecretsRedacted(error, credentials.accessToken, credentials.refreshToken, 'body-secret')
+  })
+
+  it('aborts a request after the configured timeout', async () => {
+    const fetchImpl = mock(
+      async (_url: string | URL | Request, init?: RequestInit): Promise<Response> =>
+        await new Promise((_resolve, reject) => {
+          init?.signal?.addEventListener('abort', () => {
+            reject(Object.assign(new Error('timed out with access-secret'), { name: 'AbortError' }))
+          })
+        }),
+    )
+
+    const error = await captureError(refreshKakaoOAuthToken(credentials, { fetchImpl, timeoutMs: 5 }))
+
+    expect(error).toMatchObject({ code: 'refresh_timeout' })
+    expectSecretsRedacted(error, credentials.accessToken, credentials.refreshToken)
+  })
+
+  it('keeps the timeout active while consuming a stalled response body', async () => {
+    const fetchImpl = mock(async (_url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+      const body = new ReadableStream<Uint8Array>({
+        start(controller) {
+          const fallback = setTimeout(() => {
+            controller.error(Object.assign(new Error('stalled body access-secret'), { name: 'AbortError' }))
+          }, 50)
+
+          init?.signal?.addEventListener(
+            'abort',
+            () => {
+              clearTimeout(fallback)
+              controller.error(Object.assign(new Error('stalled body access-secret'), { name: 'AbortError' }))
+            },
+            { once: true },
+          )
+        },
+      })
+
+      return new Response(body, { status: 200, headers: { 'Content-Type': 'application/json' } })
+    })
+
+    const error = await captureError(refreshKakaoOAuthToken(credentials, { fetchImpl, timeoutMs: 5 }))
+
+    expect(error).toMatchObject({ code: 'refresh_timeout' })
+    expectSecretsRedacted(error, credentials.accessToken, credentials.refreshToken)
+  })
+
+  it('classifies response body transport failures without retaining a secret-bearing cause', async () => {
+    const fetchImpl = mock(async (): Promise<Response> => {
+      const body = new ReadableStream<Uint8Array>({
+        start(controller) {
+          controller.error(new Error(`body failure ${credentials.accessToken} ${credentials.refreshToken}`))
+        },
+      })
+
+      return new Response(body, { status: 200, headers: { 'Content-Type': 'application/json' } })
+    })
+
+    const error = await captureError(refreshKakaoOAuthToken(credentials, { fetchImpl }))
+
+    expect(error).toMatchObject({ code: 'refresh_request_failed' })
+    expect(error.cause).toBeUndefined()
+    expectSecretsRedacted(error, credentials.accessToken, credentials.refreshToken)
+  })
+
+  it('classifies network failures without retaining a secret-bearing cause', async () => {
+    const fetchImpl = mock(async () => {
+      throw new Error(`network failure ${credentials.accessToken} ${credentials.refreshToken}`)
+    })
+
+    const error = await captureError(refreshKakaoOAuthToken(credentials, { fetchImpl }))
+
+    expect(error).toMatchObject({ code: 'refresh_request_failed' })
+    expect(error.cause).toBeUndefined()
+    expectSecretsRedacted(error, credentials.accessToken, credentials.refreshToken)
+  })
+})

package/src/platforms/kakaotalk/auth/oauth-refresh.ts

@@ -0,0 +1,144 @@
+import { createHash, randomUUID } from 'node:crypto'
+
+import { ANDROID_AGENT, ANDROID_USER_AGENT } from './kakao-login'
+
+const ANDROID_OAUTH_REFRESH_URL = 'https://katalk.kakao.com/android/account/oauth2_token.json'
+const DEFAULT_REFRESH_TIMEOUT_MS = 15_000
+
+export type KakaoOAuthRefreshErrorCode =
+  | 'refresh_credentials_missing'
+  | 'refresh_http_error'
+  | 'refresh_malformed_response'
+  | 'refresh_rejected'
+  | 'refresh_request_failed'
+  | 'refresh_timeout'
+
+export class KakaoOAuthRefreshError extends Error {
+  readonly code: KakaoOAuthRefreshErrorCode
+  readonly serverStatus?: number
+  readonly httpStatus?: number
+
+  constructor(code: KakaoOAuthRefreshErrorCode, options?: { serverStatus?: number; httpStatus?: number }) {
+    super(`KakaoTalk OAuth token refresh failed (${code})`)
+    this.name = 'KakaoOAuthRefreshError'
+    this.code = code
+    this.serverStatus = options?.serverStatus
+    this.httpStatus = options?.httpStatus
+  }
+}
+
+export interface KakaoOAuthRefreshInput {
+  accessToken: string
+  refreshToken: string
+  deviceUuid: string
+}
+
+export interface KakaoOAuthRefreshResult {
+  accessToken: string
+  refreshToken: string
+  tokenType?: string
+  expiresIn?: number
+}
+
+export interface KakaoOAuthRefreshOptions {
+  fetchImpl?: typeof fetch
+  requestId?: () => string
+  timeoutMs?: number
+}
+
+function buildDeviceId(deviceUuid: string): string {
+  if (/^[a-f0-9]{40,64}$/i.test(deviceUuid)) return deviceUuid
+  return createHash('sha256').update(`dkljleskljfeisflssljeif ${deviceUuid}`, 'utf8').digest('hex')
+}
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null
+}
+
+function transportError(error: unknown, signal: AbortSignal): KakaoOAuthRefreshError {
+  const timedOut = signal.aborted || (error instanceof Error && error.name === 'AbortError')
+  return new KakaoOAuthRefreshError(timedOut ? 'refresh_timeout' : 'refresh_request_failed')
+}
+
+export async function refreshKakaoOAuthToken(
+  input: KakaoOAuthRefreshInput,
+  options: KakaoOAuthRefreshOptions = {},
+): Promise<KakaoOAuthRefreshResult> {
+  if (!input.accessToken || !input.refreshToken || !input.deviceUuid) {
+    throw new KakaoOAuthRefreshError('refresh_credentials_missing')
+  }
+
+  const fetchImpl = options.fetchImpl ?? fetch
+  const controller = new AbortController()
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_REFRESH_TIMEOUT_MS)
+
+  try {
+    let response: Response
+    try {
+      response = await fetchImpl(ANDROID_OAUTH_REFRESH_URL, {
+        method: 'POST',
+        headers: {
+          A: ANDROID_AGENT,
+          Authorization: `${input.accessToken}-${buildDeviceId(input.deviceUuid)}`,
+          'User-Agent': ANDROID_USER_AGENT,
+          'Accept-Language': 'ko',
+          'Content-Type': 'application/json; charset=utf-8',
+          C: (options.requestId ?? randomUUID)(),
+          Connection: 'Close',
+        },
+        body: JSON.stringify({
+          access_token: input.accessToken,
+          refresh_token: input.refreshToken,
+          grant_type: 'refresh_token',
+        }),
+        signal: controller.signal,
+      })
+    } catch (error) {
+      throw transportError(error, controller.signal)
+    }
+
+    let body: Record<string, unknown> | null
+    try {
+      body = readRecord(await response.json())
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw transportError(error, controller.signal)
+      body = null
+    }
+
+    const serverStatus = body && typeof body.status === 'number' ? body.status : undefined
+    if (!response.ok) {
+      throw new KakaoOAuthRefreshError(
+        serverStatus !== undefined && serverStatus !== 0 ? 'refresh_rejected' : 'refresh_http_error',
+        { serverStatus: serverStatus !== 0 ? serverStatus : undefined, httpStatus: response.status },
+      )
+    }
+
+    if (!body) {
+      throw new KakaoOAuthRefreshError('refresh_malformed_response', { httpStatus: response.status })
+    }
+
+    if (serverStatus !== undefined && serverStatus !== 0) {
+      throw new KakaoOAuthRefreshError('refresh_rejected', {
+        serverStatus,
+        httpStatus: response.status,
+      })
+    }
+
+    const accessToken = typeof body.access_token === 'string' ? body.access_token : ''
+    if (!accessToken) {
+      throw new KakaoOAuthRefreshError('refresh_malformed_response', { httpStatus: response.status })
+    }
+
+    return {
+      accessToken,
+      refreshToken:
+        typeof body.refresh_token === 'string' && body.refresh_token ? body.refresh_token : input.refreshToken,
+      tokenType: typeof body.token_type === 'string' && body.token_type ? body.token_type : undefined,
+      expiresIn: typeof body.expires_in === 'number' ? body.expires_in : undefined,
+    }
+  } finally {
+    clearTimeout(timeout)
+  }
+}

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

@@ -144,6 +144,61 @@ describe('KakaoTalkClient', () => {
         expect((e as KakaoTalkError).code).toBe('missing_user_id')
       }
     })
+
+    it('preserves invalid_access_token and never continues to LCHATLIST', async () => {
+      mockLogin.mockRejectedValue(
+        Object.assign(new Error('KakaoTalk LOGINLIST invalid access token (status -950)'), {
+          code: 'invalid_access_token',
+          serverStatus: -950,
+        }),
+      )
+      const client = await new KakaoTalkClient().login({
+        oauthToken: 'expired-access-token',
+        userId: 'user1',
+        deviceUuid: 'device1',
+      })
+
+      let error: unknown
+      try {
+        await client.getChats({ all: true })
+      } catch (cause) {
+        error = cause
+      }
+
+      expect(error).toBeInstanceOf(KakaoTalkError)
+      expect(error).toMatchObject({ code: 'invalid_access_token', serverStatus: -950 })
+      expect(mockGetChatList).not.toHaveBeenCalled()
+      expect(mockClose).toHaveBeenCalledTimes(1)
+    })
+
+    it('preserves other typed LOGINLIST rejections', async () => {
+      mockLogin.mockRejectedValue(
+        Object.assign(new Error('KakaoTalk LOGINLIST rejected (status -777)'), {
+          code: 'login_rejected',
+          serverStatus: -777,
+        }),
+      )
+      const client = await new KakaoTalkClient().login({
+        oauthToken: 'rejected-access-token',
+        userId: 'user1',
+        deviceUuid: 'device1',
+      })
+
+      await expect(client.getChats()).rejects.toMatchObject({ code: 'login_rejected', serverStatus: -777 })
+      expect(mockGetChatList).not.toHaveBeenCalled()
+    })
+
+    it('keeps interrupted LOGINLIST connections classified as login_failed', async () => {
+      mockLogin.mockRejectedValue(new Error('KakaoTalk LOGINLIST transport failed: connection closed'))
+      const client = await new KakaoTalkClient().login({
+        oauthToken: 'token',
+        userId: 'user1',
+        deviceUuid: 'device1',
+      })
+
+      await expect(client.getChats()).rejects.toMatchObject({ code: 'login_failed' })
+      expect(mockGetChatList).not.toHaveBeenCalled()
+    })
   })
 
   describe('getChats', () => {

package/src/platforms/kakaotalk/client.ts

@@ -40,11 +40,13 @@ export type KakaoSessionEventHandler = (event: KakaoSessionEvent) => void
 
 export class KakaoTalkError extends Error {
   code: string
+  readonly serverStatus?: number
 
-  constructor(message: string, code: string, options?: { cause?: unknown }) {
+  constructor(message: string, code: string, options?: { cause?: unknown; serverStatus?: number }) {
     super(message, options)
     this.name = 'KakaoTalkError'
     this.code = code
+    this.serverStatus = options?.serverStatus
   }
 }
 
@@ -280,6 +282,17 @@ function wrapError(error: unknown, code: string): KakaoTalkError {
   return new KakaoTalkError(message, code, { cause: error })
 }
 
+function isLoginResponseError(
+  error: unknown,
+): error is Error & { code: 'invalid_access_token' | 'login_rejected'; serverStatus: number } {
+  if (!(error instanceof Error)) return false
+  const candidate = error as Error & { code?: unknown; serverStatus?: unknown }
+  return (
+    (candidate.code === 'invalid_access_token' || candidate.code === 'login_rejected') &&
+    typeof candidate.serverStatus === 'number'
+  )
+}
+
 const MAX_PAGES = 50
 
 function syncStatePath(deviceUuid: string): string {
@@ -675,7 +688,11 @@ export class KakaoTalkClient {
       return { session, loginResult }
     } catch (error) {
       session.close()
-      throw new KakaoTalkError(error instanceof Error ? error.message : String(error), 'login_failed', { cause: error })
+      const code = isLoginResponseError(error) ? error.code : 'login_failed'
+      throw new KakaoTalkError(error instanceof Error ? error.message : String(error), code, {
+        cause: error,
+        serverStatus: isLoginResponseError(error) ? error.serverStatus : undefined,
+      })
     }
   }
 

package/src/platforms/kakaotalk/index.test.ts

@@ -1,8 +1,10 @@
 import { expect, it } from 'bun:test'
 
+import type { KakaoOAuthRefreshOptions } from '@/platforms/kakaotalk/index'
 import {
   classifyKakaoChat,
   CredentialManager,
+  KakaoOAuthRefreshError,
   KakaoAccountCredentialsSchema,
   KakaoCredentialManager,
   KakaoChatSchema,
@@ -18,6 +20,7 @@ import {
   KakaoProfileSchema,
   KakaoTalkPushReadEventSchema,
   KakaoTypingResultSchema,
+  refreshKakaoOAuthToken,
 } from '@/platforms/kakaotalk/index'
 
 it('KakaoTalkClient is exported from barrel', () => {
@@ -87,3 +90,11 @@ it('KakaoLeaveChatResultSchema is exported from barrel', () => {
 it('KakaoTypingResultSchema is exported from barrel', () => {
   expect(typeof KakaoTypingResultSchema.parse).toBe('function')
 })
+
+it('Kakao OAuth refresh API is exported from barrel', () => {
+  expect(typeof refreshKakaoOAuthToken).toBe('function')
+  expect(typeof KakaoOAuthRefreshError).toBe('function')
+
+  const options: KakaoOAuthRefreshOptions = { timeoutMs: 5_000 }
+  expect(options.timeoutMs).toBe(5_000)
+})

package/src/platforms/kakaotalk/index.ts

@@ -6,6 +6,7 @@ export { KakaoTalkListener } from './listener'
 export type { PendingLoginState } from './credential-manager'
 export type {
   KakaoAccountCredentials,
+  KakaoAuthErrorCode,
   KakaoAuthMethod,
   KakaoChat,
   KakaoConfig,
@@ -54,6 +55,13 @@ export {
 } from './types'
 export { attemptLogin, generateDeviceUuid, loginFlow, registerDevice, requestPasscode } from './auth/kakao-login'
 export type { LoginCredentials } from './auth/kakao-login'
+export { KakaoOAuthRefreshError, refreshKakaoOAuthToken } from './auth/oauth-refresh'
+export type {
+  KakaoOAuthRefreshErrorCode,
+  KakaoOAuthRefreshInput,
+  KakaoOAuthRefreshOptions,
+  KakaoOAuthRefreshResult,
+} from './auth/oauth-refresh'
 export { sha1Hex } from './media-upload'
 export { detectImageDimensions } from './image-meta'
 export type { AttachmentInput, AttachmentPlan, ResolvedAttachment, SingleAttachmentKind } from './attachment-router'

package/src/platforms/kakaotalk/protocol/NOTICE.md

@@ -1,8 +1,9 @@
 # Third-Party Notices
 
-This LOCO protocol implementation was written from scratch for agent-messenger.
-The protocol knowledge used to build it comes from the following open-source
-projects and their documentation. No code was copied from these projects.
+This KakaoTalk protocol and Android authentication implementation was written
+from scratch for agent-messenger. The protocol knowledge used to build it comes
+from the following open-source projects and their documentation. No code was
+copied from these projects.
 
 ---
 
@@ -37,7 +38,21 @@ Android sub-device login flow, and connection patterns.
 - Copyright (c) 2020 storycraft
 
 Referenced for: LOCO packet format, BSON command schemas, authentication flow,
-X-VC signature algorithm, channel/chat type enumerations.
+Android OAuth refresh request/response behavior, X-VC signature algorithm,
+channel/chat type enumerations.
+
+---
+
+## KakaoForge
+
+- Repository: https://github.com/play2fly/KakaoForge
+- Reference commit: 4b774ea40b1347280fadb685415436584093118b
+- License: KakaoForge Non-Commercial / No Abuse License
+- Copyright (c) 2026 aodjo
+
+Referenced for: current Android `oauth2_token.json` request fields, client
+headers, device-id handling, and token rotation/expiry response fields. Protocol
+behavior only; no source code was copied or adapted.
 
 ---
 

package/src/platforms/kakaotalk/protocol/login-response.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'bun:test'
+
+import { validateLoginListResponse } from './login-response'
+import type { LocoPacket } from './types'
+
+function packet(statusCode: number, body: Record<string, unknown>): LocoPacket {
+  return { packetId: 1, statusCode, method: 'LOGINLIST', bodyType: 0, body }
+}
+
+function captureError(fn: () => unknown): unknown {
+  try {
+    fn()
+    return undefined
+  } catch (error) {
+    return error
+  }
+}
+
+describe('LOGINLIST response classification', () => {
+  it('accepts status=0 and returns the login snapshot', () => {
+    const body = { status: 0, chatDatas: [], eof: true }
+
+    expect(validateLoginListResponse(packet(0, body))).toBe(body)
+  })
+
+  it('accepts a successful response when body.status is omitted', () => {
+    const body = { chatDatas: [], eof: true }
+
+    expect(validateLoginListResponse(packet(0, body))).toBe(body)
+  })
+
+  it('classifies body.status=-950 as invalid_access_token', () => {
+    expect(() => validateLoginListResponse(packet(0, { status: -950 }))).toThrow(
+      expect.objectContaining({ code: 'invalid_access_token', serverStatus: -950 }),
+    )
+  })
+
+  it('classifies packet statusCode=-950 as invalid_access_token', () => {
+    expect(() => validateLoginListResponse(packet(-950, {}))).toThrow(
+      expect.objectContaining({ code: 'invalid_access_token', serverStatus: -950 }),
+    )
+  })
+
+  it('classifies an unknown non-zero body status as login_rejected', () => {
+    expect(() => validateLoginListResponse(packet(0, { status: -777 }))).toThrow(
+      expect.objectContaining({ code: 'login_rejected', serverStatus: -777 }),
+    )
+  })
+
+  it('classifies an unknown non-zero packet status as login_rejected', () => {
+    expect(() => validateLoginListResponse(packet(-777, {}))).toThrow(
+      expect.objectContaining({ code: 'login_rejected', serverStatus: -777 }),
+    )
+  })
+
+  it('keeps a synthetic socket close on the transport-error path', () => {
+    const error = captureError(() => validateLoginListResponse(packet(-1, { error: 'connection closed' })))
+
+    expect(error).toBeInstanceOf(Error)
+    expect(error).toMatchObject({ message: 'KakaoTalk LOGINLIST transport failed: connection closed' })
+    expect(error).not.toHaveProperty('code')
+    expect(error).not.toHaveProperty('serverStatus')
+  })
+})

package/src/platforms/kakaotalk/protocol/login-response.ts

@@ -0,0 +1,40 @@
+import type { KakaoAuthErrorCode } from '../types'
+import type { LoginListResponse, LocoPacket } from './types'
+
+const CONNECTION_CLOSED_STATUS = -1
+const INVALID_ACCESS_TOKEN_STATUS = -950
+
+export class KakaoLoginResponseError extends Error {
+  readonly code: KakaoAuthErrorCode
+  readonly serverStatus: number
+
+  constructor(code: KakaoAuthErrorCode, serverStatus: number) {
+    const reason = code === 'invalid_access_token' ? 'invalid access token' : 'rejected'
+    super(`KakaoTalk LOGINLIST ${reason} (status ${serverStatus})`)
+    this.name = 'KakaoLoginResponseError'
+    this.code = code
+    this.serverStatus = serverStatus
+  }
+}
+
+function isSyntheticConnectionClose(response: LocoPacket): boolean {
+  return response.statusCode === CONNECTION_CLOSED_STATUS && response.body.error === 'connection closed'
+}
+
+function throwAuthenticationError(serverStatus: number): never {
+  const code: KakaoAuthErrorCode =
+    serverStatus === INVALID_ACCESS_TOKEN_STATUS ? 'invalid_access_token' : 'login_rejected'
+  throw new KakaoLoginResponseError(code, serverStatus)
+}
+
+export function validateLoginListResponse(response: LocoPacket): LoginListResponse {
+  if (isSyntheticConnectionClose(response)) {
+    throw new Error('KakaoTalk LOGINLIST transport failed: connection closed')
+  }
+
+  const bodyStatus = typeof response.body.status === 'number' ? response.body.status : 0
+  if (bodyStatus !== 0) throwAuthenticationError(bodyStatus)
+  if (response.statusCode !== 0) throwAuthenticationError(response.statusCode)
+
+  return response.body as unknown as LoginListResponse
+}