iop/agent-contract/inner/client-control-plane-wire.md

Client-Control Plane Wire Contract

계약 메타

• id: iop.client-control-plane-wire
• boundary: inner
• status: active-mvp
• 원본 경로:
  • proto/iop/control.proto
  • apps/control-plane/internal/wire/wire.go
  • apps/control-plane/internal/wire/client.go
  • apps/control-plane/cmd/control-plane/credential_http_handlers.go
  • apps/control-plane/cmd/control-plane/credential_commands.go
  • apps/client/lib/iop_wire/client_wire_client.dart
  • apps/client/lib/iop_wire/parser_map.dart
• human docs:
  • apps/control-plane/README.md
  • apps/client/README.md

읽는 조건

• Client /client WebSocket proto-socket endpoint를 바꿀 때
• ClientHelloRequest 또는 ClientHelloResponse를 바꿀 때
• Client가 Control Plane을 통해 Edge/Node 운영 상태를 관찰하는 wire baseline을 검토할 때
• principal bootstrap, credential-slot/route HTTPS lifecycle, or client-facing credential ownership changes

범위

Client protobuf wire는 hello-only를 유지하고, post-bootstrap slot write는 server-authenticated HTTPS와 principal auth로 수행한다. 최초 principal/bootstrap은 계속 host-local CLI 전용이며 remote wire에 노출하지 않는다.

주요 흐름

• Client는 /client WebSocket으로 Control Plane에 연결한다.
• Client가 ClientHelloRequest를 보내면 Control Plane은 ClientHelloResponse로 readiness, protocol, server time, message를 응답한다.
• Control Plane listen 주소는 server config와 IOP_WIRE_LISTEN/compose port 기준으로 주입한다.

Credential HTTPS boundary

• Principal bootstrap is an offline, host-local CLI operation. It returns the raw IOP token once; no WebSocket or remote HTTP bootstrap route exists.
• Post-bootstrap slot and route lifecycle uses the dedicated credential HTTPS listener only. The listener presents the configured server certificate, and callers validate its CA and server name.
• Every credential request requires Authorization: Bearer <IOP token>. Slot create and rotate accept the provider secret only as an application/octet-stream body; list, disable, enable, revoke, and route operations never return provider plaintext.
• Slot mutations use an explicit expected revision. A successful mutation rebuilds the secret-free principal projection and synchronizes it to connected managed Edges before the operation is treated as complete.
• TLS private keys, the at-rest encryption keyring, the lease issuer private key, and raw principal/provider credentials are external mounts. They are never tracked config or Client wire fields.

필드 의미

• ClientHelloRequest.client_id: client instance 식별자다.
• ClientHelloRequest.client_version: client build/version 관찰값이다.
• ClientHelloResponse.ready: Control Plane이 client 요청을 받을 수 있는지 나타낸다.
• ClientHelloResponse.protocol: 현재 protobuf-socket 값을 사용한다.
• server_time_unix_nano: client가 Control Plane time 기준을 관찰하는 값이다.

금지 사항

• Client가 Edge나 Node 내부 TCP/protobuf transport에 직접 연결하는 계약을 만들지 않는다.
• Client를 특정 외부 제품 shell 또는 navigation 계약으로 고정하지 않는다.
• Client wire에 실제 환경 endpoint, credential, private host 값을 tracked 문서로 기록하지 않는다.
• Dart protobuf 생성물을 proto 원본과 불일치하게 두지 않는다.
• 최초 principal/bootstrap을 remote wire나 Client WebSocket에 노출하지 않는다. post-bootstrap credential slot write는 server-authenticated HTTPS credential-plane listener와 principal auth token으로만 수행하며, raw provider secret은 request body로 한 번만 전달되고 저장되지 않는다.
• Do not reuse the Client hello WebSocket as a credential transport, and do not expose ciphertext, lease envelopes, raw tokens, private keys, or provider credentials through Client responses.

변경 시 확인할 코드/테스트

• proto/iop/control.proto
• apps/control-plane/internal/wire/client_test.go
• apps/client/test/iop_wire/client_wire_client_test.dart
• apps/client/test/iop_wire/parser_map_test.dart
• apps/control-plane/internal/credentialops/service_test.go
• apps/control-plane/cmd/control-plane/credential_http_handlers_test.go
• apps/control-plane/cmd/control-plane/credential_store_test.go
• apps/control-plane/cmd/control-plane/secure_delivery_integration_test.go
• proto 변경 시 make proto와 make proto-dart