# P5-004 Scratchpad

- Objective: Add optional Authentik OIDC SSO adapter via Better Auth genericOAuth.
- Task ref: P5-004
- Issue ref: #96
- Plan:
  1. Inspect auth/gateway surfaces and Better Auth plugin shape.
  2. Add failing coverage for auth config/startup validation where feasible.
  3. Implement adapter, docs, and warnings.
  4. Run targeted typechecks, lint, and review.

- TDD note: no low-friction auth plugin or bootstrap-env test seam exists for `packages/auth/src/auth.ts` or `apps/gateway/src/main.ts`. This change is configuration-oriented and does not alter an existing behavioral contract with a current test harness. I skipped new tests for this pass and relied on exact typecheck/lint/test commands plus manual review.

- Changes:
  1. Added conditional Better Auth `genericOAuth` plugin registration for the `authentik` provider in `packages/auth/src/auth.ts`.
  2. Added a soft startup warning in `apps/gateway/src/main.ts` for incomplete Authentik env configuration.
  3. Added `docs/plans/authentik-sso-setup.md` with env, redirect URI, and test-flow guidance.
  4. Confirmed `packages/auth/src/index.ts` already exports `AuthConfig`; no change required there.

- Verification:
  1. `pnpm --filter @mosaicstack/db build`
  2. `pnpm --filter @mosaicstack/auth typecheck`
  3. `pnpm --filter @mosaicstack/gateway typecheck`
  4. `pnpm lint`
  5. `pnpm format:check`
  6. `pnpm --filter @mosaicstack/auth test`
  7. `pnpm --filter @mosaicstack/gateway test`

- Results:
  1. `@mosaicstack/auth` typecheck passed after replacing the non-existent `enabled` field with conditional plugin registration.
  2. `@mosaicstack/gateway` typecheck passed.
  3. Repo lint passed.
  4. Prettier check passed after formatting `apps/gateway/src/main.ts`.
  5. `@mosaicstack/auth` tests reported `No test files found, exiting with code 0`.
  6. `@mosaicstack/gateway` tests passed: `3` files, `20` tests.

- Review:
  1. Manual review of the diff found no blocker issues.
  2. External `codex-code-review.sh --uncommitted` was attempted but did not return a usable verdict in-session; no automated review findings were available from that run.

- Situational evidence:
  1. Provider activation is env-gated by `AUTHENTIK_CLIENT_ID`.
  2. Misconfigured optional SSO surfaces a warning instead of crashing gateway startup.
  3. Setup doc records the expected redirect path: `{BETTER_AUTH_URL}/api/auth/callback/authentik`.