notParsec / 문서전체 문서

생성 코드·템플릿

server_plan_extension.py

design/server_plan_extension.py

출처: 현재 작업 폴더 · 원문 다운로드

"""Explicit personal control-server scope; original Parsec backend is not recovered."""

SERVER_IDS = [f'F{i}' for i in range(71, 80)]


def extend(add, features):
    add('F71', 'M4', '연결 관리 서버 실행 기반·API 계약',
        '개인 홈서버에서 실행할 Rust 서버를 별도 개발 산출물로 만든다.',
        'apps/control-server에 Tokio/axum REST·WSS router, versioned DTO, 설정 검증, 구조화 오류, bounded 작업 큐, graceful shutdown, liveness/readiness를 구현한다. HTTP는 기존 reverse proxy 뒤에서 실행하고 media/GPU 처리와 분리한다. 상세 계약은 CONTROL_SERVER.ko.md를 따른다.',
        ['Linux 대상 clean build와 임시 설정 기동·정상 종료, Windows host/client와 protocol 호환 시험', '필수 설정 누락·포트 충돌·미지원 API 버전·과대 요청에 결정적인 오류, 내부 의존성 실패 시 readiness 실패'],
        ['F01', 'F03', 'F04', 'F05'], 'apps/control-server / protocol::control', 'Tokio·axum 후보; 채택 버전 고정')
    add('F72', 'M4', '서버 DB·마이그레이션·영속 상태',
        '장치·권한·초대·접속 이력을 재시작 후에도 일관되게 보존한다.',
        'SQLite의 devices, trust_grants, enrollment_codes, invitations, sessions, session_audit와 schema_version을 정의한다. 단일 사용 token 소비·권한 변경·세션 전이는 transaction으로 처리한다. 라이브 소켓과 presence lease는 메모리로 두고 재시작 뒤 offline/unknown부터 재동기화한다.',
        ['빈 DB/직전 schema에서 migration, 원자성·동시 token 소비·constraint 검증', '강제 종료·디스크 쓰기 실패 뒤 권한이 확대되지 않고 유령 online/Streaming 상태를 표시하지 않음'],
        ['F71'], 'control::store / migrations', 'SQLite·Rust DB adapter 후보')
    add('F73', 'M4', '장치 등록·API 인증·키 수명',
        '누가 서버를 사용하고 어떤 장치인지 서버가 검증한다.',
        '로컬 관리자 bootstrap으로 고엔트로피 일회 등록 코드를 발급하고 hash·만료·대상 권한을 저장한다. 새 장치는 공개키 소유 증명을 제출한다. API/WSS는 장치 키 challenge와 짧은 수명의 credential로 인증하며 장치별 접근 범위를 확인한다. 서버 signing key·장치 key rotation·분실 철회·rate limit·redaction을 설계한다.',
        ['만료/중복 등록·잘못된 서명·재사용 challenge·다른 장치 사칭·철회 credential 거부', '키 교체에 기존 키 증명 또는 로컬 재등록 요구; 서버가 host pin을 자동 교체하지 않음'],
        ['F72', 'F06'], 'control::enrollment / auth / keyring', 'OS CSPRNG·검증된 서명/토큰 라이브러리', '등록 코드만 알아도 무제한 제어 권한을 얻는 설계로 만들지 않는다.')
    add('F74', 'M4', '장치 목록 API·온라인 상태·WSS 재동기화',
        'UI의 컴퓨터 목록을 실제 서버 상태와 연결한다.',
        'GET /v1/devices와 인증 WSS에서 허용된 장치만 조회한다. heartbeat lease, boot_id/connection generation, capability와 목록 revision을 관리한다. 재접속은 snapshot부터 동기화하며 느린 구독자의 큐를 제한한다. 후보 IP는 전체 장치 목록에 노출하지 않는다.',
        ['다른 장치의 목록·capability 접근 차단, heartbeat 만료·서버 재시작 뒤 offline 판정', '중복 socket·늦은 disconnect·역순 이벤트가 새 online 상태를 덮지 않고 재접속 snapshot으로 복구'],
        ['F73'], 'control::directory / presence / events', 'axum WebSocket·bounded channels')
    add('F75', 'M4', '접속 중개·호스트 승인·세션 ticket',
        '연결 요청부터 승인·취소·종료까지 서버의 권한과 상태를 일관되게 유지한다.',
        'Requested→AwaitingApproval→Authorized→Connecting→Active→Closed와 Denied/Expired/Canceled를 정의한다. SessionId·revision·idempotency key로 경합을 처리하고 지정 host만 승인한다. ticket을 두 장치 키·세션 epoch·권한·nonce·audience·만료에 묶는다. host는 ticket과 client 키·자체 정책을 확인한 후에만 미디어/입력을 허용한다.',
        ['타 host 승인·취소 뒤 늦은 승인·이중 요청·ticket 재생·변조·만료·다른 세션 사용 거부', '서버 연결 단절·host offline·승인 timeout·양쪽 시작/종료 보고가 UI와 일관됨; Active는 전달한 승인만으로 표시하지 않음'],
        ['F74', 'F17'], 'control::sessions / protocol::ticket', 'Rust 상태 머신·검증된 서명 구현')
    add('F76', 'M4', '초대·신뢰 정책·철회 서버',
        '초대 UI의 만료·승인·철회가 실제 접속 권한에 반영되게 한다.',
        '일회 장치 등록과 특정 host에 대한 접속 초대를 구분한다. 초대를 수신 장치 키·host·권한·기한에 묶고 hash로 저장하며 수락과 소비를 원자적으로 처리한다. 철회 시 새 요청/ticket/relay 갱신을 차단하고 host에 종료 이벤트를 보내 ACK를 추적한다. 서버 단절 시에는 사전에 선택한 host의 offline 정책을 적용한다.',
        ['동시 초대 수락·초대 유출·이미 소비/폐기한 token으로 권한 상승이 불가능', '온라인 host는 철회 뒤 입력 해제·세션 종료; offline host는 즉시 철회 미확인을 표시하고 정해진 lease 만료로 종료'],
        ['F75'], 'control::invitations / grants / revocation', 'SQLite transaction·기존 F06/F17 권한 모델')
    add('F77', 'M4', '접속 후보 교환·경로 정책·relay 발급',
        'PC가 접속할 주소와 허용된 중계 경로를 서버가 제한해 제공한다.',
        '승인된 두 장치 사이에서만 LAN/명시 공인 endpoint/STUN 후보를 교환한다. 후보 크기·개수·TTL·세대·주소 범위를 검증하며 QUIC socket과 외부 매핑의 관계는 client transport가 담당한다. relay가 선택된 경우 별도 audience·quota·만료의 allocation credential을 발급한다. 서버는 제출 주소로 임의 URL fetch나 내부망 스캔을 하지 않는다.',
        ['미승인/종료 세션의 후보 조회·교환 거부, 과다 후보·오래된 세대·변조 relay credential 거부', 'UDP 40010 명시 endpoint를 전달해 외부 회선의 두 PC 연결; relay 미설정이면 사용 가능으로 광고하지 않음'],
        ['F75', 'F10'], 'control::rendezvous / relay-issuer / transport', 'F32 STUN/후보 검사와 F33 relay의 서버 경계', 'STUN·QUIC 라이브러리 설치만으로 NAT 통과를 완료 처리하지 않는다.')
    add('F78', 'M4', '홈서버 배포·TLS·관측·백업 복원',
        'API가 개발 PC에서 실행되는 수준을 넘어 지속 운영 가능한 상태로 만든다.',
        'Linux Compose 또는 systemd 중 실제 환경에 맞는 배포 묶음을 작성한다. 기존 reverse proxy의 HTTPS/WSS, 영속 DB/key, 최소 권한, health/readiness, 재시작·로그 회전·인증 실패/접속 지연 지표를 설정한다. SQLite 일관 백업·암호화 key 백업·복원 후 pending 세션 무효화·schema 호환 rollback을 문서화한다.',
        ['시험 환경에서 재부팅·TLS 갱신·proxy timeout·DB 잠금/용량 부족·WSS reconnect 검증', '빈 환경으로 DB·key 복원 후 장치 pin/철회 보존; 만료 초대나 이전 세션이 부활하지 않음', '기본 로그에서 credential·초대 원문·미디어·입력/채팅 본문 제외, 운영 지표와 보존 기간 확인'],
        ['F72', 'F73', 'F74', 'F75', 'F76', 'F77'], 'deploy/control / operations', '기존 reverse proxy 또는 Caddy·SQLite backup API', '서버 OS·실제 도메인·경로·회선 속도는 배포 전 확정한다.')
    add('F79', 'M4', '연결 관리 서버·PC 앱 통합 합격 시험',
        '서버 API와 체크리스트 UI가 실제 외부 접속 경험으로 이어지는지 판정한다.',
        '실제 home control-server와 두 Windows 앱에서 등록→목록→승인→직접 연결→종료→철회를 시험한다. 외부 회선과 재부팅·WSS 단절·취소 경합·오프라인 정책을 포함한다. F32/F33 선택 시 NAT/relay 시험을 추가하되 수동 endpoint 경로와 결과를 구분한다.',
        ['두 물리 PC·서로 다른 회선에서 30분 영상/오디오/입력 및 10회 접속/종료; 단일 PC mock은 대체 증거로 인정하지 않음', '로그·API·양쪽 UI의 SessionId/상태와 철회 결과 일치; 직접/VPN/relay별 실행한 조건과 미검증 조건 기록'],
        ['F78', 'F64', 'F65', 'F67', 'F31'], 'tests/control-e2e / host / client', '기존 F25/F28 시험 harness·장애 주입')

    by_id = {f['id']: f for f in features}
    by_id['F06']['acceptance'] = [a.replace('신뢰 철회·재인증·초대 요청 상태가 실행 권한에 즉시 반영됨', '로컬 신뢰 변경은 즉시 반영하고 원격 서버 철회는 host ACK/lease 상태와 구별해 표시') for a in by_id['F06']['acceptance']]
    for fid, dependency in [('F32', 'F77'), ('F64', 'F74'), ('F65', 'F76')]:
        by_id[fid]['dependencies'].append(dependency)
    by_id['F64']['phase'] = by_id['F65']['phase'] = 'M4'
    by_id['F32']['implementation'] = ('F71–F77 서버 계약 위에서 STUN 탐색·같은 UDP socket 유지·후보 교환·검사·hole punching을 구현한다. 집 안 STUN만으로 외부 매핑이 확보된다고 가정하지 않는다. 명시 공인 endpoint 경로와 자동 NAT 경로를 구분하며 UPnP는 opt-in 보조 수단이다.')
    by_id['F32']['module'] = 'control::rendezvous / transport::nat'
    by_id['F64']['implementation'] += ' F74의 장치 목록·presence revision을 소비하고 서버 장애와 host offline을 구별한다.'
    by_id['F65']['implementation'] += ' 서버의 초대/철회는 F76 계약을 사용하고 offline host에 즉시 철회가 전달됐다고 표시하지 않는다.'
    by_id['F33']['implementation'] += ' F77의 제한된 allocation credential을 사용한다. 자체 UDP relay와 coturn adapter 중 하나를 선택하며 내부 PC 간 QUIC 암호화를 유지한다.'
    by_id['F33']['acceptance'][0] = '직접 경로는 실패하지만 양쪽에서 relay UDP에는 도달 가능한 외부망에서 중계 연결'
    features.sort(key=lambda f: int(f['id'][1:]))


def catalogue():
    return dict(
        title='연결 관리 서버', featureIds=SERVER_IDS,
        audit=[
            dict(area='장치 키·호스트 승인', before='F06/F17에 PC 측 신뢰·승인 모델 존재', after='F73 API 인증과 F75 서버 ticket 계약 추가'),
            dict(area='접속 중개·NAT·relay', before='F32/F33에 최소 서버·후보 교환·중계 개요만 존재', after='F71/F75/F77으로 서버 책임 분리; F32/F33은 실제 경로 구현'),
            dict(area='컴퓨터 목록·초대 UI', before='F64/F65에 UI와 동작 요구는 있으나 서버 선행 조건 미지정', after='F74/F76을 선행 조건으로 연결하고 M4로 이동'),
            dict(area='DB·실행·배포·통합 합격', before='독립 기능과 구체적 완료 기준 부족', after='F71/F72/F78/F79 신규 체크 항목')
        ],
        document='CONTROL_SERVER.ko.md',
        note='F71–F79는 자체 notParsec 서버 구현 계획이다. Parsec 서버 코드를 복구했다는 의미가 아니다.'
    )