android-sdd 1.0.0

package/skills/Security/Keystore/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: keystore
+description: >
+  Android Keystore System for cryptographic key management.
+  Load this skill when generating, storing, or using cryptographic keys,
+  implementing encrypt/decrypt operations backed by Keystore,
+  requiring user authentication before key use, or managing key lifecycle.
+---
+
+# Keystore
+
+## Overview
+The Android Keystore System lets you store cryptographic keys in a container that makes them harder to extract — keys can be bound to secure hardware (TEE/StrongBox) and never leave the device. Keystore is the foundation for all local encryption, biometric authentication, and signing operations.
+
+---
+
+## Core Principles
+
+- Keys are **generated inside Keystore** — never imported from outside unless necessary
+- Keys **never leave the secure enclave** — only the operations (encrypt/decrypt/sign) are performed
+- Specify **purpose at key generation** — a key for encryption cannot be used for signing
+- Use **StrongBox** when available for highest security (hardware security module)
+- Keys can require **user authentication** (biometric/PIN) before use
+
+---
+
+## Generating a Symmetric Key (AES)
+
+```kotlin
+// ✅ Generate AES key for encryption/decryption
+fun generateAesKey(alias: String) {
+    val keyGenerator = KeyGenerator.getInstance(
+        KeyProperties.KEY_ALGORITHM_AES,
+        "AndroidKeyStore"
+    )
+
+    keyGenerator.init(
+        KeyGenParameterSpec.Builder(
+            alias,
+            KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+        )
+            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+            .setKeySize(256)
+            .setUserAuthenticationRequired(false)   // set true to require biometric/PIN
+            .setInvalidatedByBiometricEnrollment(true)
+            .build()
+    )
+
+    keyGenerator.generateKey()
+}
+
+// ✅ Generate key that requires biometric authentication
+fun generateBiometricBoundKey(alias: String) {
+    val keyGenerator = KeyGenerator.getInstance(
+        KeyProperties.KEY_ALGORITHM_AES,
+        "AndroidKeyStore"
+    )
+
+    keyGenerator.init(
+        KeyGenParameterSpec.Builder(
+            alias,
+            KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+        )
+            .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+            .setKeySize(256)
+            .setUserAuthenticationRequired(true)
+            .setUserAuthenticationParameters(
+                0,   // 0 = every use requires auth
+                KeyProperties.AUTH_BIOMETRIC_STRONG or KeyProperties.AUTH_DEVICE_CREDENTIAL
+            )
+            .setInvalidatedByBiometricEnrollment(true)
+            .build()
+    )
+
+    keyGenerator.generateKey()
+}
+```
+
+---
+
+## Generating an Asymmetric Key (RSA / EC)
+
+```kotlin
+// ✅ Generate EC key pair for signing
+fun generateEcKeyPair(alias: String) {
+    val keyPairGenerator = KeyPairGenerator.getInstance(
+        KeyProperties.KEY_ALGORITHM_EC,
+        "AndroidKeyStore"
+    )
+
+    keyPairGenerator.initialize(
+        KeyGenParameterSpec.Builder(
+            alias,
+            KeyProperties.PURPOSE_SIGN or KeyProperties.PURPOSE_VERIFY
+        )
+            .setAlgorithmParameterSpec(ECGenParameterSpec("secp256r1"))
+            .setDigests(KeyProperties.DIGEST_SHA256, KeyProperties.DIGEST_SHA512)
+            .build()
+    )
+
+    keyPairGenerator.generateKeyPair()
+}
+
+// ✅ Generate RSA key pair for encryption
+fun generateRsaKeyPair(alias: String) {
+    val keyPairGenerator = KeyPairGenerator.getInstance(
+        KeyProperties.KEY_ALGORITHM_RSA,
+        "AndroidKeyStore"
+    )
+
+    keyPairGenerator.initialize(
+        KeyGenParameterSpec.Builder(
+            alias,
+            KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+        )
+            .setKeySize(2048)
+            .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_RSA_OAEP)
+            .setDigests(KeyProperties.DIGEST_SHA256)
+            .build()
+    )
+
+    keyPairGenerator.generateKeyPair()
+}
+```
+
+---
+
+## Encrypt / Decrypt with AES-GCM
+
+```kotlin
+class KeystoreCrypto @Inject constructor() {
+    private val keyStore = KeyStore.getInstance("AndroidKeyStore").also { it.load(null) }
+
+    // ✅ Encrypt — returns IV + ciphertext (IV needed for decryption)
+    fun encrypt(alias: String, plaintext: ByteArray): EncryptedData {
+        ensureKeyExists(alias)
+        val key = keyStore.getKey(alias, null) as SecretKey
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+        cipher.init(Cipher.ENCRYPT_MODE, key)
+
+        val ciphertext = cipher.doFinal(plaintext)
+        return EncryptedData(iv = cipher.iv, ciphertext = ciphertext)
+    }
+
+    // ✅ Decrypt — requires same IV used during encryption
+    fun decrypt(alias: String, data: EncryptedData): ByteArray {
+        val key = keyStore.getKey(alias, null) as SecretKey
+        val cipher = Cipher.getInstance("AES/GCM/NoPadding")
+        val spec = GCMParameterSpec(128, data.iv)
+        cipher.init(Cipher.DECRYPT_MODE, key, spec)
+        return cipher.doFinal(data.ciphertext)
+    }
+
+    fun deleteKey(alias: String) {
+        if (keyStore.containsAlias(alias)) {
+            keyStore.deleteEntry(alias)
+        }
+    }
+
+    fun hasKey(alias: String): Boolean = keyStore.containsAlias(alias)
+
+    private fun ensureKeyExists(alias: String) {
+        if (!keyStore.containsAlias(alias)) generateAesKey(alias)
+    }
+}
+
+data class EncryptedData(
+    val iv: ByteArray,
+    val ciphertext: ByteArray
+) {
+    // ✅ Serialize for storage — prepend IV to ciphertext
+    fun toByteArray(): ByteArray = iv + ciphertext
+
+    companion object {
+        private const val IV_SIZE = 12  // GCM IV is always 12 bytes
+
+        fun fromByteArray(data: ByteArray): EncryptedData = EncryptedData(
+            iv = data.copyOfRange(0, IV_SIZE),
+            ciphertext = data.copyOfRange(IV_SIZE, data.size)
+        )
+    }
+}
+```
+
+---
+
+## Sign / Verify with EC
+
+```kotlin
+class KeystoreSigner @Inject constructor() {
+    private val keyStore = KeyStore.getInstance("AndroidKeyStore").also { it.load(null) }
+
+    fun sign(alias: String, data: ByteArray): ByteArray {
+        val privateKey = keyStore.getKey(alias, null) as PrivateKey
+        return Signature.getInstance("SHA256withECDSA").run {
+            initSign(privateKey)
+            update(data)
+            sign()
+        }
+    }
+
+    fun verify(alias: String, data: ByteArray, signature: ByteArray): Boolean {
+        val publicKey = keyStore.getCertificate(alias).publicKey
+        return Signature.getInstance("SHA256withECDSA").run {
+            initVerify(publicKey)
+            update(data)
+            verify(signature)
+        }
+    }
+}
+```
+
+---
+
+## StrongBox (Hardware Security Module)
+
+```kotlin
+// ✅ Use StrongBox when available (Pixel 3+, Android 9+)
+fun generateStrongBoxKey(context: Context, alias: String) {
+    val hasStrongBox = context.packageManager
+        .hasSystemFeature(PackageManager.FEATURE_STRONGBOX_KEYSTORE)
+
+    val spec = KeyGenParameterSpec.Builder(
+        alias,
+        KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
+    )
+        .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
+        .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+        .setKeySize(256)
+        .apply {
+            if (hasStrongBox) setIsStrongBoxBacked(true)
+        }
+        .build()
+
+    KeyGenerator.getInstance(KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore")
+        .apply { init(spec) }
+        .generateKey()
+}
+```
+
+---
+
+## Key Aliases (Convention)
+
+```kotlin
+object KeystoreAliases {
+    const val DATABASE_KEY   = "app_database_key"
+    const val AUTH_TOKEN_KEY = "app_auth_token_key"
+    const val BIOMETRIC_KEY  = "app_biometric_key"
+    const val SIGNING_KEY    = "app_signing_key"
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Generating keys outside AndroidKeyStore — keys in memory can be extracted
+- Reusing the same IV for multiple encryptions with the same key — breaks GCM security
+- Storing the IV separately in an insecure location — IV must be stored with ciphertext
+- Using ECB mode (`AES/ECB/PKCS5Padding`) — no IV, patterns visible in ciphertext
+- Ignoring `KeyPermanentlyInvalidatedException` — thrown when biometrics change; handle gracefully
+
+---
+
+## Related Skills
+- `encrypted-storage` — using Keystore-backed keys for storage encryption
+- `biometric` — biometric authentication tied to Keystore keys
+- `cryptography` — higher-level crypto operations
+- `secure-networking` — certificate pinning and TLS

package/skills/Security/Network Security Config/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: network-security-config
+description: >
+  Android Network Security Config for controlling TLS and cleartext traffic.
+  Load this skill when configuring network security policy via XML,
+  blocking cleartext HTTP, trusting custom CAs, defining per-domain rules,
+  or allowing debug-only network policies.
+---
+
+# Network Security Config
+
+## Overview
+Network Security Config is an Android XML-based mechanism for defining a per-app network security policy without code changes. It controls which CAs are trusted, whether cleartext (HTTP) traffic is allowed, certificate pinning, and debug-only overrides. It applies to all HTTP(S) connections made through standard Android networking APIs.
+
+---
+
+## Core Principles
+
+- **Declare in manifest** — `android:networkSecurityConfig` on `<application>`
+- **Default behavior** (no config): cleartext allowed on API < 28, blocked on API 28+
+- **Block cleartext explicitly** — don't rely on the default
+- **Debug overrides** are only active in debug builds — safe to include user CAs there
+- **Per-domain rules** override the base config for specific hosts
+
+---
+
+## Full Configuration Reference
+
+```xml
+<!-- res/xml/network_security_config.xml -->
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+
+    <!-- ✅ Base config — applies to all connections not covered by domain-config -->
+    <base-config cleartextTrafficPermitted="false">
+        <trust-anchors>
+            <certificates src="system" />   <!-- trust system CAs only -->
+        </trust-anchors>
+    </base-config>
+
+    <!-- ✅ Per-domain config — overrides base-config for specific hosts -->
+    <domain-config cleartextTrafficPermitted="false">
+        <domain includeSubdomains="true">api.example.com</domain>
+        <trust-anchors>
+            <certificates src="system" />
+        </trust-anchors>
+        <!-- Certificate pinning (optional — prefer OkHttp pinning for flexibility) -->
+        <pin-set expiration="2026-01-01">
+            <pin digest="SHA-256">AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</pin>
+            <pin digest="SHA-256">BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=</pin>
+        </pin-set>
+    </domain-config>
+
+    <!-- ✅ Allow cleartext for specific internal/local hosts only -->
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="false">10.0.2.2</domain>   <!-- emulator localhost -->
+        <domain includeSubdomains="false">192.168.1.1</domain>
+    </domain-config>
+
+    <!-- ✅ Debug overrides — ONLY active in debug builds, ignored in release -->
+    <debug-overrides>
+        <trust-anchors>
+            <certificates src="system" />
+            <certificates src="user" />     <!-- allows Charles/Burp SSL proxy on debug -->
+        </trust-anchors>
+    </debug-overrides>
+
+</network-security-config>
+```
+
+---
+
+## AndroidManifest.xml
+
+```xml
+<application
+    android:networkSecurityConfig="@xml/network_security_config"
+    android:usesCleartextTraffic="false"   <!-- ✅ belt-and-suspenders for API < 24 -->
+    ...>
+```
+
+---
+
+## Common Configurations
+
+```xml
+<!-- ✅ Minimal production config — block all cleartext, system CAs only -->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false">
+        <trust-anchors>
+            <certificates src="system" />
+        </trust-anchors>
+    </base-config>
+    <debug-overrides>
+        <trust-anchors>
+            <certificates src="system" />
+            <certificates src="user" />
+        </trust-anchors>
+    </debug-overrides>
+</network-security-config>
+
+<!-- ✅ Trust a custom/private CA (e.g. internal enterprise API) -->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false">
+        <trust-anchors>
+            <certificates src="system" />
+            <certificates src="@raw/my_ca_cert" />   <!-- place CA cert in res/raw/ -->
+        </trust-anchors>
+    </base-config>
+</network-security-config>
+
+<!-- ✅ Override for one domain with stricter rules -->
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false">
+        <trust-anchors>
+            <certificates src="system" />
+        </trust-anchors>
+    </base-config>
+    <domain-config>
+        <domain includeSubdomains="true">payments.example.com</domain>
+        <pin-set expiration="2026-06-01">
+            <pin digest="SHA-256">primaryPinBase64==</pin>
+            <pin digest="SHA-256">backupPinBase64==</pin>
+        </pin-set>
+    </domain-config>
+</network-security-config>
+```
+
+---
+
+## Certificate Sources
+
+| `src` value | Meaning |
+|---|---|
+| `system` | Android system CA store |
+| `user` | User-installed CAs (avoid in production) |
+| `@raw/cert_file` | Bundled CA certificate in `res/raw/` |
+
+---
+
+## Pin Expiration
+
+```xml
+<!-- ✅ Always set pin expiration — prevents permanent lockout if pin rotation fails -->
+<pin-set expiration="2026-06-01">
+    <pin digest="SHA-256">primaryPinBase64==</pin>
+    <pin digest="SHA-256">backupPinBase64==</pin>
+</pin-set>
+
+<!-- After expiration date, pinning is disabled — connections proceed without pinning -->
+<!-- ✅ Better to use OkHttp certificate pinning for runtime flexibility -->
+```
+
+---
+
+## Verifying Config is Applied
+
+```bash
+# ✅ Test that cleartext is blocked
+adb shell am start -a android.intent.action.VIEW \
+  -d http://example.com com.example.app
+
+# Expected: NetworkSecurityPolicy blocks the connection
+# Logcat: CLEARTEXT communication to example.com not permitted by network security policy
+
+# ✅ Verify config with Network Inspector in Android Studio
+# View > Tool Windows > App Inspection > Network Inspector
+```
+
+---
+
+## Anti-Patterns
+
+- `cleartextTrafficPermitted="true"` in base-config for production — allows HTTP interception
+- `<certificates src="user" />` in base-config (not debug-overrides) — allows proxy attacks
+- No `debug-overrides` block — forces developers to modify production config for local testing
+- Embedding private keys in `res/raw/` — only embed **CA certificates**, never private keys
+- Relying solely on XML pinning — prefer OkHttp pinning which supports easier rotation
+
+---
+
+## Related Skills
+- `secure-networking` — overall network security setup
+- `certificate-pinning` — OkHttp-based certificate pinning
+- `certificate-transparency` — CT enforcement
+- `okhttp` — OkHttp configuration

package/skills/Security/Obfuscation/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: obfuscation
+description: >
+  Code obfuscation for Android apps using R8 and ProGuard.
+  Load this skill when configuring obfuscation rules, protecting sensitive
+  logic from reverse engineering, keeping required classes unobfuscated,
+  or troubleshooting crashes caused by obfuscation.
+---
+
+# Obfuscation
+
+## Overview
+Obfuscation renames classes, methods, and fields to meaningless names, making reverse-engineered code harder to understand. In Android, R8 (the successor to ProGuard) handles shrinking, obfuscation, and optimization in a single pass. Obfuscation is enabled by default in release builds.
+
+---
+
+## Core Principles
+
+- **Obfuscation ≠ security** — it raises the bar, not a complete defense
+- R8 is the default since Android Gradle Plugin 3.4 — prefer R8 over ProGuard
+- **Keep rules are critical** — wrong keeps = broken app; missing keeps = crashes
+- Always **test release builds** — obfuscation bugs only appear in release
+- **Mapping file** must be saved — needed to decode crash stack traces
+
+---
+
+## Enable in build.gradle.kts
+
+```kotlin
+// ✅ Release build config
+android {
+    buildTypes {
+        release {
+            isMinifyEnabled = true        // enables R8 obfuscation + shrinking
+            isShrinkResources = true      // removes unused resources
+            proguardFiles(
+                getDefaultProguardFile("proguard-android-optimize.txt"),
+                "proguard-rules.pro"
+            )
+        }
+
+        // ✅ Optional: test obfuscation in debug
+        debug {
+            isMinifyEnabled = false
+        }
+    }
+}
+```
+
+---
+
+## proguard-rules.pro
+
+```proguard
+# ============================================================
+# Data classes used with serialization (Gson, kotlinx.serialization, Moshi)
+# ============================================================
+-keepclassmembers class com.example.app.data.remote.dto.** {
+    <fields>;
+}
+-keep class com.example.app.data.remote.dto.** { *; }
+
+# ============================================================
+# Room entities and DAOs
+# ============================================================
+-keep class * extends androidx.room.RoomDatabase
+-keep @androidx.room.Entity class *
+-keepclassmembers @androidx.room.Entity class * { <fields>; }
+
+# ============================================================
+# Retrofit interfaces
+# ============================================================
+-keep interface com.example.app.data.remote.api.** { *; }
+-keepclassmembernames interface * {
+    @retrofit2.http.* <methods>;
+}
+
+# ============================================================
+# Hilt — generated components must not be obfuscated
+# ============================================================
+-keep class dagger.hilt.** { *; }
+-keep class javax.inject.** { *; }
+-keep @dagger.hilt.android.HiltAndroidApp class *
+-keep @dagger.hilt.InstallIn class *
+-keep @dagger.hilt.android.AndroidEntryPoint class *
+
+# ============================================================
+# Parcelable
+# ============================================================
+-keep class * implements android.os.Parcelable {
+    public static final android.os.Parcelable$Creator *;
+}
+
+# ============================================================
+# Enums
+# ============================================================
+-keepclassmembers enum * {
+    public static **[] values();
+    public static ** valueOf(java.lang.String);
+}
+
+# ============================================================
+# Serialization — kotlinx.serialization
+# ============================================================
+-keepattributes *Annotation*, InnerClasses
+-dontnote kotlinx.serialization.AnnotationsKt
+-keepclassmembers class kotlinx.serialization.json.** {
+    *** Companion;
+}
+-keepclasseswithmembers class **$$serializer {
+    static **$$serializer INSTANCE;
+}
+
+# ============================================================
+# Crash reporting — keep line numbers for stack traces
+# ============================================================
+-keepattributes SourceFile,LineNumberTable
+-renamesourcefileattribute SourceFile
+
+# ============================================================
+# Firebase
+# ============================================================
+-keep class com.google.firebase.** { *; }
+-keep class com.google.android.gms.** { *; }
+
+# ============================================================
+# OkHttp / Retrofit
+# ============================================================
+-dontwarn okhttp3.**
+-dontwarn retrofit2.**
+-keep class okhttp3.** { *; }
+-keep interface okhttp3.** { *; }
+
+# ============================================================
+# WebView JS interface
+# ============================================================
+-keepclassmembers class * {
+    @android.webkit.JavascriptInterface <methods>;
+}
+```
+
+---
+
+## Saving the Mapping File
+
+```kotlin
+// ✅ Store mapping file for crash deobfuscation
+// The mapping.txt is generated at:
+// app/build/outputs/mapping/release/mapping.txt
+
+// ✅ Upload to Firebase Crashlytics automatically
+android {
+    buildTypes {
+        release {
+            // Crashlytics uploads mapping.txt automatically when minifyEnabled = true
+        }
+    }
+}
+
+// ✅ Or upload to Play Console manually
+// Google Play Console > App Bundle Explorer > Download mapping.txt
+```
+
+---
+
+## Decoding Obfuscated Stack Traces
+
+```bash
+# ✅ Use retrace to decode a stack trace
+# Located at: $ANDROID_SDK/tools/proguard/bin/retrace.sh
+
+retrace.sh mapping.txt obfuscated_stacktrace.txt
+
+# ✅ Or use bundletool / R8's retrace
+java -jar r8.jar retrace --map mapping.txt stacktrace.txt
+```
+
+---
+
+## Testing Obfuscation
+
+```kotlin
+// ✅ Create a release variant that's debuggable for testing obfuscation
+android {
+    buildTypes {
+        create("releaseDebug") {
+            initWith(getByName("release"))
+            isDebuggable = true
+            signingConfig = signingConfigs.getByName("debug")
+            applicationIdSuffix = ".releasedebug"
+        }
+    }
+}
+```
+
+---
+
+## Common Crash Causes After Obfuscation
+
+| Crash | Cause | Fix |
+|---|---|---|
+| `ClassNotFoundException` | Class renamed by R8 | Add `-keep class com.example.MyClass` |
+| `NoSuchMethodException` | Method renamed | Add `-keepclassmembers` rule |
+| Gson deserialization returns null | DTO fields renamed | Keep DTO fields |
+| Room `IllegalStateException` | Entity/DAO renamed | Keep Room annotated classes |
+| Hilt `ComponentNotFound` | Hilt generated class renamed | Keep Hilt annotations |
+| `NullPointerException` in Retrofit | Interface methods renamed | Keep Retrofit interfaces |
+
+---
+
+## Anti-Patterns
+
+- `isMinifyEnabled = false` in release builds — ships unobfuscated code
+- `-keep class com.example.** { *; }` — keeps everything, defeats obfuscation
+- Discarding the mapping file — crash stack traces become unreadable
+- Never testing release builds — obfuscation breaks discovered only in production
+- Obfuscation as the only security measure — combine with encryption, root detection, pinning
+
+---
+
+## Related Skills
+- `r8` — R8-specific optimization and shrinking beyond obfuscation
+- `proguard` — legacy ProGuard rules reference
+- `reverse-engineering-resistance` — broader anti-tampering strategy
+- `gradle` — build configuration for release variants
+- `build-variant` — managing debug/release/staging variants