diff --git a/.gitignore b/.gitignore index ba4cec2..fc91269 100644 --- a/.gitignore +++ b/.gitignore @@ -9,3 +9,4 @@ *.pem *.key .DS_Store +.mockups/ diff --git a/docs/design/sync.md b/docs/design/sync.md new file mode 100644 index 0000000..8fa7f1a --- /dev/null +++ b/docs/design/sync.md @@ -0,0 +1,328 @@ +# `kc sync` 설계 (초안 v0.4, 2026-10-13) + +상태: 사용자 검토 대기. 구현 전. +근거: Opus 설계안과 codex(gpt-6-astra) 설계안을 서로 보여 주지 않고 따로 받아 종합했다(v0.1). 이후 logi(1pass.dev) 레포 점검 결과와 codex 공격자 관점 리뷰(P1 9건·P2 6건)를 반영했다(v0.2). v0.2 재리뷰의 새 P1 4건과 부분 해결 항목을 반영했다(v0.3). v0.3 재리뷰(13건 중 10건 해결)에서 나온 착수 전 고정 계약 5개를 §12 로 정했다(v0.4). + +## 0. 확정된 사용자 결정 + +| 결정 | 내용 | +|---|---| +| D1 | kc 에 `sync` 기능을 만든다(일회성 이동이 아니라 상시 동기화) | +| D2 | 동기화 대상은 사람이 목록에서 고른다. 기본은 아무것도 동기화하지 않는다 | +| D3 | 중요한 작업은 사람 승인이 필요하다. 승인 창구는 1pass.dev(logi)다 | +| D4 | 1pass.dev 는 승인을 **전달만** 한다. 승인의 증거는 서명이고, 각 kc 기기가 직접 검증한다 | +| D5 | logi 가 보류해 둔 "기기 서명 영수증"(내용에 묶인 기기 서명)을 kc 를 계기로 시작한다 | +| D6 | logi 에는 kc 전용 승인 도메인을 새로 만든다(관례 D2). 부품은 에이전트 승인 게이트에서 가져온다 | +| D7 | TOTP 는 kc 승인 경로에 넣지 않는다. 1pass.dev 계정 로그인 2단계 인증으로만 남긴다(logi 소관) | +| D8 | 휴대폰이 없을 때는 FIDO2 보안 키(YubiKey 등)로 승인한다. 서버 없이 kc 가 직접 검증한다 | +| D9 | 휴대폰 승인 서명은 logi 패스키가 아니라 **logi 앱의 기기 고정 키**로 한다(§3.4, 2026-10-13 확정). logi 패스키는 여러 기기에 동기화되고 RP ID 를 웹과 공유해서, 장악된 1pass.dev 가 "로그인" 화면으로 위장해 승인 서명을 받아 낼 수 있다 | +| D10 | 구현은 v0.3 을 한 번 더 리뷰해 남은 부분 해결 항목을 닫은 뒤 시작한다 | + +## 1. 요약 + +- 기존 "기억된 기기" 인박스 위에 얹는다. **중계 서버(kc-relay)는 바꾸지 않는다.** +- 항목마다 직접 넣는(opt-in) 동기화다. 다른 기기가 보낸 새 항목도 **받는 기기에서 사람이 확인해야** 대상이 된다. +- 기존 값을 덮어쓰는 원격 변경은 **사람 승인 서명이 붙어 있고, 그 서명이 지금 내 값을 정확히 대체한다고 적고 있을 때만** 자동 적용한다. 그 밖에는 보류하거나 충돌로 둔다. +- 값 삭제는 다른 기기로 전파하지 않는다. 충돌은 자동으로 풀지 않고 모든 후보 값을 보존한다. +- 원격 덮어쓰기 전에 **복구 기준점**(사람이 마지막으로 확인한 값)을 따로 보존한다. 사람이 확인하기 전에는 지워지지 않는다. + +## 2. 동기화 모델 + +### 2.1 동기화 대상(sync set) +- 대상 목록은 기기마다 따로 둔다(`sync.json`). 목록 자체는 동기화하지 않는다. +- `kc sync add NAME`(L) 은 이 기기의 대상에 넣고, 다른 기기에는 **제안**을 보낸다. 받는 쪽은 값이 같든 다르든, 그 이름이 있든 없든 **제안함에만** 넣는다. `kc sync review`(L)에서 받아들여야 대상이 되고 값이 쓰인다. + - v0.1 은 "없으면 자동 생성·같으면 자동 가입"이었다. 공격 기기가 자기가 아는 값으로 등록시킨 뒤 피해 기기가 나중에 바꾼 비밀을 받아 가는 경로가 되어 없앴다(codex P1-1). +- 받아들일 때 그 이름을 **어느 기기들과** 동기화할지(기기별 범위)를 함께 정한다. 기본은 제안을 보낸 기기 하나다. +- `kc sync rm NAME` 뒤에는 그 이름의 **등록 세대**를 올린다. 이전 세대로 온 늦은 제안·변경은 무시한다(지연된 add 로 다시 등록되는 것을 막음). +- `kc sync add --from-keychain` 은 OS 키체인 항목 목록(서비스·계정 이름만, 값은 읽지 않음)을 체크리스트로 보여 주고, 고른 것만 `adopt` 해서 대상에 넣는다. 대화형으로만 한다. +- 200 KiB 를 넘는 항목은 대상에 넣지 않는다. 메시지는 **실제 직렬화 크기**로 묶어 256 KiB 를 넘지 않게 한다. 큰 항목 분할 전송은 나중 단계(§8 Phase 4). + +### 2.2 버전과 순서 +- 항목 상태 = `{head: vid(16바이트 무작위), lineage(최근 vid 64개), vid별 값 지문}`. 값 지문 = `HMAC(sys:sync-key, 이름‖종류‖값)` 이고 키는 이 기기 키체인에만 있다. 지문은 값이 같은지 비교하는 데만 쓰고 밖으로 보내지 않는다. +- **vid 는 불변이다.** 같은 vid 로 다른 값이 오면 프로토콜 위반으로 보고, 그 기기에서 온 해당 항목의 흐름을 격리한다(codex P2-10). +- 원격 변경 판정(순수 함수 `decide`): + 1. 받은 vid = 내 head → 무시(값 지문이 다르면 위반) + 2. 받은 vid 가 내 lineage 에 있음 → 낡은 변경, 무시 + 3. **승인 서명이 "parent = 내 head" 를 정확히 적고 있음** → 앞으로 감기. 한도 검사 뒤 적용 + 4. 값이 같음(지문 일치) → 수렴. 두 기기 모두 `head = max(vid_a, vid_b)`, lineage 는 합집합으로 같은 결과를 낸다. 쓰기는 없다 + 5. 그 밖 → 충돌 +- v0.1 은 보낸 쪽이 주장하는 lineage 만 보고 앞으로 감기를 허용했다. 뚫린 기기가 lineage 에 내 head 를 끼워 넣으면 충돌이 덮어쓰기로 바뀐다(codex P1-4). v0.2 에서는 **승인 서명에 묶인 parent 만** 믿고, lineage 는 낡은 변경을 거르는 데만 쓴다. 승인이 없거나 parent 가 내 head 와 다르면 충돌 또는 보류다. +- 기각한 방식: 시각 기준 마지막 쓰기 우선(시계 조작에 약함), 버전 벡터(codex v0.1 안; 빠진 이력을 원작자에게 받아 와야 해서 복잡함). + +### 2.3 로컬 쓰기와 원격 적용의 경쟁 +- 모든 쓰기(로컬 `kc set`·`restore`·`adopt`, 원격 적용, 충돌 해결)는 **같은 잠금(items)** 안에서 한다. 잠금 순서: `items` → `sync.json` → `seen.json`. +- 원격 적용 직전, 잠금 안에서 현재 값 지문과 head 를 **다시 확인**한다. 스캔 뒤 다른 프로세스가 `kc set` 을 했으면 원격 변경은 충돌로 바뀐다(codex P1-6). +- 쓰기 순서: ① 의도 기록(journal) → ② 키체인 쓰기 → ③ `sync.json`(head·lineage·큐·승인 소비) 갱신 → ④ journal 정리. 시작할 때 남은 journal 이 있으면 현재 값 지문으로 ②가 끝났는지 판정해 ③을 마저 하거나 되돌린다. 기존 인박스 journal(`crates/kc-cli/src/commands/inbox.rs:157`)을 확장한다. +- 한계(문서에 명시): kc 밖에서 키체인 값을 `A→B→A` 로 바꾸고 그 사이에 sync 가 돌지 않으면 감지하지 못한다. + +### 2.4 충돌 +- 모든 후보 값(2개 이상일 수 있음)을 내부 슬롯에 보존한다. 그 항목은 **일반 변경 적용만** 멈추고, 해결(resolve) 메시지와 다른 기기의 충돌 후보는 계속 받는다(codex P2-11). +- `kc sync status` 는 값 대신 지문과 기기 이름을 보여 준다. +- `kc sync resolve NAME --keep mine|LABEL`(L + A): 결과는 새 vid 이고 승인 서명의 parent 목록에 **알려진 모든 후보 head** 를 적는다. 받는 쪽은 **자기가 알고 있는 모든 미해결 후보 head(자기 head 포함)가 그 목록에 다 들어 있을 때만** 받아들인다. 하나라도 빠졌으면 충돌로 남긴다(v0.2 재리뷰 P1). 해결 메시지를 적용하는 일은 원자적이다. +- lineage 합집합이 64개를 넘으면 오래된 것부터 자른다. 잘림 순서는 각 vid 를 처음 본 시각이 아니라 **vid 값 오름차순**으로 정해 모든 기기가 같은 결과를 낸다. +- vid 의 parent 도 불변이다. 같은 vid 로 다른 parent 를 주장하면 위반이다. + +### 2.5 삭제 +- 동기화 대상에 `kc rm` 을 하면 거부한다("`kc sync rm NAME` 먼저"). +- `kc sync rm NAME` 은 이 기기의 대상에서만 빼고 등록 세대를 올린다. +- `kc sync rm NAME --everywhere`(A+) 는 다른 기기에서도 대상에서만 빼고 **값은 남긴다**. +- 값 삭제 전파는 지원하지 않는다. + +### 2.6 복구 기준점 +- v0.1 의 "`#prev` 에 항상 공격 전 값이 남는다"는 틀렸다. `#prev` 는 한 단계뿐이라 24시간 간격의 두 번 덮어쓰기면 원래 값이 사라진다(codex P1-9). +- 원격 덮어쓰기를 처음 적용하기 전에 그때 값을 **복구 기준점** 슬롯(`sync/kg/<이름 해시>`)에 복사한다. 이후 원격 덮어쓰기는 이 슬롯을 바꾸지 않는다. +- 사람이 `kc sync status` 나 `review` 에서 "현재 값 확인"(L)을 하면 그 값이 새 기준점이 된다. `kc sync restore-checkpoint NAME` 으로 되돌린다. +- 보류·충돌·기준점·보낼 값 스냅샷 슬롯의 총량에 상한을 둔다(기본 대상 항목 수 × 4). 기준점 슬롯은 **원격 쓰기 전에 먼저 확보**한다. 확보하지 못하면 원격 변경을 적용하지 않고 보류한다. 상한에 닿으면 새 제안·보류를 받지 않고 status 에 표시한다. + +### 2.7 실행 시점 +1. `kc sync`: 로컬 스캔 → 인박스 받기·적용 → 보낼 것 보내기 → 요약(digest) 교환 +2. `kc set`·`restore`·`adopt` 직후: 대상 항목이면 바로 보내기를 시도하고, 실패하면 큐에 남긴다. +3. `kc sync install [--every 15m]`: macOS LaunchAgent(서명된 릴리스 바이너리 경로 고정) / Linux systemd `--user` 타이머 / Windows 작업 스케줄러 "로그온한 경우에만"(로그온 없는 모드 금지). +- 상주 long-poll 은 하지 않는다(15분 주기 = 시간당 4회, 같은 IP 시간당 120회 한도에 여유). + +### 2.8 전달 확인과 재동기화 +- 받는 기기는 변경을 적용(또는 보류·충돌로 기록)하고 **저장이 끝난 뒤에만** 영수증(ACK)을 보낸 기기에 돌려준다. 이미 처리한 변경이 다시 오면 ACK 만 다시 보낸다(ACK 유실 대비). 보낸 기기는 그 기기의 ACK 를 받을 때까지 그 변경을 큐에 둔다(codex P2-12). +- 보낸 기기는 ACK 를 기다리는 동안 보낸 값 스냅샷을 키체인 내부 슬롯에 보관한다. 그 사이 새 로컬 변경이 생기면 새 변경이 이전 것을 대체하고, 받는 쪽이 중간 변경을 건너뛰어도 parent 가 맞지 않으면 충돌·digest 재요청으로 이어진다. +- 하루 한 번 digest 로 서로의 head 를 비교하고, 상대가 뒤처졌으면 최신 값을 **새 승인과 함께** 다시 보낸다(옛 승인은 만료됐을 수 있음). +- 인박스 메시지가 72시간 만료로 사라졌거나, 30일 미접속으로 인박스가 사라졌으면 다음 sync 에서 digest 로 감지해 다시 보낸다. 인박스 재연결이 필요하면 status 에 표시한다. +- 각 기기는 **자기 변경만** 보낸다(남의 변경을 중계하지 않음). 그래서 변경을 만든 기기가 영영 사라지면, 그 변경을 받지 못한 기기는 사람이 남은 사본을 새 변경으로 다시 보내야 한다. 이 한계를 status 에 표시한다. + +## 3. 사람 승인 + +### 3.1 두 층 +| 층 | 수단 | 막는 것 | +|---|---|---| +| L: 로컬 확인 | Touch ID · Windows Hello · Linux polkit | 같은 기기에서 kc 를 부르는 **에이전트**(터미널 판별은 PTY 로 우회되지만 지문은 우회 못 한다) | +| A: 서명 승인 | logi 앱 기기 고정 키 · FIDO2 보안 키 | **뚫린 기기 한 대**. 다른 기기들이 서명을 직접 검증한다 | +| A+: 강한 서명 승인 | **logi 앱 기기 고정 키만** (자체 화면에서 문서를 보여 주고 서명) | 신뢰 루트를 바꾸거나 여러 기기에 영향이 큰 작업 | + +- 일반 FIDO2 보안 키는 **A 등급까지만** 인정한다. 보안 키에는 자체 화면이 없어, 뚫린 컴퓨터가 다른 문서를 서명시켜도 사용자가 알 수 없다(v0.2 재리뷰 P1). A+ 작업은 휴대폰 승인을 기다린다. +- 기기 하드웨어 키(device-uv, v0.1 의 A 수단)는 **기본으로 쓰지 않는다**(codex P1-7). 어떤 키가 정말 하드웨어에 묶여 매번 생체 인증을 거치는지 받는 기기가 검증할 방법(키 증명)을 명세하기 전까지는, 소프트웨어 키를 등록한 뚫린 기기가 승인을 스스로 만들어 낼 수 있다. 나중 단계에서 키 증명과 함께 다시 검토한다. + +### 3.2 작업별 요구 수준 +| 작업 | 보내는 기기 | 받는 기기 | +|---|---|---| +| `sync add`·`rm`(이 기기만), `sync peer add`·`rm` | L | — | +| 받은 제안 받아들이기(`review`) | — | L | +| **기존 값 덮어쓰기**(set 뒤 sync, resolve) | A 요청 | **A**(parent 일치), 없으면 보류 | +| `sync rm --everywhere` | A+ 요청 | **A+**, 없으면 보류 | +| 보류분 직접 승인(`review`), `unfreeze`, 기준점 확인 | — | L | +| 새 기기 페어링 | L(양쪽) + 기존 코드·확인 단어 | — | +| `device rotate`, `sync install`, `approver enroll` | L | — | +| 승인자 추가 | L + 기존 승인자의 A+ | 각 기기에서 L 로 지문 확인 후 고정 | +| 승인자 제거 | L | — (마지막 승인자를 지우면 덮어쓰기는 전부 보류. 새 등록은 각 기기 L 확인 필요) | + +**기존 명령도 같은 규칙을 따른다**(codex P1-8). 동기화 대상 항목을 `kc inbox --on-conflict overwrite`·`kc receive`·v1 인박스 메시지로 덮어쓰려 하면 sync 정책으로 보낸다. 승인 서명이 없으면 L 이 필요하고, 비대화형이면 보류한다. + +에이전트는 L·A·A+ 어느 것도 통과하지 못한다. 할 수 있는 최대치는 승인 요청을 올리는 것과 제안을 보내는 것이다. + +### 3.3 승인 문서 +서명 대상은 `SHA-256("kc1 approval" ‖ 작업 종류 ‖ 문서)` 이다. **작업마다 구조체를 따로 둔다**(codex P1-3). +```text +ValueChange { v, origin_fp, doc_id(16바이트 무작위), created_at, expires_at(≤7일), agent_origin, + entries: [{ name, kind, new_vid, parents: [vid…], targets: [{ target_fp, generation, c }] }] } + c = HMAC(HKDF(X25519(origin_sk, target_pk), "kc1 commit"), name ‖ kind ‖ new_vid ‖ generation ‖ 값)[..16] +Retire { v, origin_fp, doc_id, created_at, expires_at, entries: [{ name, head_vid, generation }], + targets: [fp…] } +ApproverAdd { v, origin_fp, doc_id, created_at, expires_at, + new_approver: { kind, sign_public_key, enc_public_key?, key_id, platform }, + policy: { grade: A|A+, accept_for: [작업 종류…] }, approver_generation } +``` +- 받는 기기마다 **그 기기의 등록 세대(generation)** 까지 묶는다. 제거·재등록 뒤에는 아직 쓰지 않은 옛 승인이 새 세대로 둔갑하지 못한다(v0.2 재리뷰 P1). +- 값과 parent 까지 묶는다: 승인 뒤 보내는 기기가 값만 바꾸거나, 다른 head 를 대체하는 변경으로 쓰지 못한다. 커밋 키는 기존 기기 키로 기기 쌍마다 만든다. 1pass.dev 는 c 를 계산하거나 값을 맞춰 볼 수 없다. +- 짧은 코드: 문서 해시 앞 4바이트를 단어 4개로 바꿔 터미널과 휴대폰에 함께 보여 준다. +- 한 번의 sync 에서 대기 중인 변경을 문서 하나로 묶는다(승인 피로 감소). + +**받는 기기의 검증**: 보낸 기기와 `origin_fp` 일치 → 자기 몫 `c` 재계산 일치 → 항목·parent·종류 일치 → 유효 기간 확인 → 서명 검증 → 서명 수단이 작업 등급에 맞는지 확인. + +**문서 고정**: `doc_id` 는 처음 본 문서 해시에 고정된다. 같은 `doc_id` 로 다른 문서가 오면 위반이다. 한 문서 안에서 같은 이름이 두 번 나오면 문서 전체를 거부한다. + +**승인 소비**(codex P1-5): `(doc_id, 항목, 받는 기기)` 단위로 적용 기록을 남긴다. 한 문서의 항목 일부만 적용된 상태를 허용하고, 다시 시도할 때 남은 항목만 적용한다. 순서가 뒤바뀌어 도착한 승인도 받아들인다(최고 seq 하나만 기억하는 방식은 쓰지 않음). 거절·폐기한 문서는 만료 시각까지 기록해 둔다. + +### 3.4 휴대폰 승인: logi 앱의 기기 고정 키 +- **왜 패스키가 아닌가**(codex P1-2): logi 패스키는 RP ID `api.1pass.dev` 를 웹과 공유하고 여러 기기에 동기화된다(BE=1). 장악된 1pass.dev 는 웹 페이지나 앱의 로그인 응답에 kc 승인 해시를 challenge 로 넣어, 사용자가 "로그인"이라고 생각하고 생체 인증을 하게 만들 수 있다(로그인 경로는 서버 옵션을 그대로 서명 함수에 넘긴다, `toy/logi/Packages/LogiCore/Sources/LogiCore/Auth/SessionStore.swift:372`). 서명할 credential 을 고르는 `allowCredentials` 도 서버가 정한다. WebAuthn 생체 인증은 "사람이 있다"를 증명할 뿐 "이 내용을 봤다"를 증명하지 않는다. +- **대신**: logi 앱이 kc 승인 전용 키 쌍을 기기 안에서 만든다. + - iOS: Secure Enclave P-256, 접근 제어 `biometryCurrentSet`, 동기화·내보내기 불가. 이미 있는 `DpopSigner`(Secure Enclave 서명)를 본뜬다. + - Android: StrongBox(없으면 TEE) Keystore 키, 사용자 인증 필요. + - **서명할 때마다** 생체 인증을 요구한다(재사용 창 없음). 하드웨어 키를 만들 수 없는 기기에서는 등록을 거부한다(소프트웨어 키로 내려가지 않음). + - 기존 DPoP 서명 코드는 그대로 쓰지 않는다. iOS 는 생체 게이트 없이 소프트웨어 폴백을 허용하고(`toy/logi/Packages/LogiCore/Sources/LogiCore/Auth/DpopSigner.swift:143`), Android 는 사용자 인증을 끈다(`toy/logi/android/core/data/src/main/java/com/dcodelabs/logi/core/data/DpopSigner.kt:99`). 키 생성 방식만 참고한다. + - 이 키는 **앱의 kc 승인 화면에서만** 쓴다. 웹은 닿을 수 없고, 앱의 다른 화면(로그인 등)은 이 키를 쓰는 코드 경로가 없다. + - 앱이 승인 문서를 **직접 해석해서 화면에 그리고**, 그 문서의 해시에 서명한다. 서버가 보낸 표시 문구는 쓰지 않는다. +- **이름도 숨긴다**: 앱 키 쌍과 함께 암호화용 키(X25519)도 만든다. kc 는 승인 문서를 이 키로 암호화해 보내므로 1pass.dev 는 암호문과 짧은 코드만 본다(codex P2-15 의 이름 노출 문제 해결). `approval_display = "counts"` 설정은 필요 없어진다. +- **키 고정**: `kc approver enroll` 때 앱 공개키 두 개(서명·암호화)를 **함께** kc 가 받아 지문을 단어 4개로 보여 주고, 앱 화면에도 같은 단어를 띄운다. 각 kc 기기에서 사람이 대조해야 고정된다(L). +- **키 증명(선택)**: iOS App Attest·Android Key Attestation 으로 "정품 logi 앱의 하드웨어 키"임을 확인할 수 있다. 1단계에서는 지문 대조만 하고, 키 증명은 열린 문제로 둔다. +- 휴대폰 분실: 다른 기기에서 `kc approver rm`(L) 후 새 휴대폰으로 다시 등록한다. 키가 동기화되지 않으므로 새 휴대폰은 새 키다. + +### 3.5 FIDO2 보안 키(D8) +- libfido2(macOS·Linux)·`webauthn.dll`(Windows)로 kc 가 직접 서명을 받는다. 서버가 필요 없다. +- RP ID 는 **웹 도메인이 아닌 문자열**(`kc-approval`)을 쓴다. 브라우저는 자기 도메인이 아닌 RP ID 를 요청할 수 없으므로, 웹 페이지가 이 credential 로 서명을 받아 낼 수 없다. +- 받는 기기는 등록 때 고정한 공개키로 type·challenge·rpIdHash·UP·UV·알고리즘을 모두 검증한다. origin 은 kc 가 만든 고정 값과 비교한다. +- 한계: 꽂혀 있는 키를 악성 코드가 사용자를 속여 터치하게 만들 수 있다. 짧은 코드 대조가 완화책이다. + +### 3.6 1pass.dev(logi)에 새로 필요한 것 +logi 점검 결과(`scratchpad/logi-survey.md`)를 근거로, kc 전용 승인 도메인(D6)에 다음을 둔다. +1. kc 기기 연결: CLI 기기 코드 로그인을 그대로 쓴다. 이후 요청 인증은 **kc 가 직접 만든 Ed25519 키의 공개키만 등록**하는 새 API 로 한다. 기존 `AgentRegistration` 은 서버가 개인키를 만들어 내려주므로(`toy/logi/server/app/models/agent_registration.rb:234`) 그대로 쓰지 않는다(codex P2-14). 발급·교체·폐기 API 가 필요하다. +2. 승인자 등록: logi 앱이 기기 고정 키 쌍을 만들고 공개키를 kc 에 전달하는 흐름. 서버는 공개키를 **가공 없이** 중계한다. +3. 승인 요청: kc 가 올린 암호문·짧은 코드·만료 시각을 저장하고 앱에 푸시(기존 `PushNotifier`). 앱이 서명을 올리면 kc 가 long-poll 로 가져간다. 서버는 서명을 검증하지 않아도 되고, 검증해도 kc 는 그 결과를 쓰지 않는다. +4. 남용 방어: 에이전트 승인 게이트의 진행 중 요청 억제·거절 쿨다운·차단을 가져다 쓴다. 기기당 대기 요청 3건 상한. +5. 앱: kc 승인 화면(문서 복호화·해석·표시·서명), 키 생성·지문 표시, 승인자 재등록. +- **서버가 저장하는 것**: 계정↔kc 기기 연결(요청 서명 공개키 포함), 승인자 공개키, 승인 요청 암호문(처리 뒤 7일 안에 삭제), 푸시 구독. +- **서버가 볼 수 없는 것**: 값, 항목 이름, 값 지문, 기기 개인키, 인박스 토큰, 커밋 키. +- 패스키 관련 변경(무작위 challenge 대체, 공개키 노출)은 **필요 없어진다.** logi 의 "RP 에 패스키 공개키를 주지 않는다" 결정도 그대로 둔다. +- logi 보류 항목(R6 기기 서명 영수증)은 "패스키 challenge 유도" 대신 "앱 기기 고정 키 서명"으로 시작한다. logi 문서에 이 차이를 남긴다. + +### 3.7 백그라운드·에이전트 실행 +- 대화형 `kc set` 의 변경은 그 자리에서 승인을 요청한다. +- 비대화형 변경은 "승인 대기"로 두고 요청만 올린다. 7일 안에 승인이 없으면 요청만 만료되고 로컬 값은 남는다. +- 받는 기기는 승인이 없으면 보류하고, 승인이 나중에 오면 다시 평가한다. `kc sync review`(L)로 직접 승인할 수도 있다. + +### 3.8 승인 수단을 못 쓸 때 +- 휴대폰이 꺼져 있거나 1pass.dev 에 닿지 못하면 FIDO2 보안 키를 쓴다. 둘 다 없으면 큐에서 기다리고, 받는 기기에서 `review`(L)로 직접 승인할 수 있다. +- 승인자가 하나도 없으면 덮어쓰기는 모두 받는 기기의 `review` 대상이다. 제안·새 항목은 그대로 동작한다. + +## 4. 피해 범위 제한(승인이 있어도 유지) +- 항목별: 비대화형 원격 덮어쓰기는 24시간에 1회. 그 이상은 보류. +- 기기별 차단기: 24시간 안에 덮어쓰기 5건 초과, 또는 retire 3건 초과면 그 기기가 보낸 나머지를 모두 보류한다. "대상의 25% 초과" 조건은 대상이 8개 이상일 때만 쓴다(작은 집합에서 한 항목만 바뀌어도 걸리는 문제, codex P2-15). +- 재전송: 기존 메시지 id 기록과 72시간 만료, lineage 의 낡은 vid 무시, 승인 소비 기록. +- 뚫렸을 때: 다른 기기에서 `kc sync freeze`(비대화형 가능) → 기기마다 `kc peers rm LABEL` → `kc sync restore-checkpoint`. `peers rm` 은 전파하지 않는다. + +## 5. 프로토콜 +- 인박스 **바깥 봉투 버전을 2로** 올린다. v0.2 kc 는 바깥 봉투 버전을 복호화 전에 검사해(`crates/kc-proto/src/inbox.rs:329`) "지원하지 않는 버전"으로 인박스에 남겨 두고 72시간 뒤 만료된다(codex P2-13 확인). +```text +InboxPlain2 { v:2, msg_id, sender_fp, recipient_fp, created_at, expires_at, body } +body = Items(...) | Sync { kind: Hello | Offer | Accept | Leave | Changes | Ack | Digest | Approvals } +Change { name, generation, new_vid, parents: [vid…], lineage(≤64), op: Put{value,kind} | Retire, approval_ref? } +``` +- `Change.parents` 는 보낸 기기가 주장하는 직접 parent 목록이다(해결 메시지면 모든 후보 head). 승인이 붙은 변경은 `parents` 가 승인 문서의 parents 와 **정확히 같아야** 한다(다르면 거부). 승인이 없는 parents 는 보류와 충돌 중 어디로 보낼지만 정하고, 어느 쪽이든 사람이 본다. 그래서 위조해도 자동 적용으로 이어지지 않는다. +- 상대의 v2 지원 여부를 모르면 **Hello 한 통만** 보낸다. Hello 는 기능 목록만 담고 받는 쪽 상태를 바꾸지 않는 무해한 메시지다. v0.2 기기에서는 72시간 뒤 만료되는 낭비 1통으로 끝난다. Hello 응답을 받기 전에는 다른 sync 메시지를 보내지 않고 보류한다(v0.2 재리뷰 P1: 확인 전 금지 규칙이 Hello 까지 막아 교착되던 문제). **sync 변경을 v1 Items 로 낮춰 보내지 않는다.** 일반 `send --to` 는 지금처럼 v1 이다. +- `kc inbox` 와 `kc sync` 는 같은 인박스 처리 루프를 쓰고 내용 종류로 나눈다. +- `docs/PROTOCOL.md` §4(v2)·§6(sync·L/A/A+ 행)·§9(승인자로 일원화)와 `docs/SECURITY.md`(1pass.dev 신뢰 경계, 등록 시점 한계, 원작자 소실 한계)를 함께 고친다. + +## 6. 명령 +```text +kc sync 스캔→받기→보내기. "3 sent, 2 updated, 1 conflict, 1 awaiting approval" +kc sync status [--json] 항목별 상태와 기기별 마지막 요약 +kc sync add [NAMES…] [--peers a,b] [--from-keychain] +kc sync rm NAMES [--everywhere] +kc sync peer add|rm|list LABEL +kc sync review 받은 제안·보류분을 하나씩 받아들이기·거절 +kc sync resolve NAME --keep mine|LABEL +kc sync restore-checkpoint NAME +kc sync approve 대기 중인 승인 요청 상태 확인·재요청 +kc sync freeze | unfreeze +kc sync install [--every 15m] | uninstall +kc approver enroll [--fido2] | list | rm ID +``` +종료 코드: 0 = 완전히 맞음, 8 = 충돌·보류·승인 대기·제안, 4 = 키체인, 5 = 사람 필요, 6 = 중계 서버. + +## 7. 저장 위치 +- `config.toml [sync]`: 사람이 고치는 값만(`interval`, `max_remote_overwrites`, `max_proposals_per_day`, `approver_url`). +- `sync.json`: 기기 상태, 항목별 head·lineage·등록 세대·범위, 보낼 큐와 ACK 상태, 제안·보류·충돌 목록, 승인자 공개키, 승인 소비 기록, journal. **값과 값 지문은 넣지 않는다.** +- 키체인 내부 슬롯: 보류·충돌 후보 값, 복구 기준점, 보낼 값 스냅샷(보낼 때 값이 바뀌지 않게), vid별 값 지문, `sys:sync-key`(지문 HMAC 키), `sys:logi-token`, `sys:logi-request-key`(Ed25519). +- `sync.log`: 이름과 결과만, 값은 기록하지 않는다. 1 MiB 에서 교체. + +## 8. 단계 +| 단계 | 내용 | 다른 레포 | +|---|---|---| +| 0 | 인박스 v2(바깥 봉투 버전 2, **v1 과 같은 바깥 배치를 고정**하고 AAD·분기 규칙 명세), 골든 벡터, v0.2↔v2 호환 시험, 인박스 루프 공용화 | — | +| 1 | `sync.json`, add·제안·review·rm·peer·status·수동 sync, `decide`, 잠금·journal, 충돌·resolve, 복구 기준점, 한도·차단기·freeze, ACK·digest·세대 교환, 기존 명령의 sync 정책 적용, **로컬 확인(L)**. 원격 덮어쓰기는 전부 review 보류(§12.5) | — | +| 1b | 승인 문서 3종, FIDO2 검증기, 승인 소비 기록, 보류 재평가, 승인 붙은 덮어쓰기 자동 적용 켜기 | — | +| 2 | `install`(3 OS), `--from-keychain`, doctor 연동 | — | +| 2b | 1pass.dev 연동(기기 연결·요청 키, 앱 기기 고정 키 승인자, 암호화 승인 요청, 푸시, 앱 승인 화면) | **logi**(서버·iOS·Android) | +| 3 | 네이티브 위치 반영(기기별 선택, 기존 항목 갱신만, 대화형만) | — | +| 4 | 200 KiB 넘는 항목 분할 전송, device-uv 키 증명 재검토 | — | + +1·1b 만으로도 FIDO2 보안 키로 쓸 수 있다. 1pass.dev 연동(2b)은 logi 쪽 작업과 병행한다. + +## 9. 시험 +- `decide` 표 시험: 앞으로 감기(parent 일치만), 낡은 변경, 같은 vid 다른 값(위반), 수렴(양쪽 같은 head), 충돌, lineage 위조(parent 불일치 → 충돌), 잘림 경계. +- 경쟁 시험: 스캔 뒤 로컬 `kc set` 과 원격 적용이 겹칠 때 충돌로 바뀌는지, ②와 ③ 사이에서 죽은 뒤 복구. +- 결정적 시뮬레이션: 메모리 중계 위에 가상 기기 3~4대, 수정·전달·유실·순서 뒤바뀜·오프라인·72시간 만료를 무작위로 섞는다. 불변식: ACK 가 다 오면 모두 같은 값이거나 충돌 표시 / 동시 수정이 조용히 덮이는 경우 0 / 원격 메시지로 값이 지워지는 경우 0 / 복구 기준점이 사람 확인 없이 바뀌는 경우 0. +- 보안 시험: 원격 제안이 review 없이 대상이 되는 경우 0, 승인 없는 덮어쓰기 보류, `inbox --on-conflict overwrite`·`receive` 로 대상 항목 덮어쓰기 시 정책 적용, 승인 문서 종류 혼동(ValueChange 서명을 Retire 로) 거부, 부분 적용 뒤 재시도, 역순 승인 수용, 에이전트 실행에서 L·A·A+ 경로는 exit 5 또는 보류. +- 서버 단독 장악 시뮬레이션: 가짜 1pass.dev 가 임의 문서 서명 요청·서명 재사용·승인자 바꿔치기·로그인 위장을 해도 적용 0건. +- 실기기: logi 앱 Secure Enclave·StrongBox 키 생성과 서명, FIDO2 보안 키(USB) 3 OS. + +## 10. 열린 문제 +1. 키 증명(App Attest·Key Attestation)을 1단계부터 넣을지. +2. 로컬 스캔 비용(144개 전부 읽기) 실측. +3. 같은 이름이 기기마다 다른 의미일 때: 제안 review 화면에 양쪽 지문과 출처를 함께 보여 준다. +4. 네이티브 위치 반영(Phase 3)은 앱이 스스로 갱신하는 토큰을 덮어 세션을 깰 수 있어, 기존 항목 갱신만·대화형에서만 한다. +5. 승인자를 여러 명(휴대폰 + 보안 키) 둘 때 A 는 하나면 된다. A+ 는 휴대폰 승인이 필수다. 보안 키를 추가로 요구할지는 열려 있다. +6. 휴대폰 키 증명 없이 지문 대조만으로 "정품 logi 앱의 하드웨어 키"를 믿는 수준이 충분한지(열린 문제 1 과 연결). + +## 11. 화면 결정 (2026-10-13 시안 확정) +시안(검토 후 삭제)에서 받은 사용자 선택: + +| 화면 | 선택 | 내용 | +|---|---|---| +| logi 앱 승인 화면 | A · 바로 승인 | 짧은 코드 4단어를 보여 주고 바로 Face ID 승인 버튼. 코드 맞히기 단계는 두지 않는다 | +| kc 터미널 대기 | B · 항목·대안 함께 | 항목·대상 기기·코드를 함께 보여 주고, 휴대폰이 없을 때 보안 키(A 등급까지)·Ctrl-C 후 7일 유지를 안내 | +| 동기화 항목 고르기 | A · 묶음 목록 | 이름 앞부분으로 묶은 체크리스트(펼치기). 기본 선택 = 권장 분류 | + +- 승인 화면 A 를 고르면서 "사용자가 시작하지 않은 요청" 방어는 짧은 코드 **눈 대조**에 기댄다(B 의 맞히기 단계 없음). 2차 방어선(§4 한도·차단기·복구 기준점)은 그대로다. +- 초기 동기화 대상 목록은 개인 정보라 레포에 두지 않는다. 사용자 기기의 kc 설정 폴더 `sync-initial-set.toml` 에 있고, `kc sync add --from-keychain` 이 이 목록을 미리 체크해 보여 준다. + +## 12. 구현 착수 전 고정 계약 (v0.4) +v0.3 재리뷰가 "지금 정하지 않으면 다시 짜야 한다"고 꼽은 5개다. + +### 12.1 인박스 v2 형식 +- 바깥 봉투 필드와 순서는 v1 과 같다(`v, suite, sender_fp, recipient_fp, enc, ct`). `v = 2` 만 다르다. 지금 코드는 봉투 전체를 decode 한 뒤 버전을 보므로(`crates/kc-proto/src/inbox.rs:328`) **배치를 바꾸면 v0.2 가 Malformed 로 지운다.** 배치는 바꾸지 않는다. +- AAD 는 v1 과 똑같이 `postcard(v, suite, sender_fp, recipient_fp)` 다(`crates/kc-proto/src/inbox.rs:182`). `enc`·`ct` 는 넣지 않는다. HPKE info 는 `"kc2 inbox" ‖ sender_fp ‖ recipient_fp`. +- 안쪽 `InboxPlain2.v` 는 바깥 `v` 와 같아야 한다. 다르면 거부한다. +- 내용 종류는 `body` 열거형의 판별자로 나눈다. Phase 0 에서 골든 벡터로 고정한다. +- **변경 식별자** `change_id = (name, generation, new_vid)`. ACK 는 `[(change_id, 결과)]` 를 담는다. 결과 = `applied | held | conflict | stale_generation | deferred_capacity | rejected`. + +### 12.2 등록 세대 교환 +- 세대는 **받는 기기가** 정하고 보낸 기기에 알려 준다. +- `Offer{name}` → 받는 쪽이 review 에서 받아들이면 `Accept{name, generation}` 을 보낸다. 보낸 기기는 기기별로 그 세대를 기록하고, 그 뒤 변경에 이 세대를 넣는다. +- 받는 쪽에서 `sync rm` 하면 세대를 올리고 `Leave{name, generation}` 을 보낸다. 다시 넣으려면 새 Offer → 새 Accept 다. +- 세대가 맞지 않는 변경은 적용하지 않고 `stale_generation` ACK 를 돌려준다. 보낸 기기는 그 기기에 대한 큐 항목을 지우고 status 에 "다시 제안 필요"로 표시한다. +- 기기별 범위 변경(`--peers`)도 Offer·Leave 로 표현한다. + +### 12.3 ACK 와 보관·용량 +- 보낸 기기는 대상 기기 **전부**가 그 `change_id` 에 **확정 결과**(`applied | held | conflict | stale_generation | rejected`)를 ACK 하면 보낸 값 스냅샷을 지운다. `deferred_capacity` 는 확정 결과가 아니다. 스냅샷과 큐 항목을 그대로 두고 다음 digest 뒤 다시 보낸다. 같은 이름의 더 새 변경이 ACK 되면 이전 것도 지운다. ACK 는 `change_id` 가 정확히 같은 큐 항목만 지운다(옛 ACK 가 새 항목을 지우지 않음). +- 받는 기기의 보류·충돌 후보 슬롯은 해결·거절할 때 지운다. 복구 기준점은 사람이 확인할 때만 바뀐다. +- 슬롯 총량 상한 = `max(16, 대상 항목 수 × 4)`. 대상이 0개여도 첫 제안을 받을 수 있다. +- 보존 우선순위: 복구 기준점 > 충돌 후보 > 보류 값 > 제안. 상한에 닿으면 새 제안·보류를 받지 않고 `deferred_capacity` ACK 를 보낸다(보낸 쪽은 다음 digest 뒤 다시 보냄). 기준점은 절대 밀어내지 않는다. + +### 12.4 journal 복구 단위 +- 원격 적용 한 건 = 한 트랜잭션: ① journal 에 **적용 의도 레코드 전체**를 기록 — `change_id`, 보낸 기기, 이전 지문, 예정 지문, 적용 뒤 head·lineage, 소비할 승인 키, 보낼 ACK 결과, 확보할 기준점·후보 슬롯 이름. 예정 값 자체는 ② 에서 확보하는 후보 슬롯에 먼저 넣어 둔다 → ② 기준점·후보 슬롯 확보 → ③ 키체인 쓰기 → ④ `sync.json`(head·lineage·승인 소비·보낼 ACK) 갱신 → ⑤ journal 정리. +- 재시작 때 남은 journal 이 있으면 현재 값 지문으로 판정한다. + - 예정 지문과 같음 → 레코드대로 ④부터 마저 한다. + - 이전 지문과 같음 → 쓰기가 일어나지 않았으니 journal 만 지우고 다시 시도한다. + - **둘 다 아님** → 그 사이 다른 쓰기가 있었다. 덮어쓰지 않고 충돌로 남긴다. +- ACK 는 ④가 끝난 뒤에만 보낸다. +- **로컬 변경 한 건 = 한 트랜잭션**(`kc set`·`restore`·`adopt`·스캔으로 찾은 변경): ① journal 에 로컬 변경 레코드 기록 — 이름, 이전 지문, 새 지문, 새 vid, parents, 스냅샷 슬롯 이름, 만들 큐 항목(대상 기기·세대) → ② 보낼 값 스냅샷 슬롯에 값 복사 → ③ `sync.json`(head·lineage·큐) 갱신 → ④ journal 정리. `kc set` 은 키체인 쓰기를 ① 과 ② 사이에 한다. +- 재시작 때 로컬 변경 journal 이 남아 있으면, **③ 커밋 여부는 `sync.json` 의 head 가 레코드의 새 vid 인지로 판정**한다. + +| 현재 값 지문 | ③ 커밋됨? | 처리 | +|---|---|---| +| 새 지문 | 아니오, 스냅샷 없음 | 현재 값(=새 값)을 스냅샷에 다시 복사하고 ③ → ④ | +| 새 지문 | 아니오, 스냅샷 있음 | ③ → ④ | +| 새 지문 | 예 | ④ 만 | +| 새 지문이 아님(이전 지문이든 다른 값이든) | 예 | 큐가 스냅샷을 참조하므로 **스냅샷은 남긴다**(보낸 값). journal 만 정리. 다음 스캔이 지금 값을 새 vid 로 기록한다 | +| 이전 지문 | 아니오 | 키체인 쓰기가 안 일어났다. 스냅샷이 있으면 지우고 journal 정리 | +| 이전 지문도 새 지문도 아님 | 아니오 | 스냅샷을 지우고 journal 정리. 다음 스캔이 새 vid 를 만든다 | + +(행은 "현재 값 = 새 값 여부 × 커밋 여부"의 모든 조합을 덮는다.) + +- 스냅샷 슬롯은 큐 항목이 참조하는 동안 지우지 않는다. 지우는 것은 §12.3 의 확정 ACK 때뿐이다. + +### 12.5 단계 경계와 판정 순서 +- **로컬 확인(L)을 Phase 1 로 앞당긴다.** add·review·resolve 가 L 에 의존하기 때문이다. +- Phase 1 에는 서명 승인(A)이 없다. 판정은 `Change.parents` 로 한다. 판정표는 그대로 쓰되, **7번(자동 앞으로 감기)이 Phase 1 에서는 절대 걸리지 않는다**(검증된 승인이 없으므로). 그래서 parent 가 맞는 원격 덮어쓰기는 8번(review 보류), parent 가 다르면 9번(충돌)이다. 자동 적용은 Phase 1b 부터다. +- resolve: Phase 1 에서는 보내는 기기에서 L 만 요구한다. 받는 기기는 그 해결 메시지를 승인 없는 변경으로 보고 review 에 보류한다(§2.4 의 후보 포함 검사는 그대로). Phase 1b 부터 L + A 로 올리고, 승인이 붙은 해결은 자동 적용한다. +- `decide` 는 검증기가 통과시킨 승인만 받는다(`Option`). 서명 바이트를 직접 보지 않는다. +- 판정 순서(위에서 먼저 걸리는 것이 이긴다): + +| 순서 | 조건 | 결과 | +|---|---|---| +| 1 | 세대 불일치 | 거부, `stale_generation` ACK | +| 2 | freeze 상태 | 보류 | +| 3 | 같은 vid 다른 값·다른 parent | 위반, 그 기기의 해당 항목 흐름 격리 | +| 4 | 받은 vid = 내 head 또는 lineage 안 | 무시(낡은 변경), `applied` ACK | +| 5 | 이미 충돌 중 | 후보로 추가(해결 메시지면 §2.4 규칙으로 판정) | +| 6 | 값 같음 | 수렴 | +| 7 | 검증된 승인 + parent = 내 head + 한도 안 | 앞으로 감기 | +| 8 | 승인 없음·한도 초과 + parent = 내 head | 보류(review) | +| 9 | 그 밖 | 충돌 |