android-sdd 1.0.0

package/skills/Security/Biometric/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: biometric
+description: >
+  Biometric authentication for Android apps.
+  Load this skill when implementing fingerprint or face authentication,
+  using BiometricPrompt, tying biometric auth to Keystore keys,
+  handling fallback to device credentials, or checking biometric availability.
+---
+
+# Biometric
+
+## Overview
+Android's BiometricPrompt API provides a unified interface for fingerprint, face, and iris authentication. Biometric auth can be used standalone (gate access to a screen) or tied to a Keystore key (unlock a cryptographic operation). The latter is stronger — authentication is required each time the key is used.
+
+---
+
+## Core Principles
+
+- Use **BiometricPrompt** — never use FingerprintManager directly (deprecated)
+- **Crypto-based auth** (tied to Keystore key) is stronger than confirmation-only auth
+- Always provide **fallback to device credentials** (PIN/pattern/password) for accessibility
+- Handle `KeyPermanentlyInvalidatedException` — thrown when new biometrics are enrolled
+- Check availability before showing biometric UI — degrade gracefully on unsupported devices
+
+---
+
+## Check Availability
+
+```kotlin
+// ✅ Check if biometric is available before using it
+class BiometricAvailabilityChecker @Inject constructor(
+    @ApplicationContext private val context: Context
+) {
+    sealed interface Availability {
+        data object Available : Availability
+        data object NotEnrolled : Availability
+        data object NotSupported : Availability
+        data object HardwareUnavailable : Availability
+    }
+
+    fun check(): Availability {
+        val manager = BiometricManager.from(context)
+        return when (manager.canAuthenticate(
+            BiometricManager.Authenticators.BIOMETRIC_STRONG or
+            BiometricManager.Authenticators.DEVICE_CREDENTIAL
+        )) {
+            BiometricManager.BIOMETRIC_SUCCESS          -> Availability.Available
+            BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> Availability.NotEnrolled
+            BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE   -> Availability.NotSupported
+            BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE -> Availability.HardwareUnavailable
+            else -> Availability.NotSupported
+        }
+    }
+}
+```
+
+---
+
+## Simple Biometric Prompt (Confirmation Only)
+
+```kotlin
+// ✅ Gate screen access — no Keystore key involved
+class BiometricAuthManager @Inject constructor() {
+
+    sealed interface AuthResult {
+        data object Success : AuthResult
+        data class Error(val message: String) : AuthResult
+        data object Cancelled : AuthResult
+    }
+
+    fun authenticate(
+        activity: FragmentActivity,
+        title: String = "Authenticate",
+        subtitle: String = "Use biometric or device credential",
+        onResult: (AuthResult) -> Unit
+    ) {
+        val executor = ContextCompat.getMainExecutor(activity)
+
+        val prompt = BiometricPrompt(activity, executor,
+            object : BiometricPrompt.AuthenticationCallback() {
+                override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+                    onResult(AuthResult.Success)
+                }
+                override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+                    if (errorCode == BiometricPrompt.ERROR_USER_CANCELED ||
+                        errorCode == BiometricPrompt.ERROR_NEGATIVE_BUTTON) {
+                        onResult(AuthResult.Cancelled)
+                    } else {
+                        onResult(AuthResult.Error(errString.toString()))
+                    }
+                }
+                override fun onAuthenticationFailed() {
+                    // Called on each failed attempt — not terminal; don't handle as final failure
+                }
+            }
+        )
+
+        val promptInfo = BiometricPrompt.PromptInfo.Builder()
+            .setTitle(title)
+            .setSubtitle(subtitle)
+            .setAllowedAuthenticators(
+                BiometricManager.Authenticators.BIOMETRIC_STRONG or
+                BiometricManager.Authenticators.DEVICE_CREDENTIAL
+            )
+            .build()
+
+        prompt.authenticate(promptInfo)
+    }
+}
+```
+
+---
+
+## Crypto-Based Biometric (Keystore-Tied)
+
+```kotlin
+// ✅ Biometric auth that unlocks a Keystore key — stronger guarantee
+class BiometricCryptoManager @Inject constructor(
+    private val keystoreCrypto: KeystoreCrypto
+) {
+    private val keyAlias = KeystoreAliases.BIOMETRIC_KEY
+
+    // ✅ Prepare cipher before showing prompt — pass to authenticate()
+    fun prepareCipher(): Cipher? {
+        return try {
+            val keyStore = KeyStore.getInstance("AndroidKeyStore").also { it.load(null) }
+            if (!keyStore.containsAlias(keyAlias)) generateBiometricBoundKey(keyAlias)
+
+            val key = keyStore.getKey(keyAlias, null) as SecretKey
+            Cipher.getInstance("AES/GCM/NoPadding").also {
+                it.init(Cipher.ENCRYPT_MODE, key)
+            }
+        } catch (e: KeyPermanentlyInvalidatedException) {
+            // New biometrics enrolled — delete and recreate key
+            KeyStore.getInstance("AndroidKeyStore").also { it.load(null) }.deleteEntry(keyAlias)
+            null
+        }
+    }
+
+    fun authenticate(
+        activity: FragmentActivity,
+        cipher: Cipher,
+        onSuccess: (Cipher) -> Unit,
+        onFailure: () -> Unit
+    ) {
+        val executor = ContextCompat.getMainExecutor(activity)
+        val cryptoObject = BiometricPrompt.CryptoObject(cipher)
+
+        val prompt = BiometricPrompt(activity, executor,
+            object : BiometricPrompt.AuthenticationCallback() {
+                override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
+                    result.cryptoObject?.cipher?.let { onSuccess(it) } ?: onFailure()
+                }
+                override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
+                    onFailure()
+                }
+            }
+        )
+
+        val promptInfo = BiometricPrompt.PromptInfo.Builder()
+            .setTitle("Confirm identity")
+            .setSubtitle("Touch sensor to continue")
+            .setAllowedAuthenticators(BiometricManager.Authenticators.BIOMETRIC_STRONG)
+            .setNegativeButtonText("Cancel")
+            .build()
+
+        prompt.authenticate(promptInfo, cryptoObject)
+    }
+}
+```
+
+---
+
+## Compose Integration
+
+```kotlin
+// ✅ Trigger biometric from Compose via Activity
+@Composable
+fun BiometricGatedScreen(
+    onAuthenticated: () -> Unit,
+    content: @Composable () -> Unit
+) {
+    val activity = LocalContext.current as FragmentActivity
+    val biometricManager = remember { BiometricAuthManager() }
+    var isAuthenticated by rememberSaveable { mutableStateOf(false) }
+
+    LaunchedEffect(Unit) {
+        biometricManager.authenticate(
+            activity = activity,
+            onResult = { result ->
+                if (result is BiometricAuthManager.AuthResult.Success) {
+                    isAuthenticated = true
+                    onAuthenticated()
+                }
+            }
+        )
+    }
+
+    if (isAuthenticated) {
+        content()
+    } else {
+        Box(Modifier.fillMaxSize(), contentAlignment = Alignment.Center) {
+            CircularProgressIndicator()
+        }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using `FingerprintManager` — deprecated since API 28; use `BiometricPrompt`
+- Not handling `KeyPermanentlyInvalidatedException` — crashes when user enrolls new fingerprint
+- No fallback to device credential — locks out users with biometric issues
+- Calling `authenticate()` from a background thread — must be called on main thread
+- Storing sensitive data in plain storage after biometric success — biometric should unlock Keystore key
+
+---
+
+## Related Skills
+- `keystore` — generating biometric-bound Keystore keys
+- `encrypted-storage` — protecting data unlocked by biometric
+- `cryptography` — cipher operations after biometric success

package/skills/Security/Certificate Transparency/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: certificate-transparency
+description: >
+  Certificate Transparency (CT) enforcement for Android apps.
+  Load this skill when enforcing CT log verification for TLS connections,
+  understanding CT requirements on Android, or configuring OkHttp to
+  verify certificates are publicly logged.
+---
+
+# Certificate Transparency
+
+## Overview
+Certificate Transparency is a public logging framework that requires CAs to log every issued certificate to a public CT log. This makes mis-issued certificates detectable. On Android, CT enforcement is built into the OS (Android 7+) for system CAs, and can be enforced at the app level via OkHttp's `certificatetransparency` library for additional guarantees.
+
+---
+
+## Core Principles
+
+- **CT is enforced by Android OS** for system CA-signed certificates since Android 7+
+- App-level CT enforcement provides stricter, per-host control
+- CT does not replace certificate pinning — they address different threats
+- CT verifies the certificate is in public logs — pinning verifies it's a specific certificate
+- Use both for highest security: CT catches mis-issuance; pinning catches MITM
+
+---
+
+## Android OS Built-in CT
+
+```
+Android 7.0+ enforces CT for:
+  - Certificates signed by public CAs trusted by the system
+  - Connections where the certificate chain includes a public CA
+
+Android does NOT enforce CT for:
+  - Certificates in the user certificate store
+  - Privately issued certificates
+  - Certificates added via Network Security Config
+```
+
+---
+
+## App-Level CT with OkHttp (certificatetransparency-android)
+
+```kotlin
+// dependency: com.appmattus.certificatetransparency:certificatetransparency-android
+
+// ✅ Add CT verification to OkHttp
+fun buildCtEnabledOkHttpClient(): OkHttpClient {
+    val ctInterceptor = certificateTransparencyInterceptor {
+        // ✅ Enforce CT for all hosts
+        +("*.*")
+
+        // ✅ Or enforce only for specific hosts
+        +("api.example.com")
+        +("*.example.com")
+
+        // ✅ Exclude hosts where CT is not applicable (e.g. internal/dev)
+        -("internal.dev.example.com")
+    }
+
+    return OkHttpClient.Builder()
+        .addNetworkInterceptor(ctInterceptor)
+        .build()
+}
+
+// ✅ Alternative: use CTHostnameVerifier
+fun buildCtEnabledClient(): OkHttpClient {
+    val ctHostnameVerifier = certificateTransparencyHostnameVerifier {
+        +("api.example.com")
+    }
+
+    return OkHttpClient.Builder()
+        .hostnameVerifier(ctHostnameVerifier)
+        .build()
+}
+```
+
+---
+
+## Network Security Config + CT
+
+```xml
+<!-- res/xml/network_security_config.xml -->
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+    <base-config cleartextTrafficPermitted="false">
+        <trust-anchors>
+            <!-- ✅ System CAs — Android 7+ enforces CT for these -->
+            <certificates src="system" />
+        </trust-anchors>
+    </base-config>
+
+    <!-- ✅ For debug: allow user-added CAs without CT enforcement -->
+    <debug-overrides>
+        <trust-anchors>
+            <certificates src="system" />
+            <certificates src="user" />
+        </trust-anchors>
+    </debug-overrides>
+</network-security-config>
+```
+
+---
+
+## CT vs Certificate Pinning
+
+| | Certificate Transparency | Certificate Pinning |
+|---|---|---|
+| What it verifies | Certificate is publicly logged | Certificate matches expected value |
+| Protects against | Mis-issued certificates by CAs | MITM with any valid certificate |
+| Maintenance | Low (automatic) | High (pin rotation required) |
+| Failure mode | Rejects unlogged certificates | Rejects wrong certificates |
+| Use for | All public API connections | High-security endpoints |
+
+---
+
+## Hilt Integration
+
+```kotlin
+@Module
+@InstallIn(SingletonComponent::class)
+object NetworkModule {
+
+    @Provides
+    @Singleton
+    fun provideOkHttpClient(
+        authInterceptor: AuthInterceptor,
+        certificatePinner: CertificatePinner
+    ): OkHttpClient {
+        val ctInterceptor = certificateTransparencyInterceptor {
+            +("api.example.com")
+        }
+
+        return OkHttpClient.Builder()
+            .addInterceptor(authInterceptor)
+            .addNetworkInterceptor(ctInterceptor)   // ✅ CT after TLS handshake
+            .certificatePinner(certificatePinner)
+            .build()
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Assuming OS-level CT is sufficient for all use cases — app-level gives per-host control
+- Disabling CT verification in production builds — removes mis-issuance protection
+- Using CT as a replacement for certificate pinning — they complement each other
+- Not testing CT enforcement — a misconfigured CT check can block all connections silently
+
+---
+
+## Related Skills
+- `certificate-pinning` — pinning specific certificates against MITM
+- `secure-networking` — overall TLS and network security
+- `network-security-config` — Android XML-based network policy
+- `okhttp` — OkHttp configuration and interceptors

package/skills/Security/Cryptography/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: cryptography
+description: >
+  Cryptographic operations for Android apps.
+  Load this skill when implementing hashing, symmetric encryption,
+  asymmetric encryption, digital signatures, key derivation,
+  HMAC, or secure random generation.
+---
+
+# Cryptography
+
+## Overview
+Android provides the standard Java Cryptography Architecture (JCA) with hardware-backed key storage via Keystore. This skill covers the correct algorithms and patterns for common cryptographic needs — encryption, hashing, signing, and key derivation — without relying on Keystore (see `keystore` skill for that).
+
+---
+
+## Core Principles
+
+- **Use proven algorithms** — AES-GCM, ChaCha20-Poly1305, RSA-OAEP, SHA-256, PBKDF2
+- **Never roll your own crypto** — use standard JCA or Tink
+- **Always use authenticated encryption** (AES-GCM, not AES-CBC without MAC)
+- **Never reuse IV/nonce** with the same key
+- **Use Tink for high-level operations** — fewer footguns than raw JCA
+
+---
+
+## Symmetric Encryption (AES-GCM)
+
+```kotlin
+object AesGcm {
+    private const val ALGORITHM = "AES/GCM/NoPadding"
+    private const val KEY_SIZE = 256
+    private const val IV_SIZE = 12      // 96 bits — standard for GCM
+    private const val TAG_SIZE = 128    // authentication tag bits
+
+    // ✅ Generate a random AES key (for non-Keystore use)
+    fun generateKey(): SecretKey {
+        val generator = KeyGenerator.getInstance("AES")
+        generator.init(KEY_SIZE)
+        return generator.generateKey()
+    }
+
+    // ✅ Encrypt — returns IV prepended to ciphertext
+    fun encrypt(key: SecretKey, plaintext: ByteArray): ByteArray {
+        val iv = ByteArray(IV_SIZE).also { SecureRandom().nextBytes(it) }
+        val cipher = Cipher.getInstance(ALGORITHM)
+        cipher.init(Cipher.ENCRYPT_MODE, key, GCMParameterSpec(TAG_SIZE, iv))
+        val ciphertext = cipher.doFinal(plaintext)
+        return iv + ciphertext   // prepend IV for storage
+    }
+
+    // ✅ Decrypt — expects IV prepended to ciphertext
+    fun decrypt(key: SecretKey, data: ByteArray): ByteArray {
+        val iv = data.copyOfRange(0, IV_SIZE)
+        val ciphertext = data.copyOfRange(IV_SIZE, data.size)
+        val cipher = Cipher.getInstance(ALGORITHM)
+        cipher.init(Cipher.DECRYPT_MODE, key, GCMParameterSpec(TAG_SIZE, iv))
+        return cipher.doFinal(ciphertext)
+    }
+}
+```
+
+---
+
+## Hashing
+
+```kotlin
+object Hashing {
+    // ✅ SHA-256 hash
+    fun sha256(input: ByteArray): ByteArray =
+        MessageDigest.getInstance("SHA-256").digest(input)
+
+    fun sha256Hex(input: String): String =
+        sha256(input.toByteArray(Charsets.UTF_8))
+            .joinToString("") { "%02x".format(it) }
+
+    // ✅ SHA-256 of a file (streaming — no OOM for large files)
+    fun sha256File(file: File): ByteArray {
+        val digest = MessageDigest.getInstance("SHA-256")
+        file.inputStream().use { stream ->
+            val buffer = ByteArray(8192)
+            var read: Int
+            while (stream.read(buffer).also { read = it } != -1) {
+                digest.update(buffer, 0, read)
+            }
+        }
+        return digest.digest()
+    }
+
+    // ✅ HMAC-SHA256 — for message authentication
+    fun hmacSha256(key: ByteArray, message: ByteArray): ByteArray {
+        val secretKey = SecretKeySpec(key, "HmacSHA256")
+        return Mac.getInstance("HmacSHA256").run {
+            init(secretKey)
+            doFinal(message)
+        }
+    }
+}
+```
+
+---
+
+## Password Hashing (PBKDF2)
+
+```kotlin
+// ✅ Hash passwords for local verification — NOT for sending to server
+object PasswordHasher {
+    private const val ITERATIONS = 100_000
+    private const val KEY_LENGTH = 256
+    private const val SALT_SIZE = 16
+    private const val ALGORITHM = "PBKDF2WithHmacSHA256"
+
+    data class HashedPassword(val hash: ByteArray, val salt: ByteArray) {
+        fun toStorageString(): String =
+            "${Base64.encodeToString(hash, Base64.NO_WRAP)}:${Base64.encodeToString(salt, Base64.NO_WRAP)}"
+
+        companion object {
+            fun fromStorageString(value: String): HashedPassword {
+                val (hashB64, saltB64) = value.split(":")
+                return HashedPassword(
+                    hash = Base64.decode(hashB64, Base64.NO_WRAP),
+                    salt = Base64.decode(saltB64, Base64.NO_WRAP)
+                )
+            }
+        }
+    }
+
+    fun hash(password: CharArray): HashedPassword {
+        val salt = ByteArray(SALT_SIZE).also { SecureRandom().nextBytes(it) }
+        val spec = PBEKeySpec(password, salt, ITERATIONS, KEY_LENGTH)
+        val factory = SecretKeyFactory.getInstance(ALGORITHM)
+        val hash = factory.generateSecret(spec).encoded
+        spec.clearPassword()
+        return HashedPassword(hash, salt)
+    }
+
+    fun verify(password: CharArray, stored: HashedPassword): Boolean {
+        val spec = PBEKeySpec(password, stored.salt, ITERATIONS, KEY_LENGTH)
+        val factory = SecretKeyFactory.getInstance(ALGORITHM)
+        val hash = factory.generateSecret(spec).encoded
+        spec.clearPassword()
+        return MessageDigest.isEqual(hash, stored.hash)
+    }
+}
+```
+
+---
+
+## Key Derivation (HKDF)
+
+```kotlin
+// ✅ Derive multiple keys from one master key
+object KeyDerivation {
+    fun deriveKey(masterKey: ByteArray, info: String, outputLength: Int = 32): ByteArray {
+        // HKDF using HMAC-SHA256
+        val salt = ByteArray(32)   // zero salt
+        val prk = Hashing.hmacSha256(salt, masterKey)
+        val infoBytes = info.toByteArray(Charsets.UTF_8)
+        val okm = Hashing.hmacSha256(prk, infoBytes + byteArrayOf(1))
+        return okm.copyOfRange(0, outputLength)
+    }
+}
+
+// Usage: derive separate keys for encryption and authentication from one master
+val encryptionKey = KeyDerivation.deriveKey(masterKey, "encryption")
+val authKey = KeyDerivation.deriveKey(masterKey, "authentication")
+```
+
+---
+
+## Secure Random
+
+```kotlin
+// ✅ Always use SecureRandom for cryptographic purposes
+object SecureRandomUtils {
+    fun randomBytes(size: Int): ByteArray =
+        ByteArray(size).also { SecureRandom().nextBytes(it) }
+
+    fun randomHex(size: Int): String =
+        randomBytes(size).joinToString("") { "%02x".format(it) }
+
+    fun randomBase64(size: Int): String =
+        Base64.encodeToString(randomBytes(size), Base64.NO_WRAP)
+}
+```
+
+---
+
+## Tink (Recommended for Production)
+
+```kotlin
+// ✅ Google Tink — high-level crypto library, fewer footguns
+// dependency: com.google.crypto.tink:tink-android
+
+// Initialize once at app startup
+TinkConfig.register()
+
+// ✅ Authenticated encryption
+val keysetHandle = KeysetHandle.generateNew(AeadKeyTemplates.AES256_GCM)
+val aead = keysetHandle.getPrimitive(Aead::class.java)
+val ciphertext = aead.encrypt(plaintext, associatedData)
+val decrypted = aead.decrypt(ciphertext, associatedData)
+
+// ✅ Store keysets securely with Keystore integration
+val keysetHandle = AndroidKeysetManager.Builder()
+    .withSharedPref(context, "tink_keyset", "tink_prefs")
+    .withKeyTemplate(AeadKeyTemplates.AES256_GCM)
+    .withMasterKeyUri("android-keystore://tink_master_key")
+    .build()
+    .keysetHandle
+```
+
+---
+
+## Algorithm Selection Guide
+
+| Need | Algorithm | Avoid |
+|---|---|---|
+| Symmetric encryption | AES-256-GCM | AES-ECB, AES-CBC without MAC |
+| Password hashing | PBKDF2 (100k+ iterations) | MD5, SHA-1, unsalted hash |
+| General hashing | SHA-256 / SHA-3 | MD5, SHA-1 |
+| Message authentication | HMAC-SHA256 | Custom MAC schemes |
+| Asymmetric encryption | RSA-OAEP-SHA256 | RSA-PKCS1v1.5 |
+| Digital signature | ECDSA P-256, Ed25519 | RSA with SHA-1 |
+| Key agreement | ECDH P-256 | DH without authentication |
+
+---
+
+## Anti-Patterns
+
+- `Random()` instead of `SecureRandom()` — predictable, not suitable for crypto
+- AES-ECB mode — same plaintext block → same ciphertext; patterns visible
+- Reusing IV with the same key in GCM — catastrophic key recovery attack
+- MD5 or SHA-1 for security purposes — cryptographically broken
+- Storing keys as hex strings in SharedPreferences — use Android Keystore
+- Rolling custom encryption schemes — use standard JCA or Tink
+
+---
+
+## Related Skills
+- `keystore` — hardware-backed key storage for Android
+- `encrypted-storage` — applying crypto to local storage
+- `biometric` — biometric-gated crypto operations
+- `secure-networking` — TLS and certificate pinning