@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/android-security/SKILL.md

@@ -0,0 +1,577 @@
+---
+name: android-security
+description: "Secure Android apps with ProGuard/R8 obfuscation, OkHttp certificate pinning, BiometricPrompt authentication, EncryptedSharedPreferences, Play Integrity API, root detection, secure network communication, and API key protection via local.properties and BuildConfig. Use when implementing security features, auditing app security, handling sensitive data, or preparing for production release."
+---
+
+# Android Security
+
+Security patterns for Android apps covering data storage, network security,
+authentication, integrity verification, and obfuscation. Targets 2024-2025
+best practices with AndroidX Security, BiometricPrompt, and Play Integrity.
+
+## Contents
+
+- [Secure Data Storage](#secure-data-storage)
+- [Biometric Authentication](#biometric-authentication)
+- [Certificate Pinning](#certificate-pinning)
+- [API Key Protection](#api-key-protection)
+- [R8 Obfuscation](#r8-obfuscation)
+- [Play Integrity API](#play-integrity-api)
+- [Root Detection](#root-detection)
+- [Secure Network Communication](#secure-network-communication)
+- [Secure Coding Patterns](#secure-coding-patterns)
+- [Do's and Don'ts](#dos-and-donts)
+- [Troubleshooting](#troubleshooting)
+- [Review Checklist](#review-checklist)
+
+## Secure Data Storage
+
+### EncryptedSharedPreferences
+
+For sensitive key-value data. Uses AES-256 encryption under the hood.
+
+```kotlin
+import androidx.security.crypto.EncryptedSharedPreferences
+import androidx.security.crypto.MasterKey
+
+class SecureStorage @Inject constructor(
+    @ApplicationContext private val context: Context,
+) {
+    private val masterKey = MasterKey.Builder(context)
+        .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
+        .build()
+
+    private val prefs = EncryptedSharedPreferences.create(
+        context,
+        "secure_prefs",
+        masterKey,
+        EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+        EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM,
+    )
+
+    fun saveToken(token: String) {
+        prefs.edit().putString("auth_token", token).apply()
+    }
+
+    fun getToken(): String? = prefs.getString("auth_token", null)
+
+    fun clearToken() {
+        prefs.edit().remove("auth_token").apply()
+    }
+
+    fun clearAll() {
+        prefs.edit().clear().apply()
+    }
+}
+```
+
+### Android Keystore
+
+For cryptographic key management. Keys never leave the hardware.
+
+```kotlin
+import java.security.KeyStore
+import javax.crypto.Cipher
+import javax.crypto.KeyGenerator
+import javax.crypto.SecretKey
+import javax.crypto.spec.GCMParameterSpec
+import android.security.keystore.KeyGenParameterSpec
+import android.security.keystore.KeyProperties
+
+class KeystoreManager {
+
+    companion object {
+        private const val KEYSTORE_PROVIDER = "AndroidKeyStore"
+        private const val KEY_ALIAS = "app_encryption_key"
+        private const val TRANSFORMATION = "AES/GCM/NoPadding"
+    }
+
+    private fun getOrCreateKey(): SecretKey {
+        val keyStore = KeyStore.getInstance(KEYSTORE_PROVIDER).apply { load(null) }
+
+        keyStore.getEntry(KEY_ALIAS, null)?.let { entry ->
+            return (entry as KeyStore.SecretKeyEntry).secretKey
+        }
+
+        val keyGenerator = KeyGenerator.getInstance(
+            KeyProperties.KEY_ALGORITHM_AES,
+            KEYSTORE_PROVIDER,
+        )
+
+        keyGenerator.init(
+            KeyGenParameterSpec.Builder(
+                KEY_ALIAS,
+                KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT,
+            )
+            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+            .setKeySize(256)
+            .setUserAuthenticationRequired(false)
+            .build()
+        )
+
+        return keyGenerator.generateKey()
+    }
+
+    fun encrypt(data: ByteArray): Pair<ByteArray, ByteArray> {
+        val cipher = Cipher.getInstance(TRANSFORMATION)
+        cipher.init(Cipher.ENCRYPT_MODE, getOrCreateKey())
+        val encrypted = cipher.doFinal(data)
+        return Pair(cipher.iv, encrypted)
+    }
+
+    fun decrypt(iv: ByteArray, encryptedData: ByteArray): ByteArray {
+        val cipher = Cipher.getInstance(TRANSFORMATION)
+        val spec = GCMParameterSpec(128, iv)
+        cipher.init(Cipher.DECRYPT_MODE, getOrCreateKey(), spec)
+        return cipher.doFinal(encryptedData)
+    }
+}
+```
+
+### What Goes Where
+
+| Data Type | Storage | Why |
+|-----------|---------|-----|
+| Auth tokens | EncryptedSharedPreferences | Encrypted at rest, simple API |
+| Passwords | Android Keystore + encryption | Hardware-backed security |
+| API keys | BuildConfig (build-time injection) | Not in source; obfuscated by R8 |
+| User preferences (non-sensitive) | SharedPreferences / DataStore | No encryption needed |
+| Large sensitive files | Encrypted file + Keystore key | AES encryption with hardware key |
+
+## Biometric Authentication
+
+### BiometricPrompt Setup
+
+```kotlin
+class BiometricAuthenticator @Inject constructor() {
+
+    fun authenticate(
+        activity: FragmentActivity,
+        title: String = "Authenticate",
+        subtitle: String = "Verify your identity",
+        onSuccess: () -> Unit,
+        onError: (String) -> Unit,
+    ) {
+        val biometricManager = BiometricManager.from(activity)
+        val canAuthenticate = biometricManager.canAuthenticate(
+            BiometricManager.Authenticators.BIOMETRIC_STRONG or
+            BiometricManager.Authenticators.DEVICE_CREDENTIAL
+        )
+
+        if (canAuthenticate != BiometricManager.BIOMETRIC_SUCCESS) {
+            onError(mapBiometricError(canAuthenticate))
+            return
+        }
+
+        val promptInfo = BiometricPrompt.PromptInfo.Builder()
+            .setTitle(title)
+            .setSubtitle(subtitle)
+            .setAllowedAuthenticators(
+                BiometricManager.Authenticators.BIOMETRIC_STRONG or
+                BiometricManager.Authenticators.DEVICE_CREDENTIAL
+            )
+            .build()
+
+        val callback = object : BiometricPrompt.AuthenticationCallback() {
+            override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+                onSuccess()
+            }
+
+            override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+                onError(errString.toString())
+            }
+
+            override fun onAuthenticationFailed() {
+                // Called on failed attempt but user can retry
+            }
+        }
+
+        val prompt = BiometricPrompt(activity, callback)
+        prompt.authenticate(promptInfo)
+    }
+
+    private fun mapBiometricError(code: Int): String = when (code) {
+        BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE -> "No biometric hardware"
+        BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE -> "Biometric hardware unavailable"
+        BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> "No biometrics enrolled"
+        else -> "Biometric authentication unavailable"
+    }
+}
+```
+
+### Biometric + Keystore (Crypto-Based Auth)
+
+```kotlin
+fun authenticateWithCrypto(
+    activity: FragmentActivity,
+    onSuccess: (Cipher) -> Unit,
+) {
+    val key = getOrCreateBiometricKey()
+    val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+    cipher.init(Cipher.ENCRYPT_MODE, key)
+
+    val cryptoObject = BiometricPrompt.CryptoObject(cipher)
+
+    val prompt = BiometricPrompt(activity, object : BiometricPrompt.AuthenticationCallback() {
+        override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+            result.cryptoObject?.cipher?.let(onSuccess)
+        }
+    })
+
+    prompt.authenticate(promptInfo, cryptoObject)
+}
+
+private fun getOrCreateBiometricKey(): SecretKey {
+    val keyGenerator = KeyGenerator.getInstance("AES", "AndroidKeyStore")
+    keyGenerator.init(
+        KeyGenParameterSpec.Builder("biometric_key",
+            KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT)
+            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+            .setUserAuthenticationRequired(true)
+            .setInvalidatedByBiometricEnrollment(true)
+            .build()
+    )
+    return keyGenerator.generateKey()
+}
+```
+
+## Certificate Pinning
+
+### OkHttp CertificatePinner
+
+```kotlin
+val certificatePinner = CertificatePinner.Builder()
+    .add("api.example.com", "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=") // Primary
+    .add("api.example.com", "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=") // Backup
+    .build()
+
+val client = OkHttpClient.Builder()
+    .certificatePinner(certificatePinner)
+    .build()
+```
+
+### Generating Pin Hashes
+
+```bash
+# From a domain
+openssl s_client -connect api.example.com:443 -servername api.example.com \
+    | openssl x509 -pubkey -noout \
+    | openssl pkey -pubin -outform der \
+    | openssl dgst -sha256 -binary \
+    | openssl enc -base64
+
+# From a certificate file
+openssl x509 -in cert.pem -pubkey -noout \
+    | openssl pkey -pubin -outform der \
+    | openssl dgst -sha256 -binary \
+    | openssl enc -base64
+```
+
+### Network Security Config (XML-based)
+
+```xml
+<!-- res/xml/network_security_config.xml -->
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+    <domain-config cleartextTrafficPermitted="false">
+        <domain includeSubdomains="true">api.example.com</domain>
+        <pin-set expiration="2026-01-01">
+            <pin digest="SHA-256">AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</pin>
+            <pin digest="SHA-256">BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=</pin>
+        </pin-set>
+    </domain-config>
+
+    <!-- Block cleartext for all domains -->
+    <base-config cleartextTrafficPermitted="false" />
+</network-security-config>
+```
+
+```xml
+<!-- AndroidManifest.xml -->
+<application android:networkSecurityConfig="@xml/network_security_config">
+```
+
+## API Key Protection
+
+### local.properties (Gitignored)
+
+```properties
+# local.properties -- NEVER commit this file
+MAPS_API_KEY=AIzaSyB...
+BASE_URL=https://api.example.com/
+```
+
+### Build-Time Injection
+
+```kotlin
+// build.gradle.kts
+import java.util.Properties
+
+val localProperties = Properties().apply {
+    val file = rootProject.file("local.properties")
+    if (file.exists()) load(file.inputStream())
+}
+
+android {
+    defaultConfig {
+        buildConfigField("String", "MAPS_API_KEY",
+            "\"${localProperties["MAPS_API_KEY"] ?: ""}\"")
+        buildConfigField("String", "BASE_URL",
+            "\"${localProperties["BASE_URL"] ?: "https://api.example.com/"}\"")
+    }
+}
+```
+
+### Usage in Code
+
+```kotlin
+// Access via BuildConfig -- obfuscated by R8 in release builds
+val apiKey = BuildConfig.MAPS_API_KEY
+val baseUrl = BuildConfig.BASE_URL
+```
+
+### Manifest Placeholder
+
+```kotlin
+android {
+    defaultConfig {
+        manifestPlaceholders["MAPS_API_KEY"] = localProperties["MAPS_API_KEY"] ?: ""
+    }
+}
+```
+
+```xml
+<meta-data
+    android:name="com.google.android.geo.API_KEY"
+    android:value="${MAPS_API_KEY}" />
+```
+
+## R8 Obfuscation
+
+R8 is enabled automatically when `isMinifyEnabled = true`. It performs:
+- Code shrinking (removes unused code)
+- Resource shrinking (removes unused resources)
+- Obfuscation (renames classes/methods)
+- Optimization (inlining, dead code elimination)
+
+### Mapping File
+
+R8 generates `mapping.txt` for deobfuscating crash reports:
+
+```kotlin
+android {
+    buildTypes {
+        release {
+            isMinifyEnabled = true
+            isShrinkResources = true
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro",
+            )
+        }
+    }
+}
+```
+
+Upload `mapping.txt` to Google Play Console and Firebase Crashlytics for
+readable stack traces.
+
+## Play Integrity API
+
+Verify that API requests come from a genuine app on a genuine device.
+
+```kotlin
+class IntegrityVerifier @Inject constructor(
+    @ApplicationContext private val context: Context,
+) {
+    suspend fun getIntegrityToken(nonce: String): String? {
+        return try {
+            val integrityManager = IntegrityManagerFactory.create(context)
+
+            val request = IntegrityTokenRequest.builder()
+                .setNonce(nonce)
+                .build()
+
+            val response = integrityManager
+                .requestIntegrityToken(request)
+                .await()
+
+            response.token()
+        } catch (e: Exception) {
+            null
+        }
+    }
+}
+```
+
+Send the token to your server for verification. Never verify integrity tokens
+on the client -- the server must decode and validate them via the Play Integrity
+API.
+
+## Root Detection
+
+Root detection is defense-in-depth. Determined attackers can bypass it, but it
+raises the bar.
+
+```kotlin
+object RootDetector {
+
+    fun isDeviceRooted(): Boolean =
+        checkRootBinaries() || checkSuExists() || checkRootApps()
+
+    private fun checkRootBinaries(): Boolean {
+        val paths = listOf(
+            "/system/bin/su",
+            "/system/xbin/su",
+            "/sbin/su",
+            "/system/app/Superuser.apk",
+            "/system/app/SuperSU.apk",
+        )
+        return paths.any { File(it).exists() }
+    }
+
+    private fun checkSuExists(): Boolean = try {
+        Runtime.getRuntime().exec("which su").inputStream.bufferedReader().readLine() != null
+    } catch (e: Exception) {
+        false
+    }
+
+    private fun checkRootApps(): Boolean {
+        val rootPackages = listOf(
+            "com.topjohnwu.magisk",
+            "eu.chainfire.supersu",
+            "com.koushikdutta.superuser",
+        )
+        // Check if any are installed (requires QUERY_ALL_PACKAGES or specific queries)
+        return false // Simplified -- use PackageManager in production
+    }
+}
+```
+
+Use root detection as one signal among many. Combine with Play Integrity for
+stronger guarantees.
+
+## Secure Network Communication
+
+### Enforce HTTPS
+
+```xml
+<!-- network_security_config.xml -->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+</network-security-config>
+```
+
+### Debug-Only Cleartext (for local development)
+
+```xml
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false" />
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="false">10.0.2.2</domain>
+        <domain includeSubdomains="false">localhost</domain>
+    </domain-config>
+</network-security-config>
+```
+
+### TLS Configuration
+
+```kotlin
+val spec = ConnectionSpec.Builder(ConnectionSpec.MODERN_TLS)
+    .tlsVersions(TlsVersion.TLS_1_2, TlsVersion.TLS_1_3)
+    .build()
+
+val client = OkHttpClient.Builder()
+    .connectionSpecs(listOf(spec))
+    .build()
+```
+
+## Secure Coding Patterns
+
+### Never Log Sensitive Data
+
+```kotlin
+// WRONG
+Log.d("Auth", "Token: $token")
+Log.d("Payment", "Card: $cardNumber")
+
+// CORRECT
+Log.d("Auth", "Token refresh successful")
+Log.d("Payment", "Payment processed")
+```
+
+### Input Validation
+
+```kotlin
+fun validateDeepLink(uri: Uri): Boolean {
+    val allowedHosts = setOf("example.com", "www.example.com")
+    val allowedSchemes = setOf("https")
+
+    return uri.scheme in allowedSchemes &&
+           uri.host in allowedHosts &&
+           !uri.path.orEmpty().contains("..")
+}
+```
+
+### Secure WebView
+
+```kotlin
+webView.settings.apply {
+    javaScriptEnabled = false       // Enable ONLY if required
+    allowFileAccess = false
+    allowContentAccess = false
+    domStorageEnabled = false
+}
+```
+
+## Do's and Don'ts
+
+### Do's
+- Use EncryptedSharedPreferences for sensitive key-value data
+- Use Android Keystore for cryptographic keys
+- Enable R8 with `isMinifyEnabled = true` for release builds
+- Upload `mapping.txt` to Play Console and Crashlytics
+- Use Network Security Config to enforce HTTPS
+- Include at least two certificate pins (primary + backup)
+- Verify Play Integrity tokens server-side only
+- Use BiometricPrompt with BIOMETRIC_STRONG for high-security flows
+
+### Don'ts
+- Do not store secrets in SharedPreferences (use EncryptedSharedPreferences)
+- Do not hardcode API keys in Kotlin/Java source files
+- Do not commit `local.properties` or keystore files to version control
+- Do not log tokens, passwords, or card numbers
+- Do not verify integrity tokens on the client
+- Do not trust root detection as the sole security measure
+- Do not enable JavaScript in WebView unless absolutely necessary
+- Do not use `cleartextTrafficPermitted="true"` in production
+
+## Troubleshooting
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| `KeyPermanentlyInvalidatedException` | Biometric enrollment changed | Delete and recreate the Keystore key |
+| EncryptedSharedPreferences crash on upgrade | MasterKey corrupted | Handle exception, recreate storage, re-authenticate user |
+| Certificate pinning fails after cert rotation | Pin hash mismatch | Update pins; always maintain a backup pin |
+| R8 strips serialization classes | Missing keep rules | Add `-keep` rules for `@Serializable` classes |
+| Play Integrity token is null | Missing Play Core dependency or not on Play device | Check `com.google.android.play:integrity` dependency |
+| Cleartext traffic blocked | Network Security Config enforcing HTTPS | Use HTTPS or add debug-only exception for local dev |
+| BiometricPrompt not showing | Wrong authenticator type or no enrollment | Check `canAuthenticate()` before prompting |
+| Keystore key inaccessible after OS update | Keystore compatibility issue | Wrap in try/catch; recreate key if needed |
+
+## Review Checklist
+
+- [ ] Sensitive data in EncryptedSharedPreferences or Keystore, not plain SharedPreferences
+- [ ] No hardcoded API keys or secrets in source files
+- [ ] `local.properties` is in `.gitignore`
+- [ ] R8 enabled with `isMinifyEnabled = true` for release
+- [ ] `mapping.txt` uploaded to Play Console and Crashlytics
+- [ ] Network Security Config enforces HTTPS (`cleartextTrafficPermitted="false"`)
+- [ ] Certificate pinning with primary + backup pins
+- [ ] BiometricPrompt uses `BIOMETRIC_STRONG` for sensitive operations
+- [ ] No sensitive data in logs
+- [ ] Play Integrity tokens verified server-side
+- [ ] WebView has minimal permissions (JavaScript disabled by default)
+- [ ] Input and deep link URLs validated before processing

package/pipeline/skills/shared/external/android_ui_verification/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: android_ui_verification
+description: Automated end-to-end UI testing and verification on an Android Emulator using ADB.
+risk: safe
+source: community
+date_added: "2026-02-28"
+---
+
+# Android UI Verification Skill
+
+This skill provides a systematic approach to testing React Native applications on an Android emulator using ADB commands. It allows for autonomous interaction, state verification, and visual regression checking.
+
+## When to Use
+- Verifying UI changes in React Native or Native Android apps.
+- Autonomous debugging of layout issues or interaction bugs.
+- Ensuring feature functionality when manual testing is too slow.
+- Capturing automated screenshots for PR documentation.
+
+## 🛠 Prerequisites
+- Android Emulator running.
+- `adb` installed and in PATH.
+- Application in debug mode for logcat access.
+
+## 🚀 Workflow
+
+### 1. Device Calibration
+Before interacting, always verify the screen resolution to ensure tap coordinates are accurate.
+```bash
+adb shell wm size
+```
+*Note: Layouts are often scaled. Use the physical size returned as the base for coordinate calculations.*
+
+### 2. UI Inspection (State Discovery)
+Use the `uiautomator` dump to find the exact bounds of UI elements (buttons, inputs).
+```bash
+adb shell uiautomator dump /sdcard/view.xml && adb pull /sdcard/view.xml ./artifacts/view.xml
+```
+Search the `view.xml` for `text`, `content-desc`, or `resource-id`. The `bounds` attribute `[x1,y1][x2,y2]` defines the clickable area.
+
+### 3. Interaction Commands
+- **Tap**: `adb shell input tap <x> <y>` (Use the center of the element bounds).
+- **Swipe**: `adb shell input swipe <x1> <y1> <x2> <y2> <duration_ms>` (Used for scrolling).
+- **Text Input**: `adb shell input text "<message>"` (Note: Limited support for special characters).
+- **Key Events**: `adb shell input keyevent <code_id>` (e.g., 66 for Enter).
+
+### 4. Verification & Reporting
+#### Visual Verification
+Capture a screenshot after interaction to confirm UI changes.
+```bash
+adb shell screencap -p /sdcard/screen.png && adb pull /sdcard/screen.png ./artifacts/test_result.png
+```
+
+#### Analytical Verification
+Monitor the JS console logs in real-time to detect errors or log successes.
+```bash
+adb logcat -d | grep "ReactNativeJS" | tail -n 20
+```
+
+#### Cleanup
+Always store generated files in the `artifacts/` folder to satisfy project organization rules.
+
+## 💡 Best Practices
+- **Wait for Animations**: Always add a short sleep (e.g., 1-2s) between interaction and verification.
+- **Center Taps**: Calculate the arithmetic mean of `[x1,y1][x2,y2]` for the most reliable tap target.
+- **Log Markers**: Use distinct log messages in the code (e.g., `✅ Action Successful`) to make `grep` verification easy.
+- **Fail Fast**: If a `uiautomator dump` fails or doesn't find the expected text, stop and troubleshoot rather than blind-tapping.