당신의 에이전트가 피어(peer)와 6시간째 대화 중입니다. 진행 중인 요청(in-flight requests), 서명 키(signing key), API 토큰, 그리고 피어가 NAT를 통해 발견한 장기 유지 터널(long-lived tunnel)이 있습니다. 보안 팀은 말합니다:

버전 관리된 키 (Versioned keys). 모든 키에 kid (Key ID)와 활성화 기간(activation window)을 부여하세요. 가장 최신의 활성 키로 서명(Sign)하고, 활성화 기간이 아직 종료되지 않은 어떠한 키로도 검증(Verify)할 수 있게 합니다. 이는 JWKS 로테이션(rotation)이 작동하는 방식이자, TLS 교차 서명된 인증서(cross-signed certificates)가 CA 전환을 용이하게 하는 방식과 정확히 일치합니다.

class RotatingKeyring:
    """유예 기간(grace window) 동안 기존 키는 검증 가능한 상태로 유지되며, 서명만 앞으로 진행됩니다."""

...

유예 기간(Grace period) 크기 설정. 중첩 기간(overlap window)은 최악의 상황을 고려하여 설정해야 합니다. 즉, 메시지가 전송 중(in flight)일 수 있는 최대 시간, 피어가 새로운 키를 인지하는 데 걸릴 수 있는 합리적인 최대 시간, 그리고 재연결 백오프(reconnect backoff) 시간을 모두 포함해야 합니다. 유지 관리 간격(keepalive interval)의 몇 배 정도로 설정하는 것이 합리적인 시작점입니다.

순차적 로테이션 (Staggered rotation). 한 번에 하나의 노드씩 로테이션을 진행하며 에러율을 모니터링한 후 다음 단계로 넘어가세요. 전체 플릿(Fleet) 단위의 로테이션은 단 한 번의 실수를 수천 명의 목격자가 지켜보는 장애(outage)로 만듭니다.

단기 비밀 정보 (Short-lived secrets). 토큰이 1년마다 만료되는 대신 매시간 만료된다면, 로테이션은 비상 훈련(fire drill)이 아닌 백그라운드 이벤트가 됩니다. 시크릿 매니저(Secrets manager)에서 제공하는 동적 비밀 정보(Dynamic secrets, Vault 스타일의 리스(leases)가 전형적인 예시임)를 사용하면 이를 무료로 얻을 수 있습니다. 에이전트는 사람의 개입 없이 스스로 가져오고, 사용하고, 갱신합니다.

에이전트가 상황을 악화시키는 지점

표준 플레이북(playbooks)을 따르면 대부분의 문제는 해결됩니다. 하지만 에이전트는 세 가지 복잡성을 추가합니다:

• 전송 중인 메시지(In-flight messages)는 단순히 권한 부여(authorized)되는 것이 아니라 서명(signed)됩니다. 토큰 확인은 요청 시점에 발생하지만, 서명 확인은 검증(verify) 시점에 발생하며, 이는 송신자가 이미 키를 교체(rotate)한 이후일 수 있습니다. 따라서 검증 경로(verification path)는 일정 기간 동안 이전 키를 허용할 수 있어야 합니다.
• 신원(identity)이 곧 자격 증명(credential)입니다. 만약 에이전트의 "키"가 곧 그 에이전트의 신원(피어들이 에이전트를 식별하는 수단)이라면, 이를 교체하는 것은 새로운 노드가 나타나는 것과 구별할 수 없습니다. 피어들은 교체 후의 에이전트를 낯선 존재로 취급할 것입니다.
• 전송 계층(transport)은 상태 유지(stateful) 방식입니다. 에이전트는 종종 매핑된 엔드포인트(endpoint)를 가진 NAT 뒤에 위치합니다. "새 키를 적용"하기 위해 데몬(daemon)을 재시작하면 해당 매핑이 끊어질 수 있으며, 에이전트는 다음 Keepalive가 발생할 때까지 도달할 수 없는 상태가 됩니다. 재시작을 요구하는 교체는 결국 지연된 다운타임(downtime)일 뿐입니다.

핵심 관통 과제: 신원(identity)과 자격 증명(credential)을 분리(decouple)하십시오. 당신이 누구인지는 안정적이어야 하며, 인증을 위해 제시하는 것은 교체 가능해야 합니다.

신원과 자격 증명의 분리 (실질적인 해결책)

TLS는 장기 인증서(long-term certificates)와 일시적인 세션 키(ephemeral session keys)를 통해 이를 구현했습니다. 인증서가 신원(identity) 역할을 하고, 연결마다 발생하는 키 교환(key exchange)은 일회용(disposable)으로 사용됩니다. 에이전트 인프라에도 동일한 분리가 필요하며, 이것이 바로 Pilot Protocol이 내린 설계 선택입니다.

Pilot Protocol은 에이전트를 위한 오픈 소스 오버레이 네트워크(overlay network)입니다. 에이전트당 영구적인 가상 주소, 암호화된 UDP 터널, NAT 트래버설(NAT traversal), 그리고 피어별 신뢰 모델(per-peer trust model)을 제공합니다. 다음 두 가지 특성 덕분에 이곳에서의 키 교체는 번거롭지 않은 작업이 됩니다:

• 주소 지정(Addressing)이 키와 분리되어 있습니다. 모든 에이전트는 등록 시 할당되는 안정적인 가상 주소(예: 0:0000.0000.0001)를 가집니다. 이 주소는 재시작, IP 변경, 클라우드 간 이동 시에도 유지됩니다. 피어(Peers)는 키가 아닌 주소를 통해 귀하에게 도달하므로, 키 자재(key material)를 교체하더라도 귀하를 찾는 방식은 변하지 않습니다.
• 터널 비밀값(Tunnel secrets)은 연결별로 관리됩니다. 각 터널은 X25519 키 교환(key exchange)을 통해 자체적인 공유 비밀값을 도출하며, 트래픽에는 AES-256-GCM을 사용합니다. 장기 신원 자재(~/.pilot/identity.json에 있는 Ed25519 키 쌍)는 신뢰 핸드셰이크(trust handshake) 서명에 사용될 뿐, 데이터 경로(data path)에 사용되지 않습니다. 장기 자재를 교체하더라도 활성 터널은 이를 통해 암호화되지 않으므로, 활성 터널이 끊기지 않습니다.

이러한 분리가 다운타임 없는 교체를 운 좋은 타이밍의 연속이 아닌, 구조적으로 가능한 일로 만듭니다. 또한 툴링(tooling)은 이를 일급 시민(first-class) 작업으로 취급합니다: pilotctl rotate-key는 새로운 신원 키 쌍을 생성하며, 문서화된 복구 흐름(pilotctl recovery enroll / new-key / recover)이 있어 키를 _분실_하더라도 주소를 잃지 않습니다. 복구 자재를 사용하여 새로운 키로 교체하고 동일한 주소를 다시 확보할 수 있습니다.

신뢰(Trust) 또한 동일한 방식으로 처리됩니다: 데몬(daemon) 재시작 후에도 유지되며 untrust로 취소할 수 있는 명시적인 피어별 핸드셰이크를 사용합니다. 멤버십(Membership)과 신뢰는 분리되어 있습니다. 즉, 키를 교체한다고 해서 신뢰 그래프(trust graph)가 초기화되지 않으며, 피어를 취소한다고 해서 네트워크의 키를 다시 교체할 필요도 없습니다. Pilot Protocol 문서에서 주소 지정, 전송(transport), 신뢰 모델에 대해 자세히 설명합니다.

이것은 마법이 아닙니다. TLS 교체를 지루할 정도로 단순하게 만들었던 것과 동일한 신원/자격 증명 분리 원리를, 단일 연결이 아닌 에이전트의 전체 네트워킹 계층에 적용한 것입니다.

실행 중인 에이전트를 위한 교체 체크리스트

어떤 전송 방식을 사용하든 동일한 체크리스트가 적용됩니다:

1. 키에 버전을 부여하세요 (Version your keys). 당신이 서명하는 모든 것에 kid + 활성화 기간 (activation window)을 포함하세요.
2. 한 번에 하나의 노드만 교체하세요. 다음 단계로 넘어가기 전에 에러율 (error rates)을 모니터링하세요.
3. 유예 기간 (grace window)을 정직하게 설정하세요. 이는 진행 중인 메시지 (in-flight message)의 수명과 피어 재연결 백오프 (peer reconnect backoff)를 모두 커버할 수 있어야 합니다.
4. 신원 (identity)과 자격 증명 (credential)을 분리하세요. 피어들이 당신을 찾는 데 사용하는 요소는 절대 교체 대상이 되어서는 안 됩니다.
5. 세션 키 분리 (session-key separation)를 선호하세요. 활성 세션이 자체 키를 보유하고 있다면, 장기적인 키 교체 (long-term rotation)는 백그라운드 이벤트가 됩니다.
6. 스테이징 피어 (staging peer)에서 테스트하세요. 먼저 테스트용 노드를 교체하고 핸드셰이크 로그 (handshake logs)를 관찰한 다음, 운영 환경 (production)에 적용하세요.

FAQ

에이전트에게 "다운타임 없는 자격 증명 교체"란 무엇을 의미하나요?
에이전트가 계속 실행되고 피어들과 통신을 유지하는 동안, 에이전트의 API 토큰, 서명 키 (signing keys), 또는 신원 키 쌍 (identity keypair)을 교체하는 것을 의미합니다. 즉, 진행 중인 메시지가 유실되지 않고, 강제 재연결이 발생하지 않으며, 에이전트에 접속할 수 없는 구간이 생기지 않는 상태를 말합니다.

중첩 기간 (overlap window)은 어느 정도여야 하나요?
가장 오래 걸리는 진행 중인 메시지 수명에 피어가 새 키를 감지하는 데 걸리는 시간, 그리고 재연결 백오프 (reconnect backoff)를 합친 시간만큼 충분히 길어야 합니다. 유지 관리 간격 (keepalive interval)의 몇 배 정도로 설정하는 것이 합리적인 시작점입니다.

키를 교체하기 위해 에이전트를 재시작해야 하나요?
아키텍처가 자격 증명을 프로세스에 결합(couple)시킨 경우에만 그렇습니다. 만약 신원과 자격 증명이 분리되어 있고 터널이 연결별 세션 키 (per-connection session keys)를 운반한다면, 교체는 설정 수준 (config-level)의 작업이 됩니다.

API 토큰 교체와 신원 키 (identity key) 교체의 차이점은 무엇인가요?
토큰은 요청을 승인하며 교체 비용이 저렴합니다. 신원 키는 피어들이 당신을 식별하는 데 사용하는 것입니다. 중첩 기간 없이 이를 교체하면 마치 새로운 노드가 나타난 것처럼 보이게 됩니다. 이것이 안정적인 주소 패턴 (stable-address pattern)이 중요한 이유입니다.

교체는 정상적인 유지 관리 이벤트이지, 장애를 기다리는 상황이 아닙니다. 이를 성공적으로 수행하는 에이전트는 키가 바뀌더라도 신원이 변하지 않는 에이전트입니다.

Pilot Protocol 시작하기:

curl -fsSL https://pilotprotocol.network/install.sh | sh

그 후 pilotctl rotate-key와 pilotctl recovery enroll 명령어를 실행하기만 하면 됩니다. 문서: pilotprotocol.network/docs