🐛 [Fix] Watch 공유 Keychain Access Group entitlement 복구 (#1213)

UMCApp/Core/Network/Sources/Auth/KeychainTokenStore.swift

@@ -19,6 +19,11 @@ import Security
 ///   - **Accessibility**: `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly` 사용
 ///     (디바이스 잠금 해제 후 접근 가능, 백업·동기화 안 됨)
 ///   - **메모리 캐시**: 첫 조회 시 Keychain에서 로드 후 캐싱
+///   - **Access group**: 쿼리에 access group을 지정하지 않으므로 저장은 entitlement의
+///     첫 그룹(`$(AppIdentifierPrefix)com.umc.product.shared`)에, 조회는 앱이 가진
+///     모든 그룹을 대상으로 이뤄진다
+///   - **삭제 범위**: `clear()` 역시 access group을 지정하지 않아 앱이 가진 모든 그룹에서
+///     동일 키를 함께 제거한다
 public actor KeychainTokenStore: TokenStore {
 
     // MARK: - Property

UMCApp/UMCApp.entitlements

@@ -22,5 +22,13 @@
     <array>
         <string>group.com.umc.product.widget</string>
     </array>
+    <!-- 배열 첫 항목이 SecItemAdd 의 기본 access group 이므로 순서를 바꾸면 -->
+    <!-- 토큰 저장 위치가 달라진다. 공유 그룹명은 watch 타겟과 동일하게 유지한다 -->
+    <!-- (위젯은 Keychain 을 쓰지 않아 이 키가 없다). -->
+    <key>keychain-access-groups</key>
+    <array>
+        <string>$(AppIdentifierPrefix)com.umc.product.shared</string>
+        <string>$(AppIdentifierPrefix)com.umc.product</string>
+    </array>
 </dict>
 </plist>

UMCApp/UMCWatchApp/Project.swift

@@ -4,6 +4,7 @@ import ProjectDescriptionHelpers
 let project = watchAppProject(
     name: "UMCWatchApp",
     bundleId: "com.umc.product.watchkitapp",
+    entitlements: .file(path: "UMCWatchApp.entitlements"),
     dependencies: [
         .project(target: "CoreWatchConnectivity", path: .relativeToRoot("Core/WatchConnectivity")),
     ]

UMCApp/UMCWatchApp/UMCWatchApp.entitlements

@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- 배열 첫 항목이 SecItemAdd 의 기본 access group 이므로 순서를 바꾸면 -->
+    <!-- 토큰 저장 위치가 달라진다. 공유 그룹명은 iOS 앱 타겟과 동일하게 유지한다. -->
+    <key>keychain-access-groups</key>
+    <array>
+        <string>$(AppIdentifierPrefix)com.umc.product.shared</string>
+        <string>$(AppIdentifierPrefix)com.umc.product.watchkitapp</string>
+    </array>
+</dict>
+</plist>

docs/claude/build-and-modules.md

@@ -165,3 +165,38 @@ featureProject(
 - **Product Type**: 모든 모듈 `.staticFramework`
 - **Bundle ID**: Core → `dev.umc.core.*` / Feature → `dev.umc.feature.*.*`
 - **Workspace**: glob(`Core/*`, `Features/*`) + `UMCAppWidget`, `UMCWatchApp` 명시 포함
+
+### 공유 Keychain Access Group
+
+iOS 앱과 watchOS 앱은 로그인 토큰용 공유 그룹 `$(AppIdentifierPrefix)com.umc.product.shared` 를
+`keychain-access-groups` entitlement 의 **첫 항목**으로 선언합니다. 팀 ID(`8B8B4462NV`)를 문자열로
+박지 않고 `$(AppIdentifierPrefix)` 를 쓰는 것이 레포 관례입니다
+(`UMCApp/Core/Network/Tests/CoreNetworkTests.entitlements` 동일).
+
+| 타겟 | entitlements 파일 | 배선 위치 |
+|------|------------------|----------|
+| iOS 앱 | `UMCApp/UMCApp.entitlements:27-31` | `UMCApp/Project.swift:85` |
+| watchOS 앱 | `UMCApp/UMCWatchApp/UMCWatchApp.entitlements:7-11` | `UMCApp/UMCWatchApp/Project.swift:7` |
+
+- **배열 순서가 계약이다.** `kSecAttrAccessGroup` 을 지정하지 않은 `SecItemAdd` 는 배열 **첫 항목**에
+  저장한다. `UMCApp/Core/Network/Sources/Auth/KeychainTokenStore.swift` 는 저장(104-110행) ·
+  조회(120-126행) · 삭제(141-145행) 쿼리 어디에도 access group 을 지정하지 않으므로 이 기본값 규칙에
+  전적으로 의존한다. 그래서 공유 그룹이 첫 번째다.
+- **두 번째 항목(각 타겟 자기 App ID 그룹)은 안전장치다.** 검색·삭제는 access group 미지정 시 앱이 가진
+  모든 그룹을 대상으로 하므로, 기존 배포판이 기본 그룹(`$(AppIdentifierPrefix)com.umc.product`)에 저장해 둔
+  토큰이 계속 읽힌다. 이 줄을 빼면 업데이트 즉시 전 사용자 강제 로그아웃이다.
+- **워치는 배선까지 확인한다.** `watchAppProject(entitlements: .file(path: "UMCWatchApp.entitlements"))` 로
+  인자를 넘겨야 실제로 적용된다. 파일만 만들고 인자를 안 넘기면 무효다 — #1147 유실이 정확히 이 형태였다.
+- **watchOS 는 keychain 을 공유하지 않는다.** Apple Watch 는 자체 keychain 을 가진 별개 기기라 access
+  group 을 맞춰도 워치가 iPhone 의 항목을 읽지 못한다. access group 은 동일 기기 내 동일 팀 서명 타겟
+  (앱·확장) 간 공유 메커니즘이다. 워치 토큰은 WatchConnectivity 로 iPhone→Watch 전송 후 워치 자체
+  keychain 에 저장하는 경로이며 #1210/#1211 범위다. 또한 `KeychainTokenStore` 는
+  `kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly`(109행)라 iCloud Keychain 동기화 대상도 아니다.
+- **서명 주의**: 두 App ID(`com.umc.product` · `com.umc.product.watchkitapp`)에 Keychain Sharing
+  capability 가 없으면 실기기/아카이브 서명 단계에서 실패하고, 런타임 증상은 `SecItemAdd` 의
+  `errSecMissingEntitlement(-34018)` 다.
+
+> **유실 이력**: PR #627(`744ad80b`)이 공유 그룹(`$(AppIdentifierPrefix)dev.umc.shared`)을 추가했으나,
+> #1147(`a68f93c2`) 번들 ID 정렬 커밋이 "미사용 keychain-access-groups 제거" 사유로 iOS·watch 양쪽에서
+> 걷어냈다(워치 entitlements 는 파일째 삭제). 이미 **두 번 유실된** entitlement 다 — "미사용"으로 보여도
+> 제거하지 않는다.