외부 OAuth 장기 토큰은 heymoa-server DB에만 둔다

• 상태: 채택됨
• 작성일: 2026-07-22
• 관련 문서: ADR-0012, APP-68, APP-74, APP-104

맥락

agent가 Linear·GitHub에 쓰기를 하려면 사용자 OAuth 토큰이 필요하다. 토큰을 어디에 두느냐가 사고 반경을 정한다. 그 토큰이 새면 털리는 쪽은 우리 서비스가 아니라 사용자의 외부 계정이다.

결정

• 장기 크리덴셜(access/refresh)은 heymoa-server DB에만 AES-256-GCM으로 암호화해 저장한다.
• heymoa-ai는 장기 크리덴셜을 보관하지 않는다. 실행 시점에 단기 토큰만 주입받는다.
• OAuth state는 HMAC-SHA256 서명 + 서버측 TTL, nonce 쿠키는 provider별 HttpOnly·SameSite=Lax.
• 로그와 toString에서 토큰을 마스킹한다.

대안

대안 1 — AI가 직접 provider 토큰을 보관. 도구 실행 경로에서 server 왕복이 사라진다. 기각한 이유: 크리덴셜 저장소가 둘이 된다. AI 프로세스까지 유출 표면으로 들어온다. 사고 반경을 좁히는 쪽이 왕복 하나보다 값이 컸다.

대안 2 — 평문 저장. 구현이 가장 단순하다. 기각한 이유: DB 유출이 곧 외부 계정 탈취다.

결과

• 크리덴셜 저장소는 하나로 고정됐다. AI 프로세스는 유출 표면에서 빠졌다.
• 연동의 소유자를 server로 못박아 둔 덕을 두 달 뒤에 봤다. APP-104가 그 소유 단위를 사용자에서 워크스페이스로 옮길 때도 저장 위치와 암호화 방식은 손대지 않고 갈 수 있었다.
• heymoa-ai가 토큰을 갖고 있지 않으므로 도구 실행 경로에 server 왕복이 하나 붙는다.
• 암호화·마스킹·state 서명·provider별 nonce 쿠키까지 server 쪽 관리 표면이 커졌다. provider가 하나 추가될 때마다 그 표면도 따라 커진다.