Clawnet 리팩토링: 프로토콜과 인증 통합으로 더 단순한 아키텍처 만들기

개발을 하다 보면 처음에는 필요에 의해 나눴던 프로토콜들이 시간이 지나면서 관리하기 힘든 짐이 되곤 합니다. 제각각인 보안 정책을 맞추느라 코드는 중복되고, 원격 장치에서 승인 요청을 보냈는데 정작 UI는 엉뚱한 곳에서 떠서 당황했던 경험이 한 번쯤은 있으실 거예요.

이런 복잡함은 유지보수 속도를 늦출 뿐만 아니라 보안 허점을 만들기도 합니다. Clawnet은 이런 문제를 해결하기 위해 프로토콜을 단일화하고 인증 모델을 하나로 합치는 대대적인 리팩토링을 진행합니다.

필요한 것

시작하기 전에 다음 항목들이 준비되어 있는지 확인해 주세요.

• src/gateway/server/ws-connection/message-handler.ts 및 src/gateway/client.ts 소스 코드
• src/infra/bridge/server/tls.ts에 정의된 TLS 런타임
• deviceId 생성을 위한 장치별 Keypair
• Node 및 Operator 역할 구분에 대한 이해

빠른 시작

Clawnet의 새로운 구조인 단일 WS 프로토콜로 전환하는 핵심 단계입니다.

1. 역할(Role) 기반의 WS 연결 설정

기존의 Gateway WS와 Bridge 프로토콜을 하나로 합칩니다. 연결 시 role과 scope를 정의하세요.

// 연결 시 전달할 클라이언트 ID 예시
{
  "deviceId": "fingerprint_of_public_key",
  "displayName": "my-macbook-pro",
  "role": "operator", // 또는 "node"
  "scope": "operator.admin"
}

2. 통합 페어링(Pairing) 흐름 적용

모든 클라이언트는 인증되지 않은 상태로 연결된 후, Gateway의 승인을 거쳐야 합니다.

1. 클라이언트가 인증 없이 연결을 시도합니다.
2. Gateway가 해당 deviceId에 대한 pairing request를 생성합니다.
3. Operator가 요청을 승인하면 Gateway가 공개 키에 종속된 토큰을 발행합니다.
4. 클라이언트는 토큰을 저장하고 인증된 상태로 재접속합니다.

3. TLS Pinning 활성화

모든 원격 트래픽에 TLS 암호화를 적용하고 Fingerprint Pinning을 통해 보안을 강화합니다.

// src/infra/bridge/server/tls.ts의 로직을 WS에 재사용
const tlsOptions = {
  key: fs.readFileSync('server-key.pem'),
  cert: fs.readFileSync('server-cert.pem'),
  // Discovery TXT 레코드에 지문(fingerprint) 노출
};

4. 중앙 집중형 승인 시스템 구현

이제 승인 UI는 Node가 아닌 Operator가 있는 곳에 나타납니다. approval.requested 이벤트를 구독하여 처리하세요.

문제 해결

진행 과정에서 발생할 수 있는 일반적인 문제입니다.

• 동일한 장치가 UI에서 중복으로 보이는 경우: 해당 장치가 operator와 node 역할을 각각 별도의 연결로 맺었는지 확인하세요. 동일한 deviceId를 사용하면 UI에서 하나의 인스턴스로 합쳐서 보여줍니다.
• 원격 승인 팝업이 뜨지 않는 경우: 클라이언트 연결에 operator.approvals 스코프가 포함되어 있는지 확인하세요. 승인 권한이 있는 Operator에게만 팝업이 전송됩니다.

---

더 자세한 설정 방법이 궁금하다면 AI Setup Assistant에 물어보세요.

다음 단계

• Gateway Protocol 상세 문서
• Bridge Protocol 마이그레이션 가이드