ILoveBingLu/CipherTalk 딥다이브
— 내 채팅 기록을 되찾아오는 Electron 리버스엔지니어링 교보재

1프로젝트 한 줄 요약

이 앱이 실제로 제공하는 기능

2왜 주목받는가

① "데이터 주권"이라는 서사가 기능보다 앞선다

README에서 기능 목록보다 먼저 나오는 건 개발자의 비전 세 문단이다. 요약하면 이렇다.

기술 저장소가 이런 식으로 감정적 서사를 전면에 세우는 건 드물다. 그리고 이게 별 1,200개를 모은 실질적 동력이다. 배울 점은 여기 있다 — 오픈소스에서 "왜 만들었는가"는 "무엇을 만들었는가"만큼 배포력이 있다.

② 경쟁 제품 대비 — 뷰어를 넘어 "분석 워크스테이션"으로

특히 MCP 서버를 노출한다는 점이 요즘 맥락에서 중요하다. Claude Code 같은 외부 에이전트가 miyu mcp로 이 데이터에 붙을 수 있다는 뜻이고, 앱이 스스로를 "최종 UI"가 아니라 데이터 액세스 레이어로 포지셔닝했다는 신호다.

③ 그런데 왜 신중하게 봐야 하나

3기술 스택 전체 지도

메인 프로세스 (백엔드 역할)

AI · 검색 계층

렌더러 (프론트엔드)

인프라 · 빌드

4아키텍처 심화 분석

전체 시스템 구조도

1단계 — 위챗 폴더를 어떻게 찾는가

경로를 하드코딩하지 않는다. 후보를 모아 점수를 매기고 정렬한다. 사용자가 데이터 폴더를 옮겼거나 계정이 여러 개여도 견디는 방식이다.

// dbPathService.ts — 계정 디렉토리인지 판정
private isAccountDir(entryPath: string): boolean {
  return (
    existsSync(join(entryPath, 'db_storage')) ||            // 위챗 v4
    existsSync(join(entryPath, 'FileStorage', 'Image')) ||
    existsSync(join(entryPath, 'FileStorage', 'Image2')) ||
    existsSync(join(entryPath, 'msg', 'attach'))          // 위챗 v3
  )
}

// 점수 = 루트 보너스 + 계정수*10000 + 최근수정시각
//   xwechat_files(v4) = 30000 / WeChat Files(v3) = 20000 / mac 버전디렉 = 50000
// all·applet·backup·wmpf·app_data 로 시작하는 디렉토리는 제외

2단계 — 키를 어떻게 꺼내는가 (핵심)

여기가 이 프로젝트에서 기술적으로 가장 흥미로운 지점이다. SQLCipher 키 유도(PBKDF2)를 JS로 구현하지 않는다. 대신 실행 중인 위챗 프로세스의 메모리에서 이미 풀려 있는 키를 찾아낸다.

그리고 이 DLL은 아무나 부르지 못하게 Ed25519 챌린지-응답을 건다. DLL이 난수를 주면, 호출자가 개인키로 서명해 돌려줘야 진짜 작업을 해 준다.

// wxKeyService.ts — 내장 개인키 복원 (XOR 0x5a 난독화)
private getScanPrivateKey(): crypto.KeyObject {
  const obf = '6a74585b5a6a5f5c59713f2a5e785e7a...'
  const der = Buffer.from(Buffer.from(obf, 'hex').map(v => v ^ 0x5a))
  return crypto.createPrivateKey({ key: der, format: 'der', type: 'pkcs8' })
}

scanDbKeyDiag(contactDbPath: string): WxScanDiag | null {
  const wktChallenge = this.scanLib.func('int wkt_challenge(uint8_t*, size_t)')
  const wktDiag      = this.scanLib.func('void* wkt_scan_diag_auth(uint8_t*, size_t, str)')
  const wktFree      = this.scanLib.func('void wkt_free(void*)')

  const nonce = Buffer.alloc(32)
  if (wktChallenge(nonce, 32) !== 32) return null   // ① DLL이 난수 발급
  const sig = crypto.sign(null, nonce, this.getScanPrivateKey()) // ② Ed25519 서명
  const ptr = wktDiag(sig, sig.length, contactDbPath)             // ③ 인증+스캔

  const d = JSON.parse(String(koffi.decode(ptr, 'char', -1)).replace(/\0/g, ''))
  wktFree(ptr)                                            // ④ 네이티브 메모리 해제 필수
  return { key: d.key?.length === 64 ? d.key : null, auth: d.auth !== false,
           dbOk: d.db_ok !== false, pids: +d.pids||0, opened: +d.opened||0,
           bytes: +d.bytes||0, markers: +d.markers||0, candidates: +d.candidates||0 }
}

3단계 — DLL을 어떻게 부르는가

koffi로 C 함수 시그니처를 문자열로 선언하면 그대로 호출 가능한 JS 함수가 된다. 컴파일 단계가 없어서 배포가 쉽다.

// wcdbCore.ts — FFI 바인딩
this.koffi = require('koffi')
this.lib = this.koffi.load(libraryPath)   // resources/wcdb_api.dll

this.wcdbInit        = this.lib.func('int32 wcdb_init()')
this.wcdbOpenAccount = this.lib.func(
  'int32 wcdb_open_account(const char* path, const char* key, _Out_ int64* handle)')
this.wcdbExecQuery   = this.lib.func(
  'int32 wcdb_exec_query(int64 handle, const char* kind, const char* path,' +
  ' const char* sql, _Out_ void** outJson)')

// ★ 심볼 능력 탐지 — DLL에 없으면 null로 두고 기능만 degrade
const tryBind = (decl: string): any => {
  try { return this.lib.func(decl) } catch { return null }
}
this.wcdbExecQueryWithParams = tryBind('int32 wcdb_exec_query_with_params(...)')
this.wcdbExportMessageChunk  = tryBind('int32 wcdb_export_message_chunk(...)')

그리고 DB 파일을 열 때도 역시 단정하지 않는다. session.db 후보를 점수순으로 전부 시도하고, 실패 이유를 모아 둔다.

private tryOpenWithCandidates(sessionDbPaths: string[], hexKey: string) {
  for (const sessionDbPath of sessionDbPaths) {
    const handleOut = [0]
    const result = this.wcdbOpenAccount(sessionDbPath, hexKey, handleOut)
    if (result === 0 && handleOut[0] > 0)
      return { success: true, handle: handleOut[0], matchedPath: sessionDbPath }
    errors.push(`${sessionDbPath} => ${this.mapStatusCode(result)}`)
  }
  // 전부 실패 시 errors 배열이 그대로 사용자에게 노출된다
}

4단계 — 크래시 격리와 use-after-free 방어 (백미)

FFI로 네이티브를 부르면 C 쪽에서 죽을 때 Node 프로세스가 통째로 죽는다. try/catch로 못 잡는다. CipherTalk의 해법은 두 겹이다.

겹 1 — 프로세스 격리. WCDB 호출을 Electron utilityProcess에 몰아넣는다. 죽어도 그 프로세스만 죽고, 부모(wcdbService)가 대기 중인 요청을 reject한 뒤 재시작한다.

겹 2 — 요청 직렬화. 이게 진짜 핵심이다. 저장소 주석이 문제를 정확히 서술한다.

// wcdbUtilityProcess.ts
// 모든 요청을 직렬화: 각 요청(커서 open→fetch→close 전 과정)이 끝나야
// 다음이 시작된다. close/open/shutdown 이 어떤 커서 배치의 await 틈새에
// 끼어들어, 네이티브 핸들이 해제된 뒤에도 날아가던 fetch 가 그걸 쓰는
// 상황(use-after-free → koffi napi_throw → utility process fatal)을 막는다.
let queue: Promise<void> = Promise.resolve()

parentPort.on('message', (event: Electron.MessageEvent) => {
  const msg = event.data
  queue = queue.then(() => handleMessage(msg)).catch(() => undefined)
})

프로토콜은 단순한 요청-응답이되, 특수 ID로 이벤트를 섞어 보낸다.

5단계 — IPC 계층 (메인 ↔ 렌더러)

보안 설정부터 보자. 모든 창이 동일하다.

webPreferences: {
  preload: join(__dirname, 'preload.js'),
  devTools: ctx.allowDevTools,
  contextIsolation: true,     // ✅ 렌더러와 preload의 JS 컨텍스트 분리
  nodeIntegration: false,     // ✅ 렌더러에서 require 금지
  webSecurity: false          // ⚠️ 동일 출처 정책 전역 해제 — 앞서 지적한 문제
}

통신은 세 가지 패턴을 쓴다.

패턴 1 — invoke/handle (요청-응답). 지배적 패턴. preload.ts에 ipcRenderer.invoke가 303회 등장하고, 도메인별 네임스페이스로 묶여 window.electronAPI에 노출된다. 채널 이름은 도메인:동작 규약(config:get, wcdb:connect, plugin:invoke).

패턴 2 — send/on (이벤트 푸시). 여기서 배울 규약이 하나 있다. 리스너 등록 함수가 해제 함수를 리턴한다.

onChanged: (callback) => {
  const listener = (_: any, payload) => callback(payload)
  ipcRenderer.on('config:changed', listener)
  return () => { ipcRenderer.removeListener('config:changed', listener) }
}

// 덕분에 React에서 이렇게 쓸 수 있다 — 메모리 누수 원천 차단
useEffect(() => {
  return window.electronAPI.config.onChanged(setConfig)
}, [])

패턴 3 — 커스텀 RPC. invoke를 쓸 수 없는 이른 시점(preload 초기화 중)에는 requestId로 응답 채널을 만들고 타임아웃을 건다.

const requestId = `${Date.now()}-${Math.random()}`
const responseChannel = `app:getMcpLaunchConfig:response:${requestId}`
const timeout = setTimeout(() => {
  ipcRenderer.removeAllListeners(responseChannel); resolve(null)   // 실패해도 진행
}, 600)
ipcRenderer.once(responseChannel, (_, payload) => {
  clearTimeout(timeout); resolve(payload ?? null)
})
ipcRenderer.send('app:getMcpLaunchConfig:request', { requestId })

600ms 안에 답이 없으면 null로 진행한다. 부가 기능 때문에 앱 부팅이 막히지 않게 하는 설계다.

6단계 — 데이터 파싱: 리버스엔지니어링의 현실

여기서부터가 "남이 만든 포맷"과 싸우는 구간이다. 먼저 테이블 이름부터 해시다.

// 메시지 테이블 이름 = 'msg_' + md5(sessionId)
crypto.createHash('md5').update(sessionId).digest('hex').toLowerCase()

// 역방향: 테이블 목록에서 메시지 테이블만 골라내기
String(tableName).match(/^msg_([0-9a-f]{32})$/i)
"SELECT name FROM sqlite_master WHERE type='table' AND lower(name) LIKE 'msg_%'"

게다가 컬럼 이름이 위챗 버전마다 다르다. 해법은 후보 배열 + 폴백 조회다.

const MSG_TYPE_COLUMNS = ['local_type', 'localType', 'type', 'Type',
  'msg_type', 'msgType', 'MsgType', 'message_type', 'messageType',
  'WCDB_CT_local_type']

// getRowField(row, names): 정확 매치 먼저 → 없으면 소문자 매치로 폴백

본문 자체도 그냥 텍스트가 아니다. zstd 압축이 걸려 있을 수 있다.

// rowDecoders.ts — 매직 넘버로 zstd 판별
const magic = data.readUInt32LE(0)
if (magic === 0xFD2FB528) {                        // zstd 프레임 시그니처
  return Buffer.from(fzstd.decompress(data)).toString('utf-8')
}
// 실패 시: UTF-8 시도 → 대체문자(U+FFFD)가 20% 넘으면 latin1로 폴백
// hex/base64 문자열 추정은 16자 넘을 때만 (짧은 숫자열 오탐 방지)

메시지 타입은 정수 코드로 들어온다. 주요 코드를 정리하면:

49 안의 XML <type> 서브코드: 2000=송금, 2001=홍바오, 115=선물, 6=파일, 19=대화기록 전달, 33/36=미니프로그램, 57=인용, 5/49=링크.

const rawContent = content              // ① 원본 보관
content = decodeHtmlEntities(content)   // ② 표시용은 디코딩

// ③ 필드 추출은 "디코딩 전 원본"에서 — 내층은 아직 <title> 상태라 안 걸린다
const title = decodeHtmlEntities(extractXmlValue(rawContent, 'title'))

7단계 — 이미지 복호화: 하이브리드 암호의 실제

위챗 이미지는 .dat 파일로 저장되고, 버전마다 방식이 다르다. 시그니처로 판별한다.

// datDecryptCore.ts — V4 복호화
const header = bytes.subarray(0, 0x0f)
const data   = bytes.subarray(0x0f)
const aesSize = bytesToInt32(header.subarray(6, 10))
const xorSize = bytesToInt32(header.subarray(10, 14))

// PKCS7: 이미 16의 배수여도 한 블록 더 붙는다 → +16 이 정답
const alignedAesSize = aesSize + (16 - ((aesSize % 16) + 16) % 16)

const decipher = crypto.createDecipheriv('aes-128-ecb', aesKey, null)
decipher.setAutoPadding(false)   // 패딩을 직접 제거해야 정확
unpadded = strictRemovePadding(Buffer.concat([decipher.update(aesData), decipher.final()]))

return Buffer.concat([unpadded, rawData, xoredData])

XOR 키는 어떻게 알아낼까? 썸네일 파일 여러 개의 마지막 2바이트 최빈값으로 역산한다 — JPEG는 항상 FF D9로 끝난다는 사실을 이용한 기지 평문 공격(known-plaintext attack)의 실용 버전이다.

복호화 후에도 컨테이너가 wxgf 포맷이면 여러 오프셋(0x10, 0x12, 0x14, 0x18, 0x20, 0xd0, 0x100)에서 PNG/JPG/GIF/WEBP 매직을 찾고, 그래도 없으면 앞 512바이트에서 ff d8 ff를 브루트포스한다. 포맷 리버싱의 현실적인 모습이다.

8단계 — 검색: 하이브리드 RAG

키워드 검색은 "정확한 단어"에 강하고 벡터 검색은 "비슷한 의미"에 강하다. 둘을 합치면 "작년에 형이 보내준 그 식당 이름" 같은 애매한 질의도 잡힌다. 이게 요즘 RAG의 표준 구성이다.

9단계 — 프론트엔드의 한 수: 시그널 정수

가상 스크롤 리스트를 "맨 아래로 스크롤" 시키려면 보통 ref.current.scrollToBottom()처럼 명령형으로 호출한다. 이 저장소는 다르게 했다.

/** ChatPage 가 "지금 맨 아래로 가야 한다"는 의도를 표현하는 신호.
    증가할 때마다 scrollToIndex 로 하단 이동이 한 번 실행된다. */
bottomSignal: number
/** "맨 위로" 의도 신호 (날짜 점프 등) */
topSignal: number

// 자식 쪽
useEffect(() => {
  if (bottomSignal > 0) virtualizerRef.current?.scrollToIndex(items.length - 1)
}, [bottomSignal])

5디렉토리 구조 해부

읽기 순서 추천

CipherTalk-CLI — 별도로 볼 가치가 있는 서브프로젝트

같은 저장소 안에 있지만 완전히 독립된 npm 패키지다. 자체 package.json·lockfile·의존성·테스트·릴리스 워크플로를 갖고, 데스크톱 빌드에서는 "!CipherTalk-CLI/**/*"로 명시 제외된다. Electron을 전혀 쓰지 않는다.

재미있는 UX 설계가 하나 있다. 서브커맨드 없이 실행하고 TTY면 자동으로 전체화면 인터랙티브 셸에 진입하고, --quiet나 --format을 주면 파이프 모드로 동작한다. 초보자에게는 메뉴를, 스크립트에게는 JSON을 주는 이중 인터페이스다.

6학습 포인트

A. Electron — 프로세스 모델을 제대로 이해하기

Electron 튜토리얼은 보통 "메인 + 렌더러" 2개만 가르친다. 실전 앱은 4종류를 쓴다.

utilityProcess vs worker_threads 선택 기준이 이 저장소에 잘 나타난다.

워커풀 관리도 배울 만하다.

// 코어 수에 맞춰 자동 조절, 상하한 고정
const POOL_SIZE = Math.max(2, Math.min(4, cpus().length - 2))

// 60초 동안 전원 유휴면 스레드 회수 (메모리 반납)
// 풀을 못 쓰면 null 반환 → 호출자가 인라인 복호화로 폴백

cpus - 2로 여유를 남기는 것(메인·렌더러 몫), 최소 2 최대 4로 묶는 것, 유휴 시 회수하는 것 — 데스크톱 앱은 사용자 머신을 독점하면 안 된다는 감각이 담겨 있다.

B. FFI — JS에서 네이티브 부르기

koffi는 node-gyp 컴파일 없이 문자열 선언만으로 C 함수를 부른다. 그래서 배포가 압도적으로 쉽다(사용자 기기에 빌드 툴체인이 필요 없다).

대신 지켜야 할 규칙이 있다.

C. SQL — 파라미터 바인딩을 직접 구현해 보기

구버전 DLL에 wcdb_exec_query_with_params 심볼이 없을 때를 대비해, ?를 SQL 리터럴로 직접 치환하는 폴백이 있다. 따옴표 상태머신으로 문자열 내부의 ?를 건너뛰는 게 핵심이다.

function inlineParams(sql: string, params: any[]): string {
  let quote: '"' | "'" | '`' | null = null
  for (let i = 0; i < sql.length; i++) {
    const ch = sql[i]
    if (quote) {                             // 문자열 안에 있는 중
      out += ch
      if (ch === quote) {
        if (sql[i+1] === quote) out += sql[++i]  // '' 이스케이프
        else quote = null                       // 문자열 종료
      }
      continue
    }
    if (ch === "'" || ch === '"' || ch === '`') { quote = ch; out += ch; continue }
    if (ch === '?' && index < params.length) { out += sqlLiteral(params[index++]); continue }
    out += ch
  }
  if (index !== params.length)
    throw new Error(`파라미터 개수 불일치: expected ${index}, got ${params.length}`)
}

function sqlLiteral(v: any) {
  if (Buffer.isBuffer(v)) return `X'${bufferToHex(v)}'`      // BLOB 리터럴
  return `'${String(v).replace(/'/g, "''")}'`            // 작은따옴표 이스케이프
}

D. React — 대용량 리스트와 상태 관리

E. AI 애플리케이션 설계

이 저장소의 AI 구성은 요즘 "LLM 앱"의 표준 조립을 잘 보여준다.

F. 보안 — 무엇이 잘못됐는지 읽는 훈련

이 저장소는 좋은 패턴만큼이나 잘못된 선택도 명확하게 보여준다. 그래서 교보재로 좋다.

7하드웨어 · 시스템 요구사항

macOS 포팅 상태 (참고)

// wxKeyServiceMac — 에러 코드로 실패 원인이 드러난다
PROCESS_NOT_FOUND   // 위챗이 안 켜져 있음
ATTACH_FAILED       // 프로세스 attach 실패 → SIP 해제 필요
SCAN_FAILED         // 메모리는 읽었으나 키 패턴 못 찾음
HOOK_FAILED         // 훅 설치 실패
HOOK_TARGET_ONLY    // 대상 프로세스에서만 가능

macOS는 libdobby.dylib(오픈소스 훅 프레임워크 Dobby)를 쓰고, entitlements.mac.plist로 메모리 접근 권한을 요청하며, hardenedRuntime: true로 빌드된다. 다만 notarize 설정이 build 블록에 없어 서명·공증은 환경변수에 의존하거나 미서명일 가능성이 있다.

8직접 해볼 수 있는 실습 과제

// 이것들이 전부 올바르게 처리되는가?
inlineParams("SELECT * FROM t WHERE a=? AND b='?'", [1])        // 문자열 안 ? 는 건너뛰어야
inlineParams("SELECT * FROM t WHERE a=?", ["O'Brien"])         // 작은따옴표 이스케이프
inlineParams("SELECT * FROM t WHERE a=?", ["'; DROP TABLE t;--"])
inlineParams("SELECT * FROM t WHERE a=?", [Buffer.from([0xde,0xad])])
inlineParams("SELECT ? ", [1, 2])                              // 개수 불일치 → throw

function rrf(lists: string[][], k = 60): Map<string, number> {
  const scores = new Map<string, number>()
  for (const list of lists)
    list.forEach((id, rank) =>
      scores.set(id, (scores.get(id) ?? 0) + 1 / (k + rank + 1)))
  return scores   // 내림차순 정렬해서 사용
}

// core/src/index.ts — 환경을 인터페이스로 추상화
export interface Env {
  configDir: string
  readFile(p: string): Promise<Buffer>
  log(msg: string): void
}
export function createEngine(env: Env) { /* ... */ }

// desktop: app.getPath('userData') 를 주입
// cli:     ~/.myapp 를 주입          ← 같은 코어, 다른 환경

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

Electron · 프로세스

암호 · 바이너리

시스템 · FFI

데이터 · AI

설계 패턴

11참고 링크 · 한계와 주의사항

이 저장소

배경 기술 문서

이 문서를 쓰면서 확인한 것과 확인하지 못한 것

마지막으로 — 이 도구를 실제로 쓰려 한다면