@zigrivers/scaffold 3.6.0 → 3.8.0

package/content/knowledge/mobile-app/mobile-app-requirements.md

@@ -0,0 +1,147 @@
+---
+name: mobile-app-requirements
+description: Platform guidelines (Apple HIG, Material Design), performance budgets, device matrix, and accessibility requirements for mobile apps
+topics: [mobile-app, requirements, hig, material-design, accessibility, performance, device-matrix]
+---
+
+Mobile app requirements differ fundamentally from web requirements: platform guidelines are design law, not suggestions; performance budgets are stricter because CPU and battery are finite; accessibility is both a legal obligation and a market expansion. Define all of these explicitly before writing code — changing navigation patterns or accessibility models mid-project is expensive.
+
+## Summary
+
+Mobile app requirements encompass platform design guidelines (Apple HIG for iOS, Material Design for Android), performance budgets (launch time, frame rate, memory), device matrix coverage, and accessibility compliance. iOS and Android have distinct design languages, interaction patterns, and review processes — apps that ignore platform conventions face App Store rejection or poor user ratings. Document requirements across all four dimensions before implementation begins.
+
+## Deep Guidance
+
+### Apple Human Interface Guidelines (HIG)
+
+The HIG is not aspirational — App Store review uses it as a rejection criterion. Key rules:
+
+**Navigation patterns**
+- iOS uses tab bars for top-level navigation, not drawers. Bottom navigation bars with 2–5 items represent the canonical iOS navigation pattern.
+- Navigation controllers manage hierarchical content with back-button semantics. Never intercept the swipe-back gesture unless replacing it with an equivalent interaction.
+- Modal presentations are for transient tasks that interrupt the main flow. Use `.sheet` (card modal) or `.fullScreenCover` (full-screen modal) appropriately.
+- Avoid Android-style hamburger drawers on iOS — they are foreign to the platform and fail review for poor HIG compliance.
+
+**Visual design**
+- Use SF Symbols for iconography on iOS — they scale with Dynamic Type and render at all weights automatically.
+- Respect the safe area insets: status bar, home indicator, and notch are system-owned. Never place interactive controls behind them.
+- Support Dynamic Type: all text must scale from accessibility-small to accessibility-xxxlarge. Hard-coded font sizes fail accessibility audits.
+- Dark mode is not optional — it has been mandatory since iOS 13. Every screen must render correctly in both modes.
+
+**Interaction**
+- Minimum tap target size: 44×44 points. Smaller targets fail accessibility review and frustrate users on small devices.
+- Haptic feedback should mirror system patterns: `.impactOccurred()` for selections, `.notificationOccurred(.success/.error/.warning)` for outcomes.
+- Do not disable system gestures (pull-to-refresh, swipe-back, swipe-from-edge) without providing explicit equivalents.
+
+### Material Design Guidelines (Android)
+
+Material Design 3 (Material You) is the current standard for Android apps. Google Play review does not enforce it as strictly as Apple enforces HIG, but departure from Material patterns drives poor reviews.
+
+**Navigation patterns**
+- Bottom Navigation Bar for 3–5 top-level destinations (matches iOS tab bar in position and purpose).
+- Navigation Drawer for apps with 6+ top-level destinations or complex content hierarchies.
+- Top App Bar for screen titles, primary actions, and back navigation.
+- Use Navigation Component (Jetpack) with a NavGraph to manage the back stack. Manual FragmentTransaction management leads to back-stack corruption.
+
+**Visual design**
+- Material You uses dynamic color: the system extracts a palette from the wallpaper and applies it app-wide. Apps must use Material theme color roles (`colorPrimary`, `colorSurface`, etc.) — hard-coded hex colors break dynamic theming.
+- Typography scale: use `MaterialTheme.typography.*` roles (displayLarge, headlineMedium, bodyLarge, etc.), not arbitrary font sizes.
+- Elevation and shadows communicate hierarchy — use Material elevation tokens, not custom shadow implementations.
+
+**Components**
+- Use Material components from `androidx.compose.material3` (Compose) or `com.google.android.material` (View system) — custom implementations break adaptive theming.
+- Extended FAB for primary actions, regular FAB only when the action is obvious from context.
+- BottomSheet for contextual actions; Dialog for decisions requiring user input.
+
+### Performance Budgets
+
+Define performance budgets before implementation — retrofitting them is expensive.
+
+**App launch time**
+- Cold start target: under 2 seconds to interactive on a mid-range device (Pixel 4a / iPhone SE 3rd gen)
+- Warm start target: under 500ms
+- Measure with: Instruments (iOS Time Profiler), Android Studio CPU Profiler, Firebase Performance Monitoring
+- Common cold-start killers: synchronous disk I/O on main thread, large dependency graphs initialized eagerly, synchronous network calls before first frame
+
+**Frame rate**
+- Target: 60fps sustained (16ms frame budget), 120fps on ProMotion/high-refresh displays where supported
+- Drop below 60fps is visible as "jank" — users notice immediately
+- iOS: use Instruments > Core Animation template to identify dropped frames
+- Android: Profile GPU Rendering overlay (`adb shell setprop debug.hwui.profile true`) and Systrace
+
+**Memory**
+- iOS: no hard memory limit, but the OS kills apps under memory pressure. Monitor with Instruments > Allocations and Leaks.
+- Android: device RAM tiers vary wildly. Budget 100MB heap for mid-range, test on 2GB RAM devices.
+- Avoid memory leaks from retained Contexts (Android), strong reference cycles (iOS), and non-cancelled subscriptions.
+
+**Battery**
+- Background work must use platform APIs: WorkManager (Android), BGTaskScheduler (iOS). Raw background threads are killed and drain battery.
+- Network: batch requests, respect retry-after headers, use conditional requests (ETags) to avoid redundant data transfer.
+- Location: use the least precise location mode needed. Continuous GPS is the fastest path to a 1-star review.
+
+**Network**
+- Assume 3G on first launch — many users install apps on slow connections.
+- App binary size: iOS App Store thin-slicing reduces download size per device; still target under 50MB download, under 200MB install.
+- Android App Bundle (AAB) enables Play Store to serve device-optimized APKs — always build AAB for production, not APK.
+
+### Device Matrix
+
+Define the device matrix explicitly. Not all devices need testing — define tiers:
+
+**Tier 1 (must pass)**
+- iOS: current iPhone model, iPhone SE (latest), iPad (if universal app)
+- Android: current Pixel, Samsung Galaxy S-series, mid-range device (e.g., Pixel 4a or Samsung A-series)
+- OS versions: current and N-1 major (e.g., iOS 18 and 17, Android 15 and 14)
+
+**Tier 2 (should pass)**
+- iOS: 2-generation-old iPhone, older iPad models
+- Android: budget device with 2GB RAM, tablet (if supporting large-screen)
+- OS versions: N-2 for iOS, Android 13 for broader coverage
+
+**Minimum OS versions**
+- iOS: typically N-2 years of support. In 2025, iOS 16+ covers ~95% of active devices.
+- Android: API level 26 (Android 8.0) covers ~98% of active devices as of 2025. Most new projects target minSdk 26.
+- Document the min-OS decision explicitly — lowering it later breaks APIs; raising it is a business decision.
+
+**Screen size breakpoints (iOS)**
+- 375pt wide: iPhone SE/iPhone mini
+- 390pt wide: iPhone 14/15 standard
+- 430pt wide: iPhone 14/15 Pro Max
+- 768pt wide: iPad (compact width in split view)
+- 1024pt+: iPad full screen
+
+**Screen size breakpoints (Android)**
+- 360dp: compact (phone portrait)
+- 600dp: medium (phone landscape, small tablet)
+- 840dp+: expanded (tablet, foldable unfolded)
+- Use Window Size Classes (Jetpack Compose) to adapt layout to these breakpoints.
+
+### Accessibility Requirements
+
+Accessibility is legally required (ADA in the US, EN 301 549 in the EU) and a quality signal in app store reviews.
+
+**iOS VoiceOver**
+- Every interactive element must have an `accessibilityLabel` that describes its purpose (not its visual appearance).
+- Semantic roles: use `accessibilityTraits` (.button, .header, .image, .link) so VoiceOver announces element type.
+- Custom controls must implement `UIAccessibilityElement` or use SwiftUI's `.accessibilityElement(children:)` modifier.
+- Group related elements with `shouldGroupAccessibilityChildren` to reduce VoiceOver navigation steps.
+
+**Android TalkBack**
+- `contentDescription` on all `ImageView`, `ImageButton`, and custom views. Views with `android:text` inherit their label automatically.
+- `android:importantForAccessibility="no"` for decorative elements that should be skipped.
+- Jetpack Compose: use `Modifier.semantics { contentDescription = "..." }` and role modifiers.
+
+**Minimum contrast ratios (WCAG AA)**
+- Normal text: 4.5:1 contrast ratio against background
+- Large text (18pt+ or 14pt+ bold): 3:1 contrast ratio
+- Interactive elements and focus indicators: 3:1 against adjacent colors
+- Use `Color Contrast Analyzer` or Xcode Accessibility Inspector to verify.
+
+**Dynamic Type / Font Scaling**
+- iOS: test with Accessibility > Larger Text > maximum setting (~235% scale). All text must remain readable and not overflow containers.
+- Android: test with Display > Font size at the largest setting. Use `sp` units (never `dp` or `px`) for all text.
+
+**Motor accessibility**
+- Switch Control (iOS) and Switch Access (Android): all interactive elements must be reachable via sequential switch scanning.
+- Do not rely solely on swipe gestures for core functionality — provide tap-target alternatives.
+- Minimum touch target: 44pt (iOS) / 48dp (Android).

package/content/knowledge/mobile-app/mobile-app-security.md

@@ -0,0 +1,338 @@
+---
+name: mobile-app-security
+description: Secure storage (Keychain/Keystore), certificate pinning, biometric authentication, jailbreak/root detection, and data protection for mobile apps
+topics: [mobile-app, security, keychain, keystore, certificate-pinning, biometrics, jailbreak-detection, data-protection]
+---
+
+Mobile apps operate in an adversarial environment: devices are lost or stolen, users jailbreak/root their devices, and network traffic is subject to interception. Security must be designed in, not bolted on. The most common mobile security failures are storing secrets in plaintext, trusting all TLS certificates (or disabling certificate validation), and failing to protect data at rest. Implement defense in depth — assume any single control will fail.
+
+## Summary
+
+Mobile security requires secure storage (iOS Keychain, Android Keystore/EncryptedSharedPreferences), certificate pinning to prevent MITM attacks, biometric authentication for sensitive operations, and data-at-rest protection. Avoid storing sensitive data in logs, shared preferences, UserDefaults, or anywhere outside secure enclaves. Jailbreak/root detection adds a deterrent layer but is not a reliable security boundary. Apply OWASP Mobile Top 10 as the minimum security baseline.
+
+## Deep Guidance
+
+### Secure Storage
+
+**iOS Keychain**
+
+The Keychain is the correct location for all sensitive data: tokens, passwords, cryptographic keys, and session identifiers. It survives app reinstallation (with the right accessibility class) and is hardware-backed on devices with a Secure Enclave.
+
+```swift
+import Security
+
+enum KeychainError: Error {
+    case duplicateEntry, itemNotFound, unexpectedStatus(OSStatus)
+}
+
+struct Keychain {
+    static func save(key: String, data: Data, accessibility: CFString = kSecAttrAccessibleWhenUnlocked) throws {
+        let query: [CFString: Any] = [
+            kSecClass: kSecClassGenericPassword,
+            kSecAttrAccount: key,
+            kSecValueData: data,
+            kSecAttrAccessible: accessibility
+        ]
+
+        let status = SecItemAdd(query as CFDictionary, nil)
+        if status == errSecDuplicateItem {
+            // Update existing item
+            let updateQuery: [CFString: Any] = [kSecClass: kSecClassGenericPassword, kSecAttrAccount: key]
+            let updateFields: [CFString: Any] = [kSecValueData: data]
+            let updateStatus = SecItemUpdate(updateQuery as CFDictionary, updateFields as CFDictionary)
+            guard updateStatus == errSecSuccess else { throw KeychainError.unexpectedStatus(updateStatus) }
+        } else if status != errSecSuccess {
+            throw KeychainError.unexpectedStatus(status)
+        }
+    }
+
+    static func load(key: String) throws -> Data {
+        let query: [CFString: Any] = [
+            kSecClass: kSecClassGenericPassword,
+            kSecAttrAccount: key,
+            kSecReturnData: true,
+            kSecMatchLimit: kSecMatchLimitOne
+        ]
+        var result: AnyObject?
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        guard status == errSecSuccess, let data = result as? Data else {
+            throw KeychainError.itemNotFound
+        }
+        return data
+    }
+
+    static func delete(key: String) {
+        let query: [CFString: Any] = [kSecClass: kSecClassGenericPassword, kSecAttrAccount: key]
+        SecItemDelete(query as CFDictionary)
+    }
+}
+```
+
+**Keychain accessibility classes — choose carefully**
+- `kSecAttrAccessibleWhenUnlocked`: accessible only when device is unlocked. Correct for most cases.
+- `kSecAttrAccessibleAfterFirstUnlock`: accessible after first unlock until device restarts. For background-accessible tokens (e.g., background sync auth).
+- `kSecAttrAccessibleWhenPasscodeSetThisDeviceOnly`: requires a passcode to be set; deleted if passcode is removed. Highest security, not backed up.
+- `kSecAttrAccessibleAlways`: accessible even when locked. Never use — completely defeats protection.
+- Append `ThisDeviceOnly` to any class to prevent iCloud Keychain sync (appropriate for session tokens).
+
+**Android: Keystore + EncryptedSharedPreferences**
+
+The Android Keystore stores cryptographic keys in hardware (on supported devices). Use it to encrypt data stored on disk:
+
+```kotlin
+// EncryptedSharedPreferences — simplest secure storage for small values
+val masterKey = MasterKey.Builder(context)
+    .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+    .build()
+
+val securePrefs = EncryptedSharedPreferences.create(
+    context,
+    "secure_prefs",
+    masterKey,
+    EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+    EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+)
+securePrefs.edit().putString("auth_token", token).apply()
+val token = securePrefs.getString("auth_token", null)
+```
+
+For larger data (full database encryption), use SQLCipher or Room with SQLCipher:
+```kotlin
+val passphrase = SQLiteDatabase.getBytes(keyFromKeystore)
+val factory = SupportFactory(passphrase)
+Room.databaseBuilder(context, AppDatabase::class.java, "app.db")
+    .openHelperFactory(factory)
+    .build()
+```
+
+**What NOT to store in insecure storage**
+- Never use `NSUserDefaults`/`UserDefaults` for tokens, passwords, or PII
+- Never use `SharedPreferences` (unencrypted) for sensitive data
+- Never write credentials to log output — logs are readable by other apps and crash reporters
+- Never store sensitive data in the app's Documents or Cache directories without encryption
+- Never put secrets in `Info.plist`, `AndroidManifest.xml`, or any file tracked in git
+
+### Certificate Pinning
+
+Certificate pinning prevents MITM attacks by refusing connections to servers that don't present the expected certificate (or a certificate from the expected CA chain).
+
+**iOS: TrustKit or URLSession manual pinning**
+```swift
+// URLSession delegate-based pinning
+class PinnedURLSessionDelegate: NSObject, URLSessionDelegate {
+    // Expected certificate public key hashes (SHA-256, base64-encoded)
+    private let pinnedHashes: Set<String> = [
+        "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",  // Current cert
+        "BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="   // Backup cert
+    ]
+
+    func urlSession(
+        _ session: URLSession,
+        didReceive challenge: URLAuthenticationChallenge,
+        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
+    ) {
+        guard challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust,
+              let serverTrust = challenge.protectionSpace.serverTrust else {
+            completionHandler(.cancelAuthenticationChallenge, nil)
+            return
+        }
+
+        // Extract public key hash from server certificate
+        if let hash = publicKeyHash(from: serverTrust), pinnedHashes.contains(hash) {
+            completionHandler(.useCredential, URLCredential(trust: serverTrust))
+        } else {
+            completionHandler(.cancelAuthenticationChallenge, nil)
+        }
+    }
+}
+```
+
+**Android: OkHttp CertificatePinner**
+```kotlin
+val certificatePinner = CertificatePinner.Builder()
+    .add("api.example.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")
+    .add("api.example.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=") // backup pin
+    .build()
+
+val client = OkHttpClient.Builder()
+    .certificatePinner(certificatePinner)
+    .build()
+```
+
+**Certificate pinning operational rules**
+- Always pin at least two certificates: the current certificate and a backup (intermediate CA or pre-generated backup)
+- A pinned app with no backup pin is bricked when the certificate rotates — this is an outage
+- Certificate rotation procedure: add new cert pin 30+ days before rotating, deploy app update, rotate certificate, remove old pin in next app version
+- Never pin in debug builds — intercepting proxies (Charles, mitmproxy) are required for debugging
+- Consider using a reporting-only mode that logs failures without blocking before enforcing
+
+### Biometric Authentication
+
+**iOS: LocalAuthentication**
+```swift
+import LocalAuthentication
+
+func authenticateWithBiometrics() async throws {
+    let context = LAContext()
+    var error: NSError?
+
+    guard context.canEvaluatePolicy(.deviceOwnerAuthenticationWithBiometrics, error: &error) else {
+        throw error ?? LAError(.biometryNotAvailable)
+    }
+
+    try await context.evaluatePolicy(
+        .deviceOwnerAuthenticationWithBiometrics,
+        localizedReason: "Authenticate to view your account"
+    )
+}
+```
+
+- `.deviceOwnerAuthenticationWithBiometrics`: Face ID / Touch ID only. Falls back to nothing if unavailable.
+- `.deviceOwnerAuthentication`: Face ID / Touch ID, then falls back to device passcode. Preferred for high-security gates.
+- `LAContext.biometryType`: check whether device has Face ID, Touch ID, or neither — customize the prompt accordingly
+- Store the biometric-protected secret in the Keychain with `SecAccessControl` binding the item to biometric authentication
+
+**iOS: Keychain + biometric binding**
+```swift
+var error: Unmanaged<CFError>?
+guard let access = SecAccessControlCreateWithFlags(
+    nil,
+    kSecAttrAccessibleWhenUnlockedThisDeviceOnly,
+    [.biometryCurrentSet, .privateKeyUsage],  // biometryCurrentSet invalidates if biometrics change
+    &error
+) else { throw error!.takeRetainedValue() as Error }
+
+let query: [CFString: Any] = [
+    kSecClass: kSecClassGenericPassword,
+    kSecAttrAccount: "high_value_token",
+    kSecValueData: tokenData,
+    kSecAttrAccessControl: access
+]
+SecItemAdd(query as CFDictionary, nil)
+```
+
+**Android: BiometricPrompt**
+```kotlin
+val biometricPrompt = BiometricPrompt(
+    fragment,
+    executor,
+    object : BiometricPrompt.AuthenticationCallback() {
+        override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+            // result.cryptoObject contains cipher if used with CryptoObject
+            onSuccess()
+        }
+        override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+            onError(errString.toString())
+        }
+    }
+)
+
+val promptInfo = BiometricPrompt.PromptInfo.Builder()
+    .setTitle("Authenticate")
+    .setSubtitle("Access your account")
+    .setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
+    .build()
+
+biometricPrompt.authenticate(promptInfo)
+```
+
+### Jailbreak and Root Detection
+
+**iOS jailbreak detection heuristics**
+```swift
+func isJailbroken() -> Bool {
+    #if targetEnvironment(simulator)
+    return false
+    #else
+    // Check for common jailbreak files
+    let jailbreakPaths = [
+        "/Applications/Cydia.app",
+        "/usr/sbin/sshd",
+        "/etc/apt",
+        "/private/var/lib/apt/"
+    ]
+    if jailbreakPaths.contains(where: { FileManager.default.fileExists(atPath: $0) }) {
+        return true
+    }
+
+    // Check if sandboxing has been violated
+    let testPath = "/private/jailbreak_test_\(UUID().uuidString)"
+    do {
+        try "test".write(toFile: testPath, atomically: true, encoding: .utf8)
+        try FileManager.default.removeItem(atPath: testPath)
+        return true  // Wrote outside sandbox — jailbroken
+    } catch { }
+
+    return false
+    #endif
+}
+```
+
+**Android root detection**
+```kotlin
+fun isRooted(): Boolean {
+    val rootIndicators = listOf(
+        "/system/app/Superuser.apk",
+        "/sbin/su",
+        "/system/bin/su",
+        "/system/xbin/su"
+    )
+    if (rootIndicators.any { File(it).exists() }) return true
+
+    // Try to execute su
+    return try {
+        Runtime.getRuntime().exec(arrayOf("/system/xbin/which", "su"))
+        true
+    } catch (e: Exception) { false }
+}
+```
+
+**Jailbreak detection limitations**
+- All detection methods can be bypassed by a sufficiently motivated attacker — jailbreak detection is a deterrent, not a security boundary
+- Use it to degrade security guarantees (warn users) rather than block the app entirely
+- Consider integrating a commercial solution (Guardsquare, Promon, Approov) for higher-assurance requirements
+
+### Data Protection
+
+**iOS Data Protection API**
+Files stored on iOS can be encrypted with additional protection tied to the device unlock state:
+
+```swift
+// Write file with data protection
+let data = sensitiveData
+let url = documentsDirectory.appendingPathComponent("sensitive.dat")
+try data.write(to: url, options: [.completeFileProtection])
+// kSecAttrAccessibleWhenUnlocked equivalent for files
+```
+
+Protection classes:
+- `completeFileProtection`: accessible only when unlocked
+- `completeFileProtectionUnlessOpen`: accessible when unlocked or if the file was open when locked
+- `completeFileProtectionUntilFirstUserAuthentication`: accessible after first unlock
+- Set app-wide default in Info.plist: `NSFileProtectionKey: NSFileProtectionComplete`
+
+**Android: Scoped Storage**
+Android 10+ enforces scoped storage — apps can no longer access arbitrary filesystem paths:
+- Use `MediaStore` API for photos, videos, and audio shared with other apps
+- Use app-specific directories (`context.filesDir`, `context.cacheDir`) for private data
+- Request `READ_MEDIA_IMAGES` permission (Android 13+) instead of `READ_EXTERNAL_STORAGE`
+
+**Network security configuration (Android)**
+```xml
+<!-- res/xml/network_security_config.xml -->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false">
+        <trust-anchors>
+            <certificates src="system"/>
+        </trust-anchors>
+    </base-config>
+    <!-- Allow cleartext for localhost in debug only -->
+    <debug-overrides>
+        <domain-config cleartextTrafficPermitted="true">
+            <domain includeSubdomains="true">localhost</domain>
+        </domain-config>
+    </debug-overrides>
+</network-security-config>
+```
+
+Set `cleartextTrafficPermitted="false"` globally and enforce HTTPS everywhere. This is the Android equivalent of iOS's App Transport Security.