--- name: security-mobile description: Mobile-specific security per OWASP MASVS v2 (Mobile Application Security Verification Standard). Use when designing or reviewing secure storage (Keychain/Keystore vs SharedPreferences/UserDefaults), certificate pinning, root/jailbreak detection, biometric authentication, deep-link injection defenses, IPC hardening, runtime application self-protection (RASP) basics. Targets React Native (bare) on iOS + Android. Pairs with auth-patterns (auth-side hardening) and security-web (server-side hardening). tier: cross-cutting domain: [mobile, security] last_reviewed: "2026-05-11" --- # Mobile Security — MASVS-Aligned Patterns For React Native bare apps targeting iOS 16+ and Android 14+. Aligned with OWASP MASVS v2.0 (the 2024 update). Targets the realistic threat model of a consumer mobile app — not a banking app under nation-state attack, but a real app with payments, PII, and user accounts where a breach hurts. ## When to Use This Skill - Storing tokens / credentials / secrets on the device. - Choosing certificate pinning strategy (or whether to pin at all). - Adding root/jailbreak detection. - Designing biometric prompts for sensitive ops. - Reviewing native-module surface area. - Planning what NOT to log/screenshot/leak. - Auditing third-party SDKs for risky permissions. - Pre-flight before App Store / Play Store submission. For server-side / API-side security, see `security-web`. For auth flows specifically, see `auth-patterns`. ## The Threat Model — Realistic Priorities Mobile threat ranking for a consumer app (high → low priority): 1. **Lost device, no biometric / weak passcode** → app session compromised. Mitigation: biometric gate on launch + on sensitive ops; idle timeout; remote logout. 2. **Phishing → credential theft** → standard password takeover. Mitigation: passkeys (phishing-proof), magic-link with same-device check. 3. **Malicious / compromised library on the client** → can read in-memory state. Mitigation: minimize deps, audit weekly, prefer first-party libs. 4. **Insecure data at rest** → device backup or filesystem inspection leaks tokens / PII. Mitigation: Keychain/Keystore for all secrets, encrypted DB for sensitive PII. 5. **MITM on hostile networks** → tampered responses. Mitigation: TLS + (selectively) certificate pinning; refuse insecure connections. 6. **Reverse engineering for cloning / cheating** → app logic exposed. Mitigation: server-authoritative gameplay, minimal client trust, R8/ProGuard for Android. 7. **Replay of intercepted requests** → repeated actions. Mitigation: TLS, idempotency keys (api-design skill). 8. **Side-channel via screenshots / app switcher** → sensitive data leaks via screenshots, voice-over, etc. Mitigation: redact sensitive views in inactive state. **NOT realistic for most consumer apps**: nation-state attackers, kernel-level malware, hardware tampering. Don't waste effort on these unless your threat model demands them. ## Secure Storage — MASVS L1 + L2 ### What Goes Where | Data | Where | Why | |---|---|---| | Auth session tokens / refresh tokens | **Keychain (iOS) / Keystore (Android)** via react-native-keychain | OS-level encryption, biometric gate available | | OAuth tokens | Same as above | Same | | Encryption keys you own | Keychain / Keystore | Same | | TOTP shared secret | Server-side encrypted (KMS) — NOT on device | Device compromise = no 2FA bypass | | User PII (name, email) | Encrypted DB (op-sqlite + SQLCipher) OR plain DB if not sensitive | Tradeoff | | App preferences (theme, language) | MMKV / AsyncStorage (unencrypted) | Not sensitive | | Cached server data | MMKV / SQLite / TanStack Query persister | Performance vs sensitivity tradeoff | | Analytics queue | MMKV / file | Non-sensitive | | **NEVER** | files in app sandbox (anyone with backup access reads), localStorage equivalents (AsyncStorage for tokens), URL params (history) | | ### Keychain (iOS) via react-native-keychain ```typescript import * as Keychain from 'react-native-keychain'; // Store await Keychain.setGenericPassword('session', sessionToken, { accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_ANY_OR_DEVICE_PASSCODE, accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY, storage: Keychain.STORAGE_TYPE.AES_GCM, service: 'com.app.session', // namespace }); // Retrieve (prompts biometric if required) const creds = await Keychain.getGenericPassword({ service: 'com.app.session', authenticationPrompt: { title: 'Unlock', subtitle: 'Use Face ID' }, }); const token = creds ? creds.password : null; // Delete on logout await Keychain.resetGenericPassword({ service: 'com.app.session' }); ``` Key options: - **`ACCESS_CONTROL.BIOMETRY_ANY_OR_DEVICE_PASSCODE`** — biometric required, passcode fallback. The right default for "unlock app" scenarios. - **`ACCESS_CONTROL.BIOMETRY_CURRENT_SET`** — invalidates if user changes biometry (stronger; some legitimate cases like banking). - **`ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY`** — readable only when device is unlocked, never backed up to iCloud/Google. - **`STORAGE_TYPE.AES_GCM`** — symmetric AES; modern default. ### Android Keystore react-native-keychain wraps Android Keystore automatically. The `accessControl` and `accessible` options translate to BIOMETRIC_STRONG and EncryptedSharedPreferences-style storage. For raw access (rare): use `react-native-keychain` or `react-native-encrypted-storage`. NEVER `AsyncStorage` or `MMKV` (non-encrypted variant) for tokens. ### MMKV for Encrypted Non-Token Data ```typescript import { MMKV } from 'react-native-mmkv'; // Encrypted instance (key derived per-install, stored in Keychain) const secureKey = await getOrCreateMmkvKey(); // helper that uses Keychain const encryptedMmkv = new MMKV({ id: 'sensitive-cache', encryptionKey: secureKey, }); encryptedMmkv.set('user_settings', JSON.stringify(settings)); ``` For PII-heavy data (chat history, financial records), use SQLite with SQLCipher (op-sqlite supports this). ## TLS + Certificate Pinning ### TLS Baseline - **HTTPS everywhere**. Refuse `http://` connections at the framework level. - **iOS App Transport Security** (`Info.plist`): ```xml NSAppTransportSecurity NSAllowsArbitraryLoads ``` Don't whitelist domains for ATS exception unless you have to (e.g., legacy partner API). - **Android Network Security Config** (`res/xml/network_security_config.xml`): ```xml ``` Reference in `AndroidManifest.xml`: `android:networkSecurityConfig="@xml/network_security_config"`. ### Certificate Pinning — When to Pin Pinning protects against rogue CAs (a real risk in some networks). It also creates BREAKAGE risk: if your cert rotates and the pinned hash is stale, every user is locked out. **Pin when**: - App handles money or PII at high stakes (banking, healthcare, authentication infrastructure). - You can guarantee certificate rotation coordination (CI updates the app + the API in lockstep). **Don't pin when**: - Standard consumer app, no critical data flow. - You can't operationally manage rotation (you'll DDoS yourself with broken updates). ### How to Pin Pin the SUBJECT PUBLIC KEY HASH (SPKI), not the full certificate. SPKI survives cert rotation as long as you keep the same key. ```typescript // react-native-ssl-pinning OR axios + custom adapter import { fetch as pinnedFetch } from 'react-native-ssl-pinning'; const res = await pinnedFetch('https://api.app.com/lessons', { method: 'GET', sslPinning: { certs: ['cert-spki-sha256'], // base64-encoded SHA-256 of SPKI }, headers: { Authorization: `Bearer ${token}` }, }); ``` **Pin two keys** (current + backup) so rotation is non-breaking. Generate the backup key, store it offline, swap to it during rotation. ### Pin Failure Behavior DON'T just throw. Show user "Connection couldn't be verified — please update the app." Log to your error reporter. Provide an unpinned fallback if you have a graceful recovery path (most apps shouldn't). ## Biometric Auth (Local UX Gate, NOT Server Trust) Biometrics on the client are a UX gate — they unlock locally-stored tokens. They are NOT proof to the server that the user is who they claim. The server still relies on the actual session token / WebAuthn signature. ```typescript import * as Keychain from 'react-native-keychain'; async function unlockApp(): Promise { try { const creds = await Keychain.getGenericPassword({ service: 'com.app.session', authenticationPrompt: { title: 'Unlock', subtitle: 'Use Face ID to access your account', cancel: 'Use passcode', }, }); return creds ? creds.password : null; } catch (e: any) { if (e.code === 'AuthenticationFailed' || e.code === 'UserCanceled') { return null; } throw e; } } ``` Re-prompt cadence: - App cold launch → always. - App backgrounded > 60 seconds → re-prompt. - Sensitive op (transfer money, view 2FA codes) → re-prompt every time. ## Detecting Root / Jailbreak OWASP MASVS L2: should detect tampered runtime. For most consumer apps this is overkill; add when: - App handles money or compliance-required data. - You've seen abuse from rooted devices. ```typescript import JailMonkey from 'jail-monkey'; if (JailMonkey.isJailBroken()) { // Soft block: warn user, refuse to enable sensitive features. // Hard block: refuse to launch (some banks do this; loses legitimate users with rooted dev devices). } ``` JailMonkey checks: presence of `Cydia.app` (iOS), `su` binary (Android), busybox, write to `/system`, etc. Not bulletproof — determined attackers bypass it. Use as a deterrent + a server-side signal (clients with elevated risk get extra verification). ## Deep Link Injection Deep links can carry malicious payloads. Validate every parameter: ```typescript // linking.ts config: { screens: { Lesson: { path: 'lessons/:lessonId', parse: { lessonId: (raw: string) => { if (!/^lsn_[a-zA-Z0-9]{8,32}$/.test(raw)) { throw new Error('invalid lesson id'); } return raw; }, }, }, PasswordReset: { path: 'auth/reset/:token', parse: { token: (raw: string) => { if (!/^[A-Za-z0-9_-]{32,128}$/.test(raw)) { throw new Error('invalid reset token'); } return raw; }, }, }, }, }, ``` For deep links that authenticate the user (magic link, password reset), additional rules: - Reject if NOT served via HTTPS app link (refuse custom scheme for these). - Server-side: token is single-use, short-lived, scoped to action. - Client: render a "this will sign you in as user@example.com — confirm?" screen before action; defeat clickjacking. ## App Switcher / Background Redaction iOS takes a screenshot for the app switcher. If sensitive data is on screen, the screenshot lives in the cache. ```typescript import { useEffect, useState } from 'react'; import { AppState } from 'react-native'; export function useBackgroundRedaction(): boolean { const [redact, setRedact] = useState(false); useEffect(() => { const sub = AppState.addEventListener('change', (s) => { // 'inactive' is the correct trigger for the switcher screenshot. setRedact(s !== 'active'); }); return () => sub.remove(); }, []); return redact; } // In sensitive screens: const redact = useBackgroundRedaction(); return redact ? : ; ``` Android: optionally `setFlags(WindowManager.LayoutParams.FLAG_SECURE)` to prevent screenshots and screen recording entirely. Use sparingly — frustrating in normal use. ## Logging Hygiene NEVER log: - Auth tokens (Authorization header, cookies). - Passwords (even hashed). - TOTP codes / backup codes. - Session IDs. - PII: full names, emails, phone, addresses, payment details, government IDs. - Long IDs that uniquely identify users (use a hash or a short stub). Patterns to enforce: ```typescript // Strip sensitive headers from API client logs. api.interceptors.request.use((cfg) => { if (__DEV__) console.log('[api]', cfg.method, cfg.url); // NO body, NO headers return cfg; }); // In the framework error reporter: Sentry.init({ beforeBreadcrumb(breadcrumb) { if (breadcrumb.category === 'http') { delete breadcrumb.data?.request_body; delete breadcrumb.data?.response_body; } return breadcrumb; }, beforeSend(event) { return scrubPII(event); }, }); // Strip in release builds: // babel-plugin-transform-remove-console: removes all console.* in production. ``` ## SDKs — Audit Risky Permissions Many third-party SDKs request more than they need. On every dependency add: 1. Read the SDK's permission requirements. 2. Verify in the merged manifest (`./gradlew app:dependencies` + look at the rendered AndroidManifest). 3. Check for: `READ_PHONE_STATE`, `ACCESS_FINE_LOCATION`, `READ_CONTACTS`, `RECORD_AUDIO`, `READ_EXTERNAL_STORAGE`, `BIND_ACCESSIBILITY_SERVICE`. 4. If the SDK adds a permission your app doesn't need, find an alternative or use the manifest `` to strip it. Common offenders: certain ad SDKs, some analytics SDKs, push notification wrappers that ask for location. Stick to first-party / well-known options when possible (Firebase, Sentry, Notifee). ## Native Module Surface — Threat Vector A native module is direct OS access from JS. Audit yours and any third-party ones for: - Arbitrary file read/write (a malicious JS could exfiltrate any file the app can read). - Arbitrary command execution (`exec`, `Runtime.exec`). - Network calls bypassing your TLS config. - Plain-text credential storage. For modules you write: validate inputs at the JS↔native boundary; never trust JS-side strings/numbers. ```swift // iOS @objc(set:value:resolve:reject:) func set(_ key: String, value: String, resolve: ..., reject: ...) { guard key.count <= 256, value.count <= 16384 else { reject("BAD_INPUT", "size limit", nil) return } // ... safe operation } ``` ## Pre-Submission Security Review Use [assets/mobile-security-checklist.md](assets/mobile-security-checklist.md) before TestFlight/Play Internal. Run an automated scan with **MobSF** (Mobile Security Framework) on the release build — catches common issues (cleartext traffic, debuggable=true, weak crypto). For more thorough audit: OWASP MASVS L1 covers consumer apps; L2 + L3 are for high-risk apps (banking, government). ## Common Mobile-Security Mistakes 1. **Tokens in AsyncStorage / unencrypted MMKV** — trivially read via filesystem inspection or backup. 2. **TOTP secret on device** — device compromise = 2FA bypass. 3. **No biometric prompt for sensitive ops** — lost-phone scenario gives full access. 4. **Pinning without rotation strategy** — DDoS yourself the day cert renews. 5. **Pin failure throws raw error** — confuses users who can't update. 6. **Deep-link params not validated** — path traversal, SQLi via QR code. 7. **Logging Authorization header** in production traces — leaks session tokens to Sentry / Crashlytics. 8. **Sensitive views not redacted on background** — screenshot cache leak. 9. **Backup not excluded for sensitive files** — iCloud / Google backup = data leak. 10. **Debuggable=true in release** — anyone can attach a debugger and inspect memory. 11. **No R8/ProGuard** on Android release — class names leaked, easier reversing. 12. **Trusting client-side auth flags** — `if (user.isAdmin)` on the client is meaningless; server must check. 13. **Cleartext fallback in network config** — defeats TLS purpose. 14. **WebView with `setAllowFileAccess(true)`** — trivial file read from page JS. 15. **Insecure WebView origin checks** — postMessage from any page wins. ## Source Material - *OWASP MASVS v2.0* (2024 release) — primary standard. - *OWASP MSTG* (Mobile Security Testing Guide) — practical patterns per requirement. - Apple — *App Security Overview* + *Keychain Services Programming Guide*. - Android — *App Security Best Practices* + *Network Security Configuration*. - *MobSF* (Mobile Security Framework) — automated scanner. - React Native Security: