에이전트 서명 키

이 가이드를 마치면 내 서명 키로 에이전트를 서명해, 내 서버에 연결된 맥들이 새 에이전트를 자동으로 받게 돼요. 서명이 어떤 공격을 막고 무엇을 막지 못하는지는 보안 모델을 보세요.

시작하기 전에

• 저장소를 받아 둔 맥 한 대(서명하는 맥)와 Node.js, git 이 필요해요.
• 서버 올리기로 내 서버를 올렸거나 올릴 참이어야 해요.

왜 서명이 필요한가요?

에이전트는 각 맥에서 Claude Code 세션을 띄우고 서버와 잇는 프로그램이에요. 서버는 새 에이전트 파일을 연동 탭을 거쳐 맥에 내려보내요. 맥은 그 파일을 그대로 깔지 않아요. agent/keys.mjs 에 적힌 ed25519 공개키로 서명이 맞을 때만 받아요. 그래서 서버가 뚫려도 서명 없는 코드는 맥에 깔리지 않아요.

keys.mjs 도 서명되는 에이전트 파일 가운데 하나예요. 서버가 키를 바꿔치기하면 서명이 맞지 않아 맥이 거절해요. 맥은 처음 설치할 때 받은 keys.mjs 를 믿어요.

언제 내 키가 필요한가요?

저장소의 keys.mjs 는 원 운영자의 키예요. 포크해서 내 서버를 운영하면 원 운영자의 개인 키가 없으니 서명할 수 없어요. 내 키를 만들어야 내 서버의 맥들이 자동 업데이트를 받아요.

1. 키 쌍 만들기

저장소 폴더에서 한 번만 실행하세요.

node scripts/sign-agent.mjs --init

이 명령은 두 가지를 해요. 서명은 하지 않아요.

• 개인 키를 ~/.claude-bridge-signing/agent-ed25519.pem 에 만들어요(파일 0600, 폴더 0700).
• agent/keys.mjs 가 새 공개키 하나만 믿게 고쳐요.

다른 경로를 쓰려면 CLAUDE_BRIDGE_SIGN_KEY 에 파일 경로를 주세요.

CLAUDE_BRIDGE_SIGN_KEY=KEY_FILE node scripts/sign-agent.mjs --init

KEY_FILE 은 개인 키를 둘 파일의 경로예요. 그 파일이 이미 있으면 덮어쓰지 않고 서명 키가 이미 있습니다: <경로>. 덮어쓰지 않습니다. 로 끝나요. 쓰고 있는 키를 실수로 잃지 않게 하려는 거예요.

개인 키는 저장소와 서버에 두지 마세요

개인 키가 서버에 있으면, 서버가 뚫렸을 때 공격자가 서명된 코드를 모든 맥에 깔 수 있어요. 서명하는 맥에만 두고 따로 백업하세요. 키를 잃으면 그 키만 믿는 맥에는 더는 업데이트를 보낼 수 없어요.

2. 에이전트를 고칠 때마다 서명하기

agent/ 의 파일을 고쳤으면 커밋하기 전에 서명하세요.

node scripts/sign-agent.mjs

agent/agent.sig: build <build> · seq <seq> 서명함 이 보이면 돼요. 바뀐 agent/agent.sig 를 에이전트 변경과 같은 커밋에 넣으세요.

agent.sig 에는 순번(seq)이 들어가요. 순번은 서명할 때마다 커져요. 서명하는 순간의 초, 이 체크아웃 agent.sig 의 순번 + 1, origin/main 의 순번 + 1 가운데 가장 큰 값이에요. 그래서 스크립트는 서명 전에 git fetch origin main 을 해요. 맥은 지금 가진 것보다 작은 순번의 업데이트를 버려요. 예전 에이전트로 되돌릴 때도 다시 서명해 새 순번을 주세요.

npm test 가 실패하면

npm test 는 agent/agent.sig 가 지금 에이전트 파일과 맞지 않으면 실패해요. 에이전트 파일을 고친 뒤 서명을 잊었다는 뜻이에요. node scripts/sign-agent.mjs 를 실행하고 다시 돌리세요.

3. 서버에 배포하기

서명한 커밋으로 이미지를 다시 빌드해 배포하세요. 서버는 켜질 때 agent/agent.sig 를 읽고, 그 서명이 지금 에이전트 파일과 맞는지 확인해요. 맞으면 버전이 다른 맥이 연결될 때 새 파일과 서명을 함께 보내요. 맥은 세션이 쉴 때 파일을 바꾸고 다시 시작해요. 세션은 맥의 터미널 프로그램(zeropty 또는 tmux)에 남아 그대로 이어져요. 배포 절차는 끊기지 않는 배포를 보세요.

서명에 문제가 있으면 서버는 업데이트를 보내지 않고, 운영 탭의 "최신 에이전트 build" 타일에 알려요.

운영 탭 표시	뜻	해결
서명 안 됨, 업데이트 안 보냄	agent.sig 가 지금 에이전트 파일의 서명이 아니에요	서명하고 다시 배포하세요
서명 순번이 뒤로 감, 업데이트 안 보냄	이 배포의 순번이 전에 내보낸 것보다 작아요	다시 서명하고 배포하세요

서버는 지금까지 맥에 내보낸 가장 큰 순번을 데이터 폴더의 agent-seq.json 에 적어 두고 비교해요.

4. 맥 설치하기

내 서버에서 설치 스크립트를 실행한 맥은 그때 받은 keys.mjs, 곧 내 공개키를 믿어요.

curl -fsSL SITE/install.sh | bash

SITE 는 내 서버 주소예요(예: https://bridge.example.com). 설치 명령과 옵션은 설치 스크립트와 에이전트 명령을 보세요.

--init 전에 설치한 맥은 다시 설치하세요

--init 전에 설치한 맥은 원 운영자의 키나 이전 키를 믿어요. 이 맥은 새 키로만 서명한 업데이트를 받지 않아요. 그 맥에서 위 설치 명령을 한 번 더 실행하세요.

5. 키 바꾸기

맥은 지금 믿는 키로 서명된 업데이트로만 새 keys.mjs 를 받아요. 그래서 키를 바꾸는 업데이트는 지금 믿는 키로 서명해야 해요. 맥을 다시 설치하지 않고 키를 바꾸려면 두 번에 나눠 배포하세요.

1. CLAUDE_BRIDGE_SIGN_KEY 로 새 경로를 주고 --init 으로 새 키 쌍을 만드세요. 이때 keys.mjs 는 새 키 하나만 믿게 바뀌어요.
2. agent/keys.mjs 의 UPDATE_KEYS 에 이전 공개키를 다시 넣어, 두 키를 모두 믿게 하세요.
3. 이전 키로 서명하고 배포하세요. 맥들이 두 키를 믿는 keys.mjs 를 받아요.
4. 운영 탭의 사용자별 기기 에서 맥들이 모두 "최신" 이 됐는지 확인하세요.
5. UPDATE_KEYS 에서 이전 키를 빼고, CLAUDE_BRIDGE_SIGN_KEY 로 새 키를 골라 서명해 배포하세요.

원 저장소의 keys.mjs 가 키를 두 개 두는 것도 같은 이유예요. 두 번째 키는 첫 키를 바꿀 때 맥을 남겨 두지 않으려고 미리 믿게 해 둔 예비 키예요.

확인하기

• npm test 가 통과하면 agent.sig 가 지금 파일과 맞아요.
• 배포 뒤 운영 탭의 "최신 에이전트 build" 타일에 서명 경고가 없으면 성공이에요.
• 맥의 호스트 로그나 ~/.claude-bridge/agent.log 에 새 버전 <build> 을 받음(관리자 서명 확인 · 순번 <seq>) 이 보이면 맥이 업데이트를 받은 거예요.

문제가 생기면

• 서명 키가 없습니다: <경로>: 이 맥에 개인 키가 없어요. 키를 둔 맥에서 서명하거나 CLAUDE_BRIDGE_SIGN_KEY 를 확인하세요.
• 이 키는 에이전트가 믿는 키(agent/keys.mjs)가 아닙니다. 새로 만들려면 --init.: 쓰려는 개인 키의 공개키가 keys.mjs 에 없어요.
• 맥 로그에 새 버전(<build>)에 관리자 서명이 없거나 맞지 않아 버림: 그 맥이 다른 키를 믿어요. 4단계처럼 다시 설치하세요.
• 맥 로그에 지금 것보다 먼저 서명된 것 이라 버림: 순번이 작은 서명이에요. 다시 서명해 배포하세요.

다음 단계

• 끊기지 않는 배포: 서명한 버전을 요청 실패 없이 올려요.
• 문제 해결: 맥이 업데이트를 받지 않을 때 볼 곳이에요.
• 보안 모델: 서명이 막는 것과 막지 못하는 것이에요.