From ab69cc1dff1e4a9cd10afa4cce90813b2637bd50 Mon Sep 17 00:00:00 2001 From: ulfrxdev Date: Mon, 27 Apr 2026 20:42:04 +0200 Subject: [PATCH] docs(02): add validation strategy --- .../02-VALIDATION.md | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 .planning/phases/02-authentication-foundation/02-VALIDATION.md diff --git a/.planning/phases/02-authentication-foundation/02-VALIDATION.md b/.planning/phases/02-authentication-foundation/02-VALIDATION.md new file mode 100644 index 0000000..f0b89b6 --- /dev/null +++ b/.planning/phases/02-authentication-foundation/02-VALIDATION.md @@ -0,0 +1,94 @@ +--- +phase: 02 +slug: authentication-foundation +status: draft +nyquist_compliant: false +wave_0_complete: false +created: 2026-04-27 +--- + +# Phase 02 — Validation Strategy + +> Per-phase validation contract for feedback sampling during execution. + +--- + +## Test Infrastructure + +| Property | Value | +|----------|-------| +| **Framework** | kotlin.test + JUnit for server; KMP common tests for auth state/store seams | +| **Config file** | Existing Gradle/KMP test setup; no standalone test config | +| **Quick run command** | `./gradlew :server:test :composeApp:jvmTest :shared:jvmTest` | +| **Full suite command** | `./gradlew check` | +| **Estimated runtime** | ~120 seconds | + +--- + +## Sampling Rate + +- **After every task commit:** Run `./gradlew :server:test :composeApp:jvmTest :shared:jvmTest` +- **After every plan wave:** Run `./gradlew check` +- **Before `$gsd-verify-work`:** Full suite must be green and manual iOS Authentik login/logout UAT must be recorded +- **Max feedback latency:** 120 seconds for quick checks + +--- + +## Per-Task Verification Map + +| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status | +|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------| +| 02-01-01 | 01 | 1 | AUTH-01 | T-02-01 | OIDC config pins issuer, client ID, redirect URI, scopes, PKCE-compatible public-client flow | build/unit | `./gradlew :composeApp:compileKotlinIosSimulatorArm64 :composeApp:compileDebugKotlinAndroid` | ❌ W0 | ⬜ pending | +| 02-01-02 | 01 | 1 | AUTH-02 | T-02-02 | AuthState JSON store reads/writes/clears without using no-arg insecure Settings for secrets | common unit + grep | `./gradlew :composeApp:jvmTest` | ❌ W0 | ⬜ pending | +| 02-02-01 | 02 | 1 | AUTH-03 | T-02-03 | `/api/v1/me` rejects missing, expired, wrong-audience, and wrong-issuer tokens | server integration | `./gradlew :server:test --tests "*Auth*"` | ❌ W0 | ⬜ pending | +| 02-02-02 | 02 | 1 | AUTH-06 | T-02-04 | First authenticated `/api/v1/me` creates or updates a `users` row keyed by OIDC `sub` | server integration | `./gradlew :server:test --tests "*Me*"` | ❌ W0 | ⬜ pending | +| 02-03-01 | 03 | 1 | AUTH-04 | T-02-05 | Restored AuthState refreshes before `/api/v1/me` and transitions to authenticated without UI prompt | common/platform-stub unit | `./gradlew :composeApp:jvmTest` | ❌ W0 | ⬜ pending | +| 02-03-02 | 03 | 1 | AUTH-05 | T-02-06 | Logout calls end-session when possible and clears local AuthState even if network logout fails | unit + manual iOS UAT | `./gradlew :composeApp:jvmTest` | ❌ W0 | ⬜ pending | + +*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* + +--- + +## Wave 0 Requirements + +- [ ] `server/src/test/kotlin/dev/ulfrx/recipe/auth/AuthJwtTest.kt` — covers valid, missing, expired, wrong-audience, and wrong-issuer JWT cases for AUTH-03 +- [ ] `server/src/test/kotlin/dev/ulfrx/recipe/auth/MeRouteTest.kt` — covers JIT provisioning and `/api/v1/me` response shape for AUTH-06 +- [ ] `composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/AuthSessionTest.kt` — covers login, restored session refresh, invalid-grant transition, and logout state transitions for AUTH-01, AUTH-04, AUTH-05 +- [ ] `composeApp/src/commonTest/kotlin/dev/ulfrx/recipe/auth/SecureAuthStateStoreTest.kt` — covers read/write/clear store contract and guards against insecure no-arg `Settings()` use for AUTH-02 +- [ ] `docs/authentik-setup.md` — includes manual iOS UAT checklist for fresh login, reopen-with-refresh, logout, and `/api/v1/me` + +--- + +## Manual-Only Verifications + +| Behavior | Requirement | Why Manual | Test Instructions | +|----------|-------------|------------|-------------------| +| Fresh iOS install opens Authentik, completes hosted login, and returns through `recipe://callback` | AUTH-01 | Requires real Authentik provider, iOS browser handoff, and custom URL callback | Install on iOS simulator/device, tap `Zaloguj się przez Authentik`, authenticate, verify app shows `Witaj, {displayName}!` | +| Reopen after access token expiry remains signed in via refresh token | AUTH-04 | Depends on Authentik-issued refresh token and persisted OS secure storage | Sign in, close app, wait or force short token lifetime in Authentik, reopen, verify app returns to authenticated screen without credential entry | +| `Wyloguj się` clears local tokens and invokes Authentik end-session | AUTH-05 | Requires browser/end-session behavior that unit tests can only stub | Tap `Wyloguj się`, verify login screen appears, then relaunch and confirm no silent local session restore | + +--- + +## Security Threat References + +| Threat Ref | Threat | Required Mitigation | +|------------|--------|---------------------| +| T-02-01 | Authorization-code interception through custom URL scheme | Public client, PKCE S256, AppAuth state/nonce handling, redirect URI byte-match | +| T-02-02 | Refresh token persisted in plaintext | Explicit secure platform store; iOS Keychain and Android secure storage; no no-arg `Settings()` for auth secrets | +| T-02-03 | Wrong-audience or wrong-issuer token accepted by server | `withIssuer`, `withAudience`, 30-second leeway only, non-empty `sub`, negative JWT tests | +| T-02-04 | Duplicate or stale user rows on concurrent first login | Atomic upsert by unique `sub`; update email/display name on conflict | +| T-02-05 | Token expiry breaks reopened sessions | AppAuth `performActionWithFreshTokens` before authenticated calls plus Ktor bearer 401 refresh fallback | +| T-02-06 | Logout leaves recoverable local refresh token | Always clear persisted AuthState after logout attempt, even if end-session fails | + +--- + +## Validation Sign-Off + +- [ ] All tasks have `` verify or Wave 0 dependencies +- [ ] Sampling continuity: no 3 consecutive tasks without automated verify +- [ ] Wave 0 covers all MISSING references +- [ ] No watch-mode flags +- [ ] Feedback latency < 120s for quick checks +- [ ] `nyquist_compliant: true` set in frontmatter + +**Approval:** pending