docs(02): create authentication foundation plans
This commit is contained in:
193
.planning/phases/02-authentication-foundation/02-04-PLAN.md
Normal file
193
.planning/phases/02-authentication-foundation/02-04-PLAN.md
Normal file
@@ -0,0 +1,193 @@
|
||||
---
|
||||
phase: 02-authentication-foundation
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 3
|
||||
depends_on: [02-02, 02-03]
|
||||
files_modified:
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthState.kt
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthSession.kt
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthHttpClient.kt
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/MeClient.kt
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthModule.kt
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt
|
||||
- composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/AuthSessionTest.kt
|
||||
autonomous: true
|
||||
requirements: [AUTH-01, AUTH-02, AUTH-04, AUTH-05]
|
||||
must_haves:
|
||||
truths:
|
||||
- "AuthSession starts in Loading and restores persisted AuthState JSON before deciding Authenticated or Unauthenticated"
|
||||
- "Authenticated state contains User and householdId = null in Phase 2"
|
||||
- "Authenticated API calls get fresh access tokens proactively and Ktor bearer auth can reactively refresh on 401"
|
||||
- "Refresh invalid_grant transitions silently to Unauthenticated"
|
||||
- "logout() attempts RP end-session and clears local AuthState even if end-session fails"
|
||||
- "AuthSession is a Koin singleton in authModule and wired into appModule"
|
||||
artifacts:
|
||||
- path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthState.kt"
|
||||
provides: "Loading/Unauthenticated/Authenticated(user, householdId?) state model per D-28"
|
||||
contains: "householdId"
|
||||
- path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthSession.kt"
|
||||
provides: "StateFlow auth owner per D-29"
|
||||
exports: ["AuthSession"]
|
||||
- path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthHttpClient.kt"
|
||||
provides: "Ktor client bearer auth with refreshTokens per D-17"
|
||||
contains: "refreshTokens"
|
||||
- path: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/MeClient.kt"
|
||||
provides: "GET /api/v1/me client returning MeResponse"
|
||||
key_links:
|
||||
- from: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthSession.kt"
|
||||
to: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/OidcClient.kt"
|
||||
via: "login/refresh/logout delegate to platform AppAuth seam"
|
||||
pattern: "oidcClient"
|
||||
- from: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthSession.kt"
|
||||
to: "composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/MeClient.kt"
|
||||
via: "after login/restore, fetch /api/v1/me to build Authenticated(user, null)"
|
||||
pattern: "meClient"
|
||||
---
|
||||
|
||||
<objective>
|
||||
Build the common client auth runtime: `AuthSession`, authenticated Ktor client, `/api/v1/me` client, and Koin wiring.
|
||||
|
||||
Purpose: compose platform OIDC/storage from Plan 03 with server `/api/v1/me` from Plan 02 into persistent app session behavior.
|
||||
Output: tested common auth state machine and DI module.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@/Users/rwilk/.codex/get-shit-done/workflows/execute-plan.md
|
||||
@/Users/rwilk/.codex/get-shit-done/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/PROJECT.md
|
||||
@.planning/REQUIREMENTS.md
|
||||
@.planning/phases/02-authentication-foundation/02-CONTEXT.md
|
||||
@.planning/phases/02-authentication-foundation/02-RESEARCH.md
|
||||
@.planning/phases/02-authentication-foundation/02-VALIDATION.md
|
||||
@.planning/phases/02-authentication-foundation/02-PATTERNS.md
|
||||
@.planning/phases/02-authentication-foundation/02-02-SUMMARY.md
|
||||
@.planning/phases/02-authentication-foundation/02-03-SUMMARY.md
|
||||
@AGENTS.md
|
||||
@composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt
|
||||
</context>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 1: Write AuthSession state-machine tests</name>
|
||||
<read_first>
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/OidcClient.kt
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/SecureAuthStateStore.kt
|
||||
- shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/dto/MeResponse.kt
|
||||
- .planning/phases/02-authentication-foundation/02-VALIDATION.md (AuthSessionTest)
|
||||
</read_first>
|
||||
<files>composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/AuthSessionTest.kt</files>
|
||||
<behavior>
|
||||
- Empty store initializes `Loading -> Unauthenticated`.
|
||||
- Successful login writes AuthState JSON, calls `/api/v1/me`, and emits `Authenticated(user, householdId = null)`.
|
||||
- Existing store refreshes before `/api/v1/me` and emits Authenticated without login.
|
||||
- Refresh `invalid_grant` or AuthError clears store and emits Unauthenticated without UI error.
|
||||
- Logout calls `OidcClient.logout(authStateJson)` then clears store and emits Unauthenticated even when logout throws.
|
||||
- Login cancelled maps to a result the UI can render as cancelled.
|
||||
</behavior>
|
||||
<action>
|
||||
Create fakes for `OidcClient`, `SecureAuthStateStore`, and `MeClient`. Write tests for the exact behaviors above before production implementation. Keep tests in commonTest and avoid platform AppAuth classes.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>./gradlew :composeApp:jvmTest --tests "*AuthSessionTest*"</automated>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -q 'invalid_grant\\|AuthError' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/AuthSessionTest.kt`
|
||||
- `grep -q 'householdId' composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/AuthSessionTest.kt`
|
||||
- After Task 2, `./gradlew :composeApp:jvmTest --tests "*AuthSessionTest*"` exits 0
|
||||
</acceptance_criteria>
|
||||
<done>State-machine tests cover AUTH-04/AUTH-05 and validation Wave 0 requirements.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Implement AuthState, AuthSession, MeClient, and bearer HTTP client</name>
|
||||
<read_first>
|
||||
- composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/AuthSessionTest.kt
|
||||
- shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/Constants.kt
|
||||
- shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/dto/User.kt
|
||||
- shared/src/commonMain/kotlin/dev/ulfrx/recipe/shared/dto/MeResponse.kt
|
||||
- .planning/phases/02-authentication-foundation/02-CONTEXT.md (D-16, D-17, D-18, D-28, D-29)
|
||||
</read_first>
|
||||
<files>composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthState.kt, composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthSession.kt, composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthHttpClient.kt, composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/MeClient.kt</files>
|
||||
<action>
|
||||
Create sealed `AuthState` with `Loading`, `Unauthenticated`, `Authenticated(user: User, householdId: HouseholdId? = null)` and `typealias HouseholdId = String`.
|
||||
|
||||
Implement `MeClient.getMe(accessToken: String? = null)` calling `GET ${Constants.API_BASE_URL}/api/v1/me`, decoding `MeResponse`, and mapping to `User`. If `accessToken` is supplied for tests/simple calls, attach `Authorization: Bearer <token>` without logging it.
|
||||
|
||||
Implement `AuthHttpClient.create(authSession)` using Ktor Client `Auth { bearer { loadTokens { ... }; refreshTokens { ... }; sendWithoutRequest { request.url.host == Url(Constants.API_BASE_URL).host } } }`, ContentNegotiation JSON, and logging that redacts token-bearing headers.
|
||||
|
||||
Implement `AuthSession` with `state: StateFlow<AuthState>`, `initialize()`, `login()`, `logout()`, `getAccessToken()`, `currentBearerTokens()`, and `refreshBearerTokens()`. `initialize()` reads stored AuthState JSON, refreshes with AppAuth, persists updated JSON, calls `/api/v1/me`, and emits `Authenticated(user, null)`. On refresh failure, clear the store and emit Unauthenticated silently. On logout, call `OidcClient.logout(storedJson)` first, then always clear.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>./gradlew :composeApp:jvmTest --tests "*AuthSessionTest*"</automated>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -q 'StateFlow<AuthState>' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthSession.kt`
|
||||
- `grep -q 'refreshTokens' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthHttpClient.kt`
|
||||
- `grep -q 'sendWithoutRequest' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthHttpClient.kt`
|
||||
- `! grep -R 'Authorization.*\\$' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth`
|
||||
- `./gradlew :composeApp:jvmTest --tests "*AuthSessionTest*"` exits 0
|
||||
</acceptance_criteria>
|
||||
<done>Common auth runtime passes the state-machine tests and supports transparent refresh.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Wire authModule into Koin</name>
|
||||
<read_first>
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt
|
||||
- composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/Koin.kt
|
||||
- composeApp/src/androidMain/kotlin/dev/ulfrx/recipe/MainApplication.kt
|
||||
- .planning/phases/02-authentication-foundation/02-CONTEXT.md (D-29)
|
||||
</read_first>
|
||||
<files>composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthModule.kt, composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt</files>
|
||||
<action>
|
||||
Create `authModule = module { ... }` providing singleton `SecureAuthStateStore`, `OidcClient`, `MeClient`, `AuthSession`, and auth-related ViewModels only if their classes already exist. Wire `appModule` to include auth definitions without starting Koin from composables. If target-specific constructors need Android context/activity, use Koin platform APIs already available in Phase 1 Android bootstrap.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>./gradlew :composeApp:jvmTest :composeApp:compileDebugKotlinAndroid :composeApp:compileKotlinIosSimulatorArm64</automated>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -q 'val authModule' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/auth/AuthModule.kt`
|
||||
- `grep -q 'authModule' composeApp/src/commonMain/kotlin/dev/ulfrx/recipe/di/AppModule.kt`
|
||||
- `./gradlew :composeApp:jvmTest :composeApp:compileDebugKotlinAndroid :composeApp:compileKotlinIosSimulatorArm64` exits 0
|
||||
</acceptance_criteria>
|
||||
<done>AuthSession and collaborators are available as Koin singletons for the UI gate.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| AuthSession -> server | Access token attached to `/api/v1/me` |
|
||||
| AuthSession -> secure store | Refresh-capable AuthState JSON persists across app launches |
|
||||
| AuthSession -> UI | Auth failures influence rendered state and messages |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|-------------|-----------------|
|
||||
| T-02-04-01 | Information Disclosure | AuthHttpClient logging | mitigate | Redact Authorization and never log token values |
|
||||
| T-02-04-02 | Information Disclosure | AuthSession logout | mitigate | Always clear stored AuthState after logout attempt, including end-session failure |
|
||||
| T-02-04-03 | Denial of Service | refresh path | mitigate | Proactive refresh before calls and Ktor bearer reactive refresh on 401 |
|
||||
| T-02-04-04 | Spoofing | `/api/v1/me` response | mitigate | Authenticated state is built only from server `MeResponse`, not client-decoded token claims |
|
||||
| T-02-04-05 | Repudiation | silent invalid_grant | accept | Silent return to login is a locked UX decision D-18; auth warnings may log without secrets |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
Run `./gradlew :composeApp:jvmTest :composeApp:compileDebugKotlinAndroid :composeApp:compileKotlinIosSimulatorArm64`.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
AUTH-04 and AUTH-05 work at the session layer: persisted tokens restore, refresh failures clear state, and logout wipes recoverable refresh tokens.
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.planning/phases/02-authentication-foundation/02-04-SUMMARY.md`.
|
||||
</output>
|
||||
Reference in New Issue
Block a user