공개: alpha.11 검색과 전환 개선 반영

문서/115-public-technical-profile-plan.md

@@ -0,0 +1,173 @@
+# 공개 기술 문서 프로파일 기획
+
+이 문서는 공개 레포에 추가할 `기술적 측면 및 로직 상세` 문서군의 설계안이다.
+
+목표는 두 가지다.
+
+- 코드를 직접 읽지 않아도 KoTalk가 실제로 어떻게 동작하는지 이해되게 만들기
+- 과장 없이 현재 구현된 구조와 흐름만을 근거로 공개 표면을 강화하기
+
+## 기본 원칙
+
+- 공개 기술 문서는 `아키텍처 개요 1개 + 실제 흐름 문서 4개` 구성이 가장 읽기 쉽다.
+- 문서마다 독자를 분리한다. 하나의 문서에 구조, 인증, 메시지, UI 표면을 모두 섞지 않는다.
+- “현재 구현 기준”과 “향후 계획”을 같은 문단에서 섞지 않는다.
+- 소스 링크는 실제 근거를 보여 주는 최소 파일만 건다.
+
+## 도입할 문서군
+
+| 공개 문서 후보 | 역할 | 주 독자 | 공개 표면에서 증명할 것 |
+|---|---|---|---|
+| `TECHNICAL_ARCHITECTURE.md` | 시스템 구성요소와 계층 개요 | 첫 방문 기여자, 기술 평가자 | KoTalk가 제품형 계층 구조를 갖춘 저장소라는 점 |
+| `AUTH_AND_BOOTSTRAP_FLOW.md` | 가입, 토큰, 세션, bootstrap 흐름 | 백엔드 기여자, 테스트 참여자 | 가입 후 첫 화면까지가 하나의 계약으로 닫혀 있다는 점 |
+| `CONVERSATION_AND_MESSAGE_MODEL.md` | 대화/메시지/읽음 상태 모델 | 제품 평가자, 기여자 | 단순 UI가 아니라 메신저 도메인 모델이 있다는 점 |
+| `REALTIME_SYNC_AND_CLIENT_STATE.md` | WebSocket, 세션 복구, 클라이언트 상태 | 프런트엔드 기여자, QA | 실시간 반영과 복구 책임 위치가 분명하다는 점 |
+| `CLIENT_SURFACES_DESKTOP_AND_WEB.md` | 데스크톱과 웹 표면 전략 | 디자이너, 프런트엔드, 도입 검토자 | 같은 서비스 모델을 다른 표면에 어떻게 번역하는지 |
+
+## 문서별 설계
+
+### 1. `TECHNICAL_ARCHITECTURE.md`
+
+핵심 섹션:
+
+- 전체 지도: `Desktop / Web / Api / Application / Infrastructure / Domain / Contracts`
+- 요청 흐름: 입력 -> 엔드포인트 -> 서비스 -> 인프라 -> 응답
+- 계층 분리 이유: 공개 계약, 테스트 가능성, 클라이언트 병렬 개발성
+- 현재 구조의 한계와 확장 경계
+
+소스 근거:
+
+- `src/PhysOn.Api`
+- `src/PhysOn.Application`
+- `src/PhysOn.Infrastructure`
+- `src/PhysOn.Domain`
+- `src/PhysOn.Contracts`
+- `src/PhysOn.Desktop`
+- `src/PhysOn.Web`
+
+문서가 보여 줄 이점:
+
+- 저장소가 데모가 아니라 제품형 구조를 갖추고 있다는 점
+- 신규 기여자가 어디부터 읽어야 하는지 즉시 판단 가능하다는 점
+
+### 2. `AUTH_AND_BOOTSTRAP_FLOW.md`
+
+핵심 섹션:
+
+- 현재 Alpha 가입 방식: `alpha-quick`
+- 요청/응답 계약: 표시 이름, 참여 키, 토큰, bootstrap payload
+- `refresh token`과 세션 연장 흐름
+- bootstrap이 첫 화면에 필요한 데이터를 왜 한 번에 묶는지
+- 로컬/운영에서 참여 키가 시드되는 방식
+
+소스 근거:
+
+- `src/PhysOn.Api/Endpoints/MessengerEndpoints.cs`
+- `src/PhysOn.Application/Services/MessengerApplicationService.cs`
+- `src/PhysOn.Contracts/Auth/AuthContracts.cs`
+- `src/PhysOn.Infrastructure/Auth/JwtTokenService.cs`
+- `src/PhysOn.Infrastructure/Persistence/DatabaseInitializer.cs`
+- `tests/PhysOn.Api.IntegrationTests/VerticalSliceTests.cs`
+
+문서가 보여 줄 이점:
+
+- 공개 독자가 “가입 후 바로 대화까지”의 경로를 이해할 수 있다.
+- 테스트 참여자가 참여 키 구조와 현재 범위를 과장 없이 파악할 수 있다.
+
+### 3. `CONVERSATION_AND_MESSAGE_MODEL.md`
+
+핵심 섹션:
+
+- Conversation, Message, ConversationMember의 역할
+- 가입 직후 self conversation을 만드는 이유
+- 메시지 정렬, 읽음 커서, pinned/unread 상태
+- 계약 모델과 UI 표시 모델이 어떻게 이어지는지
+- 이후 확장 지점: 파일, 링크, 반응, 검색 인덱스
+
+소스 근거:
+
+- `src/PhysOn.Domain/Conversations/Conversation.cs`
+- `src/PhysOn.Domain/Messages/Message.cs`
+- `src/PhysOn.Contracts/Conversations/ConversationContracts.cs`
+- `src/PhysOn.Application/Services/MessengerApplicationService.cs`
+
+문서가 보여 줄 이점:
+
+- KoTalk가 단순 채팅 껍데기가 아니라, 실제 메시지 도메인 규칙을 갖고 있다는 점
+- 기여자가 상태 모델을 잘못 건드리지 않게 해 준다는 점
+
+### 4. `REALTIME_SYNC_AND_CLIENT_STATE.md`
+
+핵심 섹션:
+
+- bootstrap -> realtime ticket -> WebSocket 연결
+- 실시간 이벤트 계약과 클라이언트 반영 방식
+- 웹 세션 저장과 세션 복구
+- 데스크톱 레이아웃/작업 상태 저장
+- 재연결과 실패 복구에서 기대하는 현재 동작
+
+소스 근거:
+
+- `src/PhysOn.Contracts/Realtime/RealtimeContracts.cs`
+- `src/PhysOn.Api/Endpoints/MessengerEndpoints.cs`
+- `src/PhysOn.Web/src/lib/api.ts`
+- `src/PhysOn.Web/src/lib/storage.ts`
+- `src/PhysOn.Web/src/App.tsx`
+- `src/PhysOn.Desktop/ViewModels/MainWindowViewModel.cs`
+- `src/PhysOn.Desktop/Services/WorkspaceLayoutStore.cs`
+
+문서가 보여 줄 이점:
+
+- “다시 열었을 때 이어진다”는 체감이 어떤 구조에서 나오는지 설명 가능하다.
+- QA가 세션/실시간 이슈를 추적할 때 기준 문서가 생긴다.
+
+### 5. `CLIENT_SURFACES_DESKTOP_AND_WEB.md`
+
+핵심 섹션:
+
+- Desktop와 Web의 역할 차이
+- Desktop의 멀티 윈도우와 폭 저장
+- Web의 모바일형 정보 위계와 단일 전환 구조
+- 두 표면이 공유하는 개념: conversations, messages, bootstrap, reconnect
+- 현재 UX 한계와 리팩터링 방향
+
+소스 근거:
+
+- `src/PhysOn.Desktop/Views/MainWindow.axaml`
+- `src/PhysOn.Desktop/Views/ConversationWindow.axaml`
+- `src/PhysOn.Desktop/ViewModels/MainWindowViewModel.cs`
+- `src/PhysOn.Web/src/App.tsx`
+- `src/PhysOn.Web/src/App.css`
+
+문서가 보여 줄 이점:
+
+- 독자가 “왜 데스크톱과 웹이 동시에 존재하는가”를 납득할 수 있다.
+- 공개 스크린샷이 단순한 이미지 모음이 아니라 표면 전략으로 읽힌다.
+
+## 권장 공개 순서
+
+1. `TECHNICAL_ARCHITECTURE.md`
+2. `AUTH_AND_BOOTSTRAP_FLOW.md`
+3. `CONVERSATION_AND_MESSAGE_MODEL.md`
+4. `REALTIME_SYNC_AND_CLIENT_STATE.md`
+5. `CLIENT_SURFACES_DESKTOP_AND_WEB.md`
+
+## 공개 문장 원칙
+
+써야 하는 표현:
+
+- `현재 구현 기준`
+- `알파 단계에서 실제 작동하는 흐름`
+- `이 저장소에서 확인 가능한 구조`
+
+피해야 하는 표현:
+
+- `완성형 차세대 메신저`
+- `카카오톡 완전 대체`
+- `엔터프라이즈급 플랫폼 완성`
+
+## 바로 연결할 공개 표면
+
+- `README.md`에는 기술 문서군의 첫 진입점만 둔다.
+- `PROJECT_STATUS.md`에는 기술 문서로 이어지는 링크만 둔다.
+- 세부 문서는 `문서/` 아래에서 단계적으로 확장한다.

문서/116-public-security-profile-plan.md

@@ -0,0 +1,242 @@
+# 공개 보안 문서 프로파일 기획
+
+이 문서는 공개 레포에 도입할 `보안 관련 문서군`의 설계안이다.
+
+핵심 원칙은 명확하다.
+
+- 보안 문서는 슬로건이 아니라 `이미 코드에 들어간 통제`를 설명해야 한다.
+- `지금 되는 것`, `제한된 것`, `향후 계획`을 같은 문단에 섞지 않는다.
+- “안전하다”보다 “무엇을 했고, 무엇을 아직 하지 않았는가”를 분명히 적는다.
+
+## 현재 코드 기준 보안 주장선
+
+공개 문서는 아래 수준까지만 주장한다.
+
+| 영역 | 현재 코드에서 말할 수 있는 것 | 아직 말하면 안 되는 것 | 근거 파일 |
+|---|---|---|---|
+| 자체 구축 / 내부망 | `자체 호스팅과 내부망 전용 배포가 가능하도록 설계된 구조` | `기관망 즉시 적합`, `공공기관 수준 검증 완료` | `deploy/compose.mvp.yml`, `deploy/Caddyfile` |
+| 세션 / 토큰 | `짧은 수명 access token`, `회전형 refresh token`, `서버의 세션 재검증` | `device binding 완성`, `zero trust 완비` | `src/PhysOn.Infrastructure/ServiceCollectionExtensions.cs`, `src/PhysOn.Infrastructure/Auth/JwtTokenService.cs`, `src/PhysOn.Api/Endpoints/MessengerEndpoints.cs` |
+| 참여 키 흐름 | `알파 단계의 제한된 참여 키 기반 온보딩` | `정식 신원 검증`, `abuse 방어 완비` | `src/PhysOn.Application/Services/MessengerApplicationService.cs`, `src/PhysOn.Infrastructure/Persistence/DatabaseInitializer.cs` |
+| 릴리즈 무결성 | `공식 다운로드 경로와 SHA-256 체크섬 제공` | `공급망 보안 완결`, `signed build 완비` | `scripts/release/release-prepare-assets.sh`, `scripts/release/release-upload-assets.sh` |
+| 전송 계층 | `TLS 기반 공식 운영 경로`, `기본 보안 헤더`, `wss 문맥 보정` | `모든 고급 네트워크 공격 방어` | `deploy/Caddyfile`, `src/PhysOn.Mobile.Android/AndroidManifest.xml`, `src/PhysOn.Web/src/lib/realtime.ts` |
+| 비밀값 처리 | `env 기반 비밀값 주입`, `운영 기본 키 차단`, `Windows DPAPI 보호` | `중앙 secret manager 완비`, `키 회전 체계 완비` | `deploy/.env.example`, `src/PhysOn.Infrastructure/ServiceCollectionExtensions.cs`, `src/PhysOn.Desktop/Services/SessionStore.cs` |
+| 클라이언트 신뢰 경계 | `웹/데스크톱/Android가 서로 다른 저장 경계를 가진다` | `모든 클라이언트가 동일한 보안 수준` | `src/PhysOn.Web/src/lib/storage.ts`, `src/PhysOn.Desktop/Services/SessionStore.cs`, `src/PhysOn.Mobile.Android/MainActivity.cs` |
+
+## 공개 보안 문서군의 기본 구조
+
+| 프로파일 | 공개 문서 후보 | 주 독자 | 핵심 목적 |
+|---|---|---|---|
+| 보안 개요 | `SECURITY_OVERVIEW.md` | 모든 공개 독자 | 현재 보안 자세와 허용 가능한 주장선 설명 |
+| 운영 프로파일 | `SECURITY_PROFILES.md` | 인프라 담당자, 기관/사내 검토자 | 공개 배포 / 자체 구축 / 내부망 / 로컬 개발을 구분 |
+| 세션/인증 모델 | `AUTH_AND_SESSION_MODEL.md` | 백엔드, QA, 기술 검토자 | 참여 키, 토큰, 세션, realtime ticket 흐름 설명 |
+| 전송/릴리즈 신뢰 | `TRANSPORT_AND_RELEASE_TRUST.md` | 다운로드 사용자, 운영자 | TLS, 헤더, 공식 다운로드, 체크섬 설명 |
+| 클라이언트 신뢰 경계 | `CLIENT_TRUST_BOUNDARY.md` | 사용자, 평론가, 보안 검토자 | 웹/데스크톱/Android의 보호 경계 차이를 설명 |
+| 적용된 통제 | `APPLIED_SECURITY_CONTROLS.md` | 일반 사용자, 기술 검토자 | 현재 코드에 실제로 들어간 보안 통제를 설명 |
+| 위협 모델 | `SECURITY_THREAT_MODEL.md` | 보안 담당자, 기술 도입 검토자 | 자산, 공격면, 완화 조치를 구조적으로 설명 |
+| 운영 보안 | `SECURITY_OPERATING_PRACTICE.md` | 운영자, 기관/사내 검토자 | 키, 토큰, 배포, 로그, 사고 대응 원칙 설명 |
+| 자체 구축/내부망 | `SELF_HOSTING_AND_INTERNAL_NETWORK_PROFILE.md` | 인프라 담당자, 기관 검토자 | SaaS 외 운영 가능성과 현재 한계 설명 |
+| 프라이버시/데이터 | `PRIVACY_AND_DATA_HANDLING_PROFILE.md` | 일반 사용자, 평론가 | 무엇이 서버에 있고, 무엇이 로컬에 있는지 설명 |
+| 릴리즈 무결성 | `RELEASE_INTEGRITY_AND_TRANSPARENCY.md` | 다운로드 사용자, 오픈소스 기여자 | 태그, 자산, 체크섬, 미러 구조 설명 |
+| 한계 문서 | `SECURITY_LIMITS_AND_OPEN_GAPS.md` | 모든 공개 독자 | 아직 아닌 것과 향후 과제를 정직하게 분리 |
+
+## 프로파일별 설계
+
+### 0. 보안 개요
+
+핵심 메시지:
+
+- KoTalk의 공개 보안 문서는 `무엇을 이미 구현했는지`, `무엇을 아직 주장하지 않는지`, `어디까지가 운영자 책임인지`를 먼저 보여 줘야 한다.
+
+소스 근거:
+
+- `src/PhysOn.Api`
+- `src/PhysOn.Infrastructure`
+- `deploy/`
+- `scripts/release/`
+
+반드시 포함할 축:
+
+- Scope And Security Posture
+- What KoTalk Implements Today
+- What Is Explicitly Not Claimed Yet
+- Current Security Boundaries
+- Reporting A Vulnerability
+
+### 1. 적용된 통제
+
+핵심 메시지:
+
+- KoTalk는 알파 기준에서도 `JWT 서명 검증`, `세션 활성 검증`, `인증/실시간 rate limit`, `민감 응답 no-store`, `로컬 세션 보호` 같은 통제를 코드에 갖고 있다.
+
+소스 근거:
+
+- `src/PhysOn.Infrastructure/ServiceCollectionExtensions.cs`
+- `src/PhysOn.Api/Program.cs`
+- `src/PhysOn.Api/Endpoints/MessengerEndpoints.cs`
+- `src/PhysOn.Desktop/Services/SessionStore.cs`
+- `tests/PhysOn.Api.IntegrationTests/VerticalSliceTests.cs`
+
+공개 문장에서 금지할 표현:
+
+- `군사급 보안`
+- `정보유출 불가능`
+- `기관 등급 충족`
+- `완전한 종단간 암호화`
+
+### 2. 위협 모델
+
+핵심 메시지:
+
+- 자산은 `세션`, `토큰`, `메시지`, `invite`, `릴리즈 산출물`, `운영 비밀값`으로 나뉘고, 각 자산의 공격면과 완화 조치가 다르다.
+
+다뤄야 할 공격면:
+
+- invite 남용
+- refresh token 탈취
+- WebSocket misuse
+- 다운로드 미러 위조
+- 운영 환경의 비밀값 누출
+- 클라이언트 로컬 세션 탈취
+
+공개 문장에서 금지할 표현:
+
+- `완전한 위협 차단`
+- `모든 공격 시나리오 대응 완료`
+
+### 3. 운영 보안
+
+핵심 메시지:
+
+- KoTalk는 운영 환경에서 `환경변수 기반 비밀값`, `키 교체 가능성`, `세션/토큰 분리`, `릴리즈 체크섬` 같은 운영 원칙을 요구한다.
+
+다뤄야 할 항목:
+
+- JWT issuer/audience/signing key
+- bootstrap invite seed
+- 비밀값을 공개 문서에 두지 않는 기준
+- 취약점 제보와 사고 대응 흐름
+- 로그에 메시지 본문을 기본값으로 남기지 않는 원칙
+
+소스 근거:
+
+- `deploy/compose.mvp.yml`
+- `deploy/.env.example`
+- `src/PhysOn.Api/appsettings.json`
+- `src/PhysOn.Api/appsettings.Development.json`
+
+### 4. 자체 구축 / 내부망
+
+핵심 메시지:
+
+- 현재 KoTalk는 `단일 API + reverse proxy + 환경변수 + 파일 기반 DB` 구조로 작동하는 작은 배포 단위를 갖고 있어 내부망 PoC나 자체 운영 검토에 유리하다.
+
+반드시 같이 적을 제한:
+
+- 현재는 SQLite 단일 노드 MVP
+- 기관망/폐쇄망 검증 완료 상태는 아님
+- 대규모 HA/DR, 다중 리전 같은 운영 수준은 아직 문서화 단계가 아님
+
+소스 근거:
+
+- `deploy/compose.mvp.yml`
+- `src/PhysOn.Api/Program.cs`
+- `src/PhysOn.Infrastructure/Persistence/VsMessengerDbContext.cs`
+
+### 5. 프라이버시 / 데이터 처리
+
+핵심 메시지:
+
+- 지금 단계의 KoTalk는 무엇을 수집하고 어디에 저장하는지 설명 가능한 작은 표면을 갖고 있다.
+
+반드시 포함할 문장:
+
+- 현재는 E2EE가 아니다.
+- 서버 저장 구조가 존재한다.
+- 운영자가 책임지는 영역이 있다.
+- Windows 로컬 세션 저장과 웹 세션 저장의 경계가 다르다.
+
+소스 근거:
+
+- `src/PhysOn.Application/Services/MessengerApplicationService.cs`
+- `src/PhysOn.Desktop/Services/SessionStore.cs`
+- `src/PhysOn.Web/src/lib/storage.ts`
+- `src/PhysOn.Mobile.Android/MainActivity.cs`
+
+금지할 표현:
+
+- `추적하지 않는다` 단정
+- `메타데이터를 남기지 않는다`
+- `프라이버시 완전 보호`
+
+### 6. 릴리즈 무결성과 운영 투명성
+
+핵심 메시지:
+
+- 릴리즈는 `버전`, `자산`, `체크섬`, `다운로드 미러`, `릴리즈 노트` 기준으로 추적 가능해야 한다.
+
+소스 근거:
+
+- `scripts/release/release-prepare-assets.sh`
+- `scripts/release/release-publish-forge.sh`
+- `scripts/release/release-publish-github.sh`
+- `release-assets/`
+- `artifacts/builds/`
+
+금지할 표현:
+
+- `공급망 공격 차단 완료`
+- `릴리즈 무결성 완전 보장`
+
+### 7. 한계와 열린 과제
+
+핵심 메시지:
+
+- KoTalk는 지금 어디까지 구현됐고, 무엇은 아직 아니다.
+
+반드시 적어야 할 현재 갭:
+
+- Android는 현재 WebView 셸
+- 가입은 아직 참여 키 기반 alpha flow
+- 단일 DB / 단일 API MVP
+- E2EE 미구현
+- 기관 운영 검증 미완료
+
+## 기존 공개 문서와의 연결
+
+- `SECURITY.md`는 계속 허브 문서로 유지한다.
+- `TRUST_CENTER.md`는 요약/표면 문서로 두고, 세부 보안 프로파일 문서로 분기시킨다.
+- `PRIVACY_AND_DATA_HANDLING.md`가 이미 있다면, 새 프로파일 문서와 역할을 분리한다.
+- `RELEASING.md`는 릴리즈 무결성 문서와 상호 링크한다.
+- `DEVELOPMENT.md`는 테스트 참여 키, 로컬 운영, 비밀값 주입 관련 링크만 남기고 세부 보안 설명은 새 문서군으로 보낸다.
+
+## 공개 편집 원칙
+
+써야 하는 표현:
+
+- `현재 구현 기준`
+- `알파 단계에서 실제 적용된 통제`
+- `운영 환경에서는 ...를 요구`
+- `이 저장소에서 확인 가능한 근거`
+
+피해야 하는 표현:
+
+- `근본적으로 해결했다`
+- `완벽히 안전하다`
+- `완전한 탈중앙화`
+- `기관 수준 보안 충족`
+- `카카오톡 대체 완성`
+
+## 우선 공개 순서
+
+1. `SECURITY_OVERVIEW.md`
+2. `AUTH_AND_SESSION_MODEL.md`
+3. `TRANSPORT_AND_RELEASE_TRUST.md`
+4. `CLIENT_TRUST_BOUNDARY.md`
+5. `SECURITY_PROFILES.md`
+6. `APPLIED_SECURITY_CONTROLS.md`
+7. `SECURITY_THREAT_MODEL.md`
+8. `SECURITY_OPERATING_PRACTICE.md`
+9. `SELF_HOSTING_AND_INTERNAL_NETWORK_PROFILE.md`
+10. `PRIVACY_AND_DATA_HANDLING_PROFILE.md`
+11. `RELEASE_INTEGRITY_AND_TRANSPARENCY.md`
+12. `SECURITY_LIMITS_AND_OPEN_GAPS.md`

문서/117-public-doc-surface-and-link-plan.md

@@ -0,0 +1,129 @@
+# 공개 문서 표면 및 링크 체인 기획
+
+이 문서는 공개 레포에 기술/보안 문서를 넣을 때 독자가 길을 잃지 않도록 문서 표면을 어떻게 재배치할지 정리한다.
+
+## 기본 정보구조
+
+공개 표면의 기본 축은 아래 다섯 개다.
+
+- `README.md`: 첫 진입
+- `PROJECT_STATUS.md`: 현재 상태
+- `SECURITY.md`: 보안 허브
+- `DEVELOPMENT.md`: 개발 허브
+- `RELEASING.md`: 릴리즈 허브
+
+여기에 새 문서군을 추가한다.
+
+- 기술 문서군
+  - `문서/TECHNICAL_ARCHITECTURE.md`
+  - `문서/AUTH_AND_BOOTSTRAP_FLOW.md`
+  - `문서/CONVERSATION_AND_MESSAGE_MODEL.md`
+  - `문서/REALTIME_SYNC_AND_CLIENT_STATE.md`
+  - `문서/CLIENT_SURFACES_DESKTOP_AND_WEB.md`
+- 보안 문서군
+  - `문서/APPLIED_SECURITY_CONTROLS.md`
+  - `문서/SECURITY_THREAT_MODEL.md`
+  - `문서/SECURITY_OPERATING_PRACTICE.md`
+  - `문서/SELF_HOSTING_AND_INTERNAL_NETWORK_PROFILE.md`
+  - `문서/PRIVACY_AND_DATA_HANDLING_PROFILE.md`
+  - `문서/RELEASE_INTEGRITY_AND_TRANSPARENCY.md`
+  - `문서/SECURITY_LIMITS_AND_OPEN_GAPS.md`
+
+## README 상단에 고정할 링크 체인
+
+상단 문서 지도에는 아래 다섯 개를 먼저 둔다.
+
+- `프로젝트 한눈에 보기` -> `PROJECT_STATUS.md`
+- `보안이 먼저다` -> `SECURITY.md`
+- `기술/로직 상세보기` -> `문서/TECHNICAL_ARCHITECTURE.md`
+- `로컬 실행/개발` -> `DEVELOPMENT.md`
+- `배포 최신 정책` -> `RELEASING.md`
+
+그 아래 “심화 읽기” 구역에서 두 갈래로 나눈다.
+
+- 기술 갈래
+  - `TECHNICAL_ARCHITECTURE.md`
+  - `AUTH_AND_BOOTSTRAP_FLOW.md`
+  - `CONVERSATION_AND_MESSAGE_MODEL.md`
+  - `REALTIME_SYNC_AND_CLIENT_STATE.md`
+  - `CLIENT_SURFACES_DESKTOP_AND_WEB.md`
+- 보안 갈래
+  - `APPLIED_SECURITY_CONTROLS.md`
+  - `SECURITY_THREAT_MODEL.md`
+  - `SECURITY_OPERATING_PRACTICE.md`
+  - `SELF_HOSTING_AND_INTERNAL_NETWORK_PROFILE.md`
+  - `SECURITY_LIMITS_AND_OPEN_GAPS.md`
+
+## 기존 문서에 넣을 역링크
+
+### `PROJECT_STATUS.md`
+
+- 상태표 아래에 `기술/보안 상세 읽기` 소제목 추가
+- `기술 구현 흐름` -> `문서/AUTH_AND_BOOTSTRAP_FLOW.md`
+- `실시간과 복구` -> `문서/REALTIME_SYNC_AND_CLIENT_STATE.md`
+- `현재 보안 한계` -> `문서/SECURITY_LIMITS_AND_OPEN_GAPS.md`
+
+### `SECURITY.md`
+
+- `빠른 이동` 섹션 추가
+- `적용된 통제` -> `문서/APPLIED_SECURITY_CONTROLS.md`
+- `위협 모델` -> `문서/SECURITY_THREAT_MODEL.md`
+- `운영 보안` -> `문서/SECURITY_OPERATING_PRACTICE.md`
+- `릴리즈 검증` -> `문서/RELEASE_INTEGRITY_AND_TRANSPARENCY.md`
+
+### `DEVELOPMENT.md`
+
+- `관련 로직 문서` 섹션 추가
+- `가입/세션` -> `문서/AUTH_AND_BOOTSTRAP_FLOW.md`
+- `실시간/상태 저장` -> `문서/REALTIME_SYNC_AND_CLIENT_STATE.md`
+- `임시 테스트 참여키 운용` -> `문서/SECURITY_OPERATING_PRACTICE.md`
+
+### `RELEASING.md`
+
+- `릴리즈 검증 읽기` 섹션 추가
+- `릴리즈 무결성` -> `문서/RELEASE_INTEGRITY_AND_TRANSPARENCY.md`
+- `현재 상태` -> `PROJECT_STATUS.md`
+- `보안 운영` -> `문서/SECURITY_OPERATING_PRACTICE.md`
+
+## 독자별 읽기 순서
+
+일반 공개 독자:
+
+1. `README.md`
+2. `PROJECT_STATUS.md`
+3. `SECURITY.md`
+4. `RELEASING.md`
+
+기여자:
+
+1. `README.md`
+2. `DEVELOPMENT.md`
+3. `문서/TECHNICAL_ARCHITECTURE.md`
+4. `문서/REALTIME_SYNC_AND_CLIENT_STATE.md`
+
+보안/기관 검토자:
+
+1. `SECURITY.md`
+2. `문서/APPLIED_SECURITY_CONTROLS.md`
+3. `문서/SECURITY_THREAT_MODEL.md`
+4. `문서/SECURITY_OPERATING_PRACTICE.md`
+5. `PROJECT_STATUS.md`
+
+## 링크 규칙
+
+- 공개 문서는 상대경로를 우선한다.
+- 같은 문서에 링크를 과하게 나열하지 않는다. `관련 문서`는 3개 정도로 제한한다.
+- `README.md`에서는 절대 URL보다 repo-relative 링크를 우선 사용한다.
+- 기술 문서와 보안 문서는 서로 링크하되, 역할이 겹치지 않게 한다.
+
+## 공개 표면에서 피할 것
+
+- 내부 전략 메모 성격의 문장
+- 비밀값, 실제 운영 참여키, 관리자 주소
+- “완벽”, “근본적 해결”, “기관급 충족” 같은 단정형 표현
+
+## 바로 다음 단계
+
+- 기획 문서를 먼저 `문서/`에 정리
+- 이후 공개 문서 초안을 루트 문서와 `문서/`에 나눠 도입
+- README / SECURITY / DEVELOPMENT / RELEASING 역링크까지 함께 정리

문서/118-public-technical-security-doc-roadmap.md

@@ -0,0 +1,89 @@
+# 공개 기술·보안 문서 도입 로드맵
+
+이 문서는 공개 레포에 기술/보안 문서를 실제로 도입할 때의 순서를 정리한다.
+
+핵심 기준은 세 가지다.
+
+- 이미 코드에서 증명 가능한 항목부터 공개한다.
+- 보안 문서는 미사여구보다 경계와 제한을 먼저 밝힌다.
+- README와 상태 문서가 새 문서군으로 자연스럽게 연결돼야 한다.
+
+## 1단계: 바로 공개 가능한 문서
+
+현재 소스 기준으로 근거가 충분한 문서들이다.
+
+- `문서/TECHNICAL_ARCHITECTURE.md`
+- `문서/AUTH_AND_BOOTSTRAP_FLOW.md`
+- `문서/CONVERSATION_AND_MESSAGE_MODEL.md`
+- `문서/APPLIED_SECURITY_CONTROLS.md`
+- `문서/SECURITY_THREAT_MODEL.md`
+
+이 단계의 목적:
+
+- 구조와 흐름을 먼저 공개한다.
+- “이미 있는 것”을 바탕으로 신뢰를 만든다.
+
+## 2단계: 운영/배포 문서 확장
+
+현재 스크립트와 배포 구조를 근거로 쓸 수 있는 문서들이다.
+
+- `문서/REALTIME_SYNC_AND_CLIENT_STATE.md`
+- `문서/SECURITY_OPERATING_PRACTICE.md`
+- `문서/RELEASE_INTEGRITY_AND_TRANSPARENCY.md`
+- `문서/SELF_HOSTING_AND_INTERNAL_NETWORK_PROFILE.md`
+
+이 단계의 목적:
+
+- 운영자와 기술 검토자가 “어떻게 띄우고, 어떻게 검증하는지”를 볼 수 있게 한다.
+
+## 3단계: 제한과 장기 계획 분리
+
+과장 방지를 위해 별도로 두어야 하는 문서들이다.
+
+- `문서/CLIENT_SURFACES_DESKTOP_AND_WEB.md`
+- `문서/PRIVACY_AND_DATA_HANDLING_PROFILE.md`
+- `문서/SECURITY_LIMITS_AND_OPEN_GAPS.md`
+
+이 단계의 목적:
+
+- 사용자 체감 이점과 현재 한계를 같은 저장소 안에서 정직하게 보여 준다.
+
+## 문서별 독자 매핑
+
+| 문서군 | 주 독자 | 저장소에서 얻는 가치 |
+|---|---|---|
+| 기술 개요 | 기여자, 기술 평가자 | 구조와 책임 경계를 빠르게 파악 |
+| 가입/세션/실시간 | QA, 프런트엔드, 백엔드 | 실제 로직 흐름을 코드와 연결해 이해 |
+| 적용된 통제 / 위협 모델 | 보안 검토자, 기관/사내 검토자 | 과장 없이 현재 통제를 확인 |
+| 운영 / 릴리즈 / 자체 구축 | 운영자, 인프라 담당자 | 배포 가능성과 검증 가능성을 읽음 |
+| 한계 / 프라이버시 | 일반 독자, 평론가 | 무엇이 아직 아닌지 명확히 확인 |
+
+## 공개 문장 기준
+
+반드시 넣을 문장:
+
+- `현재 구현 기준`
+- `이 저장소에서 확인 가능한 근거`
+- `알파 단계에서 실제 적용된 통제`
+- `운영 환경에서는 별도 보강이 필요`
+
+반드시 피할 문장:
+
+- `근본적으로 해결`
+- `완전한 대체`
+- `완벽한 보안`
+- `기관망 검증 완료`
+- `E2EE 수준 보호`
+
+## README와 함께 바꿔야 할 부분
+
+- 문서 지도 섹션에 기술/보안 상세 문서 진입점 추가
+- `Security And Trust` 섹션을 실제 세부 문서군으로 확장
+- `Reading Paths`를 독자별로 다시 나누기
+
+## 완료 판단 기준
+
+- README에서 기술/보안 문서 진입점이 보인다.
+- 기술 문서가 소스 근거를 최소 3개 이상 갖는다.
+- 보안 문서가 허용 가능한 주장과 금지 표현을 함께 적는다.
+- `현재 구현`과 `향후 계획`이 같은 문단에서 섞이지 않는다.

문서/README.md

@@ -38,3 +38,10 @@
 - 이 폴더가 최종 기획 기준이다.
 - `docs/`는 공개 보조 문서와 시각 자산을 다룬다.
 - 소스 네임스페이스와 프로젝트 파일명 정렬은 별도 구현 작업에서 진행한다.
+
+## 공개 문서 기획
+
+- [115-public-technical-profile-plan.md](115-public-technical-profile-plan.md)
+- [116-public-security-profile-plan.md](116-public-security-profile-plan.md)
+- [117-public-doc-surface-and-link-plan.md](117-public-doc-surface-and-link-plan.md)
+- [118-public-technical-security-doc-roadmap.md](118-public-technical-security-doc-roadmap.md)