Phase1

docs/IMPLEMENTATION_STATUS.md

@@ -2,65 +2,54 @@
 
 Last updated: 2026-06-26
 
-## Current phase: Phase 0 — Repository and foundations ✅
+## Current phase: Phase 1 — Authentication & user panel ✅
 
-### Completed
+### Phase 1 completed
 
 | Area | Status | Notes |
 |------|--------|-------|
-| Monorepo layout | Done | pnpm workspace, Turborepo, shared TypeScript config |
-| `@hexahost/database` | Done | Prisma 6, 14 Kernmodelle, UUID-IDs, optimistic locking |
-| `@hexahost/contracts` | Done | Zod-Schemas (Health, RFC7807, Pagination) + Vitest |
-| `@hexahost/config` | Done | Typisierter Env-Loader mit Validierung |
-| `@hexahost/auth` | Done | Rollen-Enum und Typen (Stub für Phase 1) |
-| `@hexahost/ui` | Done | Button, Card (Tailwind, a11y) |
-| `@hexahost/api` | Done | NestJS 11 + Fastify, Health, OpenAPI, Pino, Rate Limits |
-| `@hexahost/worker` | Done | BullMQ-Queues (Stubs), Health HTTP :3002 |
-| `@hexahost/web` | Done | Next.js 15, i18n de/en, Dark Mode, Landing, Auth-UI, Dashboard |
-| Go node-agent | Done | Protokoll-Typen, Health, Agent-Loop, Unit-Tests |
-| Go edge-gateway | Stub | Deaktiviert (Phase 8) |
-| Docker Compose dev | Done | PostgreSQL, Redis, MinIO, Mailpit, API, Worker, Web |
-| `.env.example` | Done | Vollständige Konfigurationsvorlage |
-| CI pipeline | Done | Lint, typecheck, test, build, Go-Tests |
-| Dokumentation | Done | ADR, Architektur, Threat Model, Installation |
-| WHMCS-Layout | Placeholder | Verzeichnisstruktur für spätere Integration |
-| README | Done | Startbefehle und Übersicht |
+| Prisma auth models | Done | EmailVerificationToken, PasswordResetToken, TotpCredential, RecoveryCode |
+| Migration | Done | `20260626120000_phase1_auth` + platform role seed |
+| `@hexahost/auth` | Done | Argon2id, tokens, TOTP, recovery codes, username utils |
+| API AuthModule | Done | Register, login, logout, verify, reset, 2FA, `/me`, sessions |
+| Session cookies | Done | `hgc_session`, HttpOnly, Secure in prod, SameSite lax |
+| Account lockout | Done | 5 attempts → 15 min lock |
+| Worker emails | Done | `notifications` queue → nodemailer (Mailpit in dev) |
+| Web auth UI | Done | Login, register, 2FA, forgot/reset, verify, security |
+| Route protection | Done | Middleware cookie check for dashboard/security |
+| Admin bootstrap | Done | `pnpm bootstrap:admin --email … --password …` |
+| Tests | Done | Auth package vitest, API health/auth tests, contracts |
 
-### Abnahmekriterium Phase 0
+### Abnahmekriterium Phase 1
 
-- [x] Monorepo-Struktur mit allen Grundverzeichnissen
-- [x] pnpm-workspace, Turborepo, Next.js, NestJS, Worker, Go-Module
-- [x] PostgreSQL/Prisma-Grundschema
-- [x] Redis- und MinIO-Konfiguration in Compose
-- [x] Healthchecks (API, Worker, Node Agent)
-- [x] Strukturiertes Logging (Pino)
-- [x] OpenAPI unter `/api/v1/docs`
-- [x] Basis-CI
-- [x] ADR und IMPLEMENTATION_STATUS
-- [x] Build, Lint, Typecheck und Tests lokal grün
+- [x] Registration with email verification flow
+- [x] Login/logout with secure sessions
+- [x] Password reset
+- [x] TOTP 2FA setup and login challenge
+- [x] Session list and revoke
+- [x] Admin bootstrap CLI (no default credentials)
+- [x] Audit events for security actions
+- [x] Unit/integration tests pass
 
 ### Known limitations
 
-- Edge Gateway ist bewusst nicht implementiert (Join-to-Start = Phase 8).
-- Authentifizierung, Server-Lifecycle und Node-WebSocket folgen in Phase 1–2.
-- Traefik-, Ansible- und Produktions-Compose sind dokumentiert, nicht vollständig umgesetzt.
-- Docker Compose erfordert optional `docker network create traefik-network`.
-- WHMCS-Integration ist nur als Verzeichnisstruktur vorbereitet.
+- E2E Playwright tests for auth flow not yet added (planned).
+- Email templates are minimal HTML (no branded layout yet).
+- OIDC / Passkeys deferred to later phases.
+- CSRF relies on SameSite cookies + CORS origin check; no double-submit token yet.
 
 ### Test commands
 
 ```bash
 pnpm install
-pnpm lint
-pnpm typecheck
+pnpm db:migrate    # or db:push
 pnpm test
 pnpm build
-cd apps/node-agent && make test
+pnpm bootstrap:admin -- --email admin@localhost --password 'your-secure-password'
 ```
 
-### Next phase: Phase 1 — Authentication & user panel
+### Next phase: Phase 2 — Single-Node Vertical Slice
 
-- Registrierung, E-Mail-Verifizierung, Login, Sessions
-- Passwort-Reset, TOTP 2FA, Recovery Codes
-- Admin-Bootstrap-CLI
-- Vollständiger sicherer Login-Flow mit Tests
+- GameNode enrollment, Go agent WebSocket
+- Server create, provision, start/stop
+- First playable Minecraft server locally

docs/adr/0002-session-authentication.md

@@ -0,0 +1,30 @@
+# ADR 0002: Session-based authentication with HttpOnly cookies
+
+## Status
+
+Accepted — 2026-06-26
+
+## Context
+
+Phase 1 requires secure user authentication without binding to external identity providers. The web app (Next.js) and API (NestJS) run on different origins in development (`localhost:3000` / `localhost:3001`) but share credentials via CORS.
+
+## Decision
+
+- Use opaque session tokens (32 random bytes), stored as SHA-256 hash in `UserSession`.
+- Deliver sessions via HttpOnly cookie `hgc_session` with `SameSite=lax` and `Secure` in production.
+- Password hashing with Argon2id via `@node-rs/argon2`.
+- TOTP 2FA with `otplib`; recovery codes stored hashed.
+- Login challenges for 2FA stored in Redis (5 min TTL).
+- Transactional emails via BullMQ `notifications` queue processed by worker + SMTP.
+
+## Consequences
+
+- Browser clients must use `credentials: 'include'`.
+- API CORS must allow `APP_URL` with credentials.
+- Session revocation is immediate via DB `revokedAt`.
+- No JWT in localStorage (reduces XSS token theft risk).
+
+## Alternatives considered
+
+- JWT in Authorization header — rejected for Phase 1 due to refresh complexity and XSS exposure in SPA storage.
+- External auth (Auth0, Clerk) — rejected per product requirements.