android-sdd 1.0.0

package/skills/Networking/API Contract/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: api-contract
+description: >
+  Defining and consuming API contracts in Android projects.
+  Load this skill when documenting API expectations, defining request/response
+  DTOs, handling API versioning, managing breaking changes, or aligning
+  the data layer with backend contracts.
+---
+
+# API Contract
+
+## Overview
+An API contract is the formal agreement between client and server about request/response structure, status codes, error formats, and versioning. A well-defined contract prevents runtime surprises, makes the data layer predictable, and provides a stable foundation for mocking in tests.
+
+---
+
+## Core Principles
+
+- Define all request/response shapes as `@Serializable` DTOs — never use `Map<String, Any>`
+- Document the expected status codes for every endpoint
+- Version the API from day one — breaking changes require a new version
+- Use `ignoreUnknownKeys = true` in the Json instance — tolerates additive API changes
+- Never couple domain models to the API contract — always map through DTOs
+
+---
+
+## Contract Definition
+
+```kotlin
+// ✅ Request DTOs — what we send
+@Serializable
+data class CreateUserRequest(
+    @SerialName("full_name") val name: String,
+    @SerialName("email") val email: String,
+    @SerialName("password") val password: String
+)
+
+@Serializable
+data class UpdateUserRequest(
+    @SerialName("full_name") val name: String? = null,
+    @SerialName("email") val email: String? = null
+)
+
+// ✅ Response DTOs — what we receive
+@Serializable
+data class UserDto(
+    @SerialName("id") val id: String,
+    @SerialName("full_name") val name: String,
+    @SerialName("email") val email: String,
+    @SerialName("avatar_url") val avatarUrl: String? = null,
+    @SerialName("created_at") val createdAt: Long,
+    @SerialName("is_active") val isActive: Boolean = true
+)
+
+// ✅ Error response shape
+@Serializable
+data class ApiErrorResponse(
+    @SerialName("code") val code: String,
+    @SerialName("message") val message: String,
+    @SerialName("details") val details: Map<String, List<String>> = emptyMap()
+)
+```
+
+---
+
+## Endpoint Contract Documentation
+
+```kotlin
+// ✅ Document contract as comments on the API interface
+interface UserApi {
+
+    /**
+     * GET /users/{id}
+     *
+     * Success: 200 UserDto
+     * Not Found: 404 ApiErrorResponse
+     * Unauthorized: 401 ApiErrorResponse
+     */
+    @GET("users/{id}")
+    suspend fun getUser(@Path("id") id: String): UserDto
+
+    /**
+     * POST /users
+     *
+     * Success: 201 UserDto
+     * Validation Error: 422 ApiErrorResponse (details contains field errors)
+     * Conflict: 409 ApiErrorResponse (email already exists)
+     */
+    @POST("users")
+    suspend fun createUser(@Body request: CreateUserRequest): UserDto
+
+    /**
+     * DELETE /users/{id}
+     *
+     * Success: 204 (no body)
+     * Not Found: 404 ApiErrorResponse
+     * Forbidden: 403 ApiErrorResponse
+     */
+    @DELETE("users/{id}")
+    suspend fun deleteUser(@Path("id") id: String)
+}
+```
+
+---
+
+## API Versioning
+
+```kotlin
+// ✅ Version in base URL
+val retrofit = Retrofit.Builder()
+    .baseUrl("https://api.example.com/v1/")
+    .build()
+
+// ✅ Version in header (for minor versions)
+class ApiVersionInterceptor : Interceptor {
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val request = chain.request().newBuilder()
+            .addHeader("API-Version", "2024-01-01")
+            .build()
+        return chain.proceed(request)
+    }
+}
+
+// ✅ Separate API interfaces per major version
+interface UserApiV1 {
+    @GET("users/{id}")
+    suspend fun getUser(@Path("id") id: String): UserDtoV1
+}
+
+interface UserApiV2 {
+    @GET("users/{id}")
+    suspend fun getUser(@Path("id") id: String): UserDtoV2
+}
+```
+
+---
+
+## Handling Additive Changes (Non-Breaking)
+
+```kotlin
+// ✅ New optional fields — add with default value
+@Serializable
+data class UserDto(
+    @SerialName("id") val id: String,
+    @SerialName("name") val name: String,
+    // New field added by backend — safe with default
+    @SerialName("phone") val phone: String? = null,
+    @SerialName("tier") val tier: String = "free"
+)
+```
+
+---
+
+## Handling Breaking Changes
+
+```kotlin
+// ✅ Field renamed — use @SerialName to maintain compatibility
+@Serializable
+data class UserDto(
+    // Backend renamed "username" to "full_name"
+    // Keep old mapping until all clients are updated
+    @SerialName("full_name") val name: String
+)
+
+// ✅ Type changed — custom serializer as bridge
+@Serializable
+data class OrderDto(
+    // Backend changed status from Int to String
+    @Serializable(with = OrderStatusSerializer::class)
+    @SerialName("status") val status: OrderStatus
+)
+```
+
+---
+
+## Contract Testing with Fake
+
+```kotlin
+// ✅ Fake API implementation for tests — matches the real contract
+class FakeUserApi : UserApi {
+    val users = mutableListOf<UserDto>()
+
+    override suspend fun getUser(id: String): UserDto {
+        return users.firstOrNull { it.id == id }
+            ?: throw HttpException(
+                Response.error<UserDto>(404, "".toResponseBody())
+            )
+    }
+
+    override suspend fun createUser(request: CreateUserRequest): UserDto {
+        val dto = UserDto(
+            id = UUID.randomUUID().toString(),
+            name = request.name,
+            email = request.email,
+            createdAt = System.currentTimeMillis()
+        )
+        users.add(dto)
+        return dto
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Using `Map<String, Any>` for request/response — loses type safety
+- Not documenting expected status codes per endpoint
+- Coupling domain models directly to API response structure
+- Ignoring `@SerialName` — breaks when API uses snake_case
+- No versioning strategy — every backend change becomes a breaking change
+
+---
+
+## Related Skills
+- `serialization` — Kotlinx Serialization for DTO definition
+- `dto-mapping` — mapping DTOs to domain models
+- `rest` — HTTP conventions and status codes
+- `retrofit` — implementing the API interface
+- `error-handling` — mapping API errors to domain errors

package/skills/Networking/Authentication/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: authentication
+description: >
+  Authentication and token management for Android apps.
+  Load this skill when implementing login/logout flows, managing access
+  and refresh tokens, handling token expiry, securing token storage,
+  or wiring auth state to navigation.
+---
+
+# Authentication
+
+## Overview
+Authentication in Android involves obtaining tokens (JWT or session), storing them securely, attaching them to requests, and refreshing them before expiry. The auth state drives navigation — unauthenticated users go to the login flow, authenticated users go to the main flow.
+
+---
+
+## Core Principles
+
+- Store tokens in **EncryptedSharedPreferences** — never plain SharedPreferences or DataStore
+- Refresh the access token **proactively** before it expires — not reactively after a 401
+- Handle 401 responses with a **single refresh attempt** — avoid refresh loops
+- Auth state is a `StateFlow` in a singleton — all consumers observe the same source
+- Logout clears all tokens and navigates to the auth graph
+
+---
+
+## Token Storage
+
+```kotlin
+// ✅ Encrypted token storage
+class TokenStorage @Inject constructor(
+    @ApplicationContext context: Context
+) {
+    private val prefs = EncryptedSharedPreferences.create(
+        context,
+        "auth_prefs",
+        MasterKey.Builder(context).setKeyScheme(MasterKey.KeyScheme.AES256_GCM).build(),
+        EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
+        EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
+    )
+
+    fun saveTokens(accessToken: String, refreshToken: String) {
+        prefs.edit()
+            .putString(KEY_ACCESS_TOKEN, accessToken)
+            .putString(KEY_REFRESH_TOKEN, refreshToken)
+            .apply()
+    }
+
+    fun getAccessToken(): String? = prefs.getString(KEY_ACCESS_TOKEN, null)
+    fun getRefreshToken(): String? = prefs.getString(KEY_REFRESH_TOKEN, null)
+
+    fun clearTokens() {
+        prefs.edit().clear().apply()
+    }
+
+    companion object {
+        private const val KEY_ACCESS_TOKEN = "access_token"
+        private const val KEY_REFRESH_TOKEN = "refresh_token"
+    }
+}
+```
+
+---
+
+## Auth State
+
+```kotlin
+// ✅ Auth state as singleton StateFlow
+sealed interface AuthState {
+    data object Loading : AuthState
+    data object Unauthenticated : AuthState
+    data class Authenticated(val userId: String) : AuthState
+}
+
+@Singleton
+class AuthManager @Inject constructor(
+    private val tokenStorage: TokenStorage
+) {
+    private val _state = MutableStateFlow<AuthState>(AuthState.Loading)
+    val state: StateFlow<AuthState> = _state.asStateFlow()
+
+    init {
+        _state.value = if (tokenStorage.getAccessToken() != null)
+            AuthState.Authenticated(getUserIdFromToken())
+        else
+            AuthState.Unauthenticated
+    }
+
+    fun onLoginSuccess(accessToken: String, refreshToken: String, userId: String) {
+        tokenStorage.saveTokens(accessToken, refreshToken)
+        _state.value = AuthState.Authenticated(userId)
+    }
+
+    fun logout() {
+        tokenStorage.clearTokens()
+        _state.value = AuthState.Unauthenticated
+    }
+
+    private fun getUserIdFromToken(): String {
+        // decode JWT or read from storage
+        return tokenStorage.getAccessToken()?.let { JwtDecoder.getUserId(it) } ?: ""
+    }
+}
+```
+
+---
+
+## Token Refresh Interceptor
+
+```kotlin
+// ✅ Single refresh attempt on 401
+class TokenRefreshInterceptor @Inject constructor(
+    private val tokenStorage: TokenStorage,
+    private val authApi: AuthApi,
+    private val authManager: AuthManager
+) : Interceptor {
+
+    private val refreshLock = Mutex()
+
+    override fun intercept(chain: Interceptor.Chain): Response {
+        val response = chain.proceed(chain.request())
+
+        if (response.code != 401) return response
+
+        response.close()
+
+        val refreshed = runBlocking {
+            refreshLock.withLock {
+                // check if another thread already refreshed
+                val currentToken = tokenStorage.getAccessToken()
+                val requestToken = chain.request().header("Authorization")
+                    ?.removePrefix("Bearer ")
+
+                if (currentToken != requestToken) {
+                    // already refreshed by another call — use new token
+                    return@withLock true
+                }
+
+                runCatching {
+                    val newTokens = authApi.refreshToken(
+                        tokenStorage.getRefreshToken() ?: return@withLock false
+                    )
+                    tokenStorage.saveTokens(newTokens.accessToken, newTokens.refreshToken)
+                    true
+                }.getOrElse {
+                    authManager.logout()
+                    false
+                }
+            }
+        }
+
+        return if (refreshed) {
+            val newRequest = chain.request().newBuilder()
+                .header("Authorization", "Bearer ${tokenStorage.getAccessToken()}")
+                .build()
+            chain.proceed(newRequest)
+        } else {
+            chain.proceed(chain.request())
+        }
+    }
+}
+```
+
+---
+
+## Auth-Gated Navigation
+
+```kotlin
+// ✅ Root NavHost reacts to auth state
+@Composable
+fun AppNavHost(authManager: AuthManager) {
+    val authState by authManager.state.collectAsStateWithLifecycle()
+    val navController = rememberNavController()
+
+    LaunchedEffect(authState) {
+        when (authState) {
+            is AuthState.Authenticated -> navController.navigate(MainGraph) {
+                popUpTo(AuthGraph) { inclusive = true }
+            }
+            is AuthState.Unauthenticated -> navController.navigate(AuthGraph) {
+                popUpTo(MainGraph) { inclusive = true }
+            }
+            is AuthState.Loading -> Unit
+        }
+    }
+
+    NavHost(navController = navController, startDestination = AuthGraph) {
+        navigation<AuthGraph>(startDestination = LoginRoute) { /* ... */ }
+        navigation<MainGraph>(startDestination = HomeRoute) { /* ... */ }
+    }
+}
+```
+
+---
+
+## Anti-Patterns
+
+- Storing tokens in plain `SharedPreferences` or `DataStore` — not encrypted
+- Refreshing token on every request — use proactive refresh or single-retry pattern
+- Multiple simultaneous refresh calls — use `Mutex` to serialize refresh
+- Keeping auth state in a ViewModel — use a singleton `AuthManager`
+- Not clearing tokens on logout — stale tokens remain accessible
+
+---
+
+## Related Skills
+- `okhttp` — interceptor setup for auth headers
+- `encrypted-storage` — secure storage for sensitive data
+- `nested-navigation` — auth vs main flow navigation graphs
+- `savedstatehandle` — preserving state across auth transitions

package/skills/Networking/Certificate Pinning/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: certificate-pinning
+description: >
+  SSL/TLS certificate pinning for Android to prevent MITM attacks.
+  Load this skill when implementing certificate pinning via OkHttp,
+  configuring network security config, managing pin rotation,
+  or handling pinning failures gracefully.
+---
+
+# Certificate Pinning
+
+## Overview
+Certificate pinning ensures the app only communicates with servers whose TLS certificate matches a known pinned value. This prevents man-in-the-middle attacks even if a rogue CA is trusted by the OS. Android supports pinning via OkHttp's `CertificatePinner` or the Network Security Config XML.
+
+---
+
+## Core Principles
+
+- Always pin the **backup pin** alongside the primary — enables rotation without a forced update
+- Use **public key pinning** (SPKI hash), not certificate pinning — survives certificate renewal
+- Never pin in debug builds — breaks traffic inspection with Charles/Proxyman
+- Have a **pin rotation plan** before shipping — expired pins = broken app
+- Test pinning failures explicitly — they should fail closed, not open
+
+---
+
+## OkHttp Certificate Pinner
+
+```kotlin
+// ✅ CertificatePinner with primary + backup pin
+@Provides
+@Singleton
+fun provideCertificatePinner(): CertificatePinner {
+    return CertificatePinner.Builder()
+        .add(
+            "api.example.com",
+            "sha256/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",  // primary
+            "sha256/BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB="   // backup
+        )
+        .add(
+            "cdn.example.com",
+            "sha256/CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC=",
+            "sha256/DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD="
+        )
+        .build()
+}
+
+// ✅ Attach to OkHttpClient — skip in debug
+@Provides
+@Singleton
+fun provideOkHttpClient(
+    certificatePinner: CertificatePinner,
+    @IsDebug isDebug: Boolean
+): OkHttpClient {
+    return OkHttpClient.Builder()
+        .apply {
+            if (!isDebug) certificatePinner(certificatePinner)
+        }
+        .build()
+}
+```
+
+---
+
+## Network Security Config (XML)
+
+```xml
+<!-- res/xml/network_security_config.xml -->
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+    <domain-config>
+        <domain includeSubdomains="true">api.example.com</domain>
+        <pin-set expiration="2026-01-01">
+            <!-- Primary pin -->
+            <pin digest="SHA-256">AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</pin>
+            <!-- Backup pin -->
+            <pin digest="SHA-256">BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=</pin>
+        </pin-set>
+    </domain-config>
+
+    <!-- Debug: allow cleartext and trust user CAs -->
+    <debug-overrides>
+        <trust-anchors>
+            <certificates src="user"/>
+            <certificates src="system"/>
+        </trust-anchors>
+    </debug-overrides>
+</network-security-config>
+```
+
+```xml
+<!-- AndroidManifest.xml -->
+<application
+    android:networkSecurityConfig="@xml/network_security_config"
+    ...>
+```
+
+---
+
+## Extracting the Pin
+
+```bash
+# Extract SPKI hash from a live server
+openssl s_client -connect api.example.com:443 -servername api.example.com \
+  </dev/null 2>/dev/null \
+  | openssl x509 -pubkey -noout \
+  | openssl pkey -pubin -outform DER \
+  | openssl dgst -sha256 -binary \
+  | openssl enc -base64
+
+# Or from a certificate file
+openssl x509 -in cert.pem -pubkey -noout \
+  | openssl pkey -pubin -outform DER \
+  | openssl dgst -sha256 -binary \
+  | openssl enc -base64
+```
+
+---
+
+## Pinning Failure Handling
+
+```kotlin
+// ✅ Catch SSLPeerUnverifiedException — pinning failure
+suspend fun safeApiCall(call: suspend () -> T): Result<T> = runCatching {
+    call()
+}.recoverCatching { throwable ->
+    when (throwable) {
+        is SSLPeerUnverifiedException -> throw CertificatePinningException(
+            "Certificate pinning failure — possible MITM attack"
+        )
+        else -> throw throwable
+    }
+}
+
+class CertificatePinningException(message: String) : SecurityException(message)
+```
+
+---
+
+## Pin Rotation Strategy
+
+```
+1. Generate new certificate/key pair
+2. Extract SPKI hash of new cert → backup pin
+3. Ship app update with both old (primary) + new (backup) pins
+4. Wait for adoption (monitor crash-free rate)
+5. Deploy new certificate to server
+6. Ship next app update with new cert as primary + newer backup
+```
+
+---
+
+## Anti-Patterns
+
+- Pinning in debug builds — breaks all proxy-based debugging tools
+- Pinning without a backup pin — one certificate renewal breaks the app
+- Catching `SSLPeerUnverifiedException` silently — must fail closed, log the incident
+- Using certificate pinning (full cert hash) instead of public key pinning — breaks on renewal
+- Not setting an `expiration` in Network Security Config — no forced rotation reminder
+
+---
+
+## Related Skills
+- `okhttp` — OkHttp client where pinner is attached
+- `secure-networking` — broader TLS and network security
+- `network-security-config` — XML-based network security configuration
+- `certificate-transparency` — complementary server validation mechanism