shekhar23/claude-zero-to-hero-android-kmp/android-auth-security

Android / KMP Authentication and Security

Core Principles

• Authentication state is a first-class domain concern.
• Store only the minimum secret data required.
• Treat tokens and credentials differently from general preferences.
• UI decides what to render from a session state model; it does not inspect tokens directly.
• Logging must never expose passwords, tokens, refresh responses, or personally sensitive payloads.

Recommended Module Ownership

:core:domain              -> shared `SessionState`, auth error types if used broadly
:core:data or :core:auth  -> token storage abstraction, session persistence
:feature:auth:domain      -> auth contracts and models
:feature:auth:data        -> API/data source implementations
:feature:auth:presentation-> login screen, registration screen, auth ViewModels

Create a dedicated :core:auth module when auth grows beyond a few classes.

Session Model

Expose a typed session model instead of raw token checks:

sealed interface SessionState {
    data object Unknown : SessionState
    data object LoggedOut : SessionState
    data class LoggedIn(val userId: String) : SessionState
}

The app root observes SessionState and decides whether to show the auth flow or the main flow.

Auth Contracts

Keep contracts in domain:

interface AuthRepository {
    fun observeSession(): Flow<SessionState>
    suspend fun login(email: String, password: String): EmptyResult<AuthError>
    suspend fun logout(): EmptyResult<AuthError>
    suspend fun refreshSession(): EmptyResult<AuthError>
}

Use typed auth errors for expected failures such as invalid credentials, expired session, or too many attempts.

Login Flow

Recommended sequence:

1. Validate inputs locally.
2. Call auth API.
3. Persist session/token data securely.
4. Emit SessionState.LoggedIn.
5. Load user-specific bootstrap data if needed.

The login screen should not navigate by itself based on success booleans. It should react to a session/event change from the ViewModel.

Token Refresh

Token refresh belongs in the data/auth layer, not in screens or ViewModels.

• Access token: short-lived
• Refresh token: stored securely and used only for refresh
• Expired session: clear secure storage and emit LoggedOut

If the app uses Ktor, centralize refresh behavior in the Auth plugin configuration. See the android-data-layer skill.

Secure Storage

Use a storage abstraction so the rest of the app does not depend on platform APIs directly:

interface SessionStorage {
    suspend fun read(): StoredSession?
    suspend fun write(session: StoredSession)
    suspend fun clear()
}

Guidelines:

• Do not store passwords after login.
• Store refresh/session secrets in secure platform-backed storage when available.
• Use plain DataStore only for non-sensitive preferences.
• Clear all session data on logout.

App Startup / Session Restore

At app start:

1. read persisted session data
2. decide whether the session looks restorable
3. refresh if needed
4. emit final SessionState

Keep startup logic in a dedicated bootstrap/auth coordinator, not in the first composable that happens to render.

Protected Navigation

Navigation decisions should be based on SessionState, not ad-hoc token checks:

when (sessionState) {
    SessionState.Unknown -> SplashScreen()
    SessionState.LoggedOut -> AuthNavHost()
    is SessionState.LoggedIn -> MainNavHost()
}

Feature screens should assume they are already inside the correct graph.

Logout

Logout should:

• revoke session remotely when required
• clear local secure storage
• cancel user-scoped sync/work if applicable
• reset in-memory caches tied to the user
• emit SessionState.LoggedOut

Do not leave stale account data cached after logout.

Secret Handling

• Never hardcode API secrets in source.
• Use local.properties + generated config for local development.
• Keep production secrets on backend services whenever possible.
• Redact tokens, cookies, authorization headers, and PII from logs.

See the android-module-structure skill for shared secret/config guidance.

Biometrics and Device Credentials

Use biometrics only as a local unlock convenience layered on top of an existing session, not as the primary server authentication mechanism.

Good uses:

• unlock cached app session
• confirm sensitive local action
• re-enter secure section

Bad uses:

• replacing backend authorization entirely
• storing raw credentials for silent replay

Checklist: Adding Auth

• [ ] Define SessionState and auth contracts in domain
• [ ] Centralize login/logout/refresh in an auth repository
• [ ] Use secure storage abstraction for session secrets
• [ ] Base navigation on SessionState
• [ ] Clear all user-scoped state on logout
• [ ] Redact secrets from logs and analytics