/mobile-security-react-native

name: mobile-security-react-native
description: Secure storage, certificate pinning, biometric auth, jailbreak detection, code obfuscation, network security, screenshot prevention for React Native

React Native Security Patterns

> **Quick Guide:** Defense-in-depth: layer secure storage (expo-secure-store or react-native-keychain), certificate pinning, biometric authentication, jailbreak/root detection, and code obfuscation. Never store secrets in AsyncStorage or JS bundles. Use Hermes bytecode as your first obfuscation layer. iOS Keychain persists across reinstalls; Android Keystore does not. Certificate pins require at least two hashes (primary + backup) on iOS.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST NEVER store tokens, passwords, API keys, or PII in AsyncStorage or plain-text files -- use hardware-backed secure storage)**

**(You MUST use at least two public key hashes for certificate pinning on iOS -- TrustKit/iOS enforces this and will throw if only one is provided)**

**(You MUST treat jailbreak/root detection as one layer in defense-in-depth -- client-side checks can be bypassed, always validate server-side too)**

**(You MUST configure both iOS ATS and Android Network Security Config to enforce HTTPS -- never ship with `NSAllowArbitraryLoads: true` in production)**

**(You MUST add `NSFaceIDUsageDescription` to Info.plist when using Face ID -- the OS silently falls back to passcode without it)**

</critical_requirements>

---

**Auto-detection:** secure storage, SecureStore, expo-secure-store, react-native-keychain, Keychain, Keystore, certificate pinning, SSL pinning, react-native-ssl-public-key-pinning, TrustKit, jailbreak detection, root detection, jail-monkey, biometric authentication, expo-local-authentication, Face ID, Touch ID, fingerprint, code obfuscation, Hermes bytecode, ProGuard, R8, screen capture prevention, App Transport Security, Network Security Config, MITM

**When to use:**

• Storing credentials, tokens, or sensitive data on device
• Implementing certificate pinning to prevent MITM attacks
• Adding biometric authentication (Face ID, Touch ID, fingerprint)
• Detecting jailbroken/rooted devices
• Hardening builds with code obfuscation (Hermes, ProGuard/R8)
• Preventing screenshot/screen recording of sensitive screens
• Configuring network security (ATS on iOS, Network Security Config on Android)

**When NOT to use:**

• General React Native component architecture (not a security concern)
• Server-side API security (use your backend security approach)
• Web-only applications (web security patterns differ fundamentally)

**Key patterns covered:**

• Secure storage with expo-secure-store and react-native-keychain
• Certificate pinning with react-native-ssl-public-key-pinning
• Biometric authentication with expo-local-authentication and react-native-keychain
• Jailbreak/root detection with jail-monkey
• Code obfuscation: Hermes bytecode, Metro transformer, ProGuard/R8
• Network security: iOS ATS and Android Network Security Config
• Screenshot and screen recording prevention
• Defense-in-depth strategy and security layering

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Secure storage, certificate pinning, biometric auth
• [examples/hardening.md](examples/hardening.md) - Code obfuscation, jailbreak detection, screenshot prevention, network config
• [reference.md](reference.md) - Security checklist, library API reference, pin hash commands

---

<philosophy>

Philosophy

Mobile security is **defense-in-depth** -- no single measure is sufficient. Attackers can bypass any individual protection, so layer multiple defenses: secure storage protects data at rest, certificate pinning protects data in transit, biometric authentication protects access, jailbreak detection identifies compromised environments, and code obfuscation raises the cost of reverse engineering.

**Core principles:**

1. **Never trust the client** -- all sensitive operations need server-side validation. Client-side checks are speed bumps, not walls. 2. **Hardware-backed storage** -- iOS Keychain and Android Keystore provide hardware-level encryption. AsyncStorage is a plain-text file. 3. **HTTPS everywhere** -- enforce TLS for all network communication. Certificate pinning adds a second layer against compromised CAs. 4. **Minimal data exposure** -- store the least sensitive data possible on device. Prefer short-lived tokens over long-lived credentials. 5. **Fail secure** -- when security checks fail (biometric, jailbreak), deny access by default rather than falling back to insecure paths.

**Mental model:**

Think of mobile security as concentric rings. Each ring (secure storage, pinning, biometrics, obfuscation, jailbreak detection) independently slows attackers. The combination creates a security posture that makes exploitation impractical for most threat models.

**Platform differences that matter:**

| Concern | iOS | Android | |---------|-----|---------| | Secure storage | Keychain (persists across reinstalls) | Keystore + SharedPreferences (cleared on uninstall) | | Biometrics | Face ID / Touch ID | Fingerprint / Face Unlock (weak vs strong) | | Network security | ATS (default HTTPS since iOS 9) | Network Security Config (clear text blocked API 28+) | | Code protection | Hermes bytecode (no ProGuard for JS) | Hermes bytecode + ProGuard/R8 for native/Java | | Screenshot prevention | Effective (screen recording + screenshots) | FLAG_SECURE (effective for screenshots, partial for recording) |

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Secure Storage

Two main libraries: **expo-secure-store** (Expo-managed, simpler API, 2KB value limit) and **react-native-keychain** (bare RN, biometric-protected credentials, no size limit).

**expo-secure-store** uses iOS Keychain and A