# Milestone: macOS 배포와 sandbox 검증

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/security-distribution/PHASE.md`

## 목표

AppSok을 사내 Mac에서 안정적으로 배포할 수 있도록 signing, notarization 배포 기준을 정리하고, sandbox entitlements와 bundled ADB packaging이 배포 산출물에서 유지되는지 검증한다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- SDD: 불필요 - 기존 macOS 배포 스크립트, 문서, 원격 runner 검증을 정리하는 범위이며 새 cross-repo 계약/API/schema 설계 gate가 없다.
- 잠금 해제 조건: 충족. signing/notarization/배포 자동화 기준은 원격 Mac runner evidence 기준으로 확정한다.
- 결정 필요: 없음
- 확정:
  - [x] 사용자 표시명은 `AppSok`으로 통일하고, URL scheme/package/bundle id의 소문자 `appsok` 식별자는 유지한다.
  - [x] 사내 배포 경로는 Developer ID signing과 Apple notarization 기준으로 둔다.
  - [x] AppSok 배포 signing identity는 원격 Mac runner의 `Developer ID Application: Dongmyung Lee (AWA82DP9WD)`를 사용한다.
  - [x] `notarytool`은 원격 Mac runner의 SOPS encrypted CI secret과 login Keychain에 저장된 `appsok-notary` profile을 사용한다. 비밀값은 기록하지 않는다.
  - [x] 배포 산출물은 notarized/stapled `AppSok.app`을 포함한 `AppSok-certified.zip`과 `.sha256` checksum 파일로 둔다.
  - [x] "아무 맥에서나 설치" 범위는 현재 certified build 산출물 기준 universal build(`x86_64 arm64`)로 둔다.
  - [x] sandbox는 유지한다. signed app entitlements의 `app-sandbox`와 `network.client`는 true이며, bundled `adb devices -l`은 certified app bundle resource에서 실행된다.

## 범위

- macOS app bundle metadata
- entitlement와 sandbox 검증
- network client entitlement와 bundled ADB resource packaging 검증
- bundled ADB runtime의 nested binary/dylib signing과 실행 검증
- Developer ID signing, notarization, staple, MDM 배포 후보 문서화

## 기능

### Epic: [distribution] 배포 방식

엔드유저가 경고 없이 설치하고 실행할 수 있는 사내 배포 방식을 정한다.

- [x] [bundle-id] bundle id와 앱 표시 이름 정책을 확정한다.
- [x] [signing] Developer ID signing/notarization 또는 MDM 배포 절차를 문서화한다.
- [x] [notary-profile] `notarytool` Keychain profile 존재 여부와 세팅 절차를 비밀값 없이 문서화한다.
- [x] [staple-assess] notarization 후 stapling과 `spctl --assess` 검증 절차를 문서화한다.
- [x] [arch-policy] Apple Silicon only 또는 universal build 배포 정책을 문서화한다.
- [x] [platform-tools] bundled ADB runtime의 포함 파일, version pinning, 업데이트 책임, NOTICE 보존 방식을 문서화한다.
- [x] [release-checklist] 배포 전 검증 checklist를 작성한다.

## 완료 리뷰

- 상태: 통과
- 요청일: 2026-06-17
- 완료 근거:
  - 원격 Mac runner의 current HEAD `4aaedc8`에서 `./scripts/build-certified-macos.sh`가 Flutter gate, macOS build, Developer ID signing, notarization `Accepted`, stapling, Gatekeeper assessment를 모두 통과했다.
  - certified artifact `AppSok-certified.zip`과 `.sha256`이 생성됐고, bundle metadata, signing identity, sandbox/network entitlement, bundled ADB runtime, universal binary 여부를 확인했다. 최신 checksum은 `0b379602777efcf51b662581bcbaea9d2ab7c10737cab932b1aaf614c540bc6a`다.
  - 배포 방식 Epic의 모든 기능 Task가 문서와 원격 evidence로 충족됐다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-17 22:10 UTC certified build evidence 기준으로 완료한다. 배포 산출물 사용 중 발견한 문제는 이 Milestone의 기능 Task가 아니라 별도 Milestone 또는 follow-up Task로 추가한다.

## 범위 제외

- Auth Broker 또는 Jenkins plugin 구현
- 중앙 감사 서버
- 사용자 Mac의 Android Studio 또는 Android Platform Tools 설치를 기본 전제로 삼는 배포 방식
- Windows/Linux desktop target

## 작업 컨텍스트

- 관련 경로: `macos/Runner/`, `macos/Runner.xcodeproj/`, `pubspec.yaml`
- 표준선(선택): sandbox는 가능한 유지하고, 불가능한 경우 사유와 대안을 문서화한다.
- 표준선(선택): 내부 ops 도구 기준으로 ADB는 AppSok-managed bundled runtime을 기본 제공하고, 사용자 환경의 `adb`는 override/fallback으로만 둔다.
- 검증 메모: bundled `adb`, `NOTICE.txt`, `source.properties`를 포함하고 signing/notarization 전후 실행 여부를 remote Mac runner에서 확인한다. 현 pinned `adb`는 `otool -L` 기준 비시스템 dylib 의존성이 없어 별도 `lib64/*.dylib` bundle이 필요하지 않다.
- 2026-06-17 원격 검증: `toki@toki-labs.com` checkout `4aaedc8`에서 `./scripts/build-certified-macos.sh`가 `flutter analyze`, `flutter test`, `flutter build macos`, bundled `adb` Developer ID signing, app signing, notarization `Accepted`, `stapler`, `spctl --assess`를 모두 통과했다.
- 2026-06-17 certified artifact: `build/macos/Build/Products/Release/AppSok-certified.zip`, size `23M`, sha256 `0b379602777efcf51b662581bcbaea9d2ab7c10737cab932b1aaf614c540bc6a`.
- 2026-06-17 bundle metadata: built app의 `CFBundleName=AppSok`, `CFBundleIdentifier=com.tokilabs.appsok`, URL scheme `appsok`을 확인했다.
- 2026-06-17 signing/runtime: signed app의 `TeamIdentifier=AWA82DP9WD`, authority `Developer ID Application: Dongmyung Lee (AWA82DP9WD)`, hardened runtime, entitlements `com.apple.security.app-sandbox=true`, `com.apple.security.network.client=true`를 확인했다.
- 2026-06-17 ADB runtime: certified app bundle resource의 `adb version`은 `35.0.0-11411520`, `adb devices -l`은 Android emulator를 감지했고, AppSok app binary와 bundled `adb`는 모두 `x86_64 arm64` universal binary다.
- 선행 작업: 사용 가능한 MVP
- 후속 작업: Auth Broker와 Jenkins Plugin 후보 검토
- 정리: 실제 사용자 환경에서의 앱 조작 확인은 이 Milestone의 기능 Task로 추적하지 않는다. 배포 산출물 사용 중 발견한 문제는 별도 follow-up으로 추가한다.