학습 문서 · DNS부터 내 폴더까지: 인증서·Cloudflare·터널의 원리 ↗
내 폴더를 여는
가장 짧은 통로.
Windows에서 명령 하나로 폴더를 열고,
다른 네트워크에서는 웹 드라이브처럼 사용합니다.
임시 주소 발급, 원하는 이름의 주소 예약, 파일 탐색·다운로드·업로드와 터널 관리. 먼저 웹을 완성하고, Windows 네트워크 드라이브 연결을 후속 단계로 개발합니다.
PS D:\Projects\Shared> tunnels serve . --name studio --permissions read,upload --ttl 8h → https://studio.tunnels.n3m.kr → 종료: Ctrl+C
운영 도메인은 확정됐습니다.
명령은 목표 사용 예시이며 실제 지원 범위는 진행 원장과 검증 기록으로 확인합니다.
Windows에서 열기
폴더에서 터미널을 열어 공유 시작. 생성된 URL 또는 사용자가 지정한 이름으로 외부망에서 접근.
웹에서 파일 쓰기
목록·경로 탐색·다운로드·업로드. 큰 파일, 연결 끊김, 권한과 충돌을 함께 설계.
중앙에서 관리
모든 열린 터널·접속 출처·요청/전송 로그·접근권한을 중앙에서 관리. console.n3m.kr에 notparsec와 N3M Tunnels 관리를 통합하고 네트워크 드라이브는 후속 구현.
항공우주 기술문서의 구조를 적용합니다.
기준은 S1000D Issue 6 / 6.A의 모듈·식별·개정·적용성 관리 개념입니다. 이 문서는 프로젝트용으로 조정한 HTML 계획서입니다. 정식 DMC, XML Schema, BREX 규칙 검사, CSDB 교환 패키지를 구현하지 않았으므로 완전한 S1000D 적합성은 미검증입니다. S1000D 공식 현행판과 도입 설명을 기준으로 범위를 구분합니다.
| 문서 식별 | PW-PLAN-001 · 제목: N3M Tunnels 파일 터널 서비스 개발 계획 | 개정 / 상태 | 001 / 06 · 확정 요구 반영 · 초기 구현 진행 |
|---|---|---|---|
| 발행 기준일 | 2026-10-05 · Asia/Seoul | 적용 대상 | 호스트: Windows 11 x64 우선 / 클라이언트: Windows Edge·Chrome 우선 / 서버: Linux |
| 요구 책임 / 작성 | 요청자 / Codex 작성 초안 | 검토 / 승인 | 2026-10-04 중앙 콘솔 통합·Rust 확정. 2026-10-05 N3M Tunnels·tunnels.n3m.kr 명칭 확정. 상세 기술안은 검증 전 |
| 공개 범위 | 외부 열람용 계획. 키·계정·실제 공유 경로·파일 내용 제외 | 원천 관리 | JSON 카탈로그·진행 원장 + HTML 템플릿 + 생성기 |
| 참고 표준 / 원칙 | 이 문서에 적용하는 규칙 | 적용 한계 |
|---|---|---|
| S1000D · 모듈 | 각 절에 PW-DM 식별자, 목적별 독립 내용, 참조와 변경 이력 | PW-DM은 내부 ID이며 공식 DMC가 아님 |
| S1000D · 식별 / 상태 | 문서 ID·개정·날짜·적용 대상·검토 상태를 표시 | XML 식별/상태 요소의 구현은 후속 결정 |
| S1000D · 공통 원천 | 한 카탈로그에서 기능표·통계·검증표를 생성. 출력 HTML 직접 편집 금지 | 파일 기반 원천 관리. 정식 CSDB 시스템 미구축 |
| 프로젝트 작성 규칙 BR-PW-01~04 | 요구는 하나의 검증 가능한 동작으로 작성. 사실·제안·미결정을 표시. 완료는 증빙으로 판정. 개정 시 기존 ID 보존 | 기계 검사는 누락·참조·상태만 검사하며 사실성을 대신하지 않음 |
| ASD-STE100 · Issue 9 | 일관된 용어, 짧은 절차, 한 단계에 한 동작이라는 작성 원칙 차용 | 영어 기술문서 표준. 한국어 본문을 STE 적합으로 선언하지 않음 |
| NASA Systems Engineering | 사용자 요구 → 상세 요구 → 설계 → 시험 → 증빙 연결. 검증과 사용 목적 확인을 구분 | 항공 인증·비행 소프트웨어 보증 표준 적용을 의미하지 않음 |
모듈 등록: PW-DM-000 목표 / 010 문서통제 / 020 운용 / 025 중앙 관리 콘솔 / 027 임시 주소 발급 / 030 구조 / 040 전송 / 050 기술 / 060 요구추적 / 070 보안·장애 / 080 개발·검증 / 090 배포·통합 / 100 결정·용량 / 110 정비·근거. 모든 모듈은 이 발행본의 개정·상태·적용성을 따릅니다. 정식 표준 납품이 필요해지면 프로젝트 BRDP/BREX, SNS/DMC, XML·QA와 교환 절차를 먼저 확정합니다.
여는 사람은 터미널, 사용하는 사람은 브라우저.
PROC-01 · 폴더 공유 시작
예정 절차 · 선행 조건: Windows 앱 설치, 서버 계정·기기 등록, 인터넷 HTTPS 443 연결, 공유 폴더 권한.
- 공유할 폴더에서 PowerShell을 엽니다.
tunnels login --server https://tunnels.n3m.kr으로 기기를 등록하는 흐름을 구현합니다. 관리 진입점은 console.n3m.kr이며, 콘솔 관리자 인증·에이전트 인증·파일 방문자 인증은 용도별로 분리합니다. 브라우저 로그인 연계와 자격증명 저장은 요구별 진행 원장을 따릅니다.tunnels serve .를 실행합니다. 기본값 제안은 자동 이름·읽기 전용·8시간 만료·접근 비밀번호입니다. 비밀번호는 별도 입력으로 받아 명령 이력에 남기지 않습니다.- 출력된 HTTPS 주소를 접속자에게 전달합니다. 접속 비밀번호는 별도로 전달합니다.
Ctrl+C로 신규 요청을 차단하고 활성 전송을 취소합니다. 연결 종료 시 임시 업로드 정리 정책을 적용합니다.
PROC-02 · 이름 지정과 웹 사용
# 목표 명령 예시 · 초기 구현과 후속 기능 구분
tunnels serve . --name studio --permissions read,upload --ttl 8h
# 확정 서비스 도메인 · 서버 TLS 확인 / 아래 이름 지정 기능은 목표 예시
https://studio.tunnels.n3m.kr
tunnels list
tunnels stop <tunnel-id>
tunnels names reserve studio접속자는 비밀번호 입력 후 경로 이동, 파일 검색·정렬, 선택 다운로드, 업로드 큐를 사용합니다. 읽기 권한과 업로드 권한은 독립적입니다. 삭제·이름 변경은 별도 권한을 명시할 때만 제공합니다.
주소 규칙 · 확정 도메인 / ADR-01
공유 URL은 https://<random>.tunnels.n3m.kr, 제어 진입점은 https://tunnels.n3m.kr으로 설계합니다. 서비스명은 N3M Tunnels, 콘솔 메뉴는 Tunnels로 통일합니다. ADR-08 명칭 결정이 이전 철자와 임시 이름보다 우선합니다. 사용자 이름은 계정에 예약하고 대소문자·길이·금지어·동시 충돌을 서버에서 판정합니다. 예를 들어 studio가 다른 소유자의 이름이면 409 오류로 종료하며 임의 탈취하지 않습니다. DNS 준비 전에는 loopback과 명시적 테스트 Host로 경로를 검증합니다. 시험 URL을 공개 운영 주소로 보고하지 않습니다. 별도 사용자 도메인 연결은 현재 구현 원장 밖의 검토 후보이며 기본 이름 예약과 구분합니다.
예약 이름의 소유권과 활성 공유의 유효시간은 별개입니다. 종료 뒤 예약 주소를 새 공유로 다시 열면 새 tunnel generation을 발급하고 예전 접속 세션·전송권은 재사용하지 않습니다. 와일드카드 DNS·인증서와 전용 파일 도메인 확보는 운영 전 선행 작업입니다. 임시 주소 발급·접속·만료의 전체 과정을 다음 설명에서 확인할 수 있습니다.
웹 파일 화면
경로 표시, 폴더/파일 목록, 크기·수정시간, 정렬·현재 폴더 검색, 선택 다운로드, 업로드 큐, 권한·오프라인·만료 표시.
Windows CLI 화면
공유 루트·URL·만료·권한·접속 상태·전송량 표시. 재연결 상태와 종료 이유를 구분. 토큰·비밀번호는 출력하지 않음.
관리 화면
관리자는 전체 열린 터널·접속 출처·요청/전송/감사 로그를 조회하고 접근 차단·종료·정책을 제어. 일반 소유자는 자기 터널만 관리. 상세는 중앙 관리 콘솔에 정의.
열린 터널 전체와 접속 이력을 한곳에서 관리합니다.
사용자 확정 요구 · 2026-10-04. Cloudflare·ngrok처럼 중앙 관리 페이지에서 현재 열린 터널을 모두 보고 제어하며, 누가 어디서 접근했고 어떤 작업을 했는지 확인합니다. M2 웹 MVP의 필수 기능으로 포함합니다. 아래 화면 구성과 API는 N3M Tunnels의 설계 초안이며, 실제 연결이나 로그가 표시되는 운영 화면은 아닙니다.
전체 터널
주소·소유자·호스트·상태·시작/만료 시각·마지막 heartbeat·연결 세대·활성 세션/전송·속도·누적량을 조회합니다. 종료된 터널도 이력에서 찾습니다.
접근 출처와 활동
접속 IP·추정 국가/지역·ASN/통신사, 로그인 주체 또는 익명, 브라우저/OS 추정, 요청 시각·동작·허용/거부·전송 결과를 연결합니다.
중앙 제어
접근 일시차단·재허용, 강제 종료, 세션/전송 취소, 만료·권한·한도 변경과 IP 규칙을 관리합니다. 누가 설정을 바꿨는지도 감사 이력에 남깁니다.
상단: 전체/내 터널 · 상태 · 소유자 · 호스트 · 주소 검색 / 상세 탭: 개요 · 현재 접속 · 요청/전송 로그 · 정책 · 변경 이력
| 터널 / 호스트 | 연결 / 접근 정책 | 접속 / 전송 | 마지막 활동 | 제어 메뉴 예시 |
|---|---|---|---|---|
| studio.tunnels.n3m.kr owner-A / WIN-STUDIO | 온라인 · 접근 허용 | 세션 2 · 전송 3 | 예시: 2초 전 | 상세 · 일시차단 · 종료 |
| review.tunnels.n3m.kr owner-B / WIN-LAPTOP | 온라인 · 읽기 전용 | 세션 1 · 전송 1 | 예시: 5초 전 | 상세 · 권한 변경 · 종료 |
| archive.tunnels.n3m.kr owner-A / WIN-OFFICE | 재연결 중 · 상태 확인 필요 | 실시간 값 확인 불가 | 예시: 2분 전 | 로그 · 접근 차단 · 폐기 |
| 시각 / 터널 | 접속 출처 | 주체 / 동작 | 결과 / 연결 키 |
|---|---|---|---|
| 예시: 14:05:12 KST studio | 198.51.100.24 국가·지역·통신사: 조회 결과 자리 | guest-7 · DOWNLOAD file-82 · 120 MiB | 완료 · HTTP 200 request-r1 / transfer-t1 |
| 예시: 14:05:18 KST review | 203.0.113.17 위치: 미확인 | 익명 · 접근 인증 | 거부 · HTTP 401 request-r2 / 인증 실패 |
숫자는 문서의 구현 완료 통계와 무관합니다. 화면 예시 IP는 문서용이며 실제 위치를 매핑하지 않습니다. 세션 수·연결 수·전송 수·고유 IP 수는 서로 다른 지표입니다. 같은 IP를 같은 사람으로 집계하지 않습니다.
어디서 접근했는지 · 관측값과 추정값
| 필드 | 표시/판정 규칙 | 확인할 한계 |
|---|---|---|
| 원본 접속 IP / 수신 peer IP | IPv4/IPv6의 실제 수신 peer와 최종 client IP를 별도 저장. direct, trusted-proxy, unknown 판정 및 사용한 신뢰 설정 revision 표시 | 임의 X-Forwarded-For·Forwarded·CF-Connecting-IP를 그대로 믿지 않음. 허용 프록시 경로에서만 원본 IP 채택 |
| 국가 · 지역 · 도시 · ASN/통신사 | IP 지리정보 조회가 가능할 때만 추정값으로 표시. 데이터 제공자·DB 버전/조회 시각·정확도 정보가 있으면 함께 저장 | VPN·공유 NAT·모바일망에서는 출구 위치일 수 있음. 집 주소·정확한 실제 위치·실제 인물을 뜻하지 않음. 실패/사설 IP는 미확인 |
| 주체 · 브라우저 · OS | 인증된 계정/초대 주체와 비밀이 아닌 session 식별자 표시. User-Agent는 정제 후 추정값으로 표시 | 공유 비밀번호만 사용한 접속은 개인 이름을 알 수 없음. User-Agent도 위조 가능 |
| 무엇을 했는지 | 목록·다운로드·업로드·로그인·정책 변경, 허용된 상대경로/파일 ID, 요청/전송 ID, 상태·바이트·시간·오류 | 파일 본문·비밀번호·Authorization/Cookie·토큰 query·Windows 절대경로는 수집하지 않음. 숨긴 필드는 숨김으로 표시 |
원본 IP 처리는 배포 경로별 계약입니다. Nginx가 유일한 app 진입점이면 app의 직접 접속을 차단하고 Nginx에서 신뢰 헤더를 재작성합니다. Cloudflare를 사용하면 허용된 Cloudflare 경로에서 받은 헤더만 신뢰하도록 origin 접근 통제와 IP 목록 갱신을 함께 검증합니다. Cloudflare를 필수 중계 사업자로 선택했다는 뜻은 아닙니다. 원본 IP 복원 근거 · IP 위치 정확도의 한계.
IP 정책 상세 제안: IPv4/IPv6 CIDR을 지원하고 차단 규칙이 우선합니다. 허용 목록이 있으면 일치가 필요하며, IP 제한이 활성화된 상태에서 신뢰할 원본 IP를 판정하지 못하면 거부합니다. 정책 미설정 상태는 기존 인증·권한 규칙을 따릅니다. IP 정책은 PW-045의 신뢰 IP 판정 이후에 적용하며 직접/프록시·위조 헤더·중첩 CIDR을 시험합니다.
로그의 종류와 수집 흐름
| 종류 | 구체 기록 | 관리 화면 |
|---|---|---|
| 연결 로그 | agent 접속/단절·heartbeat·재연결·lease 만료·버전·단절 원인 | 터널 연결 상태와 파일 서비스 준비/권한 오류는 별도 표시. 마지막 확인 시각. 끊긴 값을 온라인/0건으로 표시하지 않음 |
| 접근/요청 로그 | 시작/종료·request ID·tunnel ID·주체·접속 출처·동작·상태·거부 원인 | 기간·터널·소유자·IP·국가/ASN·동작·성공/거부/오류 필터 |
| 전송 로그 | transfer ID·관련 request ID·방향·전송 바이트·지속시간·재개/취소·최종 커밋 결과 | 업로드/다운로드 이력, 진행 전송, 속도·누적량. 동일 논리 전송의 재개 요청만 하나로 연결. 전송 생성 전 거절은 request/event ID로 추적 |
| 감사 로그 | 행위자·범위·변경 전/후 정책 version·action ID·요청/적용/실패·로그 조회/내보내기 | 관리자 조작 추적. 일반 역할이 삭제·수정할 수 없고 운영 보존 정책 변경도 기록 |
중앙 제어의 결과를 구분합니다.
제어 요청은 action_id와 tunnel generation·기대 policy version을 포함합니다. 화면에는 요청됨 → 서버 적용됨 → agent 확인됨 / 확인 대기 / 실패를 구분합니다. 반복 클릭은 중복 실행하지 않고, 다른 관리자가 먼저 변경했다면 충돌을 알립니다. 종료된 과거 터널 행의 명령이 같은 이름으로 새로 열린 터널에 적용되어서는 안 됩니다.
긴급 차단은 서버에서 신규 접근을 거부하고 진행 전송을 취소합니다. agent와 연락이 끊기면 로컬 반영은 확인 대기로 남기고 lease 만료로 닫습니다. “온라인 연결”과 “접근 허용/일시차단”은 별도 상태입니다. 일시차단 해제는 살아 있는 유효 터널에만 적용하며, 철회·만료·종료된 터널은 새 generation과 재인증이 필요합니다. 꺼진 PC나 종료된 Windows 프로세스를 웹 버튼만으로 켤 수 있다고 표시하지 않습니다.
| 관리 API 초안 | 계약 |
|---|---|
| GET /api/v1/admin/tunnels GET /api/v1/admin/tunnels/{id} | 권한에 따른 전체/소유 범위, 상태·주소·소유자 필터, cursor 페이지 처리, 응답 snapshot 시각. 상세는 접속 세션·전송과 연결 |
| POST /api/v1/admin/tunnels/{id}/actions | 일시차단/해제·종료·세션/전송 취소·정책 변경. 역할·CSRF·generation·version·중복 방지 검사. 결과를 action ID로 조회 |
| GET /api/v1/admin/events GET /api/v1/admin/events/stream | 이력 검색 및 인증된 SSE. 최종 event ID로 재접속하고 저장 범위 밖이면 로그 공백을 표시. 새 인가마다 범위 확인, 권한 철회 시 스트림 중단 |
| POST /api/v1/admin/events/exports | 허용 필터·기간·최대 행수로 JSON/CSV 생성. export 권한 재검사·감사 기록·다운로드 수명. 스프레드시트 수식 주입 방어 |
관측 범위도 표시합니다. 서버에 도달한 요청의 로그와 상위 CDN/프록시에서 차단된 요청은 다릅니다. 상위 로그 연동이 없으면 “상위 차단 요청 미수집”을 표시합니다. 실시간 연결 단절은 마지막 갱신 시각·지연·재연결 상태로 보여주고 빈 로그를 활동 없음으로 단정하지 않습니다. 정책상 저장하지 않은 필드와 수집 실패를 구분합니다. edge와 원본 응답을 구분하는 Cloudflare 요청 필드를 참고합니다.
보존 제안: 요청·전송·연결 상세 7일, 감사 90일, 일별 집계 30일. M2에서 운영자가 변경 가능하게 하며 저장 용량 상한·삭제·백업 범위도 표시합니다. IP 조회는 로컬 GeoIP DB 우선 후보이고 라이선스·갱신 주기·제공자는 미결정입니다. 로그 용량 초과·수집 중단은 손실 카운터와 구간을 기록하며, 감사 저장 불가 시 정책 변경을 성공으로 처리하지 않습니다. 차단/종료는 우선 실행하고 별도 영속 복구 저널에 남기며 그것마저 실패하면 감사 미기록 상태를 명시합니다.
요구 추적: PW-030 전체 관리, PW-031 감사/보존, PW-032 역할, PW-043 실시간 현황, PW-044 중앙 제어, PW-045 출처, PW-046 로그 탐색, PW-047 수집 신뢰성.
명령을 실행하면, 서버가 이 폴더로 가는 주소를 발급합니다.
핵심 원리. N3M Tunnels가 미리 준비한 공용 도메인 아래에서 임의의 이름을 하나 배정하고, 그 이름을 현재 연결된 Windows 터널에 연결합니다. 예를 들어 tunnels serve .를 실행하면 https://k7m2…q4.tunnels.n3m.kr 같은 주소를 받는 방식으로 계획합니다. 주소에 접속하면 공개 서버가 요청을 받아 해당 PC의 폴더로 중계합니다.
PS D:\Shared> tunnels serve . 폴더 확인 → 기기 인증 → 터널 연결 → 주소 배정 공개 주소: https://k7m2…q4.tunnels.n3m.kr 접근: 비밀번호 필요 / 읽기 전용 유효시간: 최대 8시간 (기본값 제안) 종료: Ctrl+C
도메인은 확정됐으며 표시는 목표 실행 예시입니다. 초기 구현이 지원하는 옵션과 Windows 검증 여부는 별도로 기록합니다. …는 긴 임의 이름을 줄인 표시입니다. 실제 URL에는 생략 기호가 들어가지 않습니다.
미리 준비하는 것
- 운영자가 확정 도메인
tunnels.n3m.kr의 DNS 제어권과 공개 진입점을 준비합니다. *.tunnels.n3m.kr에 맞는 DNS와 HTTPS 인증서를 준비합니다.- 외부에서 접속 가능한 게이트웨이와 Control/Relay 서버를 실행합니다.
- Windows 기기를 등록하고 터널을 만들 권한을 부여합니다.
이 준비는 서버 운영 단계의 작업입니다. 사용자가 폴더를 열 때마다 도메인을 구매하거나 DNS 레코드·인증서를 새로 만드는 과정은 필요하지 않게 설계합니다. 2026-10-05 19:55 KST 후속 검증에서 세 서비스 실행, 새 임의 공유 이름의 신뢰·이름 TLS 검증과 공개 readiness를 확인했습니다. 미등록 공유는 404를 반환합니다. Windows CLI·실제 외부망 파일 왕복과 이름 예약 기능의 전체 검증은 별도입니다.
PROC-03 · 임시 주소가 나오는 순서
- Windows에서 공유할 폴더를 고정합니다.
현재 폴더의 존재·접근 권한·허용 루트를 확인합니다. 로컬 절대경로는 agent가 보관하고 서버에는 불투명한share_id만 보냅니다. 폴더가 잘못됐으면 URL을 발급하기 전에 실패합니다. - 에이전트가 공용 서버로 먼저 연결합니다.
기기 인증 후 HTTPS/WSS 443의 제어 연결을 엽니다. 서버가 Windows의 사설 IP로 새 연결을 걸지 않으므로 사용자 공유기의 포트포워딩을 요구하지 않습니다. 네트워크가 이 외부 연결을 허용해야 한다는 조건은 남습니다. - 임의 주소 생성을 요청합니다.
POST /api/v1/tunnels에 임의/예약 이름 모드, share ID, 권한 상한, 희망 유효시간과 중복 방지 키를 보냅니다. 서버는 소유자·기기·할당량·도메인 정책을 확인하며 유효시간을 서버 상한으로 제한합니다. - 서버가 이름을 만들고 중복 없이 확보합니다.
암호학적 난수로 이름을 생성합니다. 제안값은 128-bit 난수의 padding 없는 소문자 base32(a–z, 2–7) 표현입니다. DB의 이름 고유 제약으로 예약 이름·현재 사용 이름·폐기 이름과 충돌을 검사하고, 충돌하면 제한된 횟수 안에서 다시 생성합니다. 난수 확률만 믿고 중복 검사를 생략하지 않습니다. - 이름과 실제 터널의 연결을 확인합니다.
서버는hostname → owner/device/tunnel/generation의 준비 중 매핑을 만들고 agent에 열기 요청을 보냅니다. agent가 루트·권한·수신 준비를 확인한 뒤, 서버가 현재 인증·연결·만료 조건을 다시 검사하여 활성 경로로 전환합니다. 준비 실패·timeout은 성공으로 표시하지 않습니다. - 준비 완료된 URL을 터미널과 관리 화면에 표시합니다.
CLI는ONLINE확인 후 접속 URL·권한·만료를 표시합니다. 응답을 잃고 같은 요청을 재시도해도 중복 방지 키로 같은 결과를 돌려주어 터널이 여러 개 생기지 않게 합니다. 중복 방지 키는 한 번의 실행 시도에 귀속하며, 사용자가 새로 실행한 공유 요청은 새 키와 새로운 임의 주소를 받습니다.
새 주소를 바로 쓸 수 있는 이유: DNS와 서버의 역할이 다릅니다.
운영자가 *.tunnels.n3m.kr에 대응하는 DNS 레코드를 미리 구성하면, 별도 레코드가 없는 임의 이름도 설정한 공개 진입점으로 해석할 수 있습니다. DNS는 어느 서버로 갈지를 알려주고, 서버의 경로표는 어느 Windows 터널로 보낼지를 결정합니다. 개별 이름마다 DNS 변경이 전파되기를 기다리는 모델이 아닙니다. 와일드카드 DNS의 동작과 우선순위.
와일드카드 DNS에도 매칭 규칙이 있으며, 이미 존재하는 이름이나 위임·별도 레코드는 결과에 영향을 줍니다. M1에서는 단일 label의 평평한 이름 공간과 실제 DNS 응답을 검증합니다. *.tunnels.n3m.kr 와일드카드 인증서는 abc.tunnels.n3m.kr 같은 한 단계 이름을 대상으로 준비하며, a.b.tunnels.n3m.kr이나 상위 이름 자체까지 자동 포함하는 것으로 취급하지 않습니다. TLS 이름 일치 규칙.
인증서 운영 후보: Let’s Encrypt를 사용한다면 와일드카드 인증서는 DNS-01로 도메인 제어권을 확인해 발급·갱신합니다. HTTP-01만으로 와일드카드 인증서를 발급하는 것으로 설계하지 않습니다. 개인키와 DNS API 권한은 운영 측에 보호하고 Windows 사용자에게 나눠주지 않습니다. Let’s Encrypt 검증 방식.
임시 주소와 지정 주소의 차이
| 항목 | 임시 주소 · M1 | 예약한 지정 주소 · M2 |
|---|---|---|
| 명령 예시 | tunnels serve . | tunnels serve . --name studio |
| 이름 결정 | 서버가 충돌을 검사한 난수 이름을 배정 | 계정이 소유한 이름 사용. 다른 소유자의 예약이면 거부 |
| 완전히 종료 후 새로 실행 | 새로운 임의 주소 발급 | 같은 이름 사용 가능. 새 tunnel generation과 새 인증 세션 생성 |
| 잠깐 끊겼다가 복구 | 공유 만료 전 동일한 논리 터널의 정당한 재접속이면 같은 주소 유지 | 동일한 조건에서 같은 이름과 터널 유지 |
| 실제로 파일을 열 수 있는 조건 | 유효한 공유 + 현재 agent 연결 + 허용 정책 + 방문자 인증. 주소 보유나 DNS 조회 성공만으로는 접근할 수 없음 | |
| 종료/만료 후 이름 | 자동 재배정하지 않는 폐기 이름 기록(tombstone)으로 남기는 방안 권고 | 주소 예약 소유권은 별도 보존. 활성 공유와 방문자 권한은 만료 |
수명은 네 가지를 구분합니다.
① 공유 유효시간
expires_at은 URL이 해당 공유에 유효한 최대 기한입니다. 기본 8시간은 제안값입니다. 기한이 지나면 연결이 살아 있어도 신규 접근과 진행 전송을 닫습니다.
② 짧은 연결 생존 임대
heartbeat로 agent가 살아 있는지 확인하는 짧은 lease입니다. 갱신이 멈추면 ONLINE 표시와 파일 전달을 중단합니다. 이 기한이 끝났다고 최대 8시간 공유 기한을 자동 연장하거나 모든 공유를 영구 폐기하지 않습니다.
③ 재연결의 소유권
재연결은 같은 기기·터널·generation과 공유 기한/철회 여부를 검증합니다. 유효하면 공유의 generation은 유지하면서 재연결마다 증가하는 connection epoch로 이전 소켓을 배제해 같은 URL에 활성 agent가 둘 생기지 않도록 합니다. 서버 재시작 뒤에도 재인증 전 저장된 경로를 온라인으로 믿지 않습니다.
④ DNS 캐시 시간
DNS TTL은 도메인이 어느 공개 서버를 가리키는지 캐시하는 시간입니다. 공유의 유효시간이나 파일 접근권한이 아닙니다. 터널 종료 때 DNS 캐시가 남아 있어도 서버의 경로·권한 검사로 접근을 차단합니다.
짧은 heartbeat 주기·오프라인 판정 시간·재연결 backoff 상한은 M1 망 시험 후 확정합니다. 사용자가 Ctrl+C로 종료하거나 관리자가 폐기한 터널은 일시적인 통신 단절과 구분하며, 자동 재연결로 되살리지 않습니다. 업로드가 끊긴 뒤 같은 전송으로 재개 가능한지는 별도의 파일 버전·offset·권한 계약을 따릅니다.
실패와 주소 재사용도 설계합니다.
| 상황 | 계획 동작 |
|---|---|
| 기기 미등록·인증 실패·공유 한도 초과 | 준비 완료 URL을 표시하지 않고 원인을 반환. 비밀값은 오류/로그에 포함하지 않음 |
| 난수 이름 충돌·동시 생성 | 이름 DB의 고유 제약으로 한 번만 할당. 난수 충돌은 재생성, 사용자 지정 이름 충돌은 409 |
| 생성 응답 유실·중복 재시도 | 소유자/기기 범위의 idempotency key와 요청 내용 hash로 동일 요청을 식별. 다른 내용에 같은 키는 거부. 최소 해당 공유의 전체 수명과 재시도 유예 동안 같은 결과를 유지. 전체 결과를 정리해도 만료 키의 요약 기록을 보존해 늦은 재시도에는 만료 오류를 반환하고 새 터널을 만들지 않음 |
| 주소 확보 뒤 agent 준비 실패 | PREPARING에 짧은 timeout 적용. 활성 경로는 만들지 않고 할당량을 회수. 실패·종료 이름도 새 방문자가 다른 소유자로 이동하지 않도록 재사용 정책 적용 |
| agent 절전·네트워크 끊김 | 오프라인/재연결 중 표시. 인증된 조회에는 503 등 사유를 반환하되 미인증 사용자에게 존재 정보를 불필요하게 노출하지 않음 |
| 명시 종료·공유 만료·관리자 철회 | 서버가 요청과 전송을 차단하고 agent 확인/lease 종료를 추적. 인증된 조회에는 종료/만료 사유를 구분. DNS 레코드를 삭제하는 방식에 의존하지 않음 |
| 예전 임시 링크를 다른 사람이 열기 | 폐기된 임의 이름을 타인에게 재배정하지 않는 방안을 M1에서 확정. 작은 이름/tombstone만 유지하며 원본 파일은 저장하지 않음. 이 기록은 일반 접근 로그 보존기간과 별개이고 지정 이름 예약 API도 과거 임의 이름을 재사용할 수 없게 함. 저장량 상한·backup 복원 시 재사용 방지·도메인 폐기 정책도 함께 정함 |
| TLS 인증서 만료·DNS 오설정 | 공개 진입점 사전 점검이 실패하면 새 공유를 성공으로 표시하지 않으며 건강 상태·갱신 알림으로 운영자가 처리. 운영 중 새로 생긴 외부 DNS/회선 문제는 별도 접속 장애로 표시. 인증서 검증을 끄는 우회는 제공하지 않음 |
주소는 비밀번호가 아닙니다. 긴 임의 이름은 충돌과 손쉬운 추측을 줄이는 용도입니다. 링크가 전달되거나 로그에 남을 수 있으므로 파일 접근은 별도 비밀번호/초대 권한으로 인증하고, 각 요청에서 터널의 현재 수명·generation·권한을 검사합니다.
구조 참고: ngrok의 agent → cloud TLS 연결과 공개 endpoint 전달 설명. 임의 이름 생성·만료·재사용·예약 정책은 이 문서의 N3M Tunnels 설계안이며 ngrok의 현재 계정/요금제별 주소 정책을 복제한다고 주장하지 않습니다.
요구 추적: PW-001 폴더 확인, PW-006 역방향 연결, PW-007 임시 발급, PW-008 예약 주소, PW-009 DNS/TLS, PW-010 수명·재연결, PW-025 인증, PW-029 철회. 설명을 보강하는 개정이며 구현 완료를 뜻하지 않습니다.
바깥에서 접속하고, 안쪽에서 연결을 엽니다.
권고안 ADR-02: Windows 에이전트가 서버로 outbound TLS 443 연결을 유지합니다. 가정용 공유기의 포트포워딩 없이 서버가 요청을 전달할 수 있습니다. 이 구조는 임의 TCP 서비스를 노출하는 범용 터널이 아니라 지정 폴더용 파일 서비스입니다. 아래 도식은 Rust 개발 단계 전체의 목표 구조입니다. 첫 구현의 단일 WSS·8 MiB 제한과 구분합니다. 공용 콘솔과 기존 notparsec의 연결은 09절에 정의하며, 새 도메인의 운영 전환은 아직 검증하지 않았습니다.
| 구성요소 / 구현 경계 | 책임 | 보유 데이터 / 경계 |
|---|---|---|
| agent / crates/portway/src/bin/portway.rs | CLI, 루트 고정, Windows 핸들 검증, 기기 키, 터널 수명, 로컬 읽기·쓰기 | Windows 사용자 권한. 원본·임시 업로드·자기 기기 자격증명 |
| server / crates/portway/src/server.rs | Control: 계정·기기·주소·권한·전체 관리. Relay: 요청 ID·연결 배정·취소·속도 제한. 이벤트 수집·로그/집계·감사·출처 신뢰 검증 | 메타데이터 DB. 파일 본문 영속 저장 안 함. 모듈은 분리하되 초기 배포는 단일 프로세스 |
| protocol / crates/portway/src/protocol.rs | 버전·메시지 타입·길이·요청 ID·에러·타임아웃 계약 | 플랫폼 비종속. 클라이언트와 서버를 같은 버전으로 강제하는 대신 지원 범위 협상 |
| filesystem / crates/portway/src/files.rs | 루트 경계, reparse point·ADS 차단, 파일 식별·변경 감지·커밋 | 공유 폴더 밖 접근 금지. 문자열 경로 검사만으로 통과시키지 않음 |
| 파일 웹 / N3M Tunnels 관리 웹 / ../n3m-console | N3M Tunnels는 파일 탐색·전송 UI. n3m-console은 전체 터널 관리·notparsec 관리 진입점·로그 조회 | console.n3m.kr과 *.tunnels.n3m.kr의 세션·Origin 분리. 장기 관리 토큰은 브라우저 저장소에 두지 않음 |
| ops / deploy | DNS·TLS·Nginx·systemd·백업·관찰·서명·배포 | 관리 키와 DB 접근 최소화. remote.n3m.kr 기존 경로를 유지하며 서비스별 배포·복구 경계 분리 |
데이터 모델 · 초안
FIG-02 · 논리 관계. 이름 예약은 계정당 여러 개이고, 이름 하나의 활성 터널 바인딩은 최대 하나입니다. Tunnel은 이름을 최대 하나 사용합니다. 상세 스키마·보존 기간은 M1 설계에서 고정합니다. 파일 절대경로는 서버에 저장하지 않고 agent의 로컬 share ID로 매핑합니다.
전송은 중계하고, 완료는 원본 PC가 확인합니다.
ADR-03 초안은 상시 제어 WSS 한 개 + 전송별 별도 WSS 연결입니다. 기본 WebSocket은 여러 독립 스트림의 다중화를 제공하지 않으므로 큰 파일과 제어 요청을 한 큐에 섞지 않습니다. M1에서 프록시 호환성·지연·연결 수를 비교한 뒤 확정합니다. RFC 6455.
다운로드 계약
GET /api/v1/files/{id}/content, HEAD, 길이·이름·Content-Disposition. Range / If-Range로 이어받고 206·416·변경된 파일을 구분합니다. 파일 버전은 이름만으로 식별하지 않습니다.
읽는 중 수정·교체를 탐지하면 기존 조각에 이어 붙이지 않습니다. 복수 Range·압축 다운로드·폴더 ZIP은 별도 복잡도이므로 P1/P2 선택 항목입니다. 브라우저가 큰 파일 전체를 메모리에 올리지 않는 저장 방식을 검증합니다. HTTP Range.
업로드 계약
POST /api/v1/uploads로 생성, HEAD로 offset 확인, PATCH로 재개하는 tus 1.0 후보. upload ID는 소유자·터널 generation·목표 파일·길이에 결속합니다.
같은 디스크에 임시파일 기록 → 길이/해시 검증 → 목적 파일로 반영. 청크 ACK는 실제 기록된 offset 기준입니다. 중복 PATCH·offset 충돌·재시도·만료 후 업로드를 구분하고 로컬 재개 기록은 crash 뒤에도 복구합니다.
터널 상태 모델
| 경계 / 초안 인터페이스 | 인증과 제한 | 오류 · 호환성 |
|---|---|---|
| CLI → Control /api/v1/devices · /tunnels · /names | 짧은 수명 기기 credential, 소유자 권한, 요청 중복 방지 키 | 401 인증 / 403 권한 / 409 이름 충돌 / 429 제한 |
| Agent → Relay /tunnel/v1/control · /data | 기기·tunnel ID·generation·transfer ID 결속. 데이터 ticket 재사용 거부 | HELLO(version, capabilities), 거부 가능한 최소/최대 버전. 잘못된 메시지 길이는 연결 종료 |
| 브라우저 → 파일 API | Host-only Secure HttpOnly SameSite 쿠키, 변경 요청 CSRF·Origin 검사, 각 요청 권한 재검사 | 410 만료 / 409 파일 버전 충돌 / 413 크기 초과 / 503 호스트 오프라인. 비인증 요청에는 존재 정보 숨김 |
| Transfer 오류 envelope | error code, 안전한 설명, request ID, retryable 필드. 절대경로·토큰 제외 | DISK_FULL / FILE_LOCKED / OFFSET_MISMATCH / ROOT_CHANGED / LEASE_EXPIRED |
| 공통 wire 규칙 | 제어 JSON ≤64 KiB, 데이터 프레임 ≤256 KiB, 최대 4개 전송/터널, RAM 한도는 제안값 | 큐 상한·역압·취소·timeout을 프로토콜 계약으로 정의. M1 실험 후 수치 확정 |
Windows 파일 처리와 안정적인 전송을 우선합니다.
사용자가 Rust 기반 개발을 확정했습니다. 에이전트·Control/Relay·중앙 콘솔은 Rust를 기준으로 구현합니다. Tokio·axum·rustls·SQLite를 채택하며 세부 버전은 Cargo.lock과 빌드 기록으로 고정합니다. 웹 표현 계층의 작은 HTML/JavaScript 사용은 허용하되 서버 핵심을 다른 언어로 대체하지 않습니다.
| 영역 | 채택 / 후속 후보 | 선택 이유 / 확인할 점 | 구현·검증 경계 |
|---|---|---|---|
| Windows agent / 서버 | Rust · Tokio · axum · rustls · clap · serde · tracing | 비동기 스트리밍·명시적 자원 수명·Windows API 연동. blocking 파일 작업 분리, 인증서 저장소와 프록시 호환 확인. Tokio / axum | Rust 확정. Linux 로컬 빌드 통과와 Windows 실행 검증은 별도로 기록 |
| Windows 파일·키 | windows crate · Win32 handles · DPAPI/Credential Manager | 경로 재검증·NTFS 이름/권한·잠금·키 보호. 관리자 권한 없는 foreground 앱부터 | 후속 서비스는 별도 사용자 컨텍스트·수명 검토 |
| 웹 UI | Rust 서버 제공 HTML · JavaScript / 이후 TypeScript 검토 | 파일 목록·전송 UI와 중앙 관리 UI 분리. 첫 구현은 소규모 웹 화면으로 연결 경로 검증. 가상 목록·복잡한 전송 큐는 후속 확장 | 중앙 콘솔 프로젝트는 /home/ahn/n3m-console. 앱/서버는 Rust 워크스페이스에서 검증 |
| 전송 | HTTPS 파일 API + WSS reverse tunnel | TCP 443 egress 친화적. HTTP/2 대안과 비교. QUIC·P2P·STUN/TURN은 초기 필수 아님 | HTTP/2 다중 스트림: 프록시·서버 구현 복잡도 비교 |
| 재개 | 다운로드: HTTP Range / 업로드: tus 후보 | 업로드 상태의 최종 권위는 agent. relay 재시작·중복 요청·파일 변경 시험 필요 | 자체 청크 API: 외부 규격 없이 구현할 때 호환·유지 비용 증가 |
| 저장소 | SQLite WAL · 명시적 migration | 단일 서버의 메타데이터만 저장. 백업·복원·재시작 가능해야 함 | 다중 서버에서 PostgreSQL. Redis는 실제 공유 상태 필요가 생길 때 |
| 배포·관찰 | Ubuntu · Nginx · systemd · 구조화 로그 · metrics | 전용 서비스 계정·프로세스·DB. 업로드/응답 buffering·temp-file 동작 검사. WSS 설정 / buffering | 컨테이너는 선택. Kubernetes는 초기 범위에 필요 없음 |
| Windows 네트워크 드라이브 | WebDAV 호환성 실험 → WinFsp 마운트 클라이언트 비교 | 파일 잠금·랜덤쓰기·Explorer 재접속·대용량·인증을 검증한 뒤 채택. 웹 API를 그대로 드라이브 프로토콜이라 부르지 않음 | WinFsp는 설치·서명·라이선스·캐시 개발 필요. SMB 인터넷 직접 노출은 계획하지 않음 |
기능을 요구사항과 시험으로 추적합니다.
Rust 초기 개발에 착수했습니다. 계획된 기능 전체가 구현된 것은 아니며, 부분 구현·Linux 로컬 시험·Windows 실기·외부망 검증을 구분합니다. 아래 기준 상태는 프로젝트의 원본 진행 원장에서 생성됩니다. 사용자 요구와 이를 실현하기 위한 제안을 구분하며, P0는 해당 단계의 필수, P1은 품질·사용성 확장, P2는 후속 선택을 뜻합니다. 부분 구현은 진행 중으로 표시하고 기존 수용 기준 전체를 충족하기 전에는 구현 완료로 집계하지 않습니다.
공식 진행
진행 원장 불러오는 중
구현 완료와 제품 검증 완료는 독립 집계. 완료는 관련 시험·증빙 및 필수 선행 요구 완료가 있어야 인정합니다.
개인 검토 기록
체크와 메모는 이 브라우저에만 저장합니다. 구현 완료 수와 서버의 문서를 바꾸지 않습니다. 다른 PC에서는 JSON 내보내기·가져오기로 옮깁니다.
| 식별 / 단계 | 기능 · 수용 기준 | 공식 상태 | 개인 검토 · 메모 |
|---|---|---|---|
| PW-001 | 현재 폴더에서 공유 시작Windows 터미널에서 tunnels serve 또는 tunnels serve <경로>로 폴더 하나를 선택하고 접속 URL, 권한, 만료 시각을 표시한다. 수용 기준 공백·한글이 있는 로컬 폴더에서 실행해 선택한 루트가 표시되고, 존재하지 않는 경로는 URL 발급 전에 실패한다. 책임 모듈 agent / Windows CLI 선행 요구 없음 시험 ID T-PW-001 구현 위치 crates/portway/src/bin/portway.rs · crates/portway/src/protocol.rs 현재 범위 Rust CLI serve 구현. Linux 실제 실행 검증. Windows 실행/설치 미검증. 증빙 evidence/runtime-validation.json · evidence/windows-cross-check.json |
진행 중 | |
| PW-002 | 서버 선택과 장치 자격증명Linux N3M Tunnels 제어 주소 tunnels.n3m.kr과 장치 등록 정보를 설정한다. 관리 진입점은 console.n3m.kr로 통합하며 agent credential은 콘솔 세션과 구분한다. Windows Credential Manager 또는 사용자 범위 DPAPI로 장치 비밀을 보관한다. 수용 기준 재실행 시 등록을 재사용하고 로그·설정 출력에 비밀이 나타나지 않으며 폐기한 장치는 재접속하지 못한다. 책임 모듈 agent / Windows CLI 선행 요구 PW-001 시험 ID T-PW-002 구현 위치 crates/portway/src/bin/portway.rs · crates/portway/src/protocol.rs 현재 범위 별도 agent token-file와 WSS 서버 선택 구현. 장치별 등록·폐기와 OS 자격증명 보관 미구현. 증빙 evidence/runtime-validation.json · evidence/windows-cross-check.json |
진행 중 | |
| PW-003 | Windows 배포 실행파일사용자가 별도 개발 도구 없이 실행할 수 있는 Windows x64 패키지, 체크섬, 버전 정보, 설치·제거 안내를 제공한다. 서명 방식은 배포 전 결정한다. 수동 버전 교체 시 배포 서명·버전·hash를 확인하고 실패 시 이전 정상 버전으로 복원한다. 자동 업데이트는 별도 후속 결정이다. 수용 기준 깨끗한 Windows 시험 환경에서 다운로드한 배포파일의 체크섬을 확인하고 설치·실행·종료·제거 절차가 성공한다. 변조/서명 오류 패키지를 거부하고 수동 교체 실패 후 기존 정상 버전과 설정을 복구한다. 책임 모듈 agent / Windows CLI 선행 요구 PW-036 시험 ID T-PW-003 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 확인할 점 코드 서명 방식과 Windows 배포 검증은 미완료다. 서비스 도메인은 tunnels.n3m.kr, 통합 관리 도메인은 console.n3m.kr로 확정됐다. |
미착수 | |
| PW-004 | 상태 조회와 종료실행 중 URL·연결 상태·전송 상태를 확인하고 Ctrl+C 또는 stop 명령으로 공유를 종료한다. 수용 기준 종료 뒤 새 목록·전송 요청이 거절되고 기존 전송이 명세한 취소 결과로 종료되며 종료 코드는 문서와 일치한다. 책임 모듈 agent / Windows CLI 시험 ID T-PW-004 구현 위치 crates/portway/src/bin/portway.rs · crates/portway/src/protocol.rs 현재 범위 Ctrl+C/콘솔 종료 경로 구현. CLI status 명령·OS 서비스 수명은 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-005 | 복수 폴더의 독립 공유여러 터미널에서 별개 폴더를 독립 터널로 공유하고 각 권한·URL·종료 범위를 분리한다. 수용 기준 동일 Windows 사용자로 두 폴더를 공유한 뒤 하나를 종료해도 다른 공유는 계속 동작하며 상대 루트에 접근할 수 없다. 책임 모듈 agent / Windows CLI 시험 ID T-PW-005 구현 위치 crates/portway/src/bin/portway.rs · crates/portway/src/protocol.rs 현재 범위 별도 에이전트 프로세스 2개 동시 공유를 검증. 단일 프로세스 관리 기능은 후속. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-006 | 아웃바운드 역방향 연결Windows 에이전트가 Linux relay의 TLS 443으로 먼저 연결한다. 사용자는 공유기 포트 개방 없이 다른 네트워크의 브라우저에서 접속한다. 수용 기준 공유기 포트 전달과 Windows 수신 포트 개방 없이 서로 다른 네트워크의 브라우저에서 인증 후 파일 목록·다운로드가 성공한다. 책임 모듈 server Control·Relay + agent 선행 요구 PW-002 · PW-009 · PW-025 시험 ID T-PW-006 구현 위치 crates/portway/src/bin/portway.rs · crates/portway/src/protocol.rs 현재 범위 아웃바운드 WebSocket 실제 왕복 검증. 실제 Windows 외부망 WSS/TLS는 미검증. 증빙 evidence/runtime-validation.json · evidence/windows-cross-check.json 확인할 점 기업 프록시·TLS 검사 환경 지원은 별도 호환성 시험 결과로 확정한다. |
진행 중 | |
| PW-007 | 임의 주소 발급공유 시작 요청에 서버가 난수 이름을 만들고 이름 DB의 고유 제약으로 충돌 없이 배정한다. 소유자·기기·터널 generation·만료에 결속하고 agent 준비와 활성 경로 확인 후 URL을 표시한다. 실행 시도별 중복 방지 키로 재시도를 처리한다. 폐기 이름의 영속 기록과 일반 로그 보존기간을 분리하고 타인에게 재배정하지 않는 정책을 정의한다. 멱등 결과는 공유 수명과 재시도 유예 동안 유지하며 만료 키의 요약 기록으로 늦은 재시도를 새 할당 대신 명시 오류로 처리한다. 수용 기준 동시 요청·강제 난수 충돌·응답 유실 재시도에서 이름 중복이나 중복 터널이 없다. READY 실패/timeout을 준비 완료로 표시하지 않는다. 새 실행은 새 임의 URL을 받으며 과거 이름은 난수/예약 API 양쪽과 DB 복원 후에도 재배정되지 않는다. URL을 아는 것만으로 파일을 읽을 수 없다. 멱등 결과 보존 경계와 만료 키 재시도에서 새 활성 공유가 생기지 않는다. 책임 모듈 server Control·Relay + agent 선행 요구 PW-006 시험 ID T-PW-007 구현 위치 crates/portway/src/server.rs 현재 범위 96비트 난수 label과 SQLite UNIQUE·영구 이름 기록. 새 실행은 새 주소. 생성 멱등성·충돌 재시도·DNS사전검사 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-008 | 사용자 지정 하위 주소소유자가 지정한 이름을 예약해 같은 URL로 재공유한다. 예약과 온라인 상태를 분리하고 예약 충돌·금지 이름·재사용 정책을 정의한다. 예약 소유권과 활성 공유 수명을 분리한다. 완전히 종료 후 같은 이름을 새 공유에 쓰면 새 generation·방문자 권한을 발급하며 폐기된 임의 이름은 예약할 수 없다. 수용 기준 두 계정의 같은 이름 동시 예약 중 하나만 성공하고 타인이 소유한 주소를 가져올 수 없으며 재연결이 기존 소유권을 유지한다. 종료 후 재공유에서 과거 세션/전송 권한을 거부하고 폐기된 임의 주소의 이름 예약도 거부한다. 책임 모듈 server Control·Relay + agent 시험 ID T-PW-008 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 확인할 점 tunnels.n3m.kr 도메인은 확정됐다. 지정 이름 기능의 실제 공개 사용은 DNS/TLS 운영 적용과 예약 소유권 시험 후 검증한다. |
미착수 | |
| PW-009 | DNS·TLS와 호스트 라우팅console.n3m.kr은 중앙 관리, tunnels.n3m.kr은 agent 제어, *.tunnels.n3m.kr은 공유별 주소로 구성하고 remote.n3m.kr 기존 서비스를 유지한다. 운영자가 wildcard DNS와 한 단계 공유 이름 및 apex용 TLS 인증서 범위를 준비한다. 공유마다 DNS/인증서를 발급하지 않으며 DNS는 공개 게이트웨이, 검증된 Host/:authority 경로표는 실제 터널을 선택한다. 수용 기준 정상 공유 이름은 유효한 HTTPS로 열리고 임의 Host·미등록 이름·잘못된 인증서를 사용하는 연결은 거절된다. 서로 다른 새 이름을 DNS 변경 없이 공개 진입점에서 해석하고 올바른 터널로 전달한다. 등록되지 않은 이름·임의 전달 헤더·다단계 이름/TLS 불일치·별도 DNS 레코드 우선순위를 시험하고 다른 터널로 fallback하지 않는다. 책임 모듈 server Control·Relay + agent 선행 요구 없음 시험 ID T-PW-009 구현 위치 crates/portway/src/server.rs 현재 범위 Host 격리·엄격한 suffix 검증 구현. 2026-10-05 19:55 KST 사용자 설치 후 세 서비스 active/enabled, 터널 readiness의 빈 본문 200, 새 한 단계 공유 이름의 시스템 신뢰·이름·유효기간 TLS 검증, apex/wildcard SAN과 미등록 공유 404를 확인했다. 공개 경로 20개 검사는 통과했지만 요구 전체의 악성 Host/전달 헤더·다단계 이름·활성 공유 라우팅 및 Windows 외부망 인수시험을 대신하지 않는다. 증빙 evidence/runtime-validation.json · evidence/learning-document/operations-observation.json · evidence/learning-document/operations-live-verification.json · evidence/learning-document/certificate-user-confirmation.json |
진행 중 | |
| PW-010 | 임대·재연결·오프라인 상태공유 최대 expires_at과 짧은 heartbeat/연결 lease, DNS 캐시 TTL을 구분한다. 통신 단절은 RECONNECTING으로 접근을 차단하고 만료 전 재인증한 같은 논리 터널은 URL·generation을 유지한다. 재연결마다 connection epoch를 증가시켜 이전 연결을 배제한다. 명시 종료·철회·공유 만료는 자동 복구하지 않는다. 수용 기준 네트워크/제어 연결 단절과 lease 만료 시 오프라인·재연결을 표시한다. 동일 공유의 유효한 복구는 같은 URL을 쓰고 활성 연결은 하나다. 서버 재시작 뒤 인증 전 온라인 복원과 명시 종료/만료 후 재접속을 거부한다. DNS 캐시가 남아도 폐기 터널 접근은 불가하다. 책임 모듈 server Control·Relay + agent 시험 ID T-PW-010 구현 위치 crates/portway/src/server.rs 현재 범위 공유TTL·ping/pong·종료/단절/서버 재시작 fail-closed. 자동 재연결·동일 주소 복구 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-011 | 버전이 있는 제어·전송 계약WSS 제어 메시지와 전송별 데이터 연결을 분리하는 초안을 검증한다. 요청 ID·기한·크기 제한·취소·오류 코드·일회용 전송 권한을 명시한다. 수용 기준 지원하지 않는 버전·중복 전송 권한·초과 크기 메시지가 거절되고 대용량 전송 중 상태 조회와 종료 명령이 정해진 시간 안에 처리된다. 책임 모듈 server Control·Relay + agent 선행 요구 PW-006 시험 ID T-PW-011 구현 위치 crates/portway/src/bin/portway.rs · crates/portway/src/protocol.rs 현재 범위 v1 JSON 요청ID와 단일 WS 계약. 초기 파일당 8MiB bounded buffer. 전송별 스트림·취소/재개 미구현. 증빙 evidence/runtime-validation.json · evidence/windows-cross-check.json 확인할 점 WebSocket의 기본 기능을 독립 스트림 다중화로 오인하지 않는다. 전송별 연결 방식은 M1 실험 후 확정한다. |
진행 중 | |
| PW-012 | 폴더 목록과 파일 메타데이터공유 루트 아래 폴더 탐색, 이름·유형·크기·수정 시각, 정렬 및 대규모 목록 페이지 처리를 지원한다. 현재 폴더 전체의 이름 필터를 지원하며 현재 화면 페이지만 검색하지 않는다. 수용 기준 한글·공백·빈 폴더·많은 파일이 있는 시험 폴더를 탐색하고 페이지 이동에서 문서화한 일관성 정책에 맞는 결과를 얻는다. 여러 페이지에 흩어진 이름 일치 항목이 검색되고 하위 폴더까지 재귀 검색하는 것으로 오인되지 않는다. 책임 모듈 fs-windows + protocol + web 시험 ID T-PW-012 구현 위치 crates/portway/src/server.rs · crates/portway/src/files.rs 현재 범위 정렬된 폴더 목록·크기/종류와 한글 경로 검증. 폴더 1,000항목 상한. 페이지 분할 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-013 | Windows 공유 루트 경계경로 탈출·절대/UNC 경로·대체 데이터 스트림·예약 이름을 차단하고 junction·symlink·reparse point는 기본 거부한다. 문자열 검사만으로 안전 판정을 끝내지 않는다. 수용 기준 인코딩된 상위 경로·ADS·장치 이름·junction·검사 직후 경로 교체 시험에서 루트 밖 파일의 조회·읽기·쓰기·생성이 모두 실패한다. 책임 모듈 agent + server + fs-windows + web 선행 요구 없음 시험 ID T-PW-013 구현 위치 crates/portway/src/server.rs · crates/portway/src/files.rs 현재 범위 cap-std 디렉터리 capability·경로/예약명/링크 제한. Linux 탈출·hardlink 시험. Windows TOCTOU/NTFS 실기 미검증. Windows 전용 핸들 검사 코드의 교차 컴파일 통과. 증빙 evidence/runtime-validation.json · evidence/windows-cross-check.json 확인할 점 Windows 핸들 기반 경로 검증과 TOCTOU 방어는 별도 설계·공격 시험의 출시 차단 항목이다. |
진행 중 | |
| PW-014 | 단일 파일 스트리밍 다운로드파일 전체를 메모리에 올리지 않고 브라우저까지 전송한다. 파일명·길이·Content-Disposition을 안전하게 처리하고 로컬 원본 변화를 감지한다. 수용 기준 0바이트·한글 이름·4GiB 이상 파일을 내려받아 원본 해시와 비교하고 전송 도중 원본 변경 시 조용히 손상된 성공 결과를 반환하지 않는다. 책임 모듈 fs-windows + protocol + web 선행 요구 PW-012 · PW-025 · PW-034 시험 ID T-PW-014 구현 위치 crates/portway/src/server.rs · crates/portway/src/files.rs 현재 범위 SHA-256 확인 후 attachment 다운로드, 파일당 8MiB. 대용량 스트리밍은 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-015 | 다운로드 재개와 조건부 읽기HTTP Range·If-Range 또는 동등한 버전 검증으로 중단된 다운로드를 안전하게 재개한다. 파일 변화 시 기존 조각을 혼합하지 않는다. 수용 기준 연결을 끊은 뒤 같은 버전 파일은 나머지 바이트로 재개하고 변경된 버전은 재개 거절 또는 처음부터 재다운로드하여 최종 해시가 일치한다. 책임 모듈 fs-windows + protocol + web 선행 요구 PW-014 시험 ID T-PW-015 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 |
미착수 | |
| PW-016 | 브라우저 파일 업로드쓰기 권한 사용자가 브라우저에서 선택하거나 끌어놓은 파일을 Windows 공유 루트 안에 업로드한다. 수용 기준 한글 이름·0바이트·큰 파일을 업로드해 Windows에서 원본 해시를 확인하고 읽기 전용 사용자의 업로드는 쓰기 전에 거절한다. 책임 모듈 fs-windows + protocol + web 선행 요구 PW-013 · PW-018 · PW-026 · PW-027 · PW-028 시험 ID T-PW-016 구현 위치 crates/portway/src/server.rs · crates/portway/src/files.rs · crates/portway/web/app.js 현재 범위 웹 기본 업로드와 SHA-256 검증. 초기 파일당 8MiB; 대용량/재개 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-017 | 업로드 재개·취소·임시파일 정리분할 전송 ID·오프셋·조각 검증과 만료를 정의하고 재접속 후 계속 업로드한다. 임시파일은 에이전트 로컬에만 둔다. 수용 기준 전송 중 브라우저·망·에이전트 재시작 시험에서 합의한 재개 범위를 충족하고 중복 조각이 중복 저장되지 않으며 만료·취소 파일이 정리된다. 책임 모듈 fs-windows + protocol + web 선행 요구 PW-016 시험 ID T-PW-017 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 |
미착수 | |
| PW-018 | 충돌과 원자적 업로드 완료기존 이름은 기본 거절하고 명시한 정책에서만 덮어쓰기 또는 이름 변경을 허용한다. 임시파일 검증 후 같은 볼륨의 최종 이름으로 완료한다. 수용 기준 동일 이름 동시 업로드·로컬 수정·디스크 부족·프로세스 종료 시 기존 정상 파일이 보존되고 미완료 파일이 완료 목록에 노출되지 않는다. 책임 모듈 fs-windows + protocol + web 시험 ID T-PW-018 구현 위치 crates/portway/src/server.rs · crates/portway/src/files.rs 현재 범위 동일 디렉터리 임시파일→sync→no-clobber hardlink commit, 기존 파일 보존 시험. crash/Windows잠금 실기 미검증. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-019 | 폴더 생성쓰기 권한 사용자가 웹에서 새 하위 폴더를 만들 수 있게 한다. Windows 이름 규칙과 기존 항목 충돌을 처리한다. 수용 기준 허용된 이름으로 폴더를 만든 뒤 Windows에서 확인하고 중복 이름·예약 이름·권한 없는 생성은 명확한 오류를 반환한다. 책임 모듈 fs-windows + protocol + web 선행 요구 PW-016 시험 ID T-PW-019 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 |
미착수 | |
| PW-020 | 이름 변경·이동·삭제 확장클라우드 드라이브에 가까운 파일 관리 범위를 후속 확장한다. 파괴적 작업 권한·확인·로컬 변경 충돌·삭제 복구 정책을 먼저 결정한다. 수용 기준 각 작업의 권한·동시 수정·대상 소실·실패 복구 시험을 통과하고 문서화된 삭제 정책과 실제 동작이 일치한다. 책임 모듈 fs-windows + protocol + web 선행 요구 PW-018 · PW-026 · PW-031 시험 ID T-PW-020 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 확인할 점 휴지통 지원 여부와 복구 보장 범위는 미정이며 MVP의 업로드·다운로드와 구분한다. |
미착수 | |
| PW-021 | 웹 파일 탐색 화면데스크톱 브라우저에서 로그인, breadcrumb 폴더 이동, 목록 정렬, 다운로드 및 권한·만료 표시를 제공한다. 수용 기준 대상 Windows 브라우저에서 키보드만으로 로그인·하위 폴더 이동·파일 다운로드가 가능하고 긴 이름이 작업 버튼을 가리지 않는다. 책임 모듈 web + 파일 API 시험 ID T-PW-021 구현 위치 crates/portway/src/server.rs · crates/portway/web/app.js 현재 범위 정적 웹 파일 탐색·상위 이동·읽기/쓰기·키 입력 화면. 현재 로그인은 메모리 Bearer, 폴더별 1,000항목 한도. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-022 | 미착수 | ||
| PW-023 | 오프라인·만료·권한 오류 안내호스트 꺼짐, 재연결 중, 링크 만료, 접근 거절, 저장공간 부족과 예상하지 못한 실패를 구별해 안내한다. 수용 기준 각 실패 상태를 주입했을 때 원인에 맞는 안내와 가능한 다음 행동이 표시되고 로컬 절대 경로나 비밀이 오류에 노출되지 않는다. 책임 모듈 web + 파일 API 선행 요구 PW-010 · PW-021 · PW-028 시험 ID T-PW-023 구현 위치 crates/portway/src/server.rs · crates/portway/web/app.js 현재 범위 접근키 오류·권한·종료·대용량·충돌 메시지. 모든 Windows/망 오류 시나리오 미검증. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-024 | 폴더·복수 항목 다운로드 확장폴더 또는 여러 파일을 선택한 다운로드와 묶음 생성 방식을 후속 제공한다. 압축 계산 위치와 중단·재개 범위는 먼저 검증한다. 수용 기준 중첩 폴더 묶음의 상대 경로·파일 해시가 일치하고 대규모 묶음에서 제한된 메모리·취소·파일 변경 정책이 지켜진다. 책임 모듈 web + 파일 API 시험 ID T-PW-024 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 확인할 점 묶음 다운로드 재개는 일반 단일 파일 Range 지원과 동일하게 보장되지 않는다. |
미착수 | |
| PW-025 | 소유자·장치·방문자 인증 분리터널 소유자, 등록 장치, 파일 방문자의 자격과 권한을 분리한다. 기본 공유는 인증 필요 상태이며 URL만으로 접근권을 부여하지 않는다. 수용 기준 미인증·다른 소유자·폐기 장치가 파일 또는 관리 API를 사용할 수 없고 권한 없는 요청은 원본 접근 전에 거절된다. 책임 모듈 agent + server + fs-windows + web 선행 요구 PW-009 시험 ID T-PW-025 구현 위치 crates/portway/src/server.rs 현재 범위 서버 admin/agent/공유 방문자 키 분리. 초기 운영자 공유 agent token. 다중 소유자 계정·장치별 등록 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-026 | 읽기·쓰기 권한과 공유 만료읽기 전용·업로드 허용을 구분하고 만료되는 방문자 초대 권한을 제공한다. 서버 권한은 에이전트에서 허용한 최대 권한을 넘지 못한다. 수용 기준 읽기 전용 초대로 업로드·변경 API 호출이 실패하고 만료 후 새 요청과 재개 요청이 거절되며 에이전트의 읽기 전용 제한을 서버 설정으로 확대할 수 없다. 책임 모듈 agent + server + fs-windows + web 시험 ID T-PW-026 구현 위치 crates/portway/src/server.rs 현재 범위 읽기 전용 기본값·쓰기 opt-in·TTL 60초~8시간. 사용자별 세부 ACL 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-027 | 웹 세션·업로드 콘텐츠 격리호스트 한정 Secure·HttpOnly 쿠키, CSRF 방어, Origin 검증, CSP, 파일명 이스케이프를 적용한다. 임의 업로드 파일은 애플리케이션 origin에서 실행하지 않는다. 수용 기준 외부 origin의 상태변경 요청·세션을 이용한 WebSocket 연결이 거절되고 HTML·SVG·스크립트 이름의 파일로 다른 사용자의 세션에서 코드가 실행되지 않는다. 책임 모듈 agent + server + fs-windows + web 시험 ID T-PW-027 구현 위치 crates/portway/src/server.rs · crates/portway/web/app.js 현재 범위 관리/파일 hostname 분리, 메모리 Bearer, CSP·nosniff·첨부 다운로드. SSO/방문자 세션 재발급 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-028 | 크기·동시성·속도·저장공간 제한계정·터널·전송별 동시성, 파일 크기, 속도, 대기열, 임시 저장량과 디스크 여유 한도를 제한하고 역압력을 적용한다. 수용 기준 느린 소비자·동시 업로드·초과 크기·디스크 부족 시험에서 정해진 자원 한도를 넘지 않고 서버와 다른 공유의 기본 요청이 계속 처리된다. 책임 모듈 agent + server + fs-windows + web 시험 ID T-PW-028 구현 위치 crates/portway/src/server.rs 현재 범위 인증 전 본문 수집 차단·파일 8MiB·서버 전체 전송4·agent연결16 상한. 속도·디스크 quota와 부하 측정은 후속. 증빙 evidence/runtime-validation.json 확인할 점 성능 수치는 M1 계측 후 시험 환경과 함께 확정한다. |
진행 중 | |
| PW-029 | 공유·세션·장치 즉시 철회소유자 또는 관리자가 공유·초대·장치 접근을 철회하면 새 작업과 진행 중인 전송 권한을 종료한다. 이미 받은 사본은 회수할 수 없음을 표시한다. 수용 기준 철회 후 새 요청·재개·재연결이 거절되고 진행 중인 전송이 문서화한 철회 지연 한도 안에 취소된다. 책임 모듈 agent + server + fs-windows + web 시험 ID T-PW-029 구현 위치 crates/portway/src/server.rs 현재 범위 콘솔 stop과 기존 공유 키 즉시 거부·agent 종료 검증. 장치별 credential 폐기 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-030 | 서버 전체 터널의 중앙 관리 화면console.n3m.kr의 n3m-console에서 서버 관리자가 모든 계정의 열린 N3M Tunnels 터널과 종료 이력을 한 화면에서 조회·관리한다. notparsec 관리 진입점을 함께 제공하되 remote.n3m.kr 기존 서비스를 유지한다. 일반 소유자는 자기 장치·터널·주소·정책만 관리한다. 전체/소유자/호스트/상태/주소 검색과 상세 화면을 제공한다. 수용 기준 서로 다른 두 소유자의 터널을 관리자는 모두 조회·중지할 수 있고 일반 소유자는 상대 터널의 목록·상세·로그·내보내기·제어에 접근할 수 없다. 터널 상세에서 세션·전송·로그·정책·변경 이력으로 이동한다. 책임 모듈 n3m-console + N3M Tunnels Control management API 선행 요구 PW-008 · PW-010 · PW-026 · PW-029 · PW-032 시험 ID T-PW-030 구현 위치 crates/portway/src/server.rs · ../n3m-console/src/lib.rs · ../n3m-console/web/admin.js 현재 범위 중앙 콘솔 전체 활성 터널 목록·요청/전송량·stop UI와 내부 API. 공개 도메인 이관 및 세부 정책 UI 대기. 증빙 evidence/console-integration.json |
진행 중 | |
| PW-031 | 접근·전송·관리 감사 기록과 보존요청·논리 파일전송·agent 연결·관리 변경을 별도 이벤트 종류로 기록하고 ID로 연결한다. 허용·거절·실패·취소를 모두 남기며 토큰·쿠키·비밀번호·파일 본문·절대경로는 제외한다. 세부 로그·집계·감사의 보존 기간과 용량 한도를 운영자가 정한다. 수용 기준 인증 실패·전송 중단·재개·관리자 변경을 event/request/transfer/action ID로 연결한다. 비밀·본문 누출이 없고 보존 만료 기록이 정책대로 삭제된다. 로그 조회/내보내기·보존 설정 변경도 감사하며 일반 역할은 감사 원문을 임의 수정·삭제할 수 없다. 책임 모듈 server Control + web 관리 시험 ID T-PW-031 구현 위치 crates/portway/src/server.rs 현재 범위 SQLite 요청 성공/거부·admin_stop 기록, 7일/최대10,000행 제한. 별도 감사 보존·수집 실패 복구저널 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-032 | 관리자·소유자·조회 역할과 운영 한도관리자 최초 생성·권한 부여/회수 절차와 서버 전체 관리 권한을 정의한다. 일반 소유자와 조회 전용 운영자의 범위를 구분하고 로그 열람/내보내기·정책 변경 권한을 분리한다. 계정·기기·예약 수·전송·대역폭 상한을 관리한다. 관리 권한 자체가 파일 본문 열람권한을 자동 부여하지 않는다. 수용 기준 미인증/파일 공유 세션의 관리 호출과 일반 사용자의 서버 전체·관리자 전용 권한 호출을 거부한다. 소유자는 자기 터널의 허용된 관리 동작을 사용할 수 있다. 관리자 최초 등록과 회수 뒤 기존 세션·실시간 구독·내보내기 권한이 폐기된다. 조회 전용 역할은 제어를 못 하고 동시 요청도 계정 상한을 넘지 않는다. 책임 모듈 server Control + web 관리 선행 요구 PW-025 · PW-027 · PW-028 시험 ID T-PW-032 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 |
미착수 | |
| PW-033 | Linux 설치·재시작·업그레이드·복구서비스 시작·종료, 설정 검증, DB 이관·백업·복구, TLS 갱신, 버전 호환성과 되돌리기 절차를 제공한다. 수용 기준 깨끗한 Linux 환경 설치와 재부팅 후 정상 시작을 확인하고 백업 복구·실패한 업그레이드 복구에서 소유권·예약·철회 상태가 유지된다. 책임 모듈 deploy + server + 배포 검증 시험 ID T-PW-033 구현 위치 crates/portway/src/server.rs · ../n3m-console/src/lib.rs · ../n3m-console/web/admin.js 현재 범위 전용서비스·nginx·토큰분리·설치/롤백 코드와 경계시험. root/DNS/TLS 미준비로 실제 운영 미적용. 증빙 evidence/deployment-validation.json · evidence/deployment-blocked.json · evidence/release-validation.json |
진행 중 | |
| PW-034 | 파일 무보관 중계와 데이터 경계중앙 서버는 계정·장치·예약·정책 등 메타데이터를 저장하고 파일은 제한된 버퍼로만 중계한다. 프록시 임시파일·본문 로그도 점검한다. 초기 구조는 TLS 구간 암호화이며 종단간 암호화를 주장하지 않는다. 수용 기준 대용량 업로드·다운로드 및 실패 후 서버·프록시 디스크에 파일 본문이 남지 않고 메모리가 문서화한 한도 안에 유지되는지 계측한다. 책임 모듈 deploy + server + 배포 검증 선행 요구 PW-011 시험 ID T-PW-034 구현 위치 crates/portway/src/server.rs 현재 범위 relay는 파일 본문을 DB/디스크에 저장하지 않음. 현재 전송별 bounded buffer; 큰 파일 스트리밍·dump운영정책 후속. 증빙 evidence/runtime-validation.json 확인할 점 서버 운영자는 TLS 종단에서 파일 내용을 볼 수 있다. 별도 E2EE 요구가 생기면 브라우저·드라이브 호환성을 재설계해야 한다. |
진행 중 | |
| PW-035 | 건강 상태·계측·부하 시험활성 터널, 전송량·실패율·지연, 메모리·파일 핸들·디스크 여유, 인증서 만료를 관측하고 용량 한계를 기록한다. 수용 기준 정상·포화·relay 재시작·호스트 단절 상황을 계측으로 구별하고 재현 가능한 부하 보고서에 환경·동시 수·처리량·자원 최고값을 남긴다. 책임 모듈 deploy + server + 배포 검증 선행 요구 PW-028 · PW-031 · PW-033 시험 ID T-PW-035 구현 위치 crates/portway/src/server.rs 현재 범위 loopback health와 상태/전송계수 구현. 외부망 readiness·성능 metrics·부하시험 미구현. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-036 | Windows·브라우저·망 경계 회귀 시험Windows 실제 파일시스템, 대상 브라우저, 서로 다른 네트워크에서 핵심 경로와 공격·실패 사례를 지속 검증하고 요구 ID에 증거를 연결한다. 수용 기준 출시 대상 요구마다 시험 결과·버전·환경·증거 파일을 연결하고 Windows 실기 검증이 없는 기능은 검증 완료로 집계하지 않는다. 책임 모듈 deploy + server + 배포 검증 선행 요구 PW-013 · PW-014 · PW-027 · PW-029 시험 ID T-PW-036 구현 위치 crates/portway/src/server.rs 현재 범위 Linux 실서버/실agent 통합 시험과 Chromium 검증 진행. 실제 Windows/다른 인터넷 회선 미검증. 증빙 evidence/runtime-validation.json · evidence/windows-cross-check.json |
진행 중 | |
| PW-037 | 호스트 절전·잠금·로컬 접근 오류Windows 잠금·절전·재개·로그아웃·공유 폴더 삭제·파일 잠금·ACL 거절을 처리한다. 호스트가 꺼지면 파일을 사용할 수 없다는 모델을 안내한다. 수용 기준 절전·재개와 파일 독점 잠금·ACL 거절을 주입해 손상 없이 실패·재연결하고 꺼진 호스트를 온라인 또는 파일 누락으로 잘못 표시하지 않는다. 책임 모듈 deploy + server + 배포 검증 선행 요구 PW-010 · PW-017 · PW-023 시험 ID T-PW-037 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 |
미착수 | |
| PW-038 | Windows 네트워크 드라이브 실현성 조사웹 MVP 이후 WebDAV/WebClient와 전용 Windows 파일시스템 클라이언트를 비교한다. 서비스 지원·파일 크기·인증·Office 잠금·캐시·재연결을 실기로 검증한다. 수용 기준 지원할 Windows 버전별 매핑·큰 파일·재연결·인증·Office 편집 결과를 표로 남기고 채택 방식과 제약을 근거로 결정한다. 책임 모듈 후속 drive adapter + fs-windows 선행 요구 PW-017 · PW-033 · PW-037 시험 ID T-PW-038 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 확인할 점 WebDAV는 호환성 가설이며 Windows 기본 네트워크 드라이브 연결이 아직 입증되지 않았다. |
미착수 | |
| PW-039 | 미착수 | ||
| PW-040 | 드라이브 잠금·충돌·오프라인 의미Windows 파일 잠금·임시 저장·이름 변경·캐시 무효화와 재연결 정책을 정의한다. 웹과 드라이브 동시 수정의 충돌을 처리한다. 수용 기준 웹·탐색기·로컬 앱 동시 수정과 Office 저장 시험에서 조용한 덮어쓰기·부분 파일 성공이 없고 오프라인 동작이 문서와 일치한다. 책임 모듈 후속 drive adapter + fs-windows 시험 ID T-PW-040 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 확인할 점 일반 로컬 디스크와 동일한 POSIX/Win32 의미를 자동으로 보장하지 않는다. |
미착수 | |
| PW-041 | 통합 콘솔과 서비스 경계 계약console.n3m.kr의 별도 n3m-console 프로젝트에 notparsec와 N3M Tunnels의 중앙 관리를 통합한다. remote.n3m.kr 기존 서비스는 유지하고 N3M Tunnels는 tunnels.n3m.kr 및 *.tunnels.n3m.kr로 제어·공유를 제공한다. 관리 API는 서비스별 인증·권한·오류·버전 계약으로 연결하며 파일 중계·DB·agent 비밀은 N3M Tunnels 경계에 둔다. 수용 기준 로컬 계약 시험에서 console→N3M Tunnels 관리 호출의 인증과 권한을 검사하고 외부 위조 identity 헤더를 거부한다. 콘솔 장애가 기존 remote endpoint 설정이나 N3M Tunnels의 파일 경로를 변경하지 않는다. 운영 전환 전후 remote 기존 접속·다운로드·문서 동작과 새 console/tunnels HTTPS를 각각 확인한다. 책임 모듈 n3m-console service adapter + N3M Tunnels Control + notparsec management boundary 시험 ID T-PW-041 구현 위치 crates/portway/src/server.rs · ../n3m-console/src/lib.rs · ../n3m-console/web/admin.js 현재 범위 sibling Rust console service와 제한된 localhost 어댑터 구현. notparsec DB·키·장치API 소유권 유지. 증빙 evidence/console-integration.json 확인할 점 통합은 사용자 확정 요구다. 현재 DNS 등록·TLS·시스템 서비스 설치가 남아 있어 로컬 계약 검증과 운영 적용을 분리한다. |
진행 중 | |
| PW-042 | console.n3m.kr 관리 인증·화면 통합console.n3m.kr에서 중앙 관리자가 notparsec와 N3M Tunnels 관리 기능에 접근한다. 콘솔 사용자 세션과 서버 간 서비스 credential, N3M Tunnels agent와 파일 방문자 인증을 구분한다. 전체 터널 조회·중지·접근 로그를 관리 API로 제공하며 공유 도메인에 관리 쿠키나 notparsec 내부 키를 노출하지 않는다. 수용 기준 관리자·조회자·일반 소유자의 로그인/로그아웃/권한 철회와 관리 API 호출을 시험한다. 공개 파일 세션으로 콘솔에 진입할 수 없고 console 자격증명이 파일 본문 열람권한으로 오용되지 않는다. remote.n3m.kr 기존 서비스는 유지하며 console과 tunnels의 공개 DNS/TLS·설치·회귀 증빙을 남긴다. 책임 모듈 n3m-console Rust web/BFF + N3M Tunnels management API 시험 ID T-PW-042 구현 위치 crates/portway/src/server.rs · ../n3m-console/src/lib.rs · ../n3m-console/web/admin.js 현재 범위 기존 관리 화면 소스 이관·관리 Bearer 확인→별도 N3M Tunnels토큰으로 호출. 운영 DNS/TLS/root 설치 대기. 증빙 evidence/console-integration.json 확인할 점 통합 구현은 필수다. 첫 구현은 기존 notparsec 관리자 Bearer 검증과 N3M Tunnels 별도 서비스 토큰을 사용한 단일 관리자 범위다. 다중 소유자·조회자 역할, DNS/TLS와 기존 remote 회귀는 확인한 계약 범위만 구현 완료로 기록한다. |
진행 중 | |
| PW-043 | 전체 터널·접속·전송 실시간 현황터널별 소유자·주소·기기·앱 버전·연결 및 파일서비스 상태·시작/만료·heartbeat·마지막 관측 시각, 활성 세션/전송·속도·누적량·오류 집계를 제공한다. 연결 상태와 접근 정책, 방문자 세션과 데이터 연결 수를 구분한다. 수용 기준 두 소유자와 여러 터널/전송을 만들어 전체 집계와 필터가 실제 상태에 맞는다. 예약만 된 이름·전송별 WSS는 온라인 터널/방문자로 중복 계산하지 않는다. 수집 단절 시 값 0 대신 마지막 관측·지연/미확인을 표시한다. 책임 모듈 server Control·Relay·이벤트 저장 + web 관리 시험 ID T-PW-043 구현 위치 crates/portway/src/server.rs · ../n3m-console/src/lib.rs · ../n3m-console/web/admin.js 현재 범위 전체 활성 터널 상태·누적 요청/바이트와 주기갱신. 연결/전송 세부 실시간 구독 미구현. 증빙 evidence/console-integration.json |
진행 중 | |
| PW-044 | 중앙 차단·종료·정책 변경과 적용 확인전체 터널의 접근 일시차단/재허용·강제 종료·세션/전송 취소·권한/만료/한도·IP 정책을 제어한다. action ID, generation, 정책 version, 중복방지로 서버 적용과 agent 확인 결과를 따로 추적한다. 오프라인 PC 기동과 로컬 허용 범위 확대는 제공한다고 약속하지 않는다. IP 정책 상세는 IPv4/IPv6 CIDR 지원·명시적 차단 우선·허용 목록이 있으면 일치 필수·활성 IP 정책에서 원본 IP 미확인은 거부하는 제안이다. 수용 기준 관리자가 진행 전송 중인 터널을 차단하면 신규 접근과 전송이 정책대로 종료된다. 단절 agent는 확인 대기/timeout으로 표시하며 서버 차단은 유지한다. 중복 요청과 과거 generation 명령은 새 터널에 재적용하지 않고 동시 변경은 충돌을 반환한다. IP 정책 활성화 시 허용/차단 CIDR·중첩·미확인·위조 헤더 입력을 검사하고 인증 성공만으로 IP 제한을 우회할 수 없다. 책임 모듈 server Control·Relay·이벤트 저장 + web 관리 선행 요구 PW-030 · PW-029 · PW-026 · PW-032 · PW-045 시험 ID T-PW-044 구현 위치 crates/portway/src/server.rs · ../n3m-console/src/lib.rs · ../n3m-console/web/admin.js 현재 범위 stop만 구현: 신규 요청 차단과 WS 종료. 권한·만료 변경/ACK 추적은 후속. 증빙 evidence/runtime-validation.json |
진행 중 | |
| PW-045 | 접속 원본 IP·추정 위치·클라이언트 조회방문자 client IP와 수신 peer IP, agent 출발 IP를 구분하고 IP 산출 근거/신뢰 프록시 revision을 남긴다. 국가·지역·도시·ASN/통신사와 User-Agent의 브라우저/OS를 추정값으로 표시하며 인증 주체 또는 익명과 연결한다. 수용 기준 직접 접속·신뢰 프록시·다중 프록시·IPv6·위조 전달 헤더를 시험해 원본 IP와 산출 근거가 맞고 신뢰되지 않은 CF/XFF 값으로 위조할 수 없다. GeoIP 실패·사설 IP는 미확인으로 남고 VPN 위치·User-Agent·공유 비밀번호로 실명이나 정확한 실제 위치를 단정하지 않는다. 책임 모듈 server Control·Relay·이벤트 저장 + web 관리 선행 요구 PW-009 · PW-025 · PW-031 시험 ID T-PW-045 구현 위치 crates/portway/src/server.rs · ../n3m-console/src/lib.rs · ../n3m-console/web/admin.js 현재 범위 직접 peer와 설정된 proxy IP분리·위조 전달 헤더 무시 시험. GeoIP/ASN·신뢰 Cloudflare 범위 미구현. 증빙 evidence/runtime-validation.json 확인할 점 IP 위치는 추정이며 동일 IP가 같은 사람을 의미하지 않는다. GeoIP 공급자·라이선스·갱신 정책은 미결정이다. |
진행 중 | |
| PW-046 | 중앙 요청·파일 전송 로그 검색과 내보내기기간·터널·소유자·주체·IP·국가/ASN·동작·결과로 요청/전송/연결/감사 이력을 검색하고 상세 시각·방향·바이트·소요시간·거부/오류 원인·관측 지점을 조회한다. cursor 페이지 처리와 권한 있는 JSON/CSV 내보내기를 제공한다. 수용 기준 동일 논리 전송의 재개·완료·취소·오류를 같은 transfer ID로 연결하고 전송 생성 전 인증/권한 거절은 request/event ID로 추적한다. 서로 다른 전송은 합치지 않으며 필터·페이지·내보내기 결과가 일치한다. 권한 없는 터널 로그와 숨김 필드가 노출되지 않고 CSV 수식 주입과 비밀 유출을 막는다. 로그 화면에 상위 edge 미수집 범위를 표시한다. 책임 모듈 server Control·Relay·이벤트 저장 + web 관리 선행 요구 PW-031 · PW-032 · PW-045 시험 ID T-PW-046 구현 위치 crates/portway/src/server.rs · ../n3m-console/src/lib.rs · ../n3m-console/web/admin.js 현재 범위 최근 로그 조회 API/콘솔 목록. 검색·필터·내보내기는 미구현. 증빙 evidence/console-integration.json |
진행 중 | |
| PW-047 | 실시간 로그 구독·수집 공백·저장 장애 처리인증된 SSE 등으로 로그와 상태를 갱신하고 event cursor 재연결·중복 제거·snapshot 재조회·누락 구간을 처리한다. 수집 위치·지연·용량 제한·유실 건수를 표시하며 정책상 미수집과 장애를 구분한다. 비긴급 정책 변경은 감사 저장 실패 시 거부하고 긴급 차단/종료는 우선 실행 후 별도 복구 기록을 시도한다. 수용 기준 브라우저/서버 재시작·네트워크 단절·cursor 보존기간 초과·DB/디스크 부족·이벤트 폭주에서 중복과 공백이 표시된다. 긴급 차단은 로그 장애에도 유지하며 복구 기록 실패는 감사 미기록으로 드러낸다. 관리자 권한 철회/로그아웃 후 열린 스트림도 중단하고 기존 관측값을 0으로 바꾸지 않는다. 책임 모듈 server Control·Relay·이벤트 저장 + web 관리 선행 요구 PW-031 · PW-043 · PW-046 시험 ID T-PW-047 구현 위치 미착수 현재 범위 요구 전체 수용 기준은 개별 검증 기록을 확인합니다. 증빙 없음 · 제품 시험 미실행 확인할 점 외부 CDN/WAF·DNS·TLS 단계에서 끝난 시도는 별도 관측 연동 전까지 전체 수집을 보장하지 않는다. |
미착수 |
가져오기는 같은 ID의 기록을 병합합니다. 기존의 다른 ID 기록은 보존합니다. 알 수 없는 ID도 다음 개정을 위해 보관합니다. 개인 검토와 요구 카탈로그를 함께 내보내지만 가져오기는 공식 상태를 변경하지 않습니다. 개인정보·비밀번호·실제 파일 내용은 메모에 기록하지 마세요.
공유 루트와 권한을 모든 요청에서 지킵니다.
위협 모델은 익명 방문자, 권한이 낮은 접속자, 악성 파일명, 네트워크 단절, 호스트의 동시 파일 변경을 포함합니다. 서버와 운영자는 신뢰 대상입니다. 악의적 운영자나 침해된 호스트 OS로부터 파일 기밀성을 보장하지 않습니다.
| 위험 / 실패 | 필수 설계 · 제안 | 검증 시나리오 |
|---|---|---|
| 폴더 밖 접근 | 루트 핸들 고정. .., 이중 인코딩, UNC·장치 경로, ADS(:), 예약 이름 검증. reparse point·junction 기본 거부. 열기 직전·후 핸들 기반 경계 확인 | 경로 바꾸기 경합(TOCTOU), junction swap, 한글·긴 경로·대소문자·루트 교체. hard link가 공유 밖 파일과 같은 객체일 수 있어 링크 수 검사와 정책 별도 결정 |
| URL 유출 · 무차별 시도 | 주소는 비밀값이 아님. 기본 접근 비밀번호·만료·읽기 전용. 비밀번호 KDF·로그인 제한·토큰 짧은 수명·범위 결속 | 비밀번호 실패 반복, 이름 열거, 과거 세션 재사용, 다른 tunnel ID 치환 |
| 업로드 파일의 스크립트 실행 | 초기 미리보기 제한. Content-Disposition attachment + nosniff. 관리 화면과 파일 응답의 Origin·쿠키 격리, 민감 응답 no-store | HTML/SVG·악성 파일명 업로드, MIME 위장, XSS·CSRF·Origin 조작 |
| 철회 후 접근 · 오프라인 | 서버 신규 요청 차단 + 진행 전송 취소 + agent lease 만료. generation 단조 증가. TTL 경과 후 재연결 거부 | 전송 도중 철회, control 단절·relay 재시작, 시계 오차, 기기 키 폐기 |
| 데이터 유실 · 덮어쓰기 | 동일 볼륨 임시파일, 목적 파일 사전조건·파일 ID 검증, 디스크 여유 확인, 기본 충돌 거부. overwrite는 명시 정책 | 0-byte, 10 GiB, 디스크 부족, 강제 종료, 열린 Office 파일, 바이러스 검사 잠금, 중복 커밋 |
| 서버 메모리 · 대역폭 고갈 | 파일·청크·터널·기기·계정별 제한, 역압·취소·rate limit. relay는 RAM 버퍼만, Nginx·CDN의 임시 디스크/본문 로그 동작 검사 | 느린 수신, 악성 길이, 전송 1/4/16개, 연결 폭주, 무한 유휴 연결 |
| 기기 키 / 배포 교체 침해 | 사용자별 보호 저장, 토큰 로그 제외, 키 회전·폐기, 서명된 배포와 hash 확인. secret은 URL query에 넣지 않음 | 취소된 키, 변조 앱·매니페스트, 관리자 권한 없이 실행, rollback 호환성 |
| 백업·감사 오해 | 서버 백업은 메타데이터·키이며 원본 파일 백업 아님. 경로/파일명은 최소 수집·마스킹. 감사는 누가·언제·무엇을 허용/거부했는지 | DB 복원 후 폐기 권한 되살아남 방지, audit 보존 기간·다운로드·디스크 한도 |
FAULT-01 · 전송이 멈춘 경우
- 브라우저에서 원본 PC의 online/offline/expired를 확인합니다.
- 네트워크 복구 후 확정 offset과 파일 버전을 조회합니다.
- 동일한 업로드 세션이면 재개합니다. 파일이 달라졌거나 권한이 만료됐으면 이유를 표시하고 새로 시작합니다.
- 실패 임시파일은 정책 기간 뒤 정리하고 기존 목적 파일은 유지합니다.
FAULT-02 · 비정상 접근이 발견된 경우
- 해당 공유를 철회하고 진행 전송을 중단합니다.
- 기기 자격증명과 접속 세션을 폐기합니다.
- 감사 이벤트와 request ID로 영향 범위를 확인합니다.
- 새 credential·generation으로 재등록합니다. 이전 링크가 다시 인증되지 않는지 시험합니다.
먼저 한 파일의 왕복을 끝까지 만듭니다.
달력 기반 확정 일정은 없습니다. 단계별 통과 기준으로 진행하며 M1의 터널·파일 경계 실험 뒤 소요 기간을 산정합니다. M2까지 기능 MVP, M3까지 외부 공개 운영 준비로 구분합니다.
설계 기준과 추적 원장
목표·범위·기술·위험·요구 ID·검증 계획, HTML 생성과 외부 문서 게시.
읽기 전용 외부망 연결
Windows CLI·기기 등록·인증·임시 주소·루트 경계·목록·단일 다운로드·종료. 중앙 콘솔 연동 계약을 함께 구현.
업로드와 사용 경험
웹 탐색·큐·업로드·재개·충돌·이름 예약. 전체 터널 관리·접속 출처·실시간/이력 로그·중앙 제어·역할과 보존 정책.
안정성 · 배포 · 관리
한도·관측 부하/확장·기기 폐기·DB 백업/복원·배포 서명·수동 버전 교체·장시간 시험.
Windows 드라이브
WebDAV와 마운트 클라이언트 비교, 탐색기·Office 파일 잠금·랜덤 쓰기·캐시 일관성.
n3m 중앙 콘솔
console.n3m.kr에서 notparsec와 N3M Tunnels를 관리. 기존 remote.n3m.kr 서비스와 파일 중계 경로는 유지·분리.
001-03 첫 구현 묶음 · 실동작 경로부터 검증
Rust CLI가 폴더를 선택하고 임시 URL을 배정받아 WSS로 연결합니다. 브라우저 목록·다운로드·기본 업로드와 중앙 콘솔의 전체 터널 조회·중지·접근 IP 로그까지 하나의 흐름으로 연결합니다. 아래는 이번 착수 범위이며 M1/M2 전체 수용 기준을 줄이지 않습니다.
| 이번 구현 목표 | 요구 연결 | 완료로 올리기 전 남는 검증 |
|---|---|---|
| 폴더 CLI·난수 주소·agent WSS·목록·다운로드 | PW-001, 006~014, 021, 025~029, 034 | 실제 Windows 경로/경합, 인증·철회, 외부망 HTTPS, 큰 파일과 제한된 메모리 |
| 기본 업로드·같은 이름 거절·원자적 반영 | PW-013, 016, 018, 026~028 | 재개는 PW-017 후속. Windows 교체/잠금·디스크 부족·실패 복구·무결성 |
| console.n3m.kr 전체 터널 조회·중지·접근 IP 로그 | PW-030~032, 041~047 | 권한 분리·기존 remote 회귀·실시간 구독·GeoIP·이력 보존/내보내기·운영 이관 |
| 설정 예제·서비스 설치 준비·도메인 라우팅 준비 | PW-009, 033, 041, 042 | DNS 등록·wildcard TLS·관리자 권한 설치·공개 주소·장시간 시험 |
현재 코드의 지원 범위 · 전체 목표와 구분
crates/portway의 첫 개발 버전은 작은 파일로 주소 배정부터 왕복 전송·관리 종료까지 연결하는 단계입니다. 위의 목표 절차와 다이어그램에는 후속 기능도 포함됩니다. 아래 제한은 현재 코드 계약이며, Linux 시험·Windows 교차 컴파일·실제 Windows 실행은 별도 증빙으로 표시합니다.
| 항목 | 첫 구현 | 후속 / 미검증 |
|---|---|---|
| 공유 시작·인증 | tunnels serve <폴더> --token-file <공유 밖 키 파일>. 프로세스 공용 등록 토큰을 서버가 확인하며 기본 읽기 전용. --read-write로 업로드 허용. 생성된 공유 접근 키는 별도로 입력 | 기기별 등록·로그인·DPAPI/Credential Manager·키 회전·다중 소유자 권한은 후속. 목표 예시의 login/names 명령은 아직 지원하지 않음 |
| 주소·수명 | 실행마다 새 난수 이름과 접근 키. 60초~8시간 TTL. 종료/단절 후 자동 재연결 없음. 관리자가 신규 접근과 서버 응답을 차단 | 예약 이름, 동일 주소 복구, 중복 생성 방지 키, generation/lease 협상은 후속. 이미 시작된 로컬 파일 작업의 완전 취소와 장애 후 커밋 상태 복구는 미검증 |
| 파일·전송 | 파일당 8 MiB, 폴더당 표시 가능 항목 1,000개. 단일 WSS의 JSON/base64 요청·응답, 메시지 12 MiB 상한. 목록과 단일 다운로드·기본 업로드. 동일 이름은 거절 | 청크 스트리밍, Range, 업로드 재개, 전송별 WSS, 대용량/장시간 성능은 미구현. hard link를 지원하지 않는 파일시스템의 업로드는 실패로 처리. Windows 경합·junction·잠금은 실기 확인 필요 |
| 첫 경로 계약 | agent: /agent/v1/connect, 목록: GET /api/files, 파일: GET / PUT /api/file. 파일 방문자 키는 Authorization에 전달하며 브라우저 메모리에만 보관 | 위 04절의 버전 API·쿠키 세션·전송 ticket은 확장 설계. 초기 JSON/base64 방식의 크기 제한을 우회해 대용량 지원으로 표현하지 않음 |
| 중앙 관리·로그 | 관리자 한 명 기준 전체 터널 목록·중지와 요청/관리 종료 이벤트. 원본 IP와 peer IP 구분. 현재 로그 최대 10,000건/7일, 한 번 조회 최대 500건 | GeoIP·실시간 구독·다중 조건 검색·내보내기·소유자/조회자 역할·독립 전송 완료 이벤트는 후속. 응답 생성 시점의 수치를 브라우저 저장 완료로 해석하지 않음 |
요구에서 검증까지 · 프로젝트용 V 도식
| 시험 묶음 | 조건 / 제안 합격 기준 | 기록할 증빙 |
|---|---|---|
| VT-01 실제 사용 | 서로 다른 인터넷 회선의 Windows 호스트·브라우저. 포트포워딩 없이 등록→주소→목록→전송→종료. LTE/다른 ISP 포함 | OS build·앱/server commit·회선·도메인·스크린샷·단계별 결과 |
| VT-02 파일 정확성 | 0 B / 1 B / 1 MiB / 10 GiB, 한글·공백·긴 이름, 1만 항목. 전체 SHA-256 일치. 25/50/90% 단절 후 재개 | 원본/결과 hash·확정 offset·충돌·취소·임시파일 결과 |
| VT-03 안전한 경계 | 루트 탈출·junction 경합·ADS·ID 치환 거부. 취소 credential·쿠키·ticket 재사용 거부. 철회 후 신규 접근 0건 | 악성 입력 corpus·단위/속성/통합 결과, 권한 철회 관찰 시각 |
| VT-04 전송·자원 | 1/4/16 동시 전송·느린 수신·지연 20/100/300ms. 목표: relay 메모리 일정 상한, 파일 크기와 선형 증가하지 않음. 수치 목표는 M1에서 확정 | 처리량·p50/p95 시간·메모리·CPU·연결·오류율, 직접 HTTPS 대조 |
| VT-05 장애복구 | agent kill·절전·resume, relay crash, DNS/TLS 오류, 디스크 부족/잠금, DB 복원. 기존 파일 손상 0건 | 전/후 파일 hash, lease·generation·철회 유지, 복구 절차 |
| VT-08 임시 주소 수명 | 동시 생성·강제 이름 충돌·응답 유실·READY 실패·잘못된 Host/authority·lease 단절·동일/새 실행·만료·DB 복원 | PW-007~010의 이름 고유성, 중복 생성 없음, 온라인 판정, 같은/새 주소·세대 기록, 폐기 주소 재할당 거부, DNS/TLS 매칭 |
| VT-07 중앙 관리·로그 | 관리자/소유자/조회자와 다중 터널. 전체 조회·차단·만료 변경·적용 확인, IPv6/위조 헤더·위치 미확인, 성공/거부/재개 이력·권한 있는 내보내기, 스트림 단절/철회·저장 실패 | PW-030~032, PW-043~047의 역할별 API 결과·event/request/transfer/action ID·상태 시각·수집 공백·삭제/감사 결과 |
| VT-06 UI·배포 | Edge/Chrome 지원 버전, 390/1440px, 키보드·대량 목록. 배포 서명/hash·수동 버전 교체 실패 복원. 24시간 정상/전송 혼합 시험 | 브라우저/OS 버전·캡처·배포 파일·검증 로그 |
완료 규칙: 구현 위치 + 요구별 T-PW 시험 + 환경·입력·결과·실행일·증빙 파일 + 선행 요구 충족. 미실행 환경은 미검증으로 유지합니다. 문서의 정상 표시를 실제 터널·Windows 동작 검증으로 세지 않습니다.
관리는 console.n3m.kr, 파일 공유는 tunnels.n3m.kr.
2026-10-04 사용자 결정. 중앙 관리 통합과 Rust 사용이 확정됐습니다. 통합 콘솔 프로젝트는 /home/ahn/n3m-console, N3M Tunnels 구현은 /home/ahn/portway에 둡니다. 기존 remote.n3m.kr의 notparsec 서비스·클라이언트 접속·문서는 유지합니다.
| 도메인 / 프로젝트 | 책임 | 운영 경계 |
|---|---|---|
| console.n3m.kr / n3m-console | 중앙 관리 로그인·서비스 진입점·N3M Tunnels 전체 터널/로그/종료. notparsec 관리 화면 통합 | 브라우저 관리 세션과 서버 간 관리 API 인증을 분리. 파일 방문자에게 관리 권한 없음 |
| remote.n3m.kr / notparsec | 기존 원격 접속 제품과 운영 서비스·배포·문서 | 새 콘솔 도입으로 기존 앱 endpoint·DB·기기 키를 자동 변경하지 않음 |
| tunnels.n3m.kr / N3M Tunnels | agent 제어·연결 진입점과 N3M Tunnels API | Rust Control/Relay. 외부 TLS 종료 뒤 제한한 내부 연결 |
| *.tunnels.n3m.kr / 공유별 URL | 임시/예약 이름 → 활성 agent → 파일 탐색·업로드·다운로드 | 공유별 Host 검증·방문자 인증·권한. 관리 쿠키와 파일 본문 분리 |
인증과 배포 계약
콘솔은 브라우저의 관리 요청을 인증하고 권한을 확인한 후 제한된 내부 관리 API로 전달합니다. 외부의 임의 사용자/권한 헤더는 신뢰하지 않습니다. 서비스 토큰은 브라우저에 노출하지 않고 서비스별 scope·회수·오류 응답을 정의합니다. 첫 구현은 기존 notparsec 관리자 로그인에서 받은 15분 수명의 메모리 Bearer를 사용합니다. 콘솔은 요청마다 기존 관리 API로 세션을 검증하고, 별도 N3M Tunnels 서비스 토큰으로 내부 API를 호출합니다. 서비스 간 쿠키·DB·기기 키를 공유하지 않습니다. 이 계약의 검증 여부는 코드·시험 기록을 따릅니다.
관리 세션, agent 자격증명, 파일 방문자 세션은 용도가 다릅니다. .n3m.kr 전체에 관리 쿠키를 배포하거나 notparsec 내부 키를 파일 접근권한으로 재사용하지 않습니다. 파일 본문은 N3M Tunnels Relay와 agent 사이에서만 흐릅니다.
서버 운영 확인과 남은 검증
전용 프로세스·설정·DB·키·로그와 systemd/Nginx 구성을 사용자가 설치했습니다. tunnels.n3m.kr 자체 인증서와 *.tunnels.n3m.kr의 한 단계 이름용 인증서 범위를 함께 충족해야 합니다.
2026-10-05 19:55 KST: portway·n3m-console·notparsec-control 서비스 active/enabled와 올바른 readiness를 확인했습니다. 새 임의 공유 이름에 대해 시스템 신뢰·이름 검증을 켠 TLS 1.3 접속, 인증서의 apex/wildcard SAN, 미등록 공유 404 및 공개 경로 20개 검사를 확인했습니다. 갱신 시험 성공은 별도 사용자 실행 로그 근거입니다. 인증된 관리자 기능, 실제 Windows WSS 연결·파일 왕복·무결성, 유휴시간과 대용량 buffering은 남은 검증입니다.
첫 관리 API 계약 · 초기 관리자 범위
로컬 개발의 기본 주소는 n3m-console 127.0.0.1:18082, N3M Tunnels 127.0.0.1:18081입니다. 외부에는 확정된 HTTPS 도메인만 공개하고 내부 관리 API는 loopback에 제한합니다. 첫 구현은 기존 관리자 한 명을 위한 통합이며, 일반 소유자·조회자 분리와 다중 계정은 PW-032/042의 후속 검증으로 남깁니다.
| 브라우저 → console | 서버 측 처리 | 권한·구현 경계 |
|---|---|---|
/notparsec-admin/api/* | 기존 로그인/로그아웃·계정 비밀번호·장치 승인/거절/철회·hosting·다운로드의 허용된 경로만 proxy | 기존 인증 계약 유지. 임의 URL로 보내는 범용 proxy로 사용하지 않음 |
GET /api/portway/tunnels | 전체 터널 목록 → 내부 /admin/v1/* API | 브라우저 관리자 Bearer를 기존 /notparsec-admin/api/devices로 검증한 후, 서버 내부 PORTWAY_ADMIN_TOKEN으로 호출. 토큰 값은 공개 문서·브라우저에 포함하지 않음 |
POST /api/portway/tunnels/{id}/stop | 선택 터널 종료 요청 → 적용 결과와 감사 이벤트 | |
GET /api/portway/events | 접근 IP와 요청·관리 종료 이벤트 조회. 연결/전송 전용 이벤트는 후속 |
위 경로는 이번 개발 계약입니다. 실시간 구독, GeoIP, 다중 조건 검색, 로그 내보내기, 역할별 UI, 서비스 토큰의 자동 회전은 이 표만으로 구현 완료를 뜻하지 않습니다. 목록에 표시되는 source IP는 검증된 proxy 경로의 원본 주소 또는 실제 peer 주소로 구분하며, IP 위치를 실제 사람의 위치로 단정하지 않습니다.
확정된 결정과 남은 실험을 구분합니다.
| ID / 결정 | 확정 / 제안 | 검증 조건 / 영향 |
|---|---|---|
| ADR-01 주소 형태 | 확정: tunnels.n3m.kr + *.tunnels.n3m.kr. 공유별 단일 label. 이름 예약은 기존 요구 유지 | 서버 운영·apex/wildcard TLS 확인. 활성 공유 Host 라우팅과 전체 Origin 격리 인수시험은 별도 |
| ADR-02 중계 우선 | 공인 서버 relay로 시작. P2P·UDP는 후속 수요 때 | 서버 대역폭/비용·서로 다른 NAT/프록시 시험 |
| ADR-03 wire | 제어 WSS + 전송별 WSS, 버전·ID·역압·취소 | Rust/Tokio·axum·rustls 확정. 연결 분리·역압·취소·프록시 호환을 실동작으로 검증 |
| ADR-04 접근 인증 | 소유자 계정·등록 기기 + 공유 비밀번호. 세부 ACL 확장 | 개인 단일 계정 시작 vs 다중 계정 범위, 사용자 UX 검토 |
| ADR-05 재개/파일 일관성 | tus 후보 + 파일 버전/커밋 상태. 덮어쓰기 기본 금지 | Windows 파일 잠금·원자 교체·crash 복구 실험 |
| ADR-06 드라이브 | WebDAV와 WinFsp 비교, M4에서 채택 | Explorer/Office·캐시·랜덤쓰기·배포 권한·라이선스 시험 |
| ADR-07 중앙 관리 통합 | 확정: console.n3m.kr / n3m-console. remote.n3m.kr 기존 서비스 유지 | PW-041/042는 M1/M2 필수. 서비스별 인증·관리 계약·기존 앱 회귀·운영 이관 검증 |
| OD-01 지원 버전 | Windows 11 x64 먼저. Windows 10·ARM64는 별도 후보 | 필요 OS·지원 브라우저 버전을 M1 시험 환경에 고정 |
| OD-02 기본 제한 | TTL 8시간, 임시 업로드 보존 24시간, 전송 4개/터널 제안 | 안정성·용량·개인 사용 패턴 확인. 계정·서버의 상한도 함께 결정 |
| OD-03 폴더 정책 | 로컬 NTFS 우선, reparse 거부, hard link 검증 | UNC·외장 exFAT·OneDrive placeholder 포함 여부는 M1 파일 경계 실험 후 |
| OD-05 접속 출처·로그 | 원본 IP와 수신 peer 분리. GeoIP 공급자·보존 기간/용량은 제안 단계 | M2에서 프록시 신뢰 경로·IPv6·DB 라이선스·정확도·7일 상세/90일 감사/30일 집계 한도와 수집 공백 처리 확정 |
| OD-04 파일 관리 확장 | 목록·단일 전송 필수. 폴더 ZIP·삭제·이름 변경은 P1/P2. 미리보기는 구현 원장 밖의 검토 후보 | 보안 권한·대용량 메모리·취소·복원 UX를 먼저 정의 |
ADR-08 · 서비스와 개체의 이름
2026-10-05 사용자 확정. 서비스 전체 이름은 N3M Tunnels, 중앙 콘솔 표기는 Tunnels, 공개 상위 주소는 tunnels.n3m.kr입니다. 여러 터널을 열고 관리하는 서비스이므로 복수형을 사용하고, 개별 연결 하나는 tunnel이라고 부릅니다. 파일 공유는 이 서비스의 현재 용도이며 Windows 네트워크 드라이브는 후속 기능입니다.
| 용어 | 뜻과 사용 범위 |
|---|---|
| N3M Tunnels / Tunnels | 서비스 정식 이름 / 통합 콘솔 메뉴 이름. 개별 접속 세션과 구분 |
| tunnel | 에이전트와 중계 서버를 통해 여는 개별 통로. 전체 서비스 이름은 복수형 |
| Share | 공유하는 폴더와 읽기·쓰기 권한. 전체 서비스명이나 터널 연결 그 자체와 구분 |
| Agent | Windows 등 로컬 PC에서 서버로 연결을 여는 프로그램 |
| Endpoint | 접속자가 사용하는 공개 URL. 주소와 현재 연결의 수명은 별도로 관리 |
| Session | 인증된 접근 또는 연결의 수명. 관리·에이전트·파일 방문자 세션을 구분 |
사용자 실행 예는 tunnels serve ., 서버 실행 이름은 tunnels-server로 통일합니다. /home/ahn/portway, crates/portway, PORTWAY_* 환경변수, 기존 portway/portway-server 실행 별칭과 서비스·state 계정은 호환 식별자로 유지합니다. PW-PLAN-001과 PW 요구 ID, 기존 공개 문서 URL, 개인 검토 키 portway:review:v1 및 JSON의 project=portway도 보존합니다.
명칭 용례는 2026-10-04의 기존 조사인 Cloudflare Tunnel 관측과 ngrok의 agent·공개 endpoint 구조를 참고했습니다. 이 절은 프로젝트 명칭 결정이며 제품 기능의 추가 완료나 실제 운영 이관을 뜻하지 않습니다. 과거 시험 증빙의 이름·일자·해시는 유지하고 이번 문서 교정은 별도 naming-validation 기록으로 남깁니다.
대역폭과 전송 시간 · 계획용 계산기
여러 외부 클라이언트가 각자 같은 크기의 파일을 받는 상황. 각 클라이언트 속도는 동일하고 공정 분배한다고 가정합니다.
전송당 유효 Mbps = min(호스트 업로드/N, relay 송신/N, 클라이언트 수신) × 효율. 시간 = GiB × 2³⁰ × 8 / Mbps / 10⁶. relay 수신량과 송신량의 합은 파일 크기 × N × 2이며, 과금되는 외부 송신량은 공급자 정책에 따라 다릅니다. relay 수신 회선이 충분하다는 가정입니다. 재전송·디스크·TLS·RTT·프록시 한도는 별도이며 실제 성능 보장이 아닙니다.
착수 시 우선할 위험
R1 · 파일 경계 오류
루트 밖 파일 노출·덮어쓰기 위험. M1에서 Windows 핸들 기반 검증과 경합 시험을 먼저 수행.
R2 · 대용량 중계 비용
홈서버 회선과 notparsec 지연에 영향. 제한·계측·프록시 정책을 확인하고 VPS 분리 가능성 유지.
R3 · 드라이브 의미 차이
HTTP 파일 전송만으로 탐색기의 잠금·부분쓰기·캐시를 충족하지 못함. M4 전 별도 기술 검증.
원본을 바꾸고, 증빙을 남기고, 다시 게시합니다.
프로젝트 구조
portway/
AGENTS.md
README.txt
design/
requirements.json 요구 카탈로그
development-status.json 공식 진행 원장
standards-research.json 공식 출처 조사
plan.template.html 문서 틀
content.html 설명·도식 원본
plan.css / plan.js 표현·개인 기록
portway-plan.html 생성 결과
tools/build_plan.py 검증·재생성
tools/publish_docs.py 공개 snapshot 준비
tools/stage_notparsec_docs.py 기존 문서 보존 게시 준비
tools/check_browser.cjs 문서 기능 검사
evidence/ 검증·게시 기록Rust 앱은 03절의 책임 구조로 개발합니다. 코드 파일과 현재 지원 기능은 진행 원장의 구현 위치를 기준으로 확인합니다. 중앙 콘솔은 형제 프로젝트 /home/ahn/n3m-console에 둡니다.
PROC-DOC-01 · 진행 갱신
- 요구 ID를 유지하고 카탈로그의 범위·수용 기준을 수정합니다. 삭제 대신 superseded 관계를 기록합니다.
- 진행 원장에 구현 위치, 시험 결과, 실행 환경, 증빙 경로를 추가합니다.
python3 tools/build_plan.py를 실행합니다. 완료 증빙·참조·ID·선행 관계를 검사합니다.- 문서 브라우저 검증 후
python3 tools/publish_docs.py로 notparsec 문서용 공개 snapshot을 만듭니다. python3 tools/stage_notparsec_docs.py --stage로 운영 문서에 N3M Tunnels만 반영한 준비본을 만듭니다.--stage --check-current로 운영본 변경 여부를 확인한 뒤 기존 문서 전용 게시기로 게시하고 외부 HTTP·hash·문서 허브 링크를 확인합니다.
개인 검토 저장 키는 portway:review:v1로 개정 간 유지합니다. 공개 원장과 개인 메모는 서로 덮어쓰지 않습니다. 인쇄 시 모든 기능 상세를 펼칩니다.
공식 참고자료
조회 기준 2026-10-04 KST. 출처의 사실과 이 문서의 설계 제안은 구분합니다. 라이브러리 버전과 운영 환경은 실제 구현 때 재확인합니다.
STD-01 · S1000D Issue 6 공식 배포 구성
STD-02 · S1000D Getting Started — 데이터 모듈 및 CSDB
STD-03 · ASD-STE100 공식 소개 및 현재 판본
STD-04 · ASD-STE100 Downloads — Issue 9
STD-05 · NASA Systems Engineering Handbook Appendix D — Requirements Verification Matrix
STD-06 · NASA Systems Engineering Handbook Appendix I — V&V Plan Outline
TECH-01 · Microsoft — Deprecated features for Windows client
TECH-02 · Microsoft — Using the WebDAV Redirector
TECH-03 · RFC 9110 — HTTP Semantics
TECH-04 · tus resumable upload protocol 1.0.0
TECH-05 · RFC 6455 — WebSocket Protocol
TECH-06 · Tokio 공식 튜토리얼
TECH-07 · axum WebSocket API
TECH-08 · Nginx WebSocket proxying
TECH-09 · Nginx proxy buffering
TECH-10 · Microsoft reparse points
TECH-11 · Microsoft CreateFile
TECH-12 · OWASP WebSocket security
TECH-13 · OWASP File Upload
TECH-14 · Microsoft Windows credential handling
ADM-SRC-01 · Cloudflare Tunnel — Observability
ADM-SRC-02 · Cloudflare — Restoring original visitor IPs
ADM-SRC-03 · ngrok — Traffic Inspector
ADM-SRC-04 · Cloudflare Logs — HTTP requests dataset
ADM-SRC-05 · MaxMind — Geolocation accuracy
ADDR-SRC-01 · ngrok — How does ngrok's Gateway work?
ADDR-SRC-02 · Cloudflare DNS — Wildcard DNS records
ADDR-SRC-03 · Let's Encrypt — Challenge Types, DNS-01
ADDR-SRC-04 · IETF RFC 9525 — Service Identity in TLS, Section 6.3
| 개정 | 변경 | 검증 범위 |
|---|---|---|
| 001 / 06 · 2026-10-05 | 사용자의 전체 서비스 설치 후 공개 TLS·서버 실행·공개 경로 20개 검증 결과 반영. 학습 문서 001-02와 과거 장애 관측을 구분 | 요구 구현·검증 완료 수 0 및 개인 메모 키 유지. Windows CLI 실기·외부망 파일 왕복·인증된 운영자 검증은 미완료 |
| 001 / 05 · 2026-10-05 | 웹 입문 개발자용 PW-LEARN-001 학습 문서 추가. DNS·TLS·프록시·터널 원리, 인증서 자동화 도구와 최신 운영 관측을 연결 | 문서·상호 링크·공개 게시를 검증. DNS 등록과 발급 설정 생성은 관측했으나 터널 서비스·공개 wildcard TLS·Windows 왕복 완료로 판정하지 않음. 요구 구현 상태와 개인 검토 키 보존 |
| 001 / 04 · 2026-10-05 | 사용자 확정 명칭 N3M Tunnels·콘솔 Tunnels·tunnels.n3m.kr 반영. 명령 예·도식·허브 제목과 용어를 통일하고 기존 ID·경로·개인 메모 호환 유지 | 명칭·문서 생성·개인 기록 호환 검사만 새 증빙으로 기록. 제품 기능 상태와 과거 실행 시험 증빙은 보존. 실운영 게시 여부는 별도 |
| 001 / 03 · 2026-10-04 | 당시 사용자 확정: console.n3m.kr 중앙 관리 통합, remote.n3m.kr 유지, 파일 터널 도메인 지정, Rust 개발 착수. 현재 명칭·도메인은 ADR-08 우선. PW-041/042 통합 요구를 M1/M2로 승격하고 첫 실동작 구현·운영 이관 경계 기록 | 문서 생성과 코드 증빙을 분리. Linux 로컬 시험만으로 Windows/외부망/운영 완료를 표시하지 않음 |
| 001 / 02 · 2026-10-04 | 임시 URL 배정·준비 확인·DNS/TLS·호스트 라우팅·재연결/만료·재사용 방지 설명과 도식 2개 추가. PW-007~010 수용 기준 보강 | 문서 생성·표시·원문 무결성·외부 게시 검증. 제품 구현/검증은 미착수 유지 |
| 001 / 01 · 2026-10-04 | 사용자 추가 요구: 전체 터널 중앙 제어, 접속 출처와 요청/전송/감사 로그. PW-030~032 강화·M2 이동, PW-043~047 추가, 중앙 콘솔 도식 | 문서 개정 검증·재게시. 제품 구현/검증 완료 수는 0 유지 |
| 001 / 00 · 2026-10-04 | 별도 프로젝트 신설(당시 임시명은 현재 이름과 구분). 웹 우선 요구·구조·단계·후속 드라이브·선택 통합 계획 | 문서 생성·브라우저·게시 검증 기록은 evidence에 저장. 터널·파일 서버 제품 시험은 미실행 |