timsquad 3.3.0 → 3.5.0

package/templates/base/skills/mobile/flutter/security/references/mobile-security-checklist.md

@@ -0,0 +1,168 @@
+---
+title: Mobile Security Checklist (OWASP MASVS)
+category: reference
+source: owasp
+tags: owasp, masvs, checklist, mobsf, frida, penetration-testing
+---
+
+# Mobile Security Checklist (OWASP MASVS)
+
+OWASP Mobile Application Security Verification Standard (MASVS) L1/L2 기준 체크리스트.
+Flutter 앱 보안 검증을 위한 참조 문서.
+
+## Key Concepts
+
+- **MASVS L1**: 표준 보안 (모든 모바일 앱 필수)
+- **MASVS L2**: 심층 방어 (금융, 의료, 개인정보 처리 앱)
+- **MASTG**: Mobile Application Security Testing Guide (테스트 방법론)
+
+## MASVS L1 체크리스트 (필수)
+
+### MASVS-STORAGE: 데이터 저장
+
+| # | 항목 | Flutter 구현 |
+|---|------|-------------|
+| S-1 | 민감 데이터를 안전한 저장소에 보관 | `flutter_secure_storage` (Keychain/EncryptedSharedPreferences) |
+| S-2 | 로그에 민감 데이터 미출력 | Release 빌드에서 `debugPrint` 제거, `kDebugMode` 체크 |
+| S-3 | 백업에서 민감 데이터 제외 | Android `backup_rules.xml`, iOS `isExcludedFromBackup` |
+| S-4 | 클립보드에 민감 데이터 자동 클리어 | `Clipboard.setData` 후 타이머로 클리어 |
+| S-5 | 키보드 캐시에 민감 데이터 미저장 | `enableSuggestions: false`, `autocorrect: false` |
+| S-6 | 서드파티 라이브러리에 민감 데이터 미전달 | Analytics에 PII 미포함 확인 |
+
+### MASVS-CRYPTO: 암호화
+
+| # | 항목 | Flutter 구현 |
+|---|------|-------------|
+| C-1 | 검증된 암호화 알고리즘 사용 | AES-256 (`encrypt` 패키지), SHA-256 |
+| C-2 | 커스텀 암호화 구현 금지 | 표준 라이브러리만 사용 (자체 구현 X) |
+| C-3 | 하드코딩된 암호화 키 없음 | 키는 `flutter_secure_storage` 또는 빌드 주입 |
+| C-4 | 적절한 키 길이 사용 | AES: 256비트, RSA: 2048비트+ |
+
+### MASVS-AUTH: 인증
+
+| # | 항목 | Flutter 구현 |
+|---|------|-------------|
+| A-1 | 서버 측 인증 구현 | 클라이언트 인증은 UX, 실제 검증은 서버 |
+| A-2 | 세션 토큰 안전 저장 | `flutter_secure_storage` |
+| A-3 | 세션 만료 처리 | Dio interceptor 401 자동 갱신 |
+| A-4 | 생체 인증 적용 (해당 시) | `local_auth`, PIN 폴백 |
+
+### MASVS-NETWORK: 네트워크
+
+| # | 항목 | Flutter 구현 |
+|---|------|-------------|
+| N-1 | TLS 1.2+ 사용 | Dart HttpClient 기본 지원 |
+| N-2 | 인증서 검증 활성화 | `badCertificateCallback` 기본 거부 |
+| N-3 | 인증서/공개키 pinning | Dio `IOHttpClientAdapter` + `SecurityContext` |
+| N-4 | cleartext 트래픽 차단 | Android `network_security_config.xml`, iOS ATS |
+
+### MASVS-RESILIENCE: 복원력
+
+| # | 항목 | Flutter 구현 |
+|---|------|-------------|
+| R-1 | 코드 난독화 | `--obfuscate --split-debug-info` |
+| R-2 | 디버그 감지 | `kDebugMode`, `kReleaseMode` 분기 |
+| R-3 | 루팅/탈옥 감지 | `flutter_jailbreak_detection` 패키지 |
+| R-4 | 무결성 검증 | 앱 서명 검증, 변조 감지 |
+
+## MASVS L2 추가 항목 (금융/의료)
+
+| # | 항목 | Flutter 구현 |
+|---|------|-------------|
+| L2-1 | 스크린샷 방지 | Android `FLAG_SECURE`, iOS 오버레이 |
+| L2-2 | 앱 스위처 블러 | `WidgetsBindingObserver` + 오버레이 |
+| L2-3 | 고급 루팅 감지 | Magisk/Frida 감지 로직 |
+| L2-4 | 런타임 무결성 검증 | 코드 주입 감지, 후킹 방지 |
+| L2-5 | SSL pinning 우회 감지 | 핀 실패 시 서버 리포트 |
+| L2-6 | 화이트박스 암호화 | 키 보호 강화 (HSM 연동) |
+
+## 보안 테스트 도구
+
+### MobSF (Mobile Security Framework)
+
+```bash
+# 설치 및 실행
+docker run -it --rm -p 8000:8000 opensecurity/mobile-security-framework-mobsf
+
+# 사용법:
+# 1. http://localhost:8000 접속
+# 2. APK/IPA 파일 업로드
+# 3. 자동 정적 분석 (하드코딩 키, 취약 API, 권한 등)
+# 4. 보고서 확인 및 취약점 수정
+
+# 분석 항목:
+# - 하드코딩된 시크릿/API 키
+# - 안전하지 않은 권한
+# - 취약한 암호화 사용
+# - 디버그 모드 활성화
+# - 백업 허용 여부
+# - cleartext 트래픽 허용
+```
+
+### Frida (동적 분석)
+
+```bash
+# Frida 설치
+pip install frida-tools
+
+# 앱 프로세스 확인
+frida-ps -U
+
+# SSL pinning 우회 테스트 (자체 앱 검증용)
+frida -U -f com.example.app -l ssl_bypass.js
+
+# 주요 테스트:
+# - SSL pinning 우회 가능 여부
+# - 메모리 내 토큰 노출 여부
+# - 루팅 감지 우회 가능 여부
+# - 암호화 키 메모리 노출 여부
+```
+
+### 기타 도구
+
+```
+정적 분석:
+- MobSF: APK/IPA 자동 정적 분석
+- semgrep: 소스 코드 패턴 매칭 (시크릿 하드코딩 등)
+- gitleaks: git history에서 시크릿 검색
+
+동적 분석:
+- Frida: 런타임 후킹/분석
+- Objection: Frida 기반 모바일 분석 도구
+- Charles Proxy: 네트워크 트래픽 분석
+
+Android 전용:
+- apktool: APK 디컴파일/리패키징
+- jadx: DEX → Java 소스 변환
+- drozer: Android 보안 감사
+
+iOS 전용:
+- Hopper: 바이너리 역공학
+- class-dump: Objective-C 헤더 덤프
+```
+
+## 보안 리뷰 프로세스
+
+```
+릴리즈 전 보안 체크:
+1. MobSF 정적 분석 → 하드코딩 키, 취약 설정 확인
+2. MASVS L1 체크리스트 통과
+3. SSL pinning 동작 확인 (Charles Proxy 차단 확인)
+4. 난독화 확인 (jadx/apktool로 디컴파일 시 심볼 난독화)
+5. flutter_secure_storage 동작 확인 (루팅 기기 테스트)
+6. Crashlytics 디버그 심볼 업로드 확인
+7. (L2) Frida 동적 분석 → 런타임 보호 검증
+
+주기적 보안 감사:
+- 분기별: 의존성 취약점 스캔 (flutter pub outdated)
+- 반기별: 외부 보안 감사 (해당 시)
+- 상시: gitleaks pre-commit 훅 (시크릿 커밋 방지)
+```
+
+## References
+
+- [OWASP MASVS](https://mas.owasp.org/MASVS/)
+- [OWASP MASTG](https://mas.owasp.org/MASTG/)
+- [MobSF Documentation](https://mobsf.github.io/docs/)
+- [Frida Documentation](https://frida.re/docs/)
+- [Flutter Security Best Practices](https://docs.flutter.dev/security)

package/templates/base/skills/mobile/flutter/security/rules/api-key-protection.md

@@ -0,0 +1,206 @@
+---
+title: API Key Protection
+impact: HIGH
+impactDescription: "키 하드코딩 → git history 영구 노출, 앱 디컴파일 시 즉시 탈취"
+tags: dart-define, envied, environment, api-key, secret, build-injection
+---
+
+## API Key Protection
+
+**Impact: HIGH (키 하드코딩 → git history 영구 노출, 앱 디컴파일 시 즉시 탈취)**
+
+API 키, 시크릿을 소스 코드에서 분리. 빌드 시 주입하고 런타임에 안전하게 참조.
+
+### 방법 1: --dart-define (빌드 인자)
+
+**Incorrect (소스 코드에 키 하드코딩):**
+```dart
+class ApiConfig {
+  // 소스 코드에 직접 → git push 시 영구 노출
+  // 앱 디컴파일 시 문자열 검색으로 즉시 발견
+  static const apiKey = 'sk-1234567890abcdef';
+  static const googleMapsKey = 'AIzaSyB_XXXXXXXXXXXXXXXXXXXXXXX';
+}
+```
+
+**Correct (--dart-define로 빌드 시 주입):**
+```dart
+class ApiConfig {
+  // 컴파일 타임 상수 — 빌드 시 --dart-define으로 주입
+  static const apiKey = String.fromEnvironment('API_KEY');
+  static const googleMapsKey = String.fromEnvironment('GOOGLE_MAPS_KEY');
+  static const sentryDsn = String.fromEnvironment('SENTRY_DSN');
+
+  /// 필수 키 검증 (앱 시작 시)
+  static void validate() {
+    assert(apiKey.isNotEmpty, 'API_KEY not provided via --dart-define');
+    assert(googleMapsKey.isNotEmpty, 'GOOGLE_MAPS_KEY not provided');
+  }
+}
+```
+
+```bash
+# 빌드 명령어
+flutter run \
+  --dart-define=API_KEY=sk-1234567890abcdef \
+  --dart-define=GOOGLE_MAPS_KEY=AIzaSyB_XXX \
+  --dart-define=SENTRY_DSN=https://xxx@sentry.io/123
+
+# 릴리즈 빌드
+flutter build apk \
+  --dart-define=API_KEY=$API_KEY \
+  --dart-define=GOOGLE_MAPS_KEY=$GOOGLE_MAPS_KEY \
+  --release
+
+# --dart-define-from-file (Flutter 3.7+)
+flutter run --dart-define-from-file=config/dev.env
+```
+
+```properties
+# config/dev.env (gitignore 대상)
+API_KEY=sk-dev-1234567890
+GOOGLE_MAPS_KEY=AIzaSyB_dev_XXX
+SENTRY_DSN=https://dev@sentry.io/123
+```
+
+### 방법 2: envied 패키지 (코드 생성 + 난독화)
+
+```yaml
+# pubspec.yaml
+dependencies:
+  envied: ^0.5.4
+dev_dependencies:
+  envied_generator: ^0.5.4
+  build_runner: ^2.4.0
+```
+
+```dart
+// lib/config/env.dart
+import 'package:envied/envied.dart';
+
+part 'env.g.dart';
+
+@Envied(path: '.env', obfuscate: true) // obfuscate: 문자열 난독화
+abstract class Env {
+  @EnviedField(varName: 'API_KEY')
+  static const String apiKey = _Env.apiKey;
+
+  @EnviedField(varName: 'GOOGLE_MAPS_KEY')
+  static const String googleMapsKey = _Env.googleMapsKey;
+
+  @EnviedField(varName: 'SENTRY_DSN', defaultValue: '')
+  static const String sentryDsn = _Env.sentryDsn;
+}
+
+// .env (프로젝트 루트, .gitignore 필수)
+// API_KEY=sk-1234567890abcdef
+// GOOGLE_MAPS_KEY=AIzaSyB_XXXXXXX
+```
+
+```bash
+# 코드 생성
+dart run build_runner build --delete-conflicting-outputs
+
+# env.g.dart 생성됨 (obfuscate: true → XOR 난독화된 바이트 배열)
+# → 단순 문자열 검색으로 키 추출 불가
+```
+
+### 환경별 설정 분리
+
+```dart
+// lib/config/app_config.dart
+enum AppEnvironment { dev, staging, prod }
+
+class AppConfig {
+  final String apiBaseUrl;
+  final String apiKey;
+  final bool enableLogging;
+
+  const AppConfig._({
+    required this.apiBaseUrl,
+    required this.apiKey,
+    required this.enableLogging,
+  });
+
+  factory AppConfig.fromEnvironment() {
+    const env = String.fromEnvironment('APP_ENV', defaultValue: 'dev');
+
+    switch (env) {
+      case 'prod':
+        return const AppConfig._(
+          apiBaseUrl: 'https://api.example.com',
+          apiKey: String.fromEnvironment('API_KEY'),
+          enableLogging: false,
+        );
+      case 'staging':
+        return const AppConfig._(
+          apiBaseUrl: 'https://staging-api.example.com',
+          apiKey: String.fromEnvironment('API_KEY'),
+          enableLogging: true,
+        );
+      default: // dev
+        return const AppConfig._(
+          apiBaseUrl: 'https://dev-api.example.com',
+          apiKey: String.fromEnvironment('API_KEY', defaultValue: 'dev-key'),
+          enableLogging: true,
+        );
+    }
+  }
+}
+
+// Riverpod Provider
+final appConfigProvider = Provider<AppConfig>((ref) {
+  return AppConfig.fromEnvironment();
+});
+```
+
+### .gitignore 설정
+
+```gitignore
+# 환경 파일
+.env
+.env.*
+config/dev.env
+config/staging.env
+config/prod.env
+
+# envied 생성 파일 (선택: 커밋 vs 생성)
+# lib/config/env.g.dart
+
+# Firebase 설정 파일 (키 포함)
+google-services.json
+GoogleService-Info.plist
+firebase_options.dart
+```
+
+### CI/CD 연동
+
+```yaml
+# GitHub Actions 예시
+# 시크릿은 GitHub Secrets에 저장
+- name: Build APK
+  run: |
+    flutter build apk --release \
+      --dart-define=API_KEY=${{ secrets.API_KEY }} \
+      --dart-define=GOOGLE_MAPS_KEY=${{ secrets.GOOGLE_MAPS_KEY }}
+
+# 또는 .env 파일 생성 (envied 사용 시)
+- name: Create .env
+  run: |
+    echo "API_KEY=${{ secrets.API_KEY }}" >> .env
+    echo "GOOGLE_MAPS_KEY=${{ secrets.GOOGLE_MAPS_KEY }}" >> .env
+- name: Generate env
+  run: dart run build_runner build
+```
+
+### 규칙
+
+- API 키/시크릿 → 소스 코드에 절대 하드코딩 금지
+- `--dart-define` 또는 `--dart-define-from-file` → 빌드 시 주입
+- `String.fromEnvironment()` → 컴파일 타임 상수로 참조
+- `envied` + `obfuscate: true` → 디컴파일 시 문자열 검색 방지
+- `.env` 파일 → `.gitignore` 필수
+- `google-services.json` / `GoogleService-Info.plist` → `.gitignore` 권장
+- 환경별 (dev/staging/prod) → 설정 분리, 프로덕션 키는 CI/CD에서만 주입
+- `assert()` → 앱 시작 시 필수 키 존재 검증 (디버그 빌드에서 조기 발견)
+- 키 노출 사고 시 → 즉시 키 로테이션 + git history에서 제거 (`git filter-branch`)

package/templates/base/skills/mobile/flutter/security/rules/authentication.md

@@ -0,0 +1,248 @@
+---
+title: Authentication & Token Management
+impact: CRITICAL
+impactDescription: "토큰 미갱신 → 강제 로그아웃, 토큰 평문 저장 → 계정 탈취"
+tags: token, refresh, biometric, local_auth, dio-interceptor, session
+---
+
+## Authentication & Token Management
+
+**Impact: CRITICAL (토큰 미갱신 → 강제 로그아웃, 토큰 평문 저장 → 계정 탈취)**
+
+Access/Refresh Token 라이프사이클, Dio interceptor 자동 갱신, biometric 인증, 세션 타임아웃.
+
+### 의존성
+
+```yaml
+# pubspec.yaml
+dependencies:
+  dio: ^5.7.0
+  local_auth: ^2.3.0
+  flutter_secure_storage: ^9.2.0
+```
+
+### 토큰 라이프사이클
+
+**Incorrect (Access Token만 사용, 갱신 없음):**
+```dart
+// Access Token 하나만 저장 → 만료 시 강제 로그아웃
+final response = await dio.get('/api/data',
+  options: Options(headers: {'Authorization': 'Bearer $accessToken'}),
+);
+// 401 응답 → 사용자에게 "다시 로그인하세요" → UX 파괴
+```
+
+**Correct (Access + Refresh Token 분리, 자동 갱신):**
+```dart
+class AuthInterceptor extends Interceptor {
+  final SecureStorageService _storage;
+  final Dio _tokenDio; // 토큰 갱신 전용 Dio (인터셉터 없음)
+  bool _isRefreshing = false;
+  final _pendingRequests = <({RequestOptions options, ErrorInterceptorHandler handler})>[];
+
+  AuthInterceptor({
+    required SecureStorageService storage,
+    required Dio tokenDio,
+  })  : _storage = storage,
+        _tokenDio = tokenDio;
+
+  @override
+  void onRequest(RequestOptions options, RequestInterceptorHandler handler) async {
+    final token = await _storage.getAccessToken();
+    if (token != null) {
+      options.headers['Authorization'] = 'Bearer $token';
+    }
+    handler.next(options);
+  }
+
+  @override
+  void onError(DioException err, ErrorInterceptorHandler handler) async {
+    if (err.response?.statusCode != 401) {
+      return handler.next(err);
+    }
+
+    // 이미 갱신 중이면 대기열에 추가
+    if (_isRefreshing) {
+      _pendingRequests.add((options: err.requestOptions, handler: handler));
+      return;
+    }
+
+    _isRefreshing = true;
+
+    try {
+      final refreshToken = await _storage.getRefreshToken();
+      if (refreshToken == null) {
+        _forceLogout();
+        return handler.next(err);
+      }
+
+      // 토큰 갱신 요청
+      final response = await _tokenDio.post('/auth/refresh', data: {
+        'refresh_token': refreshToken,
+      });
+
+      final newAccess = response.data['access_token'] as String;
+      final newRefresh = response.data['refresh_token'] as String;
+      await _storage.saveTokens(
+        accessToken: newAccess,
+        refreshToken: newRefresh,
+      );
+
+      // 원래 요청 재시도
+      err.requestOptions.headers['Authorization'] = 'Bearer $newAccess';
+      final retryResponse = await _tokenDio.fetch(err.requestOptions);
+      handler.resolve(retryResponse);
+
+      // 대기 중인 요청 재시도
+      for (final pending in _pendingRequests) {
+        pending.options.headers['Authorization'] = 'Bearer $newAccess';
+        _tokenDio.fetch(pending.options).then(
+          (r) => pending.handler.resolve(r),
+          onError: (e) => pending.handler.reject(e as DioException),
+        );
+      }
+    } on DioException {
+      // Refresh Token도 만료 → 강제 로그아웃
+      await _storage.deleteTokens();
+      _forceLogout();
+      handler.next(err);
+    } finally {
+      _isRefreshing = false;
+      _pendingRequests.clear();
+    }
+  }
+
+  void _forceLogout() {
+    // 로그아웃 이벤트 발행 (GoRouter redirect에서 감지)
+  }
+}
+```
+
+### Biometric 인증 (local_auth)
+
+**Incorrect (biometric 실패 시 폴백 없음):**
+```dart
+final isAuthenticated = await LocalAuthentication().authenticate(
+  localizedReason: 'Verify identity',
+);
+if (!isAuthenticated) {
+  // 실패 → 아무 처리 없음 → 사용자 막힘
+}
+```
+
+**Correct (biometric + PIN 폴백):**
+```dart
+class BiometricService {
+  final LocalAuthentication _localAuth = LocalAuthentication();
+
+  /// 생체 인증 가능 여부 확인
+  Future<bool> isAvailable() async {
+    final canCheck = await _localAuth.canCheckBiometrics;
+    final isDeviceSupported = await _localAuth.isDeviceSupported();
+    return canCheck && isDeviceSupported;
+  }
+
+  /// 사용 가능한 인증 방식 목록
+  Future<List<BiometricType>> getAvailableBiometrics() async {
+    return _localAuth.getAvailableBiometrics();
+  }
+
+  /// 생체 인증 실행
+  Future<bool> authenticate({String reason = '본인 확인이 필요합니다'}) async {
+    try {
+      return await _localAuth.authenticate(
+        localizedReason: reason,
+        options: const AuthenticationOptions(
+          stickyAuth: true,         // 앱 전환 후에도 인증 유지
+          biometricOnly: false,     // 기기 PIN/패턴 폴백 허용
+          useErrorDialogs: true,    // 시스템 에러 다이얼로그 표시
+        ),
+      );
+    } on PlatformException catch (e) {
+      // NotAvailable, NotEnrolled, LockedOut, PermanentlyLockedOut
+      debugPrint('Biometric error: ${e.code}');
+      return false;
+    }
+  }
+}
+
+// Riverpod Provider
+final biometricServiceProvider = Provider<BiometricService>((ref) {
+  return BiometricService();
+});
+
+final biometricAvailableProvider = FutureProvider<bool>((ref) async {
+  return ref.watch(biometricServiceProvider).isAvailable();
+});
+```
+
+### 세션 타임아웃
+
+```dart
+class SessionManager {
+  static const _inactivityTimeout = Duration(minutes: 5);
+  Timer? _timer;
+  final SecureStorageService _storage;
+
+  SessionManager({required SecureStorageService storage})
+      : _storage = storage;
+
+  /// 사용자 활동 시마다 호출 (탭, 스크롤 등)
+  void resetTimer() {
+    _timer?.cancel();
+    _timer = Timer(_inactivityTimeout, _onTimeout);
+  }
+
+  void _onTimeout() {
+    // 민감 화면(잔액, 거래내역) → 재인증 요구
+    // 일반 화면 → 경고만 표시
+  }
+
+  /// AppLifecycleState.paused → 백그라운드 진입 시간 기록
+  Future<void> onBackground() async {
+    await _storage.saveBackgroundTime(DateTime.now());
+  }
+
+  /// AppLifecycleState.resumed → 경과 시간 확인
+  Future<bool> onForeground() async {
+    final bgTime = await _storage.getBackgroundTime();
+    if (bgTime == null) return true;
+
+    final elapsed = DateTime.now().difference(bgTime);
+    if (elapsed > _inactivityTimeout) {
+      return false; // 재인증 필요
+    }
+    return true;
+  }
+
+  void dispose() {
+    _timer?.cancel();
+  }
+}
+```
+
+### iOS/Android 설정
+
+```xml
+<!-- iOS: Info.plist (Face ID 사용 이유 설명) -->
+<key>NSFaceIDUsageDescription</key>
+<string>앱 잠금 해제를 위해 Face ID를 사용합니다.</string>
+```
+
+```xml
+<!-- Android: MainActivity.kt 변경 불필요 -->
+<!-- AndroidManifest.xml: 권한 자동 추가됨 (local_auth) -->
+<uses-permission android:name="android.permission.USE_BIOMETRIC"/>
+```
+
+### 규칙
+
+- Access Token (단수명 15-30분) + Refresh Token (장수명 7-30일) 분리
+- 401 응답 → Dio interceptor에서 자동 갱신 → 원래 요청 재시도
+- 동시 요청 중 401 → 갱신 1회만 실행, 나머지는 대기열 → 갱신 후 일괄 재시도
+- Refresh Token 만료 → `deleteTokens()` + 강제 로그아웃
+- Biometric → `biometricOnly: false` (기기 PIN/패턴 폴백 필수)
+- `stickyAuth: true` → 앱 전환 후 돌아와도 인증 세션 유지
+- 세션 타임아웃 → 비활성 5분 후 민감 화면 재인증 요구
+- 백그라운드 → 진입 시간 기록, 복귀 시 경과 확인
+- iOS → `NSFaceIDUsageDescription` plist 필수 (없으면 크래시)