# Baron Safe 하이브리드 앱 개발 정책

작성일: 2026-06-30

## 1. 목적

본 문서는 Baron Safe 앱을 PWA/WebView 하이브리드 방식으로 개발하기 위한 준비사항과 단계별 진행 순서를 정의한다.

기본 방향은 기존 Baron SSO `userfront`를 그대로 유지하면서, 그 안에서 활용 가능한 연결 앱 현황, 접속 이력, QR 화면, 기본 포털 UI, Flutter 구현 패턴을 Baron Safe 앱에서 가져다 쓰는 것이다. 단, 푸시, 생체 인증, 민감 토큰 저장, 기기 서명 같은 보안 기능은 WebView 내부 웹 코드에 맡기지 않고 Android/iOS 네이티브 또는 Flutter 플러그인 계층에서 처리한다.

## 2. 개발 원칙

### 2.1 userfront 활용 원칙

- 기존 `userfront` 원본은 Baron Safe 앱 개발을 위해 직접 변경하지 않는다.
- Baron Safe 앱에서 필요한 화면 흐름, UI 패턴, 상태관리 방식, API 호출 방식을 식별하여 활용한다.
- 연결 앱 현황, 접속 이력, QR 화면, 기본 포털 UI 중 Baron Safe에 적합한 부분을 앱 화면으로 재구성한다.
- Baron Safe 앱은 `userfront`의 단순 복제본이 아니라, 보안 확인 및 차단에 특화된 모바일 앱으로 정의한다.

### 2.2 WebView 역할

- WebView 화면은 정보 표시와 사용자 인터랙션을 담당한다.
- 최근 로그인, 현재 세션, 연결 앱, 세션 상세, 차단 버튼 등 사용자가 확인해야 하는 정보를 표시한다.
- WebView는 민감 토큰, private key, 생체 인증 결과를 직접 보관하거나 처리하지 않는다.
- WebView와 네이티브 계층 사이의 메시지는 명시적인 bridge API로 제한한다.

### 2.3 네이티브 계층 역할

- 로그인 발생 알림은 FCM/APNs 기반 네이티브 푸시로 처리한다.
- 차단, 연결 해제, 고위험 승인 전 사용자 확인은 Android/iOS 네이티브 또는 Flutter `local_auth` 계층에서 처리한다.
- 민감 토큰 저장과 향후 기기 서명은 Android Keystore, iOS Keychain/Secure Enclave 계층에서 처리한다.
- 네이티브 계층은 WebView가 요청한 민감 작업을 검증한 뒤 서버 API를 호출하거나, 필요한 경우 서명된 payload를 생성한다.

## 3. 목표 사용자 흐름

초기 기본 흐름은 `선승인 후확인 후차단` 방식이다.

1. 사용자가 Baron SSO 또는 RP 로그인 화면에서 휴대전화번호를 입력한다.
2. Baron SSO가 기존 정책에 따라 로그인을 진행한다.
3. 로그인 성공 시 세션과 접속 이력이 기록된다.
4. Baron SSO가 등록된 Baron Safe 앱으로 로그인 발생 알림을 보낸다.
5. 사용자는 Baron Safe 앱에서 접속 서비스, IP, 기기, 시간, 인증수단을 확인한다.
6. 본인 요청이면 별도 조치 없이 유지한다.
7. 의심 요청이면 앱에서 세션 차단, 로그아웃, RP 연결 해제를 수행한다.
8. 차단/해제 전에는 생체 인증 또는 앱 PIN으로 사용자 확인을 수행한다.

고위험 RP, 관리자 기능, 신규 기기 접속은 이후 단계에서 `로그인 요청 시 승인/차단` 방식으로 확장한다.

## 4. 사전 준비

### 4.0 기술 스택 정의

Baron Safe 하이브리드 앱의 기본 기술 스택은 다음과 같이 정의한다.

| 영역 | 기술 |
| --- | --- |
| App Framework | Flutter |
| Language | Dart |
| 화면 구성 | Flutter WebView 기반 하이브리드 화면 |
| WebView 대상 | Baron Safe 전용 route 또는 `userfront`에서 분리한 재사용 화면 |
| 상태 관리 | flutter_riverpod |
| Routing | go_router |
| API 통신 | http 우선, 필요 시 dio 검토 |
| Push | Firebase Cloud Messaging, iOS APNs |
| 생체 인증 | local_auth 또는 Android/iOS 네이티브 인증 |
| 보안 저장소 | Android Keystore, iOS Keychain/Secure Enclave |
| 기기 서명 | JWS/JWK 우선 검토, WebAuthn/FIDO2 확장 시 COSE 검토 |
| Backend | 기존 Baron SSO backend와 연동 |
| 인증/세션 | Ory Hydra, Ory Kratos 연동 |
| 배포 | Android APK/AAB, iOS IPA/TestFlight/MDM 검토 |
| 개발 도구 | VS Code, Flutter SDK, Android Studio SDK, Xcode |
| AI 개발 도구 | VS Code 기반 AI coding assistant, 코드 리뷰 assistant, 문서화 assistant |

기술 스택 선택 기준:

- 기존 `userfront`와의 기술 일관성을 유지한다.
- Android/iOS 공통 개발이 가능해야 한다.
- 민감 보안 기능은 WebView 내부가 아니라 네이티브 또는 Flutter 플러그인 계층에서 처리한다.
- PoC 단계에서는 구현 속도를 우선하되, MVP 단계에서 보안 저장소와 기기 서명 구조를 반드시 보강한다.

### 4.1 화면 및 기능 식별

개발 착수 전 `userfront`에서 Baron Safe에 활용 가능한 부분을 식별한다.

| 대상 | 확인 항목 |
| --- | --- |
| 연결 앱 현황 | RP 목록, 연결 상태, 최근 인증, 해지/차단 상태 |
| 접속 이력 | 로그인 시간, IP, 브라우저, 기기, 인증수단, 성공 여부 |
| 현재 세션 | 현재 접속 세션, 세션 ID, 세션 상태, 로그아웃 가능 여부 |
| QR 화면 | 기기 등록, 앱 연결, 승인 진입에 재사용 가능한지 검토 |
| 기본 포털 UI | 헤더, 메뉴, 카드, 모바일 레이아웃, 다국어 처리 방식 |
| API 호출 패턴 | 인증 쿠키/토큰 처리, 오류 처리, runtime env 처리 방식 |

### 4.2 앱 프로젝트 준비

- Baron Safe 앱용 별도 Gitea repository 또는 mono-repo 내 앱 디렉터리 구성을 결정한다.
- Android package name과 iOS bundle id를 결정한다.
- 개발/스테이징/운영 API endpoint 구분 방식을 정한다.
- 앱 버전, 빌드번호, 앱 이름, 아이콘, 권한 문구를 정한다.
- WebView에서 표시할 Baron Safe 전용 진입 URL 또는 route를 정의한다.

### 4.2.1 Gitea repository 구성

Baron Safe 앱은 기존 `userfront`를 직접 수정하지 않는다는 원칙을 유지하기 위해 별도 repository 구성을 우선 검토한다.

권장 repository:

```text
baron-safe-app
```

권장 디렉터리 구조:

```text
baron-safe-app/
  README.md
  docs/
    architecture.md
    api-contract.md
    bridge-policy.md
    release-policy.md
  app/
    pubspec.yaml
    lib/
    android/
    ios/
    test/
    integration_test/
  docker/
    Dockerfile.web
    nginx.conf
  scripts/
    bootstrap.sh
    test.sh
    build-android.sh
    build-ios.sh
  .vscode/
    settings.json
    extensions.json
    tasks.json
  .gitea/
    workflows/
      ci.yaml
```

구성 원칙:

- `app/`에는 Baron Safe Flutter 앱 코드를 둔다.
- `docs/`에는 앱 아키텍처, API 계약, WebView-native bridge 정책, 배포 정책을 둔다.
- `docker/`에는 WebView에서 로드할 정적 web build 또는 preview 서버 구성을 둔다.
- `scripts/`에는 개발자 환경 구성, 테스트, 빌드 스크립트를 둔다.
- `.vscode/`에는 팀 공통 VS Code 설정과 권장 extension을 둔다.
- `.gitea/workflows/`에는 lint, test, build 검증 workflow를 둔다.

대안:

- 기존 `baron-sso` mono-repo 내부에 `baron_safe_app/` 디렉터리로 시작할 수 있다.
- 단, 앱 배포, 모바일 권한, 서명키, release cadence가 `userfront`와 달라질 가능성이 높으므로 장기적으로는 별도 Gitea repository가 더 명확하다.

### 4.3 인프라 준비

- FCM 프로젝트 및 Android 설정 파일을 준비한다.
- iOS APNs 인증서 또는 키, bundle id, entitlement를 준비한다.
- push token 등록/갱신 API를 준비한다.
- 앱 기기 등록 테이블 또는 저장소를 설계한다.
- 로그인 이벤트 발생 시 push 발송을 트리거할 backend hook을 정의한다.

### 4.3.1 Docker 구성

모바일 앱 자체는 Docker 컨테이너로 실행되는 대상이 아니지만, 개발과 검증을 위해 다음 Docker 구성을 준비한다.

Docker 구성 대상:

- Baron Safe WebView용 web 화면 preview 서버
- API mock 서버
- 문서 preview 또는 정적 파일 서버
- CI에서 사용할 Flutter 분석/테스트 환경

권장 구성:

```text
docker/
  Dockerfile.web
  Dockerfile.flutter-ci
  nginx.conf
docker-compose.yaml
```

예상 서비스:

| 서비스 | 용도 |
| --- | --- |
| `baron-safe-web` | WebView에서 로드할 web build 또는 preview 화면 제공 |
| `baron-safe-api-mock` | 세션/연결 앱/차단 API mock 응답 제공 |
| `flutter-ci` | `flutter analyze`, `flutter test` 실행 |

Docker 구성 원칙:

- 로컬 개발에서 backend 전체를 띄우지 않아도 Baron Safe 화면과 앱 흐름을 확인할 수 있어야 한다.
- WebView URL은 개발/스테이징/운영 환경별로 분리한다.
- mock API는 PoC 단계에서만 사용하고, MVP 단계에서는 실제 Baron SSO backend API로 전환한다.
- Android/iOS 실제 빌드는 로컬 SDK 또는 CI runner 환경에서 수행하며, Docker는 보조 검증 환경으로 사용한다.

### 4.4 보안 정책 준비

- Baron Safe 기기 등록 정책을 정의한다.
- 차단/해제 전 생체 인증 또는 앱 PIN 요구 범위를 정의한다.
- 민감 토큰 저장 위치를 정의한다.
- WebView와 네이티브 bridge에서 허용할 명령 목록을 정의한다.
- 차단 시 종료할 세션 범위를 정의한다.
- 감사 로그 항목을 정의한다.

### 4.5 VS Code 기반 AI 개발 방식

Baron Safe 앱 개발은 VS Code를 기본 IDE로 두고, AI coding assistant를 활용한 개발 방식을 권장한다.

목표:

- 반복적인 Flutter 화면/상태관리 코드 작성 속도를 높인다.
- API 계약 변경 시 model, service, provider, test 코드를 일관되게 갱신한다.
- 문서와 코드의 불일치를 줄인다.
- 보안 민감 영역은 AI가 제안하더라도 사람이 반드시 리뷰한다.

권장 VS Code 구성:

| 항목 | 내용 |
| --- | --- |
| Flutter/Dart extension | Flutter 개발, debug, format, test 실행 |
| REST Client 또는 Thunder Client | API 계약 검증 |
| Docker extension | mock/preview 서버 실행 |
| Git/Gitea 연동 | branch, commit, PR 확인 |
| AI coding assistant | 코드 생성, 리팩터링, 테스트 초안, 문서화 보조 |

AI 활용 절차:

1. 작업 전 정책 문서와 API 계약을 먼저 확인한다.
2. AI에게 변경 범위를 명확히 지시한다.
3. 생성된 코드는 반드시 `flutter analyze`와 테스트를 통과시킨다.
4. 보안 저장소, 생체 인증, bridge, 서명 검증 코드는 사람 리뷰를 필수로 한다.
5. AI가 생성한 코드가 민감정보를 log에 남기지 않는지 확인한다.
6. PR 설명에는 AI 도움을 받은 범위와 사람이 검증한 항목을 기록한다.

AI 사용 제한:

- 앱 서명키, APNs key, FCM server key, private key, 운영 DB 접속정보를 AI 프롬프트에 넣지 않는다.
- 보안 정책을 완화하는 변경은 AI 제안만으로 반영하지 않는다.
- WebView bridge 허용 명령은 정책 문서에 정의된 목록을 벗어나지 않는다.
- 생성된 암호화/서명 코드는 공식 라이브러리와 플랫폼 문서를 기준으로 재검증한다.

## 5. 플랫폼 개발 전략

Flutter는 하나의 코드베이스로 Android와 iOS를 함께 지원할 수 있다. 다만 Baron Safe 앱은 일반 화면 앱이 아니라 푸시, 생체 인증, 보안 저장소, WebView-native bridge, 향후 기기 서명까지 포함하는 보안 앱이므로 양 플랫폼을 어떤 순서로 검증할지 정책이 필요하다.

### 5.1 개발 방식 후보

| 안 | 방식 | 설명 | 장점 | 단점 | 적합성 |
| --- | --- | --- | --- | --- | --- |
| 1안 | Android 우선 개발 후 iOS 확장 | Android에서 PoC와 주요 네이티브 기능을 먼저 검증하고 이후 iOS로 확장한다. | 초기 PoC가 빠름. FCM, WebView, local_auth, Keystore 검증이 상대적으로 수월함. 내부 테스트 배포가 쉬움. | iOS APNs, Keychain, WebView 정책 이슈가 뒤늦게 발견될 수 있음. | 높음 |
| 2안 | Android/iOS 동시 개발 | 처음부터 Android와 iOS를 같은 수준으로 개발하고 검증한다. | 양 플랫폼 차이를 초기에 발견할 수 있음. 최종 품질 균형이 좋음. | Xcode, APNs, 인증서, TestFlight까지 동시에 준비해야 하므로 초기 부담이 큼. | 중간 |
| 3안 | 공통 Flutter/WebView 코드 먼저 개발 후 플랫폼 기능 순차 적용 | 화면, 라우팅, API, 상태관리, WebView 구조를 먼저 만들고 Android/iOS 네이티브 기능을 순차 적용한다. | 공통 구조를 안정화한 뒤 플랫폼 기능을 붙일 수 있음. 코드 중복이 줄어듦. | 푸시, 생체 인증, 보안 저장소 같은 핵심 기능 검증이 늦어질 수 있음. | 높음 |
| 4안 | WebView/PWA PoC 먼저, 이후 앱화 | 기존 `userfront` 활용 화면과 기본 사용자 흐름을 웹/PWA 수준에서 먼저 검증한 뒤 앱으로 감싼다. | 화면과 정책을 빠르게 검증 가능. 앱 개발 전에 UX를 확정하기 좋음. | 네이티브 푸시, 생체 인증, 보안 저장소 검증은 별도 단계가 필요함. | 높음 |
| 5안 | iOS 우선 개발 후 Android 확장 | iOS의 제약을 먼저 해결하고 Android로 확장한다. | Apple 배포, APNs, Keychain 제약을 조기에 확인 가능. | 초기 개발 속도가 느릴 수 있고 테스트 환경 준비가 번거로움. | 낮음 |

### 5.2 권장 전략

권장안은 `3안 + 1안` 조합이다.

즉 소스코드는 Flutter 공통 코드로 처음부터 Android와 iOS를 고려해서 작성하되, 실제 네이티브 기능 검증은 Android를 먼저 진행하고 이후 iOS로 확장한다.

권장 순서:

1. 공통 Flutter/WebView 구조를 먼저 개발한다.
2. 세션/접속이력/연결 앱 조회, 차단 UI, API 연동 구조를 공통 코드로 만든다.
3. Android에서 FCM, WebView-native bridge, local_auth, Android Keystore를 먼저 검증한다.
4. Android 기준으로 선승인 후확인 후차단 PoC를 완성한다.
5. iOS에서 APNs, WKWebView, Face ID/Touch ID, Keychain/Secure Enclave를 확장 검증한다.
6. Android/iOS 차이를 반영하여 공통 UI와 플랫폼별 bridge를 정리한다.
7. 양 플랫폼에서 푸시 수신 상태, 앱 재설치, 기기 변경, 세션 차단을 반복 검증한다.

### 5.3 플랫폼별 검증 우선순위

| 단계 | Android | iOS |
| --- | --- | --- |
| PoC | WebView, FCM, 세션 조회, 차단 API, local_auth 우선 검증 | WebView 표시와 기본 로그인 세션 유지 수준 확인 |
| MVP | Android Keystore, push background/terminated 수신, 차단/해제 생체 인증 검증 | APNs, Keychain, Face ID/Touch ID, WKWebView 정책 검증 |
| 운영 전 | APK/AAB 배포, Play Integrity 검토 | TestFlight/MDM 배포, DeviceCheck/App Attest 검토 |

### 5.4 결정 원칙

- 공통 Flutter 코드는 처음부터 Android/iOS 모두를 고려해 작성한다.
- 플랫폼별 네이티브 기능은 Android에서 먼저 PoC를 완성한 뒤 iOS로 확장한다.
- iOS를 너무 늦게 검증하지 않는다. PoC 중에도 최소한 WebView, 로그인 세션, APNs 준비 가능 여부는 확인한다.
- 푸시, 생체 인증, 보안 저장소, bridge는 플랫폼별 차이가 크므로 공통 인터페이스와 플랫폼 구현체를 분리한다.
- 운영 배포 전에는 Android/iOS 모두 동일한 보안 기준을 통과해야 한다.

## 6. 단계별 개발 순서

### 6.1 0단계: 요구사항 및 설계 확정

목표는 개발자가 바로 구현에 들어갈 수 있는 계약을 만드는 것이다.

작업:

- 기본 흐름을 `선승인 후확인 후차단`으로 확정한다.
- 고위험 RP에만 사전 승인 방식을 적용할지 정책 초안을 정한다.
- Baron Safe에서 활용할 `userfront` 화면과 제외할 화면을 구분한다.
- 기술 스택을 확정한다.
- Gitea repository 구성 방식을 확정한다.
- Docker 기반 preview/mock/CI 구성을 확정한다.
- VS Code 기반 AI 개발 규칙을 팀에 공유한다.
- WebView 담당 기능과 네이티브 담당 기능을 분리한다.
- API 목록과 request/response 초안을 확정한다.
- 감사 로그 이벤트 이름과 필드를 정의한다.

산출물:

- 화면 흐름도
- API 계약 초안
- WebView-native bridge 명세 초안
- 보안 정책 초안
- Gitea repository 구조 초안
- Docker 구성 초안
- VS Code 설정 및 AI 개발 가이드

### 6.2 1단계: 앱 뼈대 및 WebView PoC

목표는 Baron Safe 앱에서 기존 화면 흐름을 앱처럼 보여주는 것이다.

작업:

- Gitea repository를 생성한다.
- 기본 branch 전략과 PR 규칙을 설정한다.
- `.vscode/settings.json`, `.vscode/extensions.json`, `.vscode/tasks.json`를 추가한다.
- Docker preview/mock 구성을 추가한다.
- Baron Safe 앱 프로젝트를 생성한다.
- WebView 또는 Flutter WebView 컨테이너를 구성한다.
- Baron Safe 전용 route 또는 URL을 로드한다.
- 앱 헤더, 뒤로가기, 새로고침, 오류 화면을 구현한다.
- 개발/스테이징 환경 전환 방식을 만든다.
- WebView와 네이티브 계층 사이의 최소 bridge를 만든다.

검증:

- Gitea repository에서 PR 기반 개발 흐름이 동작하는지 확인한다.
- Docker preview/mock 서버가 실행되는지 확인한다.
- VS Code task로 analyze/test/mock 실행이 가능한지 확인한다.
- Android에서 WebView 화면이 정상 로드되는지 확인한다.
- 로그인 세션이 유지되는지 확인한다.
- 네트워크 오류, 인증 만료, 뒤로가기 동작을 확인한다.

### 6.3 2단계: 기기 등록 및 push token 등록

목표는 Baron Safe 앱을 사용자 계정에 연결된 기기로 등록하는 것이다.

작업:

- 기기 등록 화면 또는 QR/등록 코드 입력 흐름을 구현한다.
- 앱에서 device id를 생성하거나 서버에서 발급받는다.
- FCM/APNs push token을 발급받는다.
- device id, push token, platform, app version을 서버에 등록한다.
- push token 갱신 시 서버에 다시 등록한다.
- 기기 해제 API와 화면을 준비한다.

검증:

- 동일 사용자의 다중 기기 등록이 가능한지 확인한다.
- push token 갱신이 누락되지 않는지 확인한다.
- 기기 해제 후 푸시가 발송되지 않는지 확인한다.

### 6.4 3단계: 세션/연결 앱 조회 화면

목표는 사용자가 Baron Safe 앱에서 최근 로그인과 연결 앱 상태를 확인할 수 있게 하는 것이다.

작업:

- 최근 로그인/현재 세션 조회 API를 구현한다.
- 연결 앱 현황 조회 API를 구현한다.
- WebView 화면에서 세션 목록, 세션 상세, 연결 앱 목록을 표시한다.
- 현재 세션, 비활성 세션, 성공/실패 상태를 구분 표시한다.
- 새로고침 및 pull-to-refresh 동작을 구현한다.

검증:

- `userfront`의 접속 이력과 Baron Safe 앱의 접속 이력이 일관되는지 확인한다.
- 세션 상태가 실시간 또는 준실시간으로 갱신되는지 확인한다.
- 사용자가 본인 요청 여부를 판단할 수 있는 정보가 충분한지 확인한다.

### 6.5 4단계: 로그인 발생 푸시

목표는 로그인 발생 시 Baron Safe 앱으로 알림을 보내는 것이다.

작업:

- 로그인 성공 이벤트 발생 시 backend에서 push 발송을 트리거한다.
- 푸시 payload에는 민감정보를 최소화한다.
- 푸시 클릭 시 해당 세션 상세 화면으로 이동한다.
- 푸시 수신 실패 시에도 앱 내 접속 이력에서 확인 가능하도록 한다.
- 반복 로그인 알림에 대한 rate limit을 적용한다.

검증:

- Android foreground/background/terminated 상태별 푸시 수신을 확인한다.
- iOS foreground/background/terminated 상태별 푸시 수신을 확인한다.
- 푸시 클릭 deep link가 정확한 세션 상세로 이동하는지 확인한다.

### 6.6 5단계: 차단/해제 기능

목표는 의심 세션 또는 RP 연결을 사용자가 앱에서 차단할 수 있게 하는 것이다.

작업:

- 세션 차단/종료 API를 구현한다.
- RP 연결 해제/차단 API를 구현한다.
- 차단 버튼 클릭 시 네이티브 생체 인증 또는 앱 PIN을 요구한다.
- 인증 성공 후 차단 API를 호출한다.
- 차단 결과를 WebView 화면에 반영한다.
- 차단 이벤트를 감사 로그로 남긴다.

검증:

- 차단 후 Hydra/Kratos 세션이 종료되는지 확인한다.
- 필요한 경우 RP refresh token이 무효화되는지 확인한다.
- 차단한 세션이 다시 활성화되지 않는지 확인한다.
- 본인 현재 세션 차단 시 UX가 자연스러운지 확인한다.

### 6.7 6단계: 민감 저장소 및 서명 기반 보강

목표는 민감 정보를 WebView가 아닌 기기 보안 계층에서 관리하는 것이다.

작업:

- Android Keystore, iOS Keychain/Secure Enclave 사용 방식을 확정한다.
- 앱 기기 key pair 생성 방식을 구현한다.
- public key를 서버에 등록한다.
- private key는 서버로 전송하지 않는다.
- 차단/해제 요청 payload에 서명하는 구조를 검토하거나 구현한다.
- 서버에서 public key로 서명을 검증한다.

검증:

- 앱 재설치, 기기 변경, OS 업데이트 시 키 관리 동작을 확인한다.
- private key export가 불가능한지 확인한다.
- 위조된 차단 요청이 거부되는지 확인한다.

### 6.8 7단계: 고위험 로그인 사전 승인 확장

목표는 기본안으로 부족한 고위험 상황에 사전 승인 방식을 추가하는 것이다.

적용 후보:

- 관리자 기능 접근
- 외부망 또는 미확인 IP 접속
- 신규 기기 로그인
- 고위험 RP 로그인
- 짧은 시간 내 반복 로그인

작업:

- 고위험 조건 판단 정책을 정의한다.
- 승인 요청 생성 API를 구현한다.
- Baron Safe 앱에서 승인/차단 화면을 제공한다.
- 승인 전 생체 인증 또는 앱 PIN을 요구한다.
- 승인 결과에 따라 Hydra login challenge를 accept/reject한다.

검증:

- 고위험 조건에서만 사전 승인이 동작하는지 확인한다.
- 승인 만료, 거절, 중복 승인 요청이 정상 처리되는지 확인한다.
- 일반 RP의 로그인 UX가 과도하게 느려지지 않는지 확인한다.

### 6.9 8단계: 운영 배포 준비

목표는 내부/협력사 사용자가 안정적으로 설치하고 사용할 수 있게 하는 것이다.

작업:

- Android 배포 방식을 결정한다.
- iOS 배포 방식을 결정한다.
- 앱 서명키와 인증서를 관리한다.
- 개인정보 처리 방침과 권한 안내 문구를 준비한다.
- 장애 대응 절차를 정한다.
- 기기 분실/교체/해제 절차를 정한다.
- 로그 모니터링과 알림을 구성한다.

검증:

- 신규 사용자 등록 절차를 테스트한다.
- 기기 교체 시 재등록 절차를 테스트한다.
- push 장애 시 대체 확인 흐름을 테스트한다.
- backend 장애 시 앱 화면의 오류 처리를 테스트한다.

## 7. WebView-Native Bridge 정책

WebView에서 네이티브 기능을 호출할 때는 허용된 명령만 처리한다.

초기 허용 명령:

| 명령 | 설명 | 네이티브 처리 |
| --- | --- | --- |
| `getDeviceInfo` | 앱 기기 정보 조회 | device id, platform, app version 반환 |
| `registerPushToken` | push token 등록 요청 | 현재 token을 서버에 등록 |
| `openBiometricPrompt` | 생체 인증 요청 | local_auth 또는 네이티브 인증 실행 |
| `blockSession` | 세션 차단 요청 | 생체 인증 후 차단 API 호출 |
| `blockLinkedApp` | RP 연결 차단 요청 | 생체 인증 후 차단 API 호출 |
| `openSettings` | 앱 설정 열기 | 네이티브 설정 화면 이동 |

금지 원칙:

- WebView에 private key를 전달하지 않는다.
- WebView에 장기 refresh token을 저장하지 않는다.
- WebView JS에서 생체 인증 성공 여부를 임의로 조작할 수 없게 한다.
- bridge 명령에는 origin 검증과 session 검증을 적용한다.

## 8. Backend API 준비 목록

초기 기본안에 필요한 API:

- `POST /api/v1/baron-safe/devices/register`
- `POST /api/v1/baron-safe/devices/push-token`
- `DELETE /api/v1/baron-safe/devices/{deviceId}`
- `GET /api/v1/baron-safe/sessions`
- `GET /api/v1/baron-safe/sessions/{sessionId}`
- `POST /api/v1/baron-safe/sessions/{sessionId}/block`
- `GET /api/v1/baron-safe/linked-apps`
- `POST /api/v1/baron-safe/linked-apps/{clientId}/block`

고위험 사전 승인 확장 시 필요한 API:

- `POST /api/v1/auth/baron-safe/login/init`
- `GET /api/v1/auth/baron-safe/requests/{authReqId}`
- `POST /api/v1/auth/baron-safe/requests/{authReqId}/decision`
- `POST /api/v1/auth/baron-safe/login/poll`

## 9. 감사 로그 정책

최소 감사 로그 이벤트:

| 이벤트 | 설명 |
| --- | --- |
| `baron_safe.device_registered` | Baron Safe 기기 등록 |
| `baron_safe.device_removed` | Baron Safe 기기 해제 |
| `baron_safe.push_token_updated` | push token 갱신 |
| `baron_safe.login_notified` | 로그인 발생 알림 발송 |
| `baron_safe.session_viewed` | 사용자가 세션 상세 확인 |
| `baron_safe.session_blocked` | 세션 차단 |
| `baron_safe.linked_app_blocked` | RP 연결 차단 |
| `baron_safe.biometric_verified` | 생체 인증 성공 |
| `baron_safe.biometric_failed` | 생체 인증 실패 |
| `baron_safe.high_risk_approved` | 고위험 로그인 승인 |
| `baron_safe.high_risk_rejected` | 고위험 로그인 거절 |

로그 필드:

- event_name
- user_id
- device_id
- client_id
- session_id
- request_ip
- user_agent
- platform
- app_version
- result
- reason
- created_at

## 10. 테스트 정책

### 10.1 기능 테스트

- 기기 등록/해제
- push token 등록/갱신
- 로그인 발생 알림
- 세션 목록 조회
- 세션 상세 조회
- 세션 차단
- RP 연결 차단
- 생체 인증 성공/실패

### 10.2 보안 테스트

- 미등록 기기의 API 접근 차단
- 다른 사용자의 세션 차단 시도 차단
- WebView bridge 명령 위조 차단
- private key export 불가 확인
- 만료된 세션 차단 요청 처리
- 반복 요청 rate limit 확인

### 10.3 플랫폼 테스트

- Android foreground/background/terminated push 수신
- iOS foreground/background/terminated push 수신
- Android Keystore 동작
- iOS Keychain/Secure Enclave 동작
- 앱 재설치/기기 변경 시 동작

## 11. 단계별 완료 기준

| 단계 | 완료 기준 |
| --- | --- |
| 0단계 | 기술스택, Gitea 구성, Docker 구성, 화면/API/bridge/보안 정책 초안 확정 |
| 1단계 | Gitea repository, VS Code 설정, Docker preview/mock, 앱 WebView 뼈대 구성 완료 |
| 2단계 | 기기 등록 및 push token 등록 완료 |
| 3단계 | 세션/연결 앱 조회 화면 동작 |
| 4단계 | 로그인 발생 푸시 수신 및 세션 상세 진입 |
| 5단계 | 생체 인증 후 세션/RP 차단 가능 |
| 6단계 | 민감 저장소와 서명 기반 요청 검증 가능 |
| 7단계 | 고위험 로그인 사전 승인 흐름 검증 |
| 8단계 | Android/iOS 배포 및 운영 절차 확정 |

## 12. 결론

Baron Safe 앱은 초기에는 하이브리드 방식으로 진행하는 것이 현실적이다. 기존 `userfront`의 화면과 구현 패턴을 활용하면 PoC 속도를 높일 수 있고, 로그인 이력 확인 및 차단이라는 기본 흐름과도 잘 맞는다.

다만 Baron Safe 앱은 인증 보조 장치 역할을 하므로, 푸시, 생체 인증, 민감 저장소, 향후 기기 서명은 반드시 네이티브 또는 Flutter 플러그인 계층에서 처리해야 한다. WebView는 화면 표시와 사용자 조작을 담당하고, 실제 보안 동작은 네이티브 계층이 담당하도록 역할을 분리하는 것이 본 정책의 핵심이다.
