mvanhorn/agentcookie

agentcookie – Mac에서 Linux 에이전트로 Chrome 쿠키 동기화

기능 설명

• macOS의 Chrome Cookies SQLite 파일을 지속적으로 감시하고, macOS Keychain을 사용하여 복호화한 뒤, 암호화된 Tailscale 채널을 통해 자동화 에이전트가 실행 중인 Linux 머신으로 변경 사항을 전송합니다.
• Linux 측에서는 쿠키가 Chrome DevTools Protocol (CDP)을 통해 Chrome의 메모리 내 저장소에 실시간으로 주입되므로, Puppeteer, Playwright 또는 원시 CDP 연결을 사용하는 모든 스크립트가 Mac과 동일한 로그인 세션을 참조할 수 있습니다.
• 쿠키 문자열을 수동으로 복사/붙여넣기하거나 추가 로그인 단계를 거칠 필요가 없으며, Linux 머신에서 Chrome의 디스크 내 SQLite 데이터베이스를 다시 작성할 필요도 없습니다.

중요성

• 많은 AI/자동화 에이전트(예: Grok Bot, 커스텀 봇, 스크래핑 도구)는 헤드리스 Linux VM에서 실행됩니다. 이들은 데스크톱에서 이미 로그인한 사이트에서 로그인한 사용자로 동작해야 하는 경우가 많습니다. agentcookie는 이 과정을 안전하고 무인으로 자동화합니다.
• AES-256-GCM 암호화와 Tailscale 페어링 의식을 통해 파생된 피어별 키를 사용하므로, 의도된 싱크(sink)만 쿠키를 읽을 수 있습니다.
• 소스 측에서는 macOS 고유의 보호 기능(Keychain, Chrome의 앱 바인딩 암호화)을 처리하고, 싱크 측에서는 안전한 주입을 위해 CDP를 활용합니다.

작동 방식(상위 수준 흐름)

1. 소스 (macOS) – agentcookie source --watch가 Chrome Cookies 파일을 감시하고, 읽기 전용으로 읽어 Keychain으로 복호화한 뒤, 구성 가능한 쿠키 정책을 적용하고 데이터를 봉인된 봉투에 담아 Tailscale 네트워크상의 HTTPS를 통해 전송합니다.
2. 싱크 (Linux) – agentcookie sink가 Tailscale 주소에서 수신 대기하고, 봉투를 복호화하며, 자체 정책을 재적용하고, CDP를 통해 Storage.setCookies를 호출하여 Chrome의 실시간 저장소에 쿠키를 넣습니다.
3. 실시간 CDP 주입 – Linux에서 SQLite를 다시 작성할 필요가 없습니다. 쿠키는 새 탭이나 헤드리스 브라우저 컨텍스트에 즉시 나타납니다.

주요 구성 요소

• 페어링 마법사 – 일회용 코드와 URL을 생성합니다. 양측은 Tailscale tailnet을 통해 공개 키를 교환합니다.
• 정책 파일 – blocklist.yaml(Linux에서는 기본적으로 비어 있음, 즉 아무것도 전송하지 않음) 또는 allowlist.yaml을 사용하여 동기화할 도메인을 제한합니다.
• 구성 – ~/.config/agentcookie/ 하위의 YAML 파일로 소스, 싱크 및 선택적 다중 싱크 설정을 관리합니다.
• CLI 명령어 – wizard install, pair, source, sink, doctor, status.

일반적인 설정

1. Mac과 Linux 모두에 바이너리를 설치(또는 go install)합니다.
2. Mac에서 소스 마법사를 실행하고 페어링 코드를 기록합니다.
3. Linux 머신에서 싱크 구성을 생성(또는 macOS 싱크에서 마법사 사용)하고 코드로 페어링합니다.
4. --remote-debugging-port=9223 옵션으로 Linux에서 Chrome을 시작합니다(또는 마법사가 기존 인스턴스를 감지하게 합니다).
5. agentcookie sink(또는 systemd 사용자 서비스)를 실행하고 동기화가 일어나는지 확인합니다.

보안 참고 사항

• 통신은 종단간 암호화되며, Tailscale WireGuard 채널이 추가적인 보안 계층을 제공합니다.
• Linux 싱크는 기본적으로 빈 차단 목록을 사용하므로 명시적으로 허용하지 않는 한 아무것도 전송되지 않습니다.
• Google/Workspace에서 사용하는 장치 바인딩 세션 자격 증명(DBSC)은 싱크에서 짧은 시간 동안만 작동합니다. Linux Chrome에서 Google에 한 번 로그인해야 합니다.
• 일반 텍스트 사이드카 파일(~/.agentcookie/cookies-plain.db)은 쿠키를 암호화하지 않고 저장하므로 임시 캐시로 취급해야 하며, 주요 보안 보장은 실시간 CDP 주입에 있습니다.

제한 사항

• 단방향 동기화만 지원(Mac → Linux). 역방향 동기화는 구현되지 않았습니다.
• DBSC로 보호된 쿠키는 싱크에서 빠르게 만료되므로 로컬에서 다시 인증해야 합니다.
• 실시간 키 교체는 아직 지원되지 않으며, 새 키를 생성하려면 마법사를 다시 실행해야 합니다.
• 다중 싱크 팬아웃은 지원되지만 모든 싱크가 전체 쿠키 세트를 수신하므로 신뢰가 필요합니다.

추가 정보

• 아키텍처 세부 정보: docs/architecture.md
• 와이어 형식 사양: docs/protocol.md
• 위협 모델: docs/threat-model.md
• 빠른 시작 가이드: docs/quickstart.md

라이선스 – MIT.

---

agentcookie는 헤드리스 Linux 박스에서 자동화 에이전트를 실행하면서 수동 쿠키 처리 없이 기존 Chrome 로그인 상태를 재사용하려는 사용자를 위한 실용적인 도구입니다. 데이터는 암호화되어 개인 Tailscale 네트워크상의 머신으로만 제한됩니다.