# Auto Login Policy (P0: Mobile Installed Browser App)

## 1. 목적
- 모바일 환경에서 브라우저 앱 설치(standalone/PWA, 홈 화면 실행)를 **최우선 경로(P0)** 로 정의합니다.
- 사용자 관점에서 앱 재실행/새로고침/짧은 백그라운드 복귀 시 재로그인을 최소화합니다.
- 기존 IDP abstraction 원칙을 유지하면서 자동 로그인 동작을 표준화합니다.

## 2. 범위
- 포함:
  - UserFront 웹 실행 컨텍스트(설치형 앱, 일반 모바일 브라우저 탭, 데스크톱 브라우저)
  - 백엔드 `/api/v1/auth/*`, `/api/v1/user/me` 기반 세션 확인/유지 정책
- 제외:
  - 네이티브 Flutter 앱 바이너리 영속 저장소 상세 설계
  - Ory 내부 스택 교체/확장 설계

## 3. 플랫폼 우선순위
1. P0: 모바일 브라우저 앱 설치(standalone/PWA)
2. P1: 모바일 브라우저 탭(Safari/Chrome 일반 탭)
3. P2: 데스크톱 브라우저
4. P3: 네이티브 Flutter 앱

## 4. 세션 정책

### 4.1 기본 원칙
- 자동 로그인 판단은 `cookie-first`로 수행합니다.
- token은 보조 수단이며, cookie 세션 확인 성공 시 cookie mode를 우선 적용합니다.
- 사용자 액션 기반 슬라이딩(30일)은 서버를 SoT로 유지합니다.

### 4.2 저장소 fallback 정책 (웹)
- 인증 보조 상태 저장소는 아래 순서를 따릅니다.
  - `localStorage -> sessionStorage -> memory`
- 저장소 접근 실패(브라우저 정책/권한/프라이버시 모드) 시 다음 저장소로 자동 fallback 합니다.

### 4.3 금지사항
- Front에서 특정 IDP 벤더 SDK를 직접 연동해 세션 로직을 구현하지 않습니다.
- 자동 로그인 유지 로직을 클라이언트 로컬 타이머/임의 만료 계산만으로 확정하지 않습니다.
  - 만료 판단은 반드시 서버 응답(예: `/api/v1/user/me`) 기준으로 확정합니다.

## 5. 수용기준 (Acceptance Criteria)
1. 설치형 모바일 브라우저 앱에서 로그인 후 앱 재실행 시 `signin`으로 튕기지 않고 보호 화면으로 진입합니다.
2. 최근 30일 내 활동이 있으면 세션 만료가 연장됩니다.
3. 30일 초과 무활동이면 세션 만료(401) 후 로그인 화면으로 이동합니다.
4. OIDC `login_challenge` 플로우에서 자동 승인/리다이렉트 회귀가 없어야 합니다.
5. cookie 세션과 token 세션이 충돌하지 않아야 합니다.

## 6. 테스트 정책 (Failing Test First)

### 6.1 단위 테스트
- 저장소 fallback 정책:
  - local 실패 시 session에서 read/write 가능해야 합니다.
  - clear 시 local/session/memory가 함께 정리되어야 합니다.
- cookie 승격 정책:
  - 일반 로그인/`login_challenge` 유무에 따른 승격 조건 회귀를 방지합니다.

### 6.2 E2E 테스트 (WASM)
- 현재 한계:
  - `userfront-e2e` 기본 설정은 `Desktop Chrome` + `serviceWorkers: block`입니다.
  - 설치형 앱 시나리오를 직접 재현하기 어렵습니다.
- 보완 방향:
  - 모바일 viewport 프로젝트 추가
  - service worker 허용 시나리오 추가
  - standalone 실행 가정 시나리오 추가

### 6.3 실기기 검증 (필수)
- Android A2HS, iOS 홈 화면 앱 각각에서 최소 1회 검증합니다.
- 이유:
  - 브라우저 엔진/OS별 저장소/쿠키 정책 차이를 Playwright만으로 완전 대체할 수 없습니다.

## 7. 구현 체크리스트
- [ ] 웹 저장소 fallback 정책 구현/테스트
- [ ] cookie-first 자동 로그인 경로 회귀 테스트
- [ ] 슬라이딩 30일 서버 정책 테스트(단위 + E2E)
- [ ] 실기기 검증 결과를 `docs/test-plan/*`에 기록

## 8. 관련 문서
- `docs/AGENTS.md`
- `https://gitea.hmac.kr/baron/baron-sso/wiki/Authentication-and-Login-Flow.-`
- `docs/consent_loop_fix_report.md`
- `https://gitea.hmac.kr/baron/baron-sso/wiki/Test-Plan-and-Principles.-`
