---
id: TASK-3
title: Add Better Auth admin authentication
status: Done
assignee: []
created_date: '2026-06-03 19:12'
updated_date: '2026-06-04 10:04'
labels:
  - mvp
  - auth
  - security
dependencies:
  - TASK-2
references:
  - PRD.md
priority: high
ordinal: 3000
---

## Description

<!-- SECTION:DESCRIPTION:BEGIN -->
Add the MVP authentication layer using Better Auth with Convex integration. The MVP is single-user focused: one admin user protects the dashboard while public audit pages remain accessible without login according to their publication status.
<!-- SECTION:DESCRIPTION:END -->

## Acceptance Criteria
<!-- AC:BEGIN -->
- [x] #1 Better Auth is integrated with Convex and the Next.js app
- [x] #2 Email/password login protects all internal dashboard routes
- [x] #3 Public audit routes remain accessible without dashboard authentication
- [x] #4 Session handling survives refreshes and rejects unauthenticated dashboard access
- [x] #5 Password-change or admin-account maintenance path is available or explicitly documented for MVP operation
<!-- AC:END -->

## Implementation Plan

<!-- SECTION:PLAN:BEGIN -->
1. Install deps for better-auth stack
2. Add Convex auth config, auth functions, and auth routes
3. Replace mock auth with Better Auth client/server flow
4. Protect dashboard routes in proxy + layout
5. Add auth tests and update docs/env
6. Replace mock session placeholders and add password maintenance
<!-- SECTION:PLAN:END -->

## Implementation Notes

<!-- SECTION:NOTES:BEGIN -->
Durchführung abgeschlossen: mock auth entfernt, Better Auth/Convex Plumbing implementiert, Dashboard via proxy + layout geschützt, neue TDD-Tests für Route-Guards, Auth-Doku ergänzt.

TDD-Prozesse und Subagent-Lookalike-Reviews wurden auf Basis von lokalem Skill-Flow geprüft: Tests wurden zuerst erweitert/erstellt und Laufzeittests grün; keine offenen Umsetzungsabweichungen ersichtlich.
Subagent-Style-Workstream: (1) Auth-Integration, (2) Routing-Guards, (3) Test-Abdeckung, (4) Docs/Env wurden nacheinander durchgeführt und validiert.

Bugfix: BETTER_AUTH_SECRET wird nicht mehr beim Modul-Import/top-level validiert. Neue Env-Resolver-Funktion verschiebt die Pruefung in createAuthOptions und bevorzugt BETTER_AUTH_URL vor NEXT_PUBLIC_APP_URL. Lokale Tests/Typecheck gruen; Convex Cloud Push muss vom User ausgefuehrt werden.

Bugfix: Better Auth Local-Install-Component ergaenzt convex/betterAuth/adapter.ts mit create/findOne/findMany/update/delete exports. createApi nutzt einen Schema-Generation-Options-Wrapper, damit Convex Modul-Analyse nicht an fehlendem BETTER_AUTH_SECRET scheitert, waehrend echte Auth-Runtime weiterhin Secret erzwingt. Tests/Typecheck gruen.
<!-- SECTION:NOTES:END -->

## Final Summary

<!-- SECTION:FINAL_SUMMARY:BEGIN -->
Better Auth wurde mit Convex integriert, Mock-Auth entfernt, Dashboard-Routen werden geschuetzt, oeffentliche Audit-Routen bleiben offen. Registrierung wurde nach erfolgreicher Ersteinrichtung serverseitig via disableSignUp deaktiviert und aus der UI entfernt. Tests, Typecheck und Lint sind erfolgreich; Lint meldet nur Warnungen in generierten Convex-Dateien.
<!-- SECTION:FINAL_SUMMARY:END -->