Add Baron Safe Flutter 앱 추진 초안.md

2026-06-24 10:04:16 +09:00
parent 8365da06b7
commit c22fc90409
1 changed files with 337 additions and 0 deletions
--- a/초안.md
+++ b/초안.md
@@ -0,0 +1,337 @@
+# Baron Safe Flutter 앱 추진 초안
+
+작성일: 2026-06-24
+
+## 1. 목적
+
+본 문서는 기존 `Baron Safe 기반 휴대폰 승인 로그인 제안안`을 실제 앱 개발 과제로 진행하기 위한 초기 실행 초안이다.
+
+팀 회의에서 제시된 방향에 따라 Baron SSO의 기존 `userfront` 기술 기반을 활용하여, Flutter 기반 `Baron Safe` 모바일 앱을 구상한다. 이 앱은 단순 로그인 화면이 아니라, 등록된 휴대폰을 인증 장치로 사용하여 사용자가 로그인 요청을 확인하고 승인 또는 거절하는 보안 승인 앱으로 정의한다.
+
+## 2. 추진 배경
+
+현재 논의 중인 휴대전화번호 기반 로그인은 사용자 편의성은 높지만, 전화번호만으로는 실제 사용자가 해당 번호의 소유자인지, 현재 로그인 요청을 직접 승인했는지 확인하기 어렵다.
+
+이를 보완하기 위해 사용자의 휴대폰에 `Baron Safe` 앱을 설치하고, 해당 앱을 사용자 계정에 사전 등록된 인증 장치로 사용한다. 사용자는 PC, 브라우저, 키오스크 또는 RP 서비스에서 로그인 요청을 시작하고, 휴대폰 앱에서 요청 서비스, 요청 기기, 요청 시간, IP 정보를 확인한 후 승인한다.
+
+이 구조는 OpenID Connect CIBA와 유사한 Out-of-Band 인증 흐름이며, Baron SSO의 Hydra/Kratos 기반 인증 흐름과도 연결할 수 있다.
+
+## 3. 기본 방향
+
+`Baron Safe`는 Flutter 기반 설치형 모바일 앱으로 개발한다.
+
+기본 방향은 다음과 같다.
+
+- Android와 iOS를 모두 지원한다.
+- 기존 Baron `userfront`의 Flutter 기술 스택과 UI/상태관리 패턴을 최대한 재사용한다.
+- 전화번호는 인증 수단이 아니라 사용자 식별자로만 사용한다.
+- 실제 인증 근거는 등록된 앱 기기, 기기 private key, 생체 인증 또는 앱 PIN, 승인 응답 서명으로 확보한다.
+- 푸시 알림은 로그인 요청을 전달하는 채널일 뿐이며 인증 수단으로 보지 않는다.
+- 승인 요청, 승인, 거절, 만료, 실패는 모두 감사 로그로 남긴다.
+
+## 4. 대상 앱 정의
+
+앱 명칭은 가칭 `Baron Safe`로 한다.
+
+주요 역할:
+
+- 사용자 휴대폰을 Baron SSO 인증 장치로 등록
+- 로그인 승인 요청 푸시 수신
+- 로그인 요청 상세 정보 표시
+- 생체 인증 또는 앱 PIN을 통한 사용자 확인
+- 승인 또는 거절 결정
+- 기기 private key를 이용한 승인 응답 서명
+- 기기 분실, 교체, 해제 대응
+
+앱은 브라우저에서 열리는 웹앱이 아니라 휴대폰에 설치되는 모바일 앱이다. 따라서 사용자의 브라우저가 열려 있을 필요는 없다. 다만 보안상 승인 행위는 사용자가 앱을 열어 직접 수행해야 하며, 백그라운드 자동 승인은 허용하지 않는다.
+
+## 5. 지원 플랫폼 및 배포
+
+| 구분 | Android | iOS |
+| --- | --- | --- |
+| 앱 형식 | APK 또는 AAB | IPA |
+| 배포 방식 | Google Play, 사내 배포, MDM, APK 배포 검토 | TestFlight, App Store, Apple Business Manager, MDM 검토 |
+| 푸시 | Firebase Cloud Messaging | APNs, Firebase 연동 가능 |
+| 보안 저장소 | Android Keystore | iOS Keychain, Secure Enclave 검토 |
+| 사용자 확인 | 지문, 얼굴, 기기 PIN | Face ID, Touch ID, 기기 암호 |
+
+초기 PoC 단계에서는 Android 우선 검증이 현실적이다. 단, 설계와 코드 구조는 iOS 확장을 전제로 둔다.
+
+## 6. 기술 스택
+
+### 6.1 기존 userfront 기반
+
+현재 `userfront`에서 확인된 주요 기술은 다음과 같다.
+
+| 영역 | 현재 기술 |
+| --- | --- |
+| Framework | Flutter |
+| Language | Dart |
+| 상태 관리 | flutter_riverpod |
+| Routing | go_router |
+| HTTP 통신 | http |
+| 다국어 | easy_localization |
+| 로컬 설정 | shared_preferences |
+| QR/스캔 관련 | qr_flutter, mobile_scanner |
+| 이미지/SVG | flutter_svg |
+| 로깅 | logging, logger |
+
+`Baron Safe` 앱은 이 구성을 기본으로 가져가되, 모바일 인증 앱에 필요한 보안/푸시 기능을 추가한다.
+
+### 6.2 추가 검토 기술
+
+| 영역 | 권장 기술 | 용도 |
+| --- | --- | --- |
+| Push Notification | firebase_messaging, APNs 연동 | 로그인 승인 요청 알림 수신 |
+| Secure Storage | flutter_secure_storage 또는 플랫폼 Method Channel | device id, refresh token, 민감 설정 저장 |
+| Private Key Storage | Android Keystore, iOS Keychain/Secure Enclave | 승인 서명용 private key 보호 |
+| Local Authentication | local_auth | 지문, Face ID, 기기 PIN 확인 |
+| Crypto Signing | JWS/JWK 또는 COSE 지원 라이브러리, 필요 시 네이티브 연동 | 승인 응답 서명 |
+| API Client | 기존 http 유지 또는 dio 검토 | 앱-SSO API 통신 |
+| State Management | flutter_riverpod 유지 | 기기 등록, 승인 요청, 세션 상태 관리 |
+| Routing | go_router 유지 | 등록, 승인, 설정 화면 전환 |
+| Deep Link | app_links 또는 firebase_dynamic_links 대체 검토 | 푸시/QR/등록 링크 진입 |
+| App Integrity | Play Integrity API, DeviceCheck/App Attest 검토 | 위변조 앱과 위험 기기 탐지 |
+
+초기에는 기존 `userfront`와의 일관성을 위해 `flutter_riverpod`, `go_router`, `http`를 유지하는 것이 좋다. 단, 인증 앱 특성상 private key 생성/서명은 일반 secure storage만으로 끝내지 말고 Android/iOS 보안 키 저장소와 직접 연동하는 방안을 검토해야 한다.
+
+## 7. 주요 기능 범위
+
+### 7.1 1단계 PoC
+
+목표는 전체 보안 완성보다 end-to-end 승인 흐름을 검증하는 것이다.
+
+기능:
+
+- 앱 설치 및 실행
+- 사용자 로그인 또는 등록 코드 입력
+- 기기 등록 요청
+- device id 발급
+- push token 등록
+- 승인 요청 목록 조회
+- 승인 요청 상세 표시
+- 승인/거절 API 호출
+- 요청 기기 화면에서 poll 방식으로 승인 결과 확인
+
+PoC 단계에서는 기기 서명을 단순화할 수 있으나, API 구조는 향후 서명 검증을 추가할 수 있도록 설계한다.
+
+### 7.2 2단계 보안형 MVP
+
+기능:
+
+- 앱 기기 등록 시 key pair 생성
+- public key 서버 등록
+- private key는 기기 보안 저장소에 보관
+- 승인 전 생체 인증 또는 앱 PIN 수행
+- 승인 응답 payload 서명
+- 서버에서 public key로 서명 검증
+- nonce, TTL, 중복 승인 방지
+- 푸시 알림 연동
+- 승인/거절/만료 감사 로그
+- 기기 해제 및 재등록
+
+### 7.3 3단계 운영 확장
+
+기능:
+
+- 다중 기기 등록
+- 기기 분실 신고 및 관리자 강제 해제
+- RP별 인증 강도 정책
+- 고위험 로그인 경고
+- number matching 또는 request code
+- FIDO2/passkey 연계 검토
+- Play Integrity, App Attest 기반 앱 무결성 검토
+- 사내/협력사 배포 체계 정립
+
+## 8. 사용자 흐름
+
+### 8.1 최초 기기 등록
+
+1. 사용자가 기존 Baron SSO 방식으로 로그인한다.
+2. 사용자 설정 화면에서 `Baron Safe 기기 등록`을 선택한다.
+3. 서버가 등록용 QR 또는 등록 코드를 생성한다.
+4. 사용자가 `Baron Safe` 앱에서 QR 또는 코드를 입력한다.
+5. 앱이 기기 정보를 생성하고 push token을 발급받는다.
+6. 앱이 기기 key pair를 생성한다.
+7. 앱은 public key, device id, push token, platform 정보를 서버에 등록한다.
+8. 서버는 해당 기기를 사용자 계정에 연결한다.
+
+### 8.2 로그인 승인
+
+1. 사용자가 RP 또는 Baron SSO 로그인 화면에서 휴대전화번호를 입력한다.
+2. Baron SSO가 등록 사용자와 등록 기기를 조회한다.
+3. Baron SSO가 승인 요청을 생성한다.
+4. Baron SSO가 등록 기기에 푸시 알림을 발송한다.
+5. 사용자가 휴대폰에서 알림을 누르고 앱을 연다.
+6. 앱이 승인 요청 상세를 서버에서 조회한다.
+7. 사용자가 요청 서비스, 요청 기기, IP, 시간을 확인한다.
+8. 앱이 생체 인증 또는 앱 PIN을 요구한다.
+9. 사용자가 승인 또는 거절을 선택한다.
+10. 앱이 승인 응답에 서명하여 서버에 제출한다.
+11. 서버가 서명, nonce, TTL, 기기 소유관계를 검증한다.
+12. 승인 성공 시 Hydra login challenge를 accept하고 RP 로그인을 완료한다.
+
+## 9. 주요 화면 초안
+
+| 화면 | 설명 |
+| --- | --- |
+| 온보딩 화면 | Baron Safe 앱 소개 및 시작 |
+| 기기 등록 화면 | QR 스캔 또는 등록 코드 입력 |
+| 등록 완료 화면 | 등록된 사용자/기기명 표시 |
+| 승인 요청 상세 화면 | 요청 서비스, 요청 기기, IP, 시간, 만료 시간 표시 |
+| 생체 인증 확인 | 승인 전 사용자 확인 |
+| 승인 완료 화면 | 승인 결과 표시 |
+| 거절 완료 화면 | 거절 결과 표시 |
+| 요청 없음 화면 | 현재 대기 중인 승인 요청 없음 표시 |
+| 기기 설정 화면 | 기기명, 등록일, 마지막 사용 시각, 기기 해제 |
+| 보안 설정 화면 | 앱 PIN, 생체 인증 사용 여부 |
+
+## 10. Backend/API 필요 항목
+
+### 10.1 기기 등록 API
+
+```text
+POST /api/v1/baron-safe/devices/register
+```
+
+요청 항목:
+
+- registration_code 또는 registration_token
+- platform
+- device_name
+- push_token
+- public_key
+- app_version
+
+응답 항목:
+
+- device_id
+- registered_at
+- user_display_name
+
+### 10.2 승인 요청 생성 API
+
+```text
+POST /api/v1/auth/baron-safe/login/init
+```
+
+요청 항목:
+
+- phone_number
+- login_challenge
+- client_id
+
+응답 항목:
+
+- auth_req_id
+- status
+- expires_in
+- interval
+
+### 10.3 앱 승인 요청 상세 조회 API
+
+```text
+GET /api/v1/auth/baron-safe/requests/{authReqId}
+```
+
+응답 항목:
+
+- auth_req_id
+- client_id
+- client_name
+- request_device
+- request_ip_address
+- requested_at
+- expires_at
+- nonce
+
+### 10.4 앱 승인/거절 제출 API
+
+```text
+POST /api/v1/auth/baron-safe/requests/{authReqId}/decision
+```
+
+요청 항목:
+
+- device_id
+- decision
+- nonce
+- user_presence
+- user_verification
+- decided_at
+- signature
+
+### 10.5 요청 기기 Poll API
+
+```text
+POST /api/v1/auth/baron-safe/login/poll
+```
+
+응답 항목:
+
+- authorization_pending
+- approved
+- rejected
+- expired
+- redirect_to
+
+## 11. 보안 고려사항
+
+필수 사항:
+
+- 앱이 휴대폰 번호를 자동으로 가져오는 방식에 의존하지 않는다.
+- 전화번호는 사용자 식별자이며 인증 수단이 아니다.
+- private key는 서버로 전송하지 않는다.
+- 승인 응답은 기기 private key로 서명한다.
+- 승인 전 생체 인증 또는 앱 PIN을 수행한다.
+- 승인 요청은 짧은 TTL을 가진다.
+- nonce는 요청별 1회용으로 사용한다.
+- 동일 요청 중복 승인, 만료 후 승인, 다른 기기 승인은 거부한다.
+- 푸시 메시지에는 민감정보를 최소화한다.
+- 승인 요청 상세는 앱이 서버 API로 조회한다.
+- 전화번호 미등록 여부와 기기 미등록 여부가 외부에 노출되지 않도록 응답 메시지를 일반화한다.
+- 반복 승인 요청에 대한 rate limit을 적용한다.
+- 모든 승인/거절/실패 이벤트를 감사 로그로 남긴다.
+
+## 12. 개발 일정 초안
+
+| 단계 | 기간 | 산출물 |
+| --- | --- | --- |
+| 0단계 | 1주 | 상세 요구사항, 화면 흐름, API 계약 초안 |
+| 1단계 PoC | 2~3주 | Android 중심 Flutter 앱, 기기 등록 Mock, 승인 요청 조회/승인 API 연동 |
+| 2단계 MVP | 4~6주 | 푸시, 생체 인증, key pair, 서명 검증, Hydra login challenge 연동 |
+| 3단계 운영화 | 4주 이상 | iOS 검증, 배포 체계, 감사 로그, 관리자 기기 관리, 보안 강화 |
+
+## 13. 우선 결정 필요 사항
+
+1. `Baron Safe`를 기존 `userfront` 프로젝트 내부 앱 모드로 둘지, 별도 Flutter 앱 프로젝트로 분리할지 결정해야 한다.
+2. 초기 PoC 대상 플랫폼을 Android 우선으로 할지, Android/iOS 동시로 할지 결정해야 한다.
+3. 앱 배포 방식을 사내 배포, MDM, 스토어 배포 중 어떤 방식으로 가져갈지 결정해야 한다.
+4. 기기 등록 시 기존 SSO 로그인 기반으로 할지, 관리자 초대/등록 코드 기반으로 할지 결정해야 한다.
+5. 승인 응답 서명 포맷을 JWS/JWK로 할지 COSE 기반으로 할지 결정해야 한다.
+6. 앱 private key를 Flutter 플러그인으로 처리할지, Android/iOS 네이티브 Method Channel로 직접 구현할지 결정해야 한다.
+
+## 14. 권장 추진안
+
+초기에는 별도 앱 프로젝트보다는 기존 `userfront` 구조와 기술 스택을 참고하여 `baron_safe_app` 형태의 별도 Flutter 앱을 구성하는 것을 권장한다. 이유는 다음과 같다.
+
+- `userfront`는 웹/포털 성격이 강하고, `Baron Safe`는 모바일 보안 인증 앱 성격이 강하다.
+- 배포 대상, 권한, 푸시 설정, 앱 서명, 보안 저장소 설정이 다르다.
+- 향후 Android/iOS 앱스토어 또는 MDM 배포를 독립적으로 관리해야 한다.
+- 다만 UI 컴포넌트, i18n, API client, Riverpod 패턴 등은 `userfront`에서 재사용 가능한 부분을 적극 차용한다.
+
+따라서 추진 순서는 다음과 같이 잡는다.
+
+1. 기존 `userfront`의 Flutter 패턴을 기준으로 `baron_safe_app` 프로젝트 초안 작성
+2. Backend에 승인 요청 생성, poll, 앱 상세 조회, 승인/거절 API 추가
+3. Mock push 또는 수동 refresh 방식으로 PoC 완성
+4. Android FCM과 생체 인증 연동
+5. 기기 key pair와 승인 응답 서명 검증 추가
+6. iOS APNs, Keychain, Face ID 검증
+7. 운영 배포 방식 확정
+
+## 15. 결론
+
+Baron Safe 앱은 Flutter로 추진하는 것이 적절하다. 기존 Baron `userfront`가 이미 Flutter 기반이므로 개발 조직의 학습 비용을 줄일 수 있고, Android와 iOS를 하나의 코드베이스로 대응할 수 있다.
+
+다만 본 앱은 일반 화면 앱이 아니라 인증 장치 역할을 하므로, 단순 Flutter 화면 구현보다 푸시, 생체 인증, 기기 보안 저장소, private key 서명, 서버 검증, 감사 로그가 핵심이다. 따라서 PoC 단계에서는 빠르게 승인 흐름을 검증하고, MVP 단계에서 기기 서명과 보안 저장소를 반드시 포함하는 방향으로 추진하는 것이 바람직하다.