# 구현된 연결 관리 계약 · 2026-09-23 이 문서는 migration 4의 실제 코드 계약이다. `CONTROL_SERVER.ko.md`의 초대/relay/분리 crate 제안 전체가 구현된 것은 아니다. 단일 소유자·최대 64개 장치이며 기기 사용자 계정은 없다. 관리자 웹은 별도의 비밀번호/로그인 세션을 사용한다. 호스트 접속 비밀번호/Argon2 verifier는 서버에 전송하거나 저장하지 않는다. ## 코드 없는 등록 및 관리자 웹 `POST /v1/devices/enrollment/request`는 `enrollment_request` challenge 서명과 display_name으로 요청하며 `POST /v1/devices/enrollment/status`는 별도 `enrollment_status` 서명으로 자기 기기의 상태만 조회한다. 응답은 `{device_id,state:{status}}`이고 status는 `not_requested`, `pending` (expires_at 추가), `registered`, `revoked`다. 요청은 600초/64개로 제한하며 중복 요청은 원래 내용/만료 시각을 유지한다. 조회는 요청을 생성하거나 연장하지 않는다. 승인 전 기존 인증/목록 API 접근은 거부되며 폐기 기기는 재등록하지 않는다. `https://remote.n3m.kr/`에서 관리자는 이름/ID/만료 시각을 확인하고 승인·거절하며 등록된 기기의 상태 확인과 등록 해제를 수행한다. 웹 API는 별도 Bearer 관리자 토큰이 필요하며 장치 token은 거부한다. `api/login`은 별도 Argon2id 관리자 비밀번호를 검증하며 서버 전체 분당 5회/최대 16세션/900초로 제한한다. 토큰은 브라우저 메모리에만 보관한다. 로그아웃, 비밀번호 교체, 재시작 후 이전 token은 무효다. 승인에는 장치 ID 전체의 명시적 확인을 요구하며 호스트 grant를 자동 생성하지 않는다. 최초 관리자 비밀번호 설정과 잊어버린 비밀번호의 복구는 서버의 `set-admin-password` 명령을 사용한다. 로그인한 관리자는 계정 관리 페이지에서 현재 비밀번호를 확인하고 새 비밀번호로 변경할 수 있다. [운영 안내](../deploy/ubuntu/WEB_ADMIN.ko.md). `POST /notparsec-admin/api/account/password`는 관리자 Bearer와 `{current_password,new_password}`를 받는다. 현재 비밀번호 재확인은 로그인·명령 다운로드와 같은 서버 전체 분당 5회 한도를 사용한다. 2026-09-27 사용자 요청에 따라 관리자 비밀번호의 길이·문자 구성·기존 값 재사용 제한을 제거했다. 빈 값만 거부하며 로그인/다운로드/CLI 초기화에도 동일한 관리자 전용 해시·검증을 적용한다. 기존 JSON 요청 크기 한도는 유지한다. 성공은 204, 유효하지 않은 관리자 세션은 401, 현재 비밀번호 불일치는 403, 빈 새 비밀번호는 400, 시도 한도 초과는 429다. 성공 시 verifier와 generation을 조건부 원자 갱신하고 모든 이전 관리자 토큰을 무효화한다. 동시 웹 변경·CLI 초기화·처리 중 로그아웃/만료가 발생하면 뒤늦은 변경을 거부한다. 기기 인증 키나 원격 PC 접속 비밀번호를 변경하는 API가 아니다. [계정 관리 구현·검증](ADMIN_ACCOUNT.ko.md). ## 통합 앱 원격 연결 API `/v1/remote`는 통합 Windows 앱의 기기 목록 연결·PC 간 TLS·화면/입력 중계 계약이다. 모든 경로에서 등록된 기기의 Bearer 인증을 요구하며 관리자 웹 토큰은 받지 않는다. 등록 승인, 대상 PC의 명시적인 접속 허용, PC 사이의 키 소유 증명과 접속 비밀번호를 순서대로 확인한다. 이 경로는 이전 `/v1/sessions`의 grant/ticket 실험 계약을 사용하지 않는다. | 경로 | 계약 | |---|---| | POST `/v1/remote/host` | 자신의 TLS 인증서 hex와 기기 서명 등록/갱신. 30초 뒤 만료 | | DELETE `/v1/remote/host` | 자신의 접속 허용 해제와 관련 중계 종료 | | GET `/v1/remote/hosts` | 유효한 접속 허용과 서명된 공개 인증서 목록 | | POST `/v1/remote/sessions` | `{host_id}`. 자신과의 연결 거부, 호스트당/클라이언트당 1개 | | GET `/v1/remote/requests` | 자기 PC에 도착한 미참여 연결 요청만 조회 | | WSS `/v1/remote/sessions/{id}/relay` | 해당 두 참가자만 1회씩 참여. URL query 거부, TLS 레코드 바이너리 전달 | | DELETE `/v1/remote/sessions/{id}` | 참가자가 중계를 취소/종료 | `GET /v1/devices`에는 `hosting` boolean을 추가한다. UI는 이 값으로 연결 버튼을 활성화한다. 중계의 메모리/대역폭/시간 상한, TLS 내부 인증과 종료 처리는 [통합 구현 문서](UNIFIED_REMOTE.ko.md)를 따른다. 중계 상태는 메모리에만 있으며 재시작 시 복원하지 않는다. 기존 SQLite schema 4는 유지한다. ## 호환성과 오류 관리자 다운로드 API는 `GET /notparsec-admin/api/downloads`에서 `{files:[{id,filename,bytes,sha256,release}]}`를 반환한다. `release`는 검증된 `{version,build,commit}` 또는 `null`이다. Windows는 실제 EXE와 `update.json`의 해시·크기가 일치해야 하며, Mac은 각 아키텍처 패키지의 `package.json.release`를 사용한다. 메타데이터가 없는 정상 파일도 수동 다운로드할 수 있다. `GET /notparsec-admin/api/downloads/{id}`의 id는 `desktop`, `desktop-macos-arm64`, `desktop-macos-x86_64`만 허용한다. 목록은 관리자 Bearer 인증이 필요하며 고정 파일 GET은 기존 명령어용 관리자 Basic 인증도 허용한다. 다운로드 응답은 `Content-Disposition: attachment`, 실제 `Content-Length`, `X-Checksum-Sha256`, `Cache-Control: no-store`를 포함한다. 게시된 통합 Windows EXE와 Mac 패키지만 제공하며 파일 경로를 입력받지 않는다. Mac DMG는 검증한 운반 패키지에서 추출한다. 폴더 미설정/파일 미배치 시 목록은 비어 있고 파일 요청은 404다. [다운로드 계약과 버전·일시 표시](ADMIN_DOWNLOAD_PAGE.ko.md)를 따른다. 기존 challenge/enroll/verify/devices/heartbeat 요청·응답은 유지한다. 장치 ID는 Ed25519 공개키의 SHA-256이며 키는 불변, key_version은 1이다. 키 교체는 기존 장치 폐기와 새 키/코드 등록으로 수행한다. 공개 challenge 메시지의 기존 domain separator를 유지하고, 클라이언트 장치 파일은 HTTPS origin에 묶인다. access token은 메모리에만 300초 보관하며 재시작 시 무효화된다. 새 DTO는 `crates/wire/src/control.rs`, 서버 구현은 `apps/control-server/src/control.rs`와 `api/control_api.rs`, 클라이언트 API·서명 검증 helper는 `crates/device-client/src/control.rs`다. 이 helper는 Windows GUI/QUIC에 아직 연결되지 않았다. `/v1` 오류는 안전한 JSON `{version:1, code, request_id, retryable}`이다. SQL/역직렬화 입력·token·코드는 응답/로그에 포함하지 않는다. 401 인증 실패, 403 권한 부족, 404 접근 불가/없는 세션, 409 revision·상태 경합, 413 본문 초과, 429 상한 초과다. client는 409 후 GET으로 다시 읽고 사용자의 의도를 재확인한다. 비밀번호 없이 연결을 자동 재개하면 안 된다. ## 구현 API 기존 API 외에 다음이 있다. 모두 Bearer 장치 인증이 필요하다. admin은 별도 실행 파일이 아니라 서버 subcommand다. | 경로 | 계약 | |---|---| | GET `/v1/server` | 버전, 현재 epoch, 공개 서명 키, timeout 상한 | | WSS `/v1/events` | snapshot 및 heartbeat_ack. 아래 연결 계약 참고 | | POST `/v1/sessions` | `{host_id,idempotency_key}`. 로컬 관리자가 허가한 장치→호스트 조합만 허용 | | GET `/v1/sessions/{id}` | 참가자만 SessionView 조회. 제3자는 404 | | POST `/v1/sessions/{id}/transition` | `{expected_revision,action}`. 아래 상태 전이 | | POST `/v1/sessions/{id}/ticket` | 승인된 client만 ticket 획득 | | POST `/v1/sessions/{id}/consume` | 지정 host만 `{ticket,peer_signature}` 원자적 소비 | | POST `/v1/sessions/{id}/lease` | 참가자 자신의 권한 lease만 갱신 | | GET/POST `/v1/sessions/{id}/candidates` | 승인 후 참가자만 후보 읽기/자신의 후보 교체 | 설계의 `/decision`, `/cancel`, `/close`는 별도 endpoint가 아니다. 구현은 `/transition`으로 통합했다. `/invitations`, `/trust`, `/relay`는 미구현이다. ## WSS 초기화·복구 HTTP Upgrade의 `Authorization: Bearer ...`와 `X-Notparsec-Boot-Id: <64자 hex>`를 사용한다. boot_id는 장치 프로세스 시작마다 OS 난수로 생성한다. URL query는 전부 거부한다. 브라우저 JS WebSocket API는 임의 Authorization 헤더를 지원하지 않으므로 이 계약은 native client용이다. 연결마다 서버가 새로운 generation을 발급하고 첫 메시지로 `{type:"snapshot",version:1,epoch,revision,generation,boot_id,devices,sessions,history_truncated,resync:true}`를 보낸다. 증분 이벤트를 무한 보관하지 않으며, DB 상태가 바뀌면 전체 snapshot을 다시 보낸다. 클라이언트는 같은 epoch에서 더 오래된 revision을 무시하고 snapshot으로 로컬 상태를 교체한다. 재연결 때도 무조건 snapshot을 받는다. epoch가 바뀌면 이전 상태/ticket을 버린다. 장치 전체 목록과 참가 세션만 포함하며, 다른 장치의 후보·ticket·비밀값은 포함하지 않는다. 장치당 미종료 세션 16개, snapshot에는 미종료를 우선한 최대 32개를 담고 오래된 종료 이력 생략 여부를 표시한다. 알고 있는 세션은 개별 GET으로 확인할 수 있다. snapshot에서 사라진 로컬 세션을 계속 사용하면 안 된다. 10초마다 `{version:1,generation,boot_id}` 텍스트 heartbeat를 보낸다. 30초 미갱신/장치 폐기/다른 generation/token 만료/서버 종료 시 연결을 닫는다. token 만료 전 공개키로 다시 인증하고 재연결한다. 기기 인증 재연결은 원격 비밀번호 재입력을 생략할 권한이 아니다. GUI는 기존 HTTP heartbeat의 30초 lease를 10초마다 자동 갱신하며 새 WSS를 자동 시작하지 않는다. 128개 broadcast revision 큐, socket 최대 64개, 프레임/수신 메시지 8KiB, 송신 snapshot 64KiB, 송신 timeout 2초다. 큐 유실·느린 소비자는 종료 후 재동기화한다. 끊긴 socket의 정리는 generation/boot_id가 현재 DB와 일치할 때만 수행한다. 관리자 CLI 변경도 최대 약 1초 polling으로 전달한다. 재시작 시 presence를 모두 비운다. ## 세션·ticket·lease `awaiting_approval → transport_ready → awaiting_password → authorized → connecting → active`다. host의 `approve`/`deny`, client의 `cancel`, 참가자의 `close`를 지원한다. `password_accepted`는 host가 로컬에서 비밀번호를 확인했다는 보고이고 비밀번호 검증을 서버가 대신한 결과가 아니다. 양쪽 `media_started` 보고가 있어야 active가 된다. 테스트의 mock 보고는 실제 스트리밍 증거가 아니다. 모든 변경은 SQLite IMMEDIATE transaction에서 이전 revision과 권한을 확인한다. idempotency_key는 client와 payload(host)에 묶이고 다른 host로 재사용하면 409다. 종료 세션은 승인으로 되살아나지 않는다. 일치하는 종료 요청은 중복 성공을 허용한다. 승인 대기 60초, 승인 후 ticket 30초, 소비 후 비밀번호 대기 90초, 인증 보고 후 시작 대기 60초다. 서버 재시작은 모든 미종료 세션을 expired로 만든다. ticket은 ring Ed25519로 `notparsec-connect-ticket-v1\n` + 정확한 payload UTF-8 바이트에 서명한다. payload는 세션 ID, 양쪽 장치 ID/공개키/key_version, epoch, host별 audience, nonce, issued_at/expires_at, `connect_attempt_requires_host_password` capability에 묶인다. host는 HTTPS로 받은 현재 서버 공개키/epoch와 `verify_ticket` helper로 확인한다. 임의 ticket 내부의 키를 신뢰 앵커로 삼지 않는다. client는 장치 키로 `notparsec-ticket-peer-v1\n` + ticket payload에 서명한다. host는 암호화된 peer transport에서 해당 키 소유/신원을 확인하고 `/consume`으로 이 증명을 보낸다. 서버는 현재 grant·장치·epoch·대상·서명·만료·단일 소비를 검사한다. 이 단계 후에도 host 비밀번호를 반드시 새로 입력·검증해야 한다. QUIC의 장치 키 증명과 이 helper의 결합은 Windows 후속 작업이다. 서명 키는 권한 0600의 `control.signing.key`다. 서버 시작마다 새로운 epoch를 생성하므로 같은 키를 복원해도 이전 ticket은 재사용할 수 없다. 서명 키 교체는 서비스 정지→DB/키 백업→기존 키를 보관 위치로 이동→시작으로 수행하고 Windows는 인증된 HTTPS로 현재 키/epoch를 다시 조회한다. 별도 공개 키 교체 API는 없다. 권한은 `grant-host --client-id ... --host-id ...`와 `revoke-grant`로 관리한다. 철회/장치 폐기는 같은 transaction에서 관련 세션을 closed로 바꾼다. WSS snapshot의 terminal 상태는 host 종료 명령이며, host는 입력 해제/미디어 종료 후 `termination_ack`를 보낸다. ACK는 SessionView의 termination_ack로 확인한다. 폐기된 host는 인증 자체가 차단되므로 ACK가 없을 수 있다. 각 참가자가 최대 30초 간격으로 lease를 갱신하고 host/client 중 하나라도 120초가 지나면 서버는 expired 처리한다. Windows는 마지막 성공 후 monotonic 시계로 120초 이내에 입력·미디어를 반드시 종료해야 한다. 서버 단절 중 실제 Windows watchdog 집행은 아직 구현/검증하지 않았다. 짧은 ticket 만료와 이미 시작한 세션의 lease 만료는 다른 개념이다. ## 명시 endpoint·상한 후보 POST는 `{generation,ttl_seconds,endpoints:["192.168.50.20:40010"]}`다. 양의 단조 증가 세대, TTL 1–60초, 세션 전체 최대 16개, 숫자 IP, UDP 포트 1024 이상만 받는다. unspecified/loopback/multicast/link-local/broadcast/IPv4-mapped IPv6는 거부한다. 다른 참가자는 승인 후에만 볼 수 있고 만료된 주소는 반환하지 않는다. 서버는 해당 주소에 접속하거나 패킷을 전송하지 않는다. 응답의 `max_probes_per_endpoint:3`은 peer 구현의 필수 상한이다. peer는 같은 UDP socket에서 작은 인증 probe만 보내고 검증 전 미디어를 보내지 않아야 한다. 이 peer 경로·공유기 포트포워딩·STUN·hole punching·relay는 아직 없다. API TCP 443과 Windows host UDP는 별개이며 이번 서버 구현 때문에 UDP 포트를 공개하지 않는다. HTTP 본문 4KiB, 서버 전체 128요청/초·동시 요청 64개, challenge/credential 각각 1024개, 장치 64개, 세션 기록 1024개다. 종료 세션은 7일 후 정리되어 idempotency 보장 기간도 7일이다. audit는 30일/최대 10,000개다. 공개 Nginx는 인증 경로 IP별 5r/s+burst10, 기타 API 30r/s+burst30, 동시 연결 32개를 적용한다. 앱은 forwarded IP 헤더를 신뢰하지 않는다. Cloudflare 경유 시 Nginx 제한은 edge IP 기준이며 실제 client IP 기반 정책은 검증된 proxy 주소 목록 설정 후 별도 도입한다. ## 후속 F32/F33 기본 홈서버와 명시 endpoint 계약을 먼저 통합한다. F32는 STUN 관측, 후보 검증, Windows peer hole punching과 외부 회선 직접 연결 시험이다. F33은 암호문 relay 프로세스, 세션별 인증/allocation/만료, 대역폭·총 트래픽·큐 상한, endpoint 반사 방지와 외부망 시험이다. 현재 control-server는 UDP를 수신하거나 relay하지 않는다. VPS/WireGuard는 필수 조건이 아니며 가정용 회선 경로의 실제 제약이 확인될 때 대안으로 검토한다.