stack/docs/scratchpads/p5-004-authentik-sso.md

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 @mosaic/db build
  2. pnpm --filter @mosaic/auth typecheck
  3. pnpm --filter @mosaic/gateway typecheck
  4. pnpm lint
  5. pnpm format:check
  6. pnpm --filter @mosaic/auth test
  7. pnpm --filter @mosaic/gateway test

• Results:

  1. @mosaic/auth typecheck passed after replacing the non-existent enabled field with conditional plugin registration.
  2. @mosaic/gateway typecheck passed.
  3. Repo lint passed.
  4. Prettier check passed after formatting apps/gateway/src/main.ts.
  5. @mosaic/auth tests reported No test files found, exiting with code 0.
  6. @mosaic/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.