# 개인 연결 관리 서버 설계 · v5 / Ubuntu 구현 보강 대상은 공인 IP와 UDP 포트포워딩이 가능한 Ubuntu 개인 홈서버 1대, 소수의 Windows 장치다. **최신 구현 계약은 [CONTROL_API_V1](CONTROL_API_V1.ko.md), 실제 배포·시험 결과는 [UBUNTU_OPERATIONS](UBUNTU_OPERATIONS.ko.md)**를 따른다. 아래 API·모듈 전체는 자체 설계이며 실제 코드와 차이가 있다. 기능 선택과 완료 기록은 [개발 체크리스트](notparsec-plan.html#server-system), 배치와 용어는 [홈서버 설명](homeserver-architecture.html)에서 확인한다. ## 확정한 단일 사용자 인증 (v5) 사용자 계정 가입·로그인·로그아웃은 구현하지 않는다. “클라이언트 비밀번호”는 접속 대상 PC(host)에 설정하고 접속 앱(client)이 매 연결마다 입력하는 비밀번호로 해석한다. F80–F82에 보호 저장·QUIC 비밀번호 gate·비밀번호 입력/설정 UI를 추가했다. 앱 내부 장치 등록과 공개키 기반 API 인증은 계정 화면 없이 유지한다. host는 Argon2id verifier를 로컬에 두고 Windows DPAPI로 개인키와 함께 보호한다. Ubuntu 서버에는 원문 비밀번호·verifier를 저장하거나 전송하지 않는다. client는 신뢰한 host 인증서를 먼저 확인한 QUIC 암호화 채널에서만 비밀번호를 보낸다. 매 새 연결/재연결에서 다시 확인하며 0-RTT 인증과 비밀번호 자동 저장은 사용하지 않는다. 명시적으로 허용한 offline direct/VPN 접속도 비밀번호 gate를 생략하지 않는다. Ubuntu 24.04.4 LTS·Intel N100·x86_64에서 Rust 1.93.1 native build와 실행을 확인했다. migration 3, WSS snapshot/revision/generation, 세션·ticket·grant·lease·철회 ACK·명시 후보 교환을 추가했다. sudo 권한 대기로 systemd/운영 Nginx 적용은 아직 하지 못했다. 격리 TLS/WSS·임시 DB·mock peer 통과와 Windows/외부망 실증은 구별한다. [현재 구현·실행 방법](../IMPLEMENTATION.md). 기존 등록 계약은 [구현 기록 2](IMPLEMENTATION_WAVE_2.ko.md), 확장 계약은 [CONTROL_API_V1](CONTROL_API_V1.ko.md)에 있다. 초대·relay·별도 control-admin/protocol/store crate는 아직 없으며 관리자 명령은 notparsec-control-server subcommand다. 개인 소유 등록 기기는 같은 장치 목록을 공유하고 host 접속 권한은 별도 grant로 검사한다. ## 재검토 결과 기존 F06/F17에는 PC 키·승인, F32/F33에는 최소 rendezvous·relay, F64/F65에는 장치 목록·초대 UI가 있었다. 서버 실행, DB transaction, API 인증, WSS 재동기화, 세션 ticket, 철회 전달, 배포·백업·통합 시험의 독립 완료 기준이 부족했다. 이를 F71–F79로 추가하고 F32→F77, F64→F74, F65→F76 선행 관계를 연결했다. F64/F65는 인터넷 사용을 완성하는 M4로 이동한다. 기존 기록을 보존하되 새 선행 항목이 미완료인 완료 기록은 재검토 경고로 표시한다. 기본 30개는 LAN 엔진 범위로 유지한다. “연결 관리 서버 추가”는 F71–F79와 선행 기능을 기존 선택에 더한다. 이 범위만으로 명시 endpoint/개인 VPN 경로를 운영할 수 있게 하고, 자동 NAT 통과(F32)·media relay(F33)는 독립 추가 선택으로 둔다. API 명세와 단위 시험만으로 F79를 완료 표시하지 않는다. ## 프로세스와 경계 ```text Windows host/client └─ HTTPS / WSS → 기존 Nginx :443 (n3m.kr) └─ apps/control-server 127.0.0.1:18080 (내부) router → auth → directory / sessions / grants ↕ bounded event dispatcher ↕ SQLite store └─ 미디어 → PC 간 QUIC 또는 암호문 relay apps/relay-server 선택, F33; media와 별도 allocation/quota control-server 명령 issue-enrollment / revoke-device / grant-host / revoke-grant crates/control-domain 상태 전이·권한·ticket 계약, 순수 Rust 시험 crates/control-store SQL·migration·transaction·backup 경계 crates/protocol host/client/server 공유 DTO·오류·버전 deploy/ubuntu systemd, 기존 Nginx include, 일관 백업·복원·rollback ``` 개인용 API는 하나의 Rust 프로세스로 시작한다. Linux 서버용 build에는 DXGI·NVENC·Windows UI를 링크하지 않는다. Tokio/axum과 SQLite adapter는 버전을 고정해 채택한다. media 평문·입력 내용·채팅 본문은 control API로 보내지 않는다. 연결 정책과 실제 미디어 권한 집행은 분리한다. 서버가 ticket을 발급했어도 host의 저장된 신뢰·로컬 정책 검사를 통과해야 한다. ## F71–F73 · 설정, 저장, 신원 설정은 listen 주소, 외부 API URL, DB/key 경로, 신뢰하는 proxy, 명시 endpoint·선택 relay, timeout/크기/로그 보존 상한을 포함한다. 비밀 값은 HTML·저장소·CLI 인자·로그에 넣지 않는다. liveness는 프로세스 상태, readiness는 migration/DB/key 준비 상태를 구분한다. DB 실패 상태에서 등록·권한·ticket 변경을 성공으로 반환하지 않는다. | 테이블 | 핵심 필드와 불변 조건 | |---|---| | devices | DeviceId, 공개키/fingerprint, 표시명, key_version, revoked_at. IP와 이름을 신원으로 사용하지 않음 | | enrollment_codes | code hash, scope, expires_at, consumed_at. 한 transaction에서 정확히 한 번만 소비 | | trust_grants | client_id, host_id, capability 범위, expiry, revision. 실제 권한은 host 정책과의 교집합 | | invitations | token hash, 발급자, host, 수신 장치 key 또는 제한된 claim 절차, 권한, 만료·소비·폐기 | | sessions | SessionId, 양쪽 key/version, epoch, 상태/revision, deadline, 권한. 이전 상태를 조건으로 전이 | | session_audit | 시각·장치/세션 ID·상태 전이·오류 이유. 민감 payload 제외, 보존 기간 설정 | | schema_version | 적용된 migration 이력과 호환 버전 | heartbeat lease, socket, 짧은 challenge·중복 요청 cache는 bounded 메모리다. 재시작 시 이전 연결은 offline/unknown, pending 세션은 expired로 처리한다. 영속 Active 기록은 현재 스트림의 생존 증명이 아니다. 양쪽 보고를 다시 수집하고 이전 ticket으로 새로운 연결을 만들지 않는다. 관리자 bootstrap은 로컬 CLI에서 시작한다. 고엔트로피 일회 등록 코드로 공개키를 등록할 때 장치가 서버 challenge에 서명하여 키 소유를 증명한다. 장치 등록과 host 조작 권한 부여는 별도다. 공개 HTTP 기반 비밀번호 계정 시스템은 초기 범위에 넣지 않는다. API 인증은 장치 서명 challenge → 짧은 수명의 access credential 방식으로 구체화하고, TLS·audience·expiry·key version·철회 상태를 검사한다. 기존 credential만 연장하는 대신 장기 키 소유 증명으로 갱신한다. WSS는 URL query에 비밀 값을 넣지 않고 인증한다. host/client 개인키는 각 PC의 보호 저장소, 서버 signing key는 서버의 권한 제한 파일/secret 저장소에 둔다. key rotation은 기존 키 증명 또는 로컬 재등록을 요구한다. 서버 인증서 갱신과 장치 신뢰 키 교체는 별개다. 서버 장애 시 복구는 관리자 로컬 절차로 제공하고 공개 우회 endpoint는 두지 않는다. ## F74 · 장치 목록과 WSS GET /v1/devices는 인증한 장치가 볼 수 있는 기기만 반환한다. online/offline/unknown, version, capability, 접속 불가 사유를 분리하며 후보 IP와 초대 원문을 목록에 포함하지 않는다. 표시 이름 중복은 허용하되 UI 선택은 DeviceId로 유지한다. WSS 연결마다 generation, host 부팅마다 boot_id를 부여한다. heartbeat는 현재 generation에만 유효하다. 오래된 socket 종료가 새 연결의 online 상태를 지우지 못하게 한다. 재연결은 snapshot과 revision을 먼저 받아 동기화하고, 손실된 이벤트를 무조건 무한 재생하지 않는다. 메모리 큐가 넘치면 느린 연결을 닫고 재동기화를 요구한다. 초기 제안값은 heartbeat 10초, offline lease 30초, 승인 대기 60초, 연결용 ticket 30초, 제어 메시지 64KiB, WSS 대기 이벤트 128개, 세션당 후보 16개다. 측정 후 조정할 설정이며 WAN 검증을 하지 않은 숫자다. 단기 연결 ticket 만료는 이미 연결된 media 세션의 종료 시각과 다르다. ## F75–F76 · 세션·승인·철회 ```text Requested → AwaitingApproval → TransportReady → AwaitingPassword → Authorized → Connecting → Active → Closed ├→ Denied ├→ Expired └→ Canceled 종료·철회는 관련 진행 상태에서 Closed로 수렴, terminal 상태에서 승인으로 되돌아가지 않음 ``` 요청은 Idempotency-Key를 세션 요청 주체에 묶는다. 상태 변경은 SessionId와 expected revision을 검사한다. host 승인과 client 취소가 경합하면 commit된 순서를 적용하고 terminal 상태의 늦은 승인을 거부한다. 승인 대상은 지정 host 키, 승인 권한은 요청과 로컬 host 정책의 교집합이다. 연결 시도용 ticket은 session_id, client/host key ID·version, epoch, capability, audience, nonce, issued_at, expires_at과 서버 서명을 가진다. host는 peer 키 소유 증명·pinning·ticket·로컬 허용 정책을 검사한 다음 매 연결의 비밀번호를 직접 검증한다. TransportReady ticket은 비밀번호 없는 미디어/입력 권한이 아니다. nonce/epoch 재생 cache와 재시작 시 ticket 무효화 정책을 둔다. relay credential은 media ticket과 audience를 분리하고 allocation·만료·byte quota를 추가한다. 검증된 암호 라이브러리를 쓰고 자체 암호 primitive를 작성하지 않는다. 서버 Active는 host/client의 같은 SessionId·epoch 시작 보고를 확인한 뒤 기록한다. 보고가 끊기면 unknown/offline을 표시하며 승인 성공만으로 “영상 정상”을 표시하지 않는다. host의 입력 watchdog과 로컬 중단은 서버의 가용성에 의존하지 않는다. 철회는 DB 권한 revision 갱신 → 새 접속/ticket/relay 갱신 차단 → host에 종료 이벤트 → ACK 확인 순서다. 기본 서버 관리 세션은 30초마다 권한 lease를 확인하고 마지막 갱신으로부터 120초가 지나면 입력 해제·종료하도록 제안한다. 서버 단절 시 최대 120초 동안 기존 연결이 계속될 수 있다. 이 값은 초기 정책이며 사용자 UI에 표시한다. 별도로 허용한 수동 direct/VPN offline 모드는 로컬 pin과 host 승인 정책으로 운용하며, 서버의 즉시 철회 보장을 받을 수 없다는 차이를 명시한다. ## API 초안 (실제 endpoint와의 차이는 CONTROL_API_V1 참고) 모든 경로는 TLS 뒤의 /v1이고 명시한 공개 bootstrap 교환 외에는 장치 인증과 리소스별 권한 검사를 적용한다. 오류는 code, request_id, retryable, 안전하게 노출할 detail로 고정한다. 관리자 변경은 장치 일반 권한과 구분한다. | API | 권한과 계약 | 기능 | |---|---|---| | POST /devices/enroll | 일회 코드 + 새 공개키 소유 증명; 원자적 소비 | F73 | | POST /auth/challenge, /auth/verify | 등록 장치 키 증명; nonce·만료·rate limit, 짧은 credential | F73 | | GET /devices | 허용 기기 목록·revision·presence | F74 | | WSS /events | 인증 장치별 snapshot / presence / offer / decision / candidate / revoke | F74/F75 | | POST /sessions | host·capability·idempotency key; 승인 전 ticket 없음 | F75 | | POST /sessions/{id}/decision | 지정 host만 승인/거절; expected revision | F75 | | POST /sessions/{id}/cancel, /close | 참가자와 상태별 검사; 중복 종료는 idempotent | F75 | | POST /sessions/{id}/lease | 활성 권한 재검사·기한 갱신; host에 적용 | F75/F76 | | POST /invitations, /invitations/claim | 권한 있는 발급자·지정 수신자·단일 소비 | F76 | | DELETE /trust/{grant_id} | 권한 있는 관리자/소유자; 철회 revision·종료 ACK | F76 | | POST /sessions/{id}/candidates | 승인된 참가자만·개수/TTL/세대 제한 | F77 | | POST /sessions/{id}/relay | 선택 relay가 있는 승인 세션만 allocation credential | F77/F33 | 관리용 장치 폐기와 초대 취소·감사 조회는 같은 권한 모델의 control-admin 명령으로 시작한다. 웹 관리자 대시보드는 필수 구현이 아니며, PC 앱 F64/F65가 장치 목록·초대·철회를 담당한다. ## F77 · 연결 경로 기본은 집 host에 명시 UDP 포트포워딩 주소를 등록하여 전달하는 방식이다. 서버가 공인 주소를 전달하는 것과 공유기 포트를 실제로 여는 것은 다르다. 후보는 승인된 세션 참가자끼리만 공유한다. transport가 동일 UDP socket에서 검사하고 검증되지 않은 임의 endpoint로 대량 패킷을 보내지 않도록 probe 제한을 둔다. F32는 STUN 관측·NAT 후보 검사·hole punching을 추가한다. F33은 두 peer가 도달할 수 있는 relay를 추가한다. control-server가 media를 복호화하거나 다른 URL을 fetch할 필요는 없다. WireGuard를 선택하면 VPN이 사설 IP 경로를 제공하고 앱 QUIC과 host 승인은 그대로 유지한다. VPN 설정·키 배포 자체는 F31의 앱 구현과 구분한 운영 절차다. ## F78–F79 · 운영과 합격 TLS/WSS는 기존 proxy, 내부 HTTP는 공개하지 않는 배치를 제안한다. API 443과 명시 host UDP·선택 relay/VPN 포트는 독립이다. OS와 설치 형태를 확정하고 예시 포트를 실제 환경에 대입한다. 단일 서버·SQLite로 시작하고 무중단 다중 replica는 초기 목표에 포함하지 않는다. 일관된 SQLite backup API 또는 quiesced snapshot과 서버 key를 함께 보관한다. WAL 동작 중 DB 본파일만 복사하는 방식을 백업으로 취급하지 않는다. migration 전 backup, 성공 여부, schema 호환 rollback 절차를 기록한다. 복원 후 pending/ticket을 무효화하고 장치 key·철회 이력이 유지되는지 시험한다. 백업에서 사라진 최근 철회를 재적용하기 전 외부 접속을 열지 않는 복원 절차를 둔다. 관측은 등록/인증 실패, 장치 online 수, WSS 재연결·큐 drop, 승인 시간, 접속 성공/실패 사유, 선택 경로, DB 오류를 포함한다. 로그 보존 일수·크기를 설정하고 token·초대 원문·개인키·미디어·채팅/입력 본문을 남기지 않는다. 네트워크 접속 metadata도 필요한 기간만 보존한다. 합격은 ① API/DB 경합 시험 ② 서버+mock peer 통합 ③ 실제 두 PC+외부 회선 시험 ④ 서버/host 재시작·네트워크 단절·철회·백업 복원으로 나눈다. 외부 환경을 사용하지 못하면 F79는 미검증으로 남긴다. F32/F33은 선택한 경우에만 별도 경로별 결과를 추가한다. ## 공식 자료 - [Parsec 연결 구성](https://support.parsec.app/hc/en-us/articles/32361410290324-Components-and-Connection-Sequence): host/client·signal·STUN 역할의 참고 자료. 위 서버 API는 자체 제안. - [axum](https://docs.rs/axum/latest/axum/), [SQLite Online Backup](https://www.sqlite.org/backup.html): 구현 후보와 일관 백업의 공식 자료. - [WireGuard 개념](https://www.wireguard.com/), [VPS 개념](https://aws.amazon.com/what-is/vps/): 사설 터널과 외부 가상 서버의 차이.