docs(02): add validation strategy

.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 `<automated>` 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