# Auth & Frontend Remediation Plan

**Created:** 2026-02-16
**Status:** Draft - Pending milestone/issue creation
**Scope:** Backend auth hardening + frontend OIDC-aware multi-method login
**Branch:** `develop`

---

## Executive Summary

The Mosaic Stack authentication system has critical gaps that cause silent 500 errors
in production and leave the frontend unable to adapt to backend configuration. The
frontend login UI is hardcoded for OIDC-only authentication with no fallback, no error
display, and no awareness of backend state.

This plan addresses both sides with a phased approach: fix the backend validation and
error handling first, then build a proper multi-method login UI that adapts to the
backend's advertised capabilities.

---

## Table of Contents

1. [Current State Assessment](#1-current-state-assessment)
2. [Architecture Design](#2-architecture-design)
3. [Backend Remediation](#3-backend-remediation)
4. [Frontend Remediation](#4-frontend-remediation)
5. [Security Hardening](#5-security-hardening)
6. [Implementation Phases](#6-implementation-phases)
7. [File Change Map](#7-file-change-map)
8. [Testing Strategy](#8-testing-strategy)
9. [Rollout & Rollback](#9-rollout--rollback)
10. [Open Questions](#10-open-questions)

---

## 1. Current State Assessment

### Backend

| Area                      | Status                 | Issue                                                |
| ------------------------- | ---------------------- | ---------------------------------------------------- |
| OIDC startup validation   | Incomplete             | `OIDC_REDIRECT_URI` not validated                    |
| BetterAuth error handling | Missing                | Silent 500s bypass NestJS exception filter           |
| Auth config discovery     | Missing                | Frontend cannot learn what auth methods exist        |
| Email/password backend    | Enabled but incomplete | No email verification service configured             |
| Docker env vars           | Inconsistent           | Swarm compose has no default for `OIDC_REDIRECT_URI` |
| trustedOrigins            | Hardcoded              | Production URLs in source code                       |
| PKCE                      | Not enabled            | genericOAuth lacks `pkce: true`                      |

### Frontend

| Area               | Grade | Issue                                       |
| ------------------ | ----- | ------------------------------------------- |
| Auth flow          | C+    | OIDC-only, no fallback path                 |
| OIDC awareness     | D     | Zero conditional logic, no env check        |
| Login UI           | C     | Single OAuth button, no email/password form |
| Error display      | D     | Callback errors silently lost               |
| Session management | A-    | AuthProvider is solid                       |
| Route protection   | B     | Component-level only, no middleware         |
| Theme storage key  | Bug   | Still reads `"jarvis-theme"`                |

### Root Cause of Production 500

`POST /auth/sign-in/oauth2` returns 500 because:

1. `OIDC_REDIRECT_URI` may be empty in the Swarm deployment (no default value)
2. BetterAuth's genericOAuth plugin fails when constructing the authorization URL
3. The error is swallowed — `toNodeHandler()` operates outside NestJS exception handling
4. `validateOidcConfig()` checks only 3 of 4 required OIDC variables

---

## 2. Architecture Design

### Auth Discovery Pattern

The backend advertises available auth methods via `GET /auth/config`. The frontend
fetches this on the login page and renders the appropriate UI dynamically.

```
Browser                    API                     Authentik
  │                         │                         │
  │ GET /auth/config        │                         │
  ├────────────────────────►│                         │
  │◄────────────────────────┤                         │
  │ { providers: [...] }    │                         │
  │                         │                         │
  │ (render login UI        │                         │
  │  based on providers)    │                         │
  │                         │                         │
  │ POST /auth/sign-in/...  │                         │
  ├────────────────────────►│                         │
  │                    (BetterAuth handles flow)      │
  │                         ├────────────────────────►│
  │                         │◄────────────────────────┤
  │◄────────────────────────┤                         │
  │ Set-Cookie + redirect   │                         │
```

**Why backend discovery (not build-time env var):**

- Auth config can change without rebuilding the frontend Docker image
- Health-aware: backend can disable a provider if its upstream is unreachable
- Single source of truth: no risk of frontend/backend config drift

### Auth Config Response Shape

```typescript
interface AuthConfigResponse {
  providers: AuthProvider[];
}

interface AuthProvider {
  id: string; // "authentik", "email"
  name: string; // Display name for UI
  type: "oauth" | "credentials";
}
```

**What is NOT exposed:** client secrets, client IDs, issuer URLs, redirect URIs,
session expiry times, rate limit thresholds. Only capability metadata.

### Frontend Auth State Machine

```
loading ──► unauthenticated ──► authenticating ──► authenticated
                 │                    │                  │
                 │◄───── error ◄──────┘                  │
                 │                                       │
                 │◄──────────── session-expired ◄────────┘
```

States:

- `loading` — checking `/auth/session` on mount
- `unauthenticated` — no valid session, show login page
- `authenticating` — OAuth redirect or form submission in progress
- `authenticated` — valid session, user object available
- `error` — auth failed (network, credentials, OAuth, backend)
- `session-expired` — session ended mid-use, redirect to login

---

## 3. Backend Remediation

### 3.1 Extend Startup Validation

**File:** `apps/api/src/auth/auth.config.ts`

Add `OIDC_REDIRECT_URI` to `REQUIRED_OIDC_ENV_VARS`. Add URL format validation:

- Must be a valid URL
- Path must start with `/auth/oauth2/callback`
- Warn if using `localhost` in production

**Tests to add:** Missing var, invalid URL, invalid path, valid URL.

### 3.2 Auth Config Discovery Endpoint

**New endpoint:** `GET /auth/config` (public, no auth required)

Returns the list of enabled providers:

- Always includes `email` provider (when `emailAndPassword.enabled`)
- Includes `authentik` provider only when `OIDC_ENABLED=true` **and** the OIDC
  provider is reachable (health check)

Cache: `Cache-Control: public, max-age=300` (5 minutes).

No rate limiting needed (read-only, public, low-risk).

**OIDC Health Check:** Implement `isOidcProviderReachable()` in `AuthService` that
fetches the OIDC discovery URL with a 2-second timeout. Cache the result for 30
seconds to avoid repeated network calls. When Authentik is unreachable, the
`authentik` provider is omitted from the config response, causing the frontend to
hide the OAuth button and show only email/password login.

**Secret leakage prevention:** The response must NOT contain `OIDC_CLIENT_SECRET`,
`OIDC_CLIENT_ID`, `OIDC_ISSUER`, `OIDC_REDIRECT_URI`, `BETTER_AUTH_SECRET`,
`JWT_SECRET`, `CSRF_SECRET`, session expiry times, or rate limit thresholds.
Add an explicit test that serializes the response body and asserts none of these
patterns appear.

**Files:**

- `apps/api/src/auth/auth.controller.ts` — add endpoint
- `apps/api/src/auth/auth.service.ts` — add `getAuthConfig()` and `isOidcProviderReachable()`
- `packages/shared/src/types/auth.types.ts` — add `AuthProvider`, `AuthConfigResponse`

### 3.3 BetterAuth Error Handling Wrapper

**File:** `apps/api/src/auth/auth.controller.ts`

Wrap the `handler(req, res)` call in try/catch:

- Log errors with full context (method, URL, stack trace)
- If response not yet sent, throw `HttpException` to trigger `GlobalExceptionFilter`
- If response already started, log warning only (can't throw after headers sent)

### 3.4 Docker Compose Fixes

**File:** `docker-compose.swarm.portainer.yml`

Change line 115 from:

```yaml
OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI}
```

To:

```yaml
OIDC_REDIRECT_URI: ${OIDC_REDIRECT_URI:-}
```

Empty string is intentional — startup validation catches it when OIDC is enabled.

### 3.5 Email/Password Status Decision

BetterAuth `emailAndPassword: { enabled: true }` is set but incomplete:

- No `sendVerificationEmail` callback configured
- No `sendResetPassword` callback configured
- No email service (SMTP/SendGrid) integrated

**Decision:** Keep enabled without email verification for MVP. This provides a
fallback login method when Authentik is unreachable. Users can sign in with
email/password but cannot reset passwords or verify email addresses. A future
milestone should add an email service (SMTP/SendGrid) with `sendVerificationEmail`
and `sendResetPassword` callbacks.

**Trade-off acknowledged:** The backend specialist recommended disabling until email
service exists (safer). We chose to keep enabled because: (a) it provides the only
fallback when Authentik is down, (b) the risk is limited — no public sign-up means
only admin-created accounts can use it, (c) password reset can be handled manually
by admins until the email service is added.

### 3.6 Extract trustedOrigins to Environment Variables

**File:** `apps/api/src/auth/auth.config.ts`

Replace hardcoded origins with a `getTrustedOrigins()` function that reads:

- `NEXT_PUBLIC_APP_URL` (primary frontend URL)
- `NEXT_PUBLIC_API_URL` (API's own origin)
- `TRUSTED_ORIGINS` (comma-separated additional origins)
- Development-only localhost fallbacks

Align with CORS configuration in `main.ts` to use the same origin list.

### 3.7 Enable PKCE

**File:** `apps/api/src/auth/auth.config.ts`

Add `pkce: true` to the genericOAuth provider config. PKCE (Proof Key for Code
Exchange) prevents authorization code interception attacks. Authentik supports PKCE.

---

## 4. Frontend Remediation

### 4.1 Login Page Redesign

The login page adapts based on the auth config from `GET /auth/config`:

**When OIDC is enabled (OAuth + email/password):**

```
┌─────────────────────────────────┐
│       Welcome to Mosaic Stack   │
│                                 │
│  [error banner if ?error param] │
│                                 │
│  ┌─────────────────────────┐    │
│  │ Continue with Authentik │    │ ← OAuthButton (primary)
│  └─────────────────────────┘    │
│                                 │
│  ──── or continue with email ── │ ← AuthDivider
│                                 │
│  Email: [________________]      │
│  Password: [_____________]      │ ← LoginForm (secondary)
│  [    Continue    ]             │
│                                 │
└─────────────────────────────────┘
```

**When OIDC is disabled (email/password only):**

```
┌─────────────────────────────────┐
│       Welcome to Mosaic Stack   │
│                                 │
│  [error banner if ?error param] │
│                                 │
│  Email: [________________]      │
│  Password: [_____________]      │ ← LoginForm (primary)
│  [    Continue    ]             │
│                                 │
└─────────────────────────────────┘
```

### 4.2 New Components

| Component              | File                                       | Purpose                                                 |
| ---------------------- | ------------------------------------------ | ------------------------------------------------------- |
| `OAuthButton`          | `components/auth/OAuthButton.tsx`          | Replaces `LoginButton`. Loading state, provider config. |
| `LoginForm`            | `components/auth/LoginForm.tsx`            | Email/password form with validation                     |
| `AuthErrorBanner`      | `components/auth/AuthErrorBanner.tsx`      | PDA-friendly error display                              |
| `AuthDivider`          | `components/auth/AuthDivider.tsx`          | "or continue with email" separator                      |
| `SessionExpiryWarning` | `components/auth/SessionExpiryWarning.tsx` | Floating banner when session nears expiry               |

**Delete:** `components/auth/LoginButton.tsx` (replaced by `OAuthButton`)

### 4.3 PDA-Friendly Error Messages

All error messages follow PDA design principles. No alarming language.

| Error Source          | Message                                                          |
| --------------------- | ---------------------------------------------------------------- |
| OAuth callback failed | "Authentication paused. Please try again when ready."            |
| Invalid credentials   | "The email and password combination wasn't recognized."          |
| Network failure       | "Unable to connect. Check your network and try again."           |
| Backend 500           | "The service is taking a break. Please try again in a moment."   |
| Backend 502/503       | "The service is temporarily unavailable. Try again in a moment." |
| Backend 504           | "The connection took longer than expected. Check your network."  |
| Rate limited          | "You've tried a few times. Take a moment and try again shortly." |
| Session expired       | "Your session ended. Please sign in again when ready."           |

**Colors:** Blue info banner (`bg-blue-50`, `border-blue-200`, `text-blue-700`).
No red. No warning icons. Info icon only.

### 4.4 Auth Config Fetching

The login page fetches `GET /auth/config` on mount to determine which providers
to render. If the fetch fails, fall back to showing only the email/password form
(safest default).

```typescript
// In login page
const [authConfig, setAuthConfig] = useState<AuthConfigResponse | null>(null);

useEffect(() => {
  fetch(`${API_BASE_URL}/auth/config`)
    .then((res) => res.json())
    .then(setAuthConfig)
    .catch(() => {
      // Fallback: show email/password only
      setAuthConfig({ providers: [{ id: "email", name: "Email", type: "credentials" }] });
    });
}, []);
```

### 4.5 Loading States

- **OAuth button:** Shows spinner + "Connecting..." during redirect
- **Login form:** Inputs disabled + submit button shows spinner during API call
- **Callback page:** Already has spinner (no changes needed)
- **Session check:** Full-page spinner while AuthProvider checks `/auth/session`

### 4.6 Error Display on Login Page

The login page reads `?error=` query params from the callback redirect and displays
them in the `AuthErrorBanner`. Error codes are sanitized against an allowlist (already
implemented in callback page).

### 4.7 Fix Theme Storage Key

**File:** `apps/web/src/providers/ThemeProvider.tsx`

Change `STORAGE_KEY` from `"jarvis-theme"` to `"mosaic-theme"`.

### 4.8 Accessibility Requirements

- All form inputs have associated `<label>` with `htmlFor`
- Error messages use `role="alert"` and `aria-live="polite"`
- Loading states use `role="status"` and `aria-label`
- Focus management: auto-focus first input on page load
- Keyboard navigation: Tab through all interactive elements
- Color contrast: WCAG 2.1 AA minimum (4.5:1 for text)
- Screen reader: descriptive `aria-label` on icon-only buttons

---

## 5. Security Hardening

### Priority: Critical

| Finding                                | Risk                               | Fix                                              |
| -------------------------------------- | ---------------------------------- | ------------------------------------------------ |
| Missing `OIDC_REDIRECT_URI` validation | Open redirect / callback hijacking | Add to `REQUIRED_OIDC_ENV_VARS` + URL validation |
| PKCE not enabled                       | Authorization code interception    | Add `pkce: true` to genericOAuth config          |

### Priority: High

| Finding                                 | Risk                              | Fix                                 |
| --------------------------------------- | --------------------------------- | ----------------------------------- |
| Auth config endpoint could leak secrets | Information disclosure            | Strict DTO, test for secret leakage |
| BetterAuth errors not logged            | Blind spot in security monitoring | Try/catch wrapper with logging      |

### Priority: Medium

| Finding                         | Risk                          | Fix                                                                        |
| ------------------------------- | ----------------------------- | -------------------------------------------------------------------------- |
| `@SkipCsrf()` on auth catch-all | Potential CSRF on auth routes | Document rationale (BetterAuth handles CSRF internally via Fetch Metadata) |
| Session lacks idle timeout      | Stale sessions                | Set `updateAge` < `expiresIn` (e.g., 2h idle, 7d absolute)                 |
| trustedOrigins hardcoded        | Configuration inflexibility   | Extract to env vars                                                        |
| Rate limits too uniform         | OAuth callbacks may hit limit | Consider dynamic rate limits per endpoint type                             |

### Priority: Low

| Finding                            | Risk                      | Fix                                   |
| ---------------------------------- | ------------------------- | ------------------------------------- |
| Cross-origin cookie behavior       | Safari/Firefox edge cases | Document; add `COOKIE_DOMAIN` env var |
| Error info leakage from BetterAuth | Stack trace exposure      | Error wrapper returns generic message |

### Session Configuration Recommendation

```typescript
session: {
  expiresIn: 60 * 60 * 24 * 7,  // 7 days absolute max
  updateAge: 60 * 60 * 2,        // 2 hours idle timeout (sliding window)
},
advanced: {
  defaultCookieAttributes: {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "lax",
  },
},
```

---

## 6. Implementation Phases

### Phase 1: Critical Backend Fixes

**Scope:** Fix the production 500 error and logging blind spot.

| Story | Description                                                                                                                                                                                                                                                                                                                                          |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.1   | Add `OIDC_REDIRECT_URI` to `REQUIRED_OIDC_ENV_VARS` with URL + path validation                                                                                                                                                                                                                                                                       |
| 1.2   | Wrap BetterAuth handler in try/catch with error logging                                                                                                                                                                                                                                                                                              |
| 1.3   | Fix `docker-compose.swarm.portainer.yml` OIDC_REDIRECT_URI default                                                                                                                                                                                                                                                                                   |
| 1.4   | Enable PKCE in genericOAuth config. Verify PKCE works by checking that authorization URL includes `code_challenge` parameter.                                                                                                                                                                                                                        |
| 1.5   | Add inline documentation above `@SkipCsrf()` explaining: BetterAuth implements CSRF protection internally via Fetch Metadata headers (Sec-Fetch-Site, Sec-Fetch-Mode) and SameSite=Lax cookies. The `@SkipCsrf()` skips the _custom_ CSRF guard to avoid double-protection conflicts. Reference: https://www.better-auth.com/docs/reference/security |

**Tests:** Validation tests, error wrapper tests, PKCE verification (check `code_challenge` in auth URL).
**Dependencies:** None. Can deploy independently.

### Phase 2: Auth Config Discovery

**Scope:** Backend advertises available auth methods.

| Story | Description                                                                      |
| ----- | -------------------------------------------------------------------------------- |
| 2.1   | Add `AuthProvider` and `AuthConfigResponse` types to `@mosaic/shared`            |
| 2.2   | Implement `getAuthConfig()` in `AuthService`                                     |
| 2.3   | Add `GET /auth/config` endpoint in `AuthController`                              |
| 2.4   | Add secret-leakage prevention test                                               |
| 2.5   | Implement `isOidcProviderReachable()` health check with 2s timeout and 30s cache |

**Tests:** Unit tests for service, integration test for endpoint, health check mock tests.
**Dependencies:** None. Backward compatible (frontend doesn't use it yet).

### Phase 3: Backend Hardening

**Scope:** Security and configuration improvements.

| Story | Description                                                                                                                                                                                                                                                                                                          |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 3.1   | Extract `trustedOrigins` to `getTrustedOrigins()` with env vars                                                                                                                                                                                                                                                      |
| 3.2   | Align CORS config in `main.ts` to use same origin list                                                                                                                                                                                                                                                               |
| 3.3   | Update session config: change `expiresIn` to `60 * 60 * 24 * 7` (7 days absolute), `updateAge` to `60 * 60 * 2` (2h idle timeout). Add `advanced.defaultCookieAttributes` with explicit `httpOnly`, `secure`, `sameSite: "lax"`. Note: existing sessions will expire naturally under old rules; no migration needed. |
| 3.4   | Add `TRUSTED_ORIGINS`, `COOKIE_DOMAIN` to `.env.example`                                                                                                                                                                                                                                                             |

**Tests:** Origin extraction tests, session config tests.
**Dependencies:** Phase 1 (validation fixes).

### Phase 4: Frontend Foundation

**Scope:** Base components needed for the login page redesign.

| Story | Description                                                                         |
| ----- | ----------------------------------------------------------------------------------- |
| 4.1   | Fix theme storage key (`"jarvis-theme"` to `"mosaic-theme"`)                        |
| 4.2   | Create `AuthErrorBanner` component with PDA-friendly messages                       |
| 4.3   | Create `AuthDivider` component                                                      |
| 4.4   | Create `OAuthButton` component (replaces `LoginButton`)                             |
| 4.5   | Create `LoginForm` component with email/password validation                         |
| 4.6   | Create `SessionExpiryWarning` component (floating banner, PDA-friendly, blue theme) |

**Tests:** Unit tests for each component.
**Dependencies:** None (components are independent).

### Phase 5: Login Page Integration

**Scope:** Wire everything together on the login page.

| Story | Description                                                                                                                                                       |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 5.1   | Fetch `GET /auth/config` on login page mount                                                                                                                      |
| 5.2   | Render providers dynamically (OAuth + email/password)                                                                                                             |
| 5.3   | Read and display `?error=` query params via `AuthErrorBanner`                                                                                                     |
| 5.4   | Add loading states to OAuth and form flows                                                                                                                        |
| 5.5   | Delete old `LoginButton.tsx` and update imports                                                                                                                   |
| 5.6   | Responsive layout (mobile-first)                                                                                                                                  |
| 5.7   | Accessibility audit per Section 4.8: run axe-core on login page, verify keyboard navigation, verify WCAG 2.1 AA color contrast (4.5:1), verify screen reader flow |

**Tests:** Integration tests, E2E tests for both auth paths.
**Dependencies:** Phase 2 (backend config endpoint), Phase 4 (components).

### Phase 6: Error Recovery & Polish

**Scope:** Robust error handling and UX polish.

| Story | Description                                                                                         |
| ----- | --------------------------------------------------------------------------------------------------- |
| 6.1   | Create `auth-errors.ts` with error parsing and PDA message mapping                                  |
| 6.2   | Add retry logic for network errors (3x exponential backoff)                                         |
| 6.3   | Enhance AuthProvider with `session-expiring` state                                                  |
| 6.4   | Integrate `SessionExpiryWarning` into authenticated layout; trigger 5 minutes before session expiry |
| 6.5   | Update `auth-client.ts` error messages to PDA-friendly language                                     |

**Tests:** Error parsing tests, retry logic tests, state transition tests.
**Dependencies:** Phase 5 (login page working).

---

## 7. File Change Map

### Files to Create

| File                                                    | Phase | Purpose                               |
| ------------------------------------------------------- | ----- | ------------------------------------- |
| `apps/web/src/components/auth/OAuthButton.tsx`          | 4     | OAuth login button with loading state |
| `apps/web/src/components/auth/LoginForm.tsx`            | 4     | Email/password form                   |
| `apps/web/src/components/auth/AuthErrorBanner.tsx`      | 4     | PDA-friendly error display            |
| `apps/web/src/components/auth/AuthDivider.tsx`          | 4     | "or continue with email" separator    |
| `apps/web/src/lib/auth/auth-errors.ts`                  | 6     | Error parsing and message mapping     |
| `apps/web/src/components/auth/SessionExpiryWarning.tsx` | 4     | Session expiry warning banner         |

### Files to Modify

| File                                       | Phase | Changes                                                            |
| ------------------------------------------ | ----- | ------------------------------------------------------------------ |
| `apps/api/src/auth/auth.config.ts`         | 1, 3  | OIDC_REDIRECT_URI validation, PKCE, trustedOrigins, session config |
| `apps/api/src/auth/auth.config.spec.ts`    | 1, 3  | New validation tests                                               |
| `apps/api/src/auth/auth.controller.ts`     | 1, 2  | Error wrapper, GET /auth/config endpoint                           |
| `apps/api/src/auth/auth.service.ts`        | 2     | getAuthConfig() method                                             |
| `apps/api/src/main.ts`                     | 3     | Align CORS with getTrustedOrigins()                                |
| `packages/shared/src/types/auth.types.ts`  | 2     | AuthProvider, AuthConfigResponse types                             |
| `packages/shared/src/types/index.ts`       | 2     | Export new types                                                   |
| `apps/web/src/app/(auth)/login/page.tsx`   | 5     | Full redesign with dynamic providers                               |
| `apps/web/src/lib/auth-client.ts`          | 6     | PDA error messages                                                 |
| `apps/web/src/lib/auth/auth-context.tsx`   | 6     | Session-expiring state                                             |
| `apps/web/src/providers/ThemeProvider.tsx` | 4     | Fix storage key                                                    |
| `docker-compose.swarm.portainer.yml`       | 1     | OIDC_REDIRECT_URI default                                          |
| `.env.example`                             | 3     | New env vars documented                                            |

### Files to Delete

| File                                                | Phase | Reason                        |
| --------------------------------------------------- | ----- | ----------------------------- |
| `apps/web/src/components/auth/LoginButton.tsx`      | 5     | Replaced by OAuthButton       |
| `apps/web/src/components/auth/LoginButton.test.tsx` | 5     | Replaced by OAuthButton tests |

---

## 8. Testing Strategy

### Unit Tests (per phase)

**Phase 1:**

- `validateOidcConfig()` with missing OIDC_REDIRECT_URI
- `validateOidcConfig()` with invalid URL
- `validateOidcConfig()` with invalid callback path
- `validateOidcConfig()` with valid config
- BetterAuth handler error wrapper (mock throw, headers sent vs not)
- PKCE: verify authorization URL includes `code_challenge` parameter

**Phase 2:**

- `getAuthConfig()` with OIDC enabled returns authentik provider
- `getAuthConfig()` with OIDC disabled returns only email provider
- `getAuthConfig()` omits authentik when OIDC provider is unreachable (mock health check)
- `GET /auth/config` returns correct response shape
- `GET /auth/config` sets Cache-Control header
- Secret leakage: serialize response body and assert it does NOT contain `CLIENT_SECRET`, `CLIENT_ID`, `JWT_SECRET`, `BETTER_AUTH_SECRET`, `CSRF_SECRET`, `REDIRECT_URI`, or `callback` strings
- Health check: `isOidcProviderReachable()` returns false on timeout, caches result for 30s

**Phase 3:**

- `getTrustedOrigins()` with various env configs
- `getTrustedOrigins()` excludes localhost in production
- Session idle timeout behavior

**Phase 4:**

- `AuthErrorBanner` renders PDA-friendly messages
- `AuthErrorBanner` is dismissible
- `LoginForm` validates email and password
- `LoginForm` shows loading state during submission
- `OAuthButton` shows loading state during redirect

**Phase 5:**

- Login page renders OAuth button when OIDC enabled
- Login page hides OAuth button when OIDC disabled
- Login page displays error from query params
- Login page falls back to email-only on config fetch failure

**Phase 6:**

- `parseAuthError()` classifies all error types
- Retry logic respects max retries
- Session expiry detection triggers warning

### E2E Tests (Playwright)

- Login with OIDC enabled: OAuth button visible, form visible, divider visible
- Login with OIDC disabled: Only email form visible
- Error display: Visit `/login?error=access_denied`, verify PDA-friendly banner
- Form validation: Submit empty form, verify error messages

### Coverage Target

Minimum 85% coverage on all new and modified files.

---

## 9. Rollout & Rollback

### Deployment Order

1. **Phase 1** (backend fixes) — Deploy immediately, fixes production 500
2. **Phase 2** (auth config endpoint) — Deploy next, backward compatible
3. **Phase 3** (hardening) — Deploy with Phase 2 or independently
4. **Phase 4-6** (frontend) — Deploy together as a single release

### Rollback Plan

**Backend (Phases 1-3):** All changes are backward compatible. No rollback needed
unless a bug is introduced. Standard revert-and-redeploy.

**Frontend (Phases 4-6):** If the new login page has issues:

1. Tag the current `develop` branch before deploying Phases 4-6: `git tag pre-auth-redesign`
2. The old `LoginButton` component is preserved in git history
3. Revert the frontend changes and redeploy from the tag
4. Backend auth config endpoint remains deployed but unused

### Monitoring

After deployment, watch for:

- Auth error rates (should decrease after Phase 1)
- `/auth/config` latency and error rate
- Login success rate by method (OAuth vs email/password)
- BetterAuth handler error logs (new visibility from Phase 1)

---

## 10. Open Questions

### Q1: Should the auth config be polled or fetched once?

**Context:** The frontend needs to know what auth methods are available.

**Recommendation:** Fetch once on login page mount. The 5-minute cache header on the
backend handles staleness. No polling needed — auth config rarely changes at runtime.

### Q2: Rate limiting granularity

**Context:** Current rate limit is 10 req/min for all auth routes. OAuth callbacks
could hit this during normal use (3 requests per login attempt).

**Recommendation:** Keep uniform rate limit for now. If users report being rate-limited
during OAuth flows, implement dynamic rate limits per endpoint type in a follow-up.

### Q3: Feature flag for gradual rollout?

**Context:** The frontend changes are significant. A feature flag could enable gradual
rollout.

**Recommendation:** Not needed for this scope. The changes are deterministic (based on
backend config) and can be tested thoroughly in staging before production deployment.

---

## Appendix A: Data Flow Diagrams

### OAuth Sign-In Flow

```
Browser                    NestJS API               Authentik
  │                            │                        │
  │ 1. GET /auth/config        │                        │
  ├───────────────────────────►│                        │
  │◄───────────────────────────┤                        │
  │ { providers: [authentik] } │                        │
  │                            │                        │
  │ 2. Click "Continue with Authentik"                  │
  │    signIn.oauth2({ providerId: "authentik" })       │
  │                            │                        │
  │ 3. POST /auth/sign-in/oauth2                       │
  ├───────────────────────────►│                        │
  │                   BetterAuth constructs auth URL    │
  │◄───────────────────────────┤                        │
  │ 302 → Authentik authorize  │                        │
  │                            │                        │
  │ 4. Redirect to Authentik   │                        │
  ├────────────────────────────────────────────────────►│
  │                            │      User authenticates│
  │◄────────────────────────────────────────────────────┤
  │ 302 → /auth/oauth2/callback/authentik?code=X               │
  │                            │                        │
  │ 5. GET /auth/oauth2/callback/authentik?code=X              │
  ├───────────────────────────►│                        │
  │                   BetterAuth exchanges code         │
  │                            ├───────────────────────►│
  │                            │◄───────────────────────┤
  │                            │ tokens                 │
  │                   Creates User + Session            │
  │◄───────────────────────────┤                        │
  │ Set-Cookie + 302 → /       │                        │
  │                            │                        │
  │ 6. Frontend /callback page │                        │
  │    refreshSession()        │                        │
  │    redirect → /tasks       │                        │
```

### Email/Password Sign-In Flow

```
Browser                    NestJS API
  │                            │
  │ 1. GET /auth/config        │
  ├───────────────────────────►│
  │◄───────────────────────────┤
  │ { providers: [email] }     │
  │                            │
  │ 2. User enters email + password
  │    Clicks "Continue"       │
  │                            │
  │ 3. POST /auth/sign-in      │
  │    { email, password }     │
  ├───────────────────────────►│
  │                   BetterAuth verifies
  │                   Creates Session
  │◄───────────────────────────┤
  │ Set-Cookie + user data     │
  │                            │
  │ 4. Frontend stores session │
  │    redirect → /tasks       │
```

---

## Appendix B: PDA Error Message Reference

These messages replace standard error language throughout the auth UI.

| Standard Term     | PDA-Friendly Alternative                          |
| ----------------- | ------------------------------------------------- |
| Error             | (omit entirely or use "Notice")                   |
| Failed            | "Paused" or "Didn't complete"                     |
| Invalid           | "Wasn't recognized"                               |
| Required          | "Needed to continue"                              |
| Try again         | "Consider trying again" or "Try again when ready" |
| Unauthorized      | "Session ended"                                   |
| Forbidden         | "Not available"                                   |
| Timeout           | "Took longer than expected"                       |
| Too many requests | "You've tried a few times"                        |

**Color scheme:** Blue (`bg-blue-50`), not red. Info icon, not warning icon.

---

## Appendix C: Environment Variables

New or modified environment variables introduced by this plan:

| Variable            | Default | Required          | Description                                  |
| ------------------- | ------- | ----------------- | -------------------------------------------- |
| `OIDC_REDIRECT_URI` | (empty) | When OIDC enabled | OAuth callback URL                           |
| `TRUSTED_ORIGINS`   | (empty) | No                | Additional trusted origins (comma-separated) |
| `COOKIE_DOMAIN`     | (empty) | No                | Cookie domain for cross-subdomain sessions   |

---

_End of plan. Future sessions will use this to create the proper milestone and
issues in the Gitea repository._