Update Baron Safe PWA/WebView 하이브리드 앱 추진 수정안.md

Baron Safe PWA/WebView 하이브리드 앱 추진 수정안.md

@@ -4,10 +4,11 @@
 
 ## 1. 목적
 
-본 문서는 기존 `Baron Safe 기반 휴대폰 승인 로그인 제안안`을 실제 앱 개발 과제로 진행하기 위한 초기 실행 초안이다.
+본 문서는 기존 `Baron Safe 기반 휴대폰 승인 로그인 제안안`을 실제 앱 개발로 진행하기 위한 초기 실행 초안이다.
 
 팀 회의에서 제시된 방향에 따라 Baron SSO의 기존 `userfront`는 그대로 유지하고, 그 안에서 활용 가능한 화면 자산과   
-구현 패턴을 Baron Safe 앱 개발 시 가져다 쓰는 방향으로 구상한다.
+구현 패턴을 Baron Safe 앱 개발 시 가져다 쓰는 방향으로 구상한다.  
+
 Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱으로 검토한다.  
 
 이 앱은 단순 로그인 화면이 아니라, 등록된 휴대폰을 인증 장치로 사용하여 사용자가 로그인 요청을 확인하고   
@@ -15,7 +16,7 @@ Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱
 
 ## 2. 추진 배경
 
-현재 논의 중인 휴대전화번호 기반 로그인은 사용자 편의성은 높지만, 전화번호만으로는 실제 사용자가 해당 번호의 소유자인지, 
+현재 적용 중인 휴대전화번호 기반 로그인은 사용자 편의성은 높지만, 전화번호만으로는 실제 사용자가 해당 번호의 소유자인지, 
 현재 로그인 요청을 직접 승인했는지 확인하기 어렵다.
 
 이를 보완하기 위해 사용자의 휴대폰에 `Baron Safe` 앱을 설치하고, 해당 앱을 사용자 계정에 사전 등록된 인증 장치로 사용한다. 
@@ -28,8 +29,10 @@ Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱
 
 `Baron Safe`는 Flutter 기반 설치형 모바일 앱, PWA, WebView/하이브리드 앱 중 하나로 구현할 수 있다.
 
-다만 현재 Baron SSO `userfront`는 이미 모바일 화면을 고려한 포털 UI, 연결 앱 현황, 접속 이력, QR 진입 흐름 등을 포함하고 있다.
+다만 현재 Baron SSO `userfront`는 이미 모바일 화면을 고려한 포털 UI, 연결 앱 현황, 접속 이력, QR 진입 흐름 등을 포함하고 있다.  
+
 따라서 기존 `userfront`를 직접 변경하거나 앱으로 전환하기보다는, Baron Safe 앱에서 필요한 화면 흐름과 구현 패턴을 가져와 활용하고,   
+
 푸시/생체 인증/보안 저장소 같은 기능은 Baron Safe 앱의 네이티브 또는 Flutter 플러그인 계층으로 보강하는 하이브리드 구조가 적절하다.
 
 기본 방향은 다음과 같다.
@@ -41,8 +44,10 @@ Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱
 - 푸시 알림은 로그인 요청을 전달하는 채널일 뿐이며 인증 수단으로 보지 않는다.
 - 승인 요청, 승인, 거절, 만료, 실패는 모두 감사 로그로 남긴다.
 
-따라서 본 초안에서는 `userfront`를 수정 대상이 아니라, Baron Safe 앱에서 활용 가능한 화면/패턴 자산으로 본다. 
+따라서 본 초안에서는 `userfront`를 수정 대상이 아니라, Baron Safe 앱에서 활용 가능한 화면/패턴 자산으로 본다.   
-단, 보안 인증 장치 역할에 필요한 private key, 생체 인증, 푸시 수신, 앱 무결성 검증은 WebView 내부 웹 코드만으로 처리하지 않고 
+
+단, 보안 인증 장치 역할에 필요한 private key, 생체 인증, 푸시 수신, 앱 무결성 검증은 WebView 내부 웹 코드만으로 처리하지 않고   
+
 네이티브 계층 또는 Flutter 플러그인 계층에서 담당하는 방향으로 검토한다.
 
 ## 4. 대상 앱 정의
@@ -59,7 +64,8 @@ Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱
 - 기기 private key를 이용한 승인 응답 서명
 - 기기 분실, 교체, 해제 대응
 
-앱은 브라우저에서 열리는 웹앱이 아니라 휴대폰에 설치되는 모바일 앱이다. 따라서 사용자의 브라우저가 열려 있을 필요는 없다.   
+앱은 브라우저에서 열리는 웹앱이 아니라 휴대폰에 설치되는 모바일 앱이다.   
+라서 사용자의 브라우저가 열려 있을 필요는 없다.   
 다만 보안상 승인 행위는 사용자가 앱을 열어 직접 수행해야 하며, 백그라운드 자동 승인은 허용하지 않는다.
 
 ## 5. 지원 플랫폼 및 배포
@@ -116,7 +122,8 @@ Baron Safe 앱 자체는 PWA 또는 WebView/하이브리드 기반 모바일 앱
 
 ### 6.3 PWA/WebView/하이브리드 방식 검토
 
-팀장 구상은 기존 `userfront`의 활용 가능한 부분을 Baron Safe 앱에서 재사용하여 PWA 또는 WebView/하이브리드 방식으로 앱처럼 제공하는 방향으로 볼 수 있다.   
+기존 구상은 `userfront`의 활용 가능한 부분을 Baron Safe 앱에서 재사용하여   
+PWA 또는 WebView/하이브리드 방식으로 앱처럼 제공하는 방향으로 볼 수 있다.   
 이 방식은 현재 구현된 모바일 포털 화면과 흐름을 참고할 수 있으므로 초기 개발 속도와 화면 일관성 측면에서 장점이 있다.
 
 | 방식 | 설명 | 장점 | 주의점 |
@@ -384,28 +391,23 @@ POST /api/v1/auth/baron-safe/login/poll
 | 2단계 MVP | 4~6주 | 푸시, 생체 인증, key pair, 서명 검증, Hydra login challenge 연동 |
 | 3단계 운영화 | 4주 이상 | iOS 검증, 배포 체계, 감사 로그, 관리자 기기 관리, 보안 강화 |
 
-## 13. 우선 결정 필요 사항
+## 13. 권장 추진안
 
-1. `userfront` 원본은 유지하고, Baron Safe 앱에서 어떤 화면/패턴/API 흐름을 활용할지 결정해야 한다.
+초기에는 기존 `userfront`는 그대로 두고,   
-2. 초기 PoC 대상 플랫폼을 Android 우선으로 할지, Android/iOS 동시로 할지 결정해야 한다.
+그 안에서 활용 가능한 화면 자산과 구현 패턴을 Baron Safe 앱에서 가져다 쓰는 WebView/하이브리드 방식을 우선 검토한다.   
-3. 앱 배포 방식을 사내 배포, MDM, 스토어 배포 중 어떤 방식으로 가져갈지 결정해야 한다.
+보안 기능은 네이티브 또는 Flutter 플러그인 계층으로 분리하는 것을 권장한다.
-4. 기기 등록 시 기존 SSO 로그인 기반으로 할지, 관리자 초대/등록 코드 기반으로 할지 결정해야 한다.
-5. 승인 응답 서명 포맷을 JWS/JWK로 할지 COSE 기반으로 할지 결정해야 한다.
-6. 앱 private key를 Flutter 플러그인으로 처리할지, Android/iOS 네이티브 Method Channel로 직접 구현할지 결정해야 한다.
-
-## 14. 권장 추진안
-
-초기에는 기존 `userfront`는 그대로 두고, 그 안에서 활용 가능한 화면 자산과 구현 패턴을 Baron Safe 앱에서 가져다 쓰는 WebView/하이브리드 방식을 우선 검토한다. 보안 기능은 네이티브 또는 Flutter 플러그인 계층으로 분리하는 것을 권장한다.
 
 이유는 다음과 같다.
 
 - 현재 `userfront`는 이미 모바일 포털 화면과 연결 앱 현황, 접속 이력, QR 진입 등 Baron Safe와 가까운 화면 흐름을 일부 포함하고 있다.
-- 팀장 구상은 PWA 또는 WebView/하이브리드 방식으로 현재 화면 자산과 구현 패턴을 Baron Safe 앱에서 활용하는 방향에 가까워 보인다.
+- 최초 구상은 PWA 또는 WebView/하이브리드 방식으로 현재 화면 자산과 구현 패턴을 Baron Safe 앱에서 활용하는 방향에 가까워 보인다.
 - 초기 PoC에서는 화면을 전부 새로 만들기보다 기존 `userfront`의 활용 가능한 부분을 가져오는 편이 빠르다.
 - 다만 푸시, 생체 인증, private key, 보안 저장소, 앱 무결성은 WebView 내부 웹 코드에만 맡기기 어렵다.
 - 따라서 `userfront`는 유지하고, Baron Safe 앱은 활용 가능한 화면/패턴을 가져오며, 인증 장치 기능은 네이티브/Flutter 앱 계층이 담당하도록 역할을 나누는 것이 적절하다.
 
-단, 장기적으로 Baron Safe가 고보안 인증 앱으로 커질 경우에는 `baron_safe_app` 형태의 별도 Flutter 앱으로 분리하는 방안도 유지한다. 이 경우에도 `userfront`는 그대로 두고 화면과 UX 패턴의 참조 자산으로 활용하며, 앱 패키지, Android/iOS 설정, 푸시 설정, 앱 서명, 보안 저장소 설정은 Baron Safe 앱에서 독립적으로 관리한다.
+단, 장기적으로 Baron Safe가 고보안 인증 앱으로 커질 경우에는 `baron_safe_app` 형태의 별도 Flutter 앱으로 분리하는 방안도 유지한다.   
+이 경우에도 `userfront`는 그대로 두고 화면과 UX 패턴의 참조 자산으로 활용하며,   
+앱 패키지, Android/iOS 설정, 푸시 설정, 앱 서명, 보안 저장소 설정은 Baron Safe 앱에서 독립적으로 관리한다.
 
 따라서 추진 순서는 다음과 같이 잡는다.
 
@@ -418,40 +420,13 @@ POST /api/v1/auth/baron-safe/login/poll
 7. 기기 key pair와 승인 응답 서명 검증을 추가한다.
 8. 운영 배포 방식과 장기적으로 완전 별도 `baron_safe_app`으로 갈지 여부를 확정한다.
 
-## 15. 결론
+## 14. 결론
 
-Baron Safe 앱은 PWA/WebView/하이브리드 방식과 Flutter 기반 별도 앱 방식을 모두 검토할 수 있다. 현재 Baron `userfront`가 이미 모바일 포털 화면을 상당 부분 갖추고 있으므로, 초기 PoC는 `userfront`를 그대로 유지한 채 활용 가능한 화면/패턴/API 흐름을 Baron Safe 앱에서 가져다 쓰는 WebView/하이브리드 방식이 현실적이다.
+Baron Safe 앱은 PWA/WebView/하이브리드 방식과 Flutter 기반 별도 앱 방식을 모두 검토할 수 있다.   
+현재 Baron `userfront`가 이미 모바일 포털 화면을 상당 부분 갖추고 있으므로,   
+초기 PoC는 `userfront`를 그대로 유지한 채 활용 가능한 화면/패턴/API 흐름을 Baron Safe 앱에서 가져다 쓰는 WebView/하이브리드 방식이 현실적이다.
 
-다만 본 앱은 일반 화면 앱이 아니라 인증 장치 역할을 하므로, 화면/패턴을 활용하더라도 푸시, 생체 인증, 기기 보안 저장소, private key 서명, 서버 검증, 감사 로그는 Baron Safe 앱의 핵심 보안 요소로 별도 설계해야 한다. 따라서 PoC 단계에서는 기존 `userfront`의 활용 가능한 부분을 바탕으로 승인 흐름을 빠르게 검증하고, MVP 단계에서 네이티브 보안 기능과 기기 서명 구조를 반드시 포함하는 방향으로 추진하는 것이 바람직하다.
+다만 본 앱은 일반 화면 앱이 아니라 인증 장치 역할을 하므로, 화면/패턴을 활용하더라도   
-
+푸시, 생체 인증, 기기 보안 저장소, private key 서명, 서버 검증, 감사 로그는 Baron Safe 앱의 핵심 보안 요소로 별도 설계해야 한다.   
-## 16. 용어 주석
+따라서 PoC 단계에서는 기존 `userfront`의 활용 가능한 부분을 바탕으로 승인 흐름을 빠르게 검증하고,   
-
+MVP 단계에서 네이티브 보안 기능과 기기 서명 구조를 반드시 포함하는 방향으로 추진하는 것이 바람직하다.
-### PoC
-
-PoC는 `Proof of Concept`의 약자이며, 한국어로는 개념 검증 또는 가능성 검증 정도로 볼 수 있다.
-
-본 문서에서 PoC는 Baron Safe 앱의 전체 보안 기능과 운영 기능을 모두 완성하기 전에, 핵심 흐름이 실제로 가능한지 먼저 확인하는 단계를 의미한다. 예를 들어 사용자가 로그인 요청을 만들고, 앱에서 승인 요청을 확인하고, 승인 결과가 서버를 통해 로그인 화면에 반영되는 end-to-end 흐름을 검증하는 것이 PoC의 목적이다.
-
-### JWS/JWK
-
-JWS는 `JSON Web Signature`의 약자이며, JSON 형태의 데이터가 중간에 위조되거나 변경되지 않았음을 서명으로 증명하는 표준이다.
-
-JWK는 `JSON Web Key`의 약자이며, 공개키 또는 비밀키 정보를 JSON 형식으로 표현하는 표준이다.
-
-본 문서에서는 Baron Safe 앱이 승인 응답을 만들 때 앱 내부의 private key로 JWS 서명을 하고, 서버는 사전에 등록된 JWK 형식의 public key로 그 서명을 검증하는 구조를 의미한다.
-
-### COSE 기반
-
-COSE는 `CBOR Object Signing and Encryption`의 약자이며, 데이터를 서명하거나 암호화하기 위한 표준 형식이다.
-
-JWS/JWK가 JSON 기반이라면, COSE는 CBOR라는 더 작고 기계 처리에 적합한 데이터 형식을 기반으로 한다. WebAuthn, FIDO2, 패스키 같은 인증 기술에서 자주 사용된다.
-
-본 문서에서 COSE 기반이라는 표현은 승인 응답 서명 구조를 JWS/JWK 대신 WebAuthn/FIDO2 계열과 더 가까운 COSE 방식으로 설계할 수 있다는 의미이다.
-
-### 앱 private key
-
-앱 private key는 Baron Safe 앱이 설치된 특정 휴대폰 안에서 생성되고 보관되는 비밀키를 의미한다.
-
-이 키는 서버로 전송하지 않으며, Android Keystore 또는 iOS Keychain/Secure Enclave 같은 기기 보안 저장소에 보관하는 것이 원칙이다. 앱은 로그인 승인 응답을 보낼 때 이 private key로 서명하고, 서버는 등록 시 저장해 둔 public key로 해당 서명이 올바른지 검증한다.
-
-따라서 앱 private key는 Baron Safe 앱이 단순 알림 앱이 아니라, 사용자 계정에 등록된 인증 장치임을 증명하는 핵심 보안 요소이다.