release: promote EPIC-01 (Authentication & User Management) to stable

[steilerDev]

Summary

Promotes all EPIC-01 (Authentication & User Management) work from beta to main for stable release.

EPIC-01 Features

• First-Run Setup Wizard — Automatic redirect to /setup when no admin exists; create initial admin account
• Local Authentication — Email/password login with bcrypt hashing, secure HTTP-only session cookies
• OIDC Single Sign-On — OpenID Connect support (Authentik, Keycloak, etc.) with auto-provisioning
• Session Management — Configurable session duration, secure cookies, trust proxy support
• User Profile Management — View/edit display name, change password (local users)
• Admin User Management — List, search, edit roles, deactivate user accounts
• Role-Based Access Control — Admin and Member roles with route-level protection
• Docker & Deployment — Health check endpoints, reverse proxy configuration, environment variables

Included PRs

EPIC-01 Stories

• feat(auth): user database schema & migration (#28) #55 — feat(auth): add user database schema, migration, and shared types (Story 1.1: User Database Schema & Migration #28)
• feat(auth): implement local admin setup, login, and auth UI (#30) #56 — feat(auth): implement local admin setup, login, and auth UI (Story 1.2: Local Admin Authentication — Initial Setup #30)
• feat(auth): implement session management (Story #32) #57 — feat(auth): implement session management (Story 1.3: Session Management #32)
• feat(auth): add requireRole RBAC preHandler decorator (Story #37) #60 — feat(auth): add requireRole RBAC preHandler decorator (Story 1.7: Role-Based Access Control — Admin/Member #37)
• feat(auth): implement OIDC authentication (Story #34) #61 — feat(auth): implement OIDC authentication (Story 1.4: OIDC Authentication #34)
• feat(auth): implement user profile management (Story #36) #62 — feat(auth): implement user profile management (Story 1.6: User Profile Management #36)
• feat(users): implement admin user management (Story #38) #63 — feat(users): implement admin user management (Story 1.8: Admin User Management #38)
• feat(auth): add logout UI to client (Story #68) #69 — feat(auth): add logout UI to client (Story Add Logout UI to Client #68)

Refinement & Fixes

• refactor(auth): EPIC-01 refinement improvements #64 — refactor(auth): EPIC-01 refinement improvements
• fix(docker): copy server/node_modules to production stage #65 — fix(docker): copy workspace-specific server/node_modules to production stage
• fix(auth): add authentication guard and routing logic #66 — fix(auth): add authentication guard and routing logic
• fix(docker): copy SQL migration files to production image #67 — fix(docker): copy SQL migration files to production image
• fix(server): add trustProxy support for reverse proxy deployments #70 — fix(server): add trustProxy support for reverse proxy deployments
• fix: add /api/health/ready to public routes for Docker healthcheck #77 — fix: add /api/health/ready to public routes for Docker healthcheck
• fix(sidebar): hide User Management nav link for non-admin users #78 — fix(sidebar): hide User Management nav link for non-admin users

Infrastructure & Testing

• chore: pre-sprint process improvements #53 — chore: pre-sprint process improvements
• chore: fix docs-writer agent model mismatch #54 — chore: fix docs-writer agent model mismatch
• chore: integrate e2e-test-engineer agent into the team #71 — chore: integrate e2e-test-engineer agent into the team
• test: add Playwright E2E test infrastructure and suites for EPIC-02 & EPIC-01 #72 — test: add Playwright E2E test infrastructure and suites
• build(deps): update 10 dependencies across all workspaces #73 — build(deps): update dependencies across all workspaces
• ci: trigger semantic-release for all conventional commit types #74 — ci: trigger semantic-release for all conventional commit types
• chore: add gwq worktree support for parallel coding sessions #75 — chore: add gwq worktree support for parallel coding sessions
• chore: add Claude Code settings with notification hooks #76 — chore: add Claude Code settings with notification hooks

Documentation

• docs: update README with EPIC-01 authentication features #81 — docs: update README with EPIC-01 authentication features

Test Results

• 614 unit/integration tests passing (Jest)
• 402 E2E tests passing, 19 viewport-specific skips (Playwright)
• 0 vulnerabilities (npm audit)
• All quality gates green (lint, format, typecheck, build)

UAT Status

• E2E gate confirmed by e2e-test-engineer ✓
• UAT validation report produced by uat-validator ✓
• Manual UAT approved by user ✓

Merge Strategy

Use merge commit (not squash) to preserve individual commits for semantic-release version analysis.

🤖 Generated with Claude Code

[github-actions]

🎉 This PR is included in version 1.7.0-beta.18 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

[steilerDev]

[product-owner] EPIC-01 Promotion Review: APPROVED

Epic Completeness Verification

All 9 EPIC-01 user stories are CLOSED and in Done status on the Projects board:

Story	Title	PR	Status
#28	1.1: User Database Schema & Migration	#55	Merged
#30	1.2: Local Admin Authentication — Initial Setup	#56	Merged
#32	1.3: Session Management	#57	Merged
#37	1.7: Role-Based Access Control — Admin/Member	#60	Merged
#34	1.4: OIDC Authentication	#61	Merged
#35	1.5: Automatic User Provisioning on First OIDC Login	(part of #61)	Merged
#36	1.6: User Profile Management	#62	Merged
#38	1.8: Admin User Management	#63	Merged
#68	Add Logout UI to Client	#69	Merged

Refinement & Fix PRs Included

• #64 — EPIC-01 refinement (COOKIE_NAME consolidation, open redirect fix, requireRole type safety, focus-visible styles)
• #65 — Docker fix: copy workspace-specific server/node_modules
• #66 — Auth guard and routing logic
• #67 — Docker fix: copy SQL migration files
• #70 — trustProxy support for reverse proxy deployments
• #77 — /api/health/ready added to public routes
• #78 — Hide User Management nav for non-admin users

Agent Responsibilities Verification

Responsibility	Agent	Status
Backend implementation	backend-developer	All 8 stories implemented and merged
Frontend implementation	frontend-developer	All UI pages, components, and API client modules delivered
Unit/Integration tests	qa-integration-tester	614 tests passing across 34 suites
E2E browser tests	e2e-test-engineer	402 tests passing, 19 viewport-specific skips
Security review	security-engineer	Reviewed all PRs; refinement addressed open redirect vulnerability
UAT scenarios	uat-validator	122 scenarios (108 automated, 14 manual); validation reports posted
Documentation	docs-writer	README updated via PR #81
Architecture	product-architect	Schema, API contract, and ADRs maintained throughout

CI Status

All checks passing:

• Quality Gates: PASS
• Docker build: PASS
• E2E Tests: PASS (9m4s, 402 tests)
• Docker Scout: PASS
• Semantic Release: PASS

UAT Status

• E2E gate confirmed by e2e-test-engineer (comment on issue #1)
• UAT validation report posted by uat-validator with 122 scenarios
• Orchestrator confirmed user approval and staged for promotion

Merge Strategy

This PR correctly uses merge commit (not squash) per CLAUDE.md conventions, preserving individual commits for semantic-release version analysis on main.

Requirements Coverage

EPIC-01 covers all authentication and user management requirements from plan/REQUIREMENTS.md Section 2.1:

• First-run setup wizard with initial admin creation
• Local email/password authentication with secure hashing
• OIDC Single Sign-On with auto-provisioning
• Session management with configurable duration
• Role-based access control (admin/member)
• User profile management (display name, password change)
• Admin user management (list, search, edit, deactivate)
• Logout with session destruction
• Docker deployment with health checks, reverse proxy support, environment configuration

Decision

APPROVED for promotion to main. EPIC-01 is release-ready. All stories are complete, all agent responsibilities fulfilled, all CI checks green, UAT validated, and documentation updated.

Co-Authored-By: Claude product-owner (Opus 4.6) noreply@anthropic.com

[steilerDev]

[security-engineer]

Security Review: EPIC-01 Promotion (beta → main)

I have completed a comprehensive security review of PR #82, covering all authentication and user management features included in this epic promotion. This review examined the full implementation across 614 unit/integration tests and 402 E2E tests.

Executive Summary

APPROVED FOR STABLE RELEASE ✓

The EPIC-01 authentication system demonstrates strong security posture with well-implemented defenses against OWASP Top 10 vulnerabilities. All critical authentication and authorization controls are correctly implemented with defense-in-depth patterns.

---

Security Review by Domain

✅ Authentication Implementation (OWASP A07 - Identification & Authentication Failures)

Local Authentication:

• Password hashing: Uses crypto.scrypt with OWASP-compliant parameters (N=16384, r=8, p=1, keylen=64). PHC-format storage includes algorithm version and parameters for future-proofing.
• Timing attack prevention: Login endpoint hashes a dummy password when user not found or has no passwordHash (OIDC users), ensuring constant-time response regardless of user existence.
• Session tokens: 256-bit entropy via crypto.randomBytes(32) — cryptographically secure, no collision risk.
• Session fixation: Fresh session tokens generated on every login/setup (no session reuse).

OIDC Implementation:

• State parameter: 256-bit entropy via crypto.randomBytes(32), stored server-side with 10-minute TTL, one-time use (consumed after validation).
• Token validation: Delegated to openid-client@6.8.2 (OpenID Certified library) — validates ID token signature, issuer, audience, and expiration.
• Redirect URI validation: openid-client enforces redirect URI match against OIDC_REDIRECT_URI config, preventing open redirect.
• Open redirect protection: isSafeRedirect() function in oidc.ts validates post-login redirect paths (must start with /, cannot be protocol-relative // or absolute URLs).

✅ Authorization (OWASP A01 - Broken Access Control)

RBAC Enforcement:

• Route protection: requireRole() preHandler decorator enforces role checks on every protected route.
• Fresh role lookup: Roles are NOT cached in session tokens. Every request performs a fresh JOIN between sessions and users tables (sessionService.ts:62), ensuring role changes take effect immediately without re-login.
• Fail-secure design: Returns 401 for unauthenticated requests before checking roles; returns 403 for insufficient permissions.
• Admin-only routes: User management endpoints (GET /api/users, PATCH /api/users/:id, DELETE /api/users/:id) correctly protected with requireRole('admin').

Object-Level Authorization:

• Profile management: /api/users/me endpoints correctly enforce that users can only modify their own profile (checks request.user.id).
• Admin checks: SELF_DEACTIVATION and LAST_ADMIN checks prevent security policy violations (admins cannot deactivate themselves, cannot deactivate the last admin).

✅ Session Management (OWASP A07)

Cookie Security:

• HttpOnly: true (prevents XSS token theft)
• Secure: Configurable via SECURE_COOKIES env var (defaults to true for production)
• SameSite: strict (CSRF protection — cookie not sent on cross-site requests)
• Path: / (applies to all routes)
• maxAge: Matches SESSION_DURATION config (default 7 days)

Session Lifecycle:

• Validation: Checks both expires_at > now AND deactivatedAt IS NULL in a single DB query (no TOCTOU race condition).
• Cleanup: Hourly setInterval cleanup via cleanupExpiredSessions() with error handling. Interval cleared on app shutdown via onClose hook.
• Logout: destroySession() deletes session from DB + clears cookie with maxAge: 0. Idempotent (works even if session doesn't exist).
• Deactivation: destroyUserSessions() called on user deactivation (users.ts:240) — immediately invalidates all active sessions.

✅ Input Validation (OWASP A03 - Injection)

Server-Side Validation:

• JSON schema validation: Fastify/AJV validates all request bodies (setupSchema, loginSchema, changePasswordSchema, etc.).
• Email format: RFC 5322 validation via AJV format: 'email'.
• Password length: Minimum 12 characters enforced in schema.
• DisplayName length: 1-100 characters enforced in schema.
• SQL injection prevention: All queries use Drizzle ORM with parameterized queries. No raw SQL with user input. Search queries use parameterized sql template literals (userService.ts:298).

Client-Side Validation:

• Matches server constraints: All client-side validation mirrors server-side rules (password min length, displayName max length, email format).
• Input length limits: maxLength attributes on all text/password inputs (256 for passwords, 100 for displayName).
• Validation timing: Client validates before submission, server validates on every request (defense in depth).

✅ XSS Prevention (OWASP A03 - Injection)

React Built-in Escaping:

• No dangerouslySetInnerHTML: Searched entire client codebase — zero occurrences.
• No innerHTML: Zero occurrences.
• No eval(): Zero occurrences.
• Text content only: All user-provided data (email, displayName, error messages) rendered as text content via React's JSX, which automatically escapes HTML entities.

Content Security:

• Error messages: Hardcoded mapping of error codes to messages (OIDC_ERROR_MESSAGES in LoginPage.tsx:13) — no user input directly rendered.
• ARIA attributes: Properly used (aria-invalid, aria-describedby, role="alert") without injection vectors.

✅ Sensitive Data Exposure (OWASP A02 - Cryptographic Failures)

Data Protection:

• toUserResponse(): Explicitly strips passwordHash and oidcSubject from ALL API responses (userService.ts:83). Every route handler uses this function before sending user data to client.
• Logging: Config plugin logs environment variables but excludes oidcClientSecret (config.ts:143).
• No secrets in cookies: Session cookies contain only the session ID (opaque token), not user data or roles.
• No client-side secrets: No tokens, passwords, or sensitive data stored in localStorage or sessionStorage. All auth state managed server-side.

✅ CSRF Protection (OWASP A01)

Primary Defense:

• SameSite=Strict cookies: Session cookies are not sent on cross-site requests, preventing CSRF attacks on authenticated endpoints.

State Parameter (OIDC):

• OIDC CSRF: State parameter prevents CSRF attacks on the OIDC callback endpoint (attacker cannot predict the state value, cannot complete the flow).

✅ Dockerfile Security

Image Security:

• Base images: Uses Docker Hardened Images (DHI) dhi.io/node:24-alpine3.23-dev (builder) and dhi.io/node:24-alpine3.23 (production) — minimal attack surface, near-zero CVEs.
• No shell in production: Production image has no /bin/sh — all commands use exec form (CMD, HEALTHCHECK).
• Minimal production image: No npm, no build tools, no unnecessary packages.
• Non-root user: DHI images run as non-root user by default (verified in DHI documentation).

Build Security:

• Multi-stage build: Builder stage discarded after copying artifacts — no source code or build tools in final image.
• Native addon handling: Copies only necessary runtime libraries (libgcc_s.so.1, libstdc++.so.6) for better-sqlite3.
• No baked-in secrets: All secrets passed via environment variables (no hardcoded credentials).

Health Check:

• Uses /api/health/ready: Properly added to public routes in PR #77, no authentication required.
• No sensitive data exposure: Health check returns generic "OK" status, no internal details.

✅ Environment Configuration

Configuration Validation:

• Type-safe config: loadConfig() function validates all environment variables with clear error messages.
• Secure defaults: SECURE_COOKIES defaults to true, SESSION_DURATION defaults to 7 days (604800 seconds).
• Proxy support: TRUST_PROXY env var enables reverse proxy support for X-Forwarded-* headers.

No Secrets in Defaults:

• All OIDC variables (OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET) are optional — no default values, no hardcoded credentials.

✅ Dependency Security

Zero Vulnerabilities:

• npm audit reports 0 vulnerabilities (0 fixable, 0 total).
• openid-client@6.8.2: No known CVEs, OpenID Certified.
• No vulnerable pinned versions preventing security patches.

---

Known Accepted Risks (Low Severity)

These findings were identified during development and accepted as low-risk for self-hosted 1-5 user deployments:

1. Email enumeration via EMAIL_CONFLICT: Registration endpoint reveals email registration status. Risk accepted as unavoidable for registration flow and low-impact for small deployment.

2. Timing attack (OIDC index lookup): Unique index on (auth_provider, oidc_subject) could theoretically leak existence via timing. Risk accepted for self-hosted 1-5 user deployment.

3. Fastify additionalProperties behavior: Schema specifies additionalProperties: false but Fastify's default AJV does NOT reject extra fields — they are silently ignored. Risk accepted as low (fail-open for unknown fields).

4. No rate limiting on login endpoint: Brute-force protection not implemented in EPIC-01. Recommendation: Add rate limiting in a future epic (consider @fastify/rate-limit).

---

Recommendations for Future Epics

1. Rate Limiting (Medium priority): Add @fastify/rate-limit to login, setup, and password change endpoints to prevent brute-force attacks.

2. Security Headers (Low priority): Install @fastify/helmet to add CSP, HSTS, X-Frame-Options, and other security headers.

3. Account Lockout (Low priority): Consider account lockout after N failed login attempts (requires adding a failed_login_attempts field to users table).

4. Security Audit Page (Documentation): Create a Security-Audit.md page on the GitHub Wiki to track findings and remediation status per the security-engineer agent instructions.

---

Conclusion

EPIC-01 demonstrates production-ready security with no critical or high-severity vulnerabilities. The authentication system follows industry best practices (OWASP guidelines, defense in depth, fail-secure design) and is appropriate for stable release.

No blocking issues identified. This epic is approved for promotion to main.

---

Review completed by: security-engineer agent (Claude Sonnet 4.5)
Review date: 2026-02-16
PR: #82 (EPIC-01 Authentication & User Management)

[steilerDev]

[product-architect] EPIC-01 Promotion Review: Architecture Compliance Verified

I have conducted a thorough architecture review of the EPIC-01 (Authentication & User Management) promotion from beta to main. This review covers 127 changed files across 20,340 additions spanning 23 commits.

Schema Design -- PASS

• Migration 0001_create_users_and_sessions.sql: Clean, well-structured DDL. Uses snake_case column names throughout (display_name, created_at, auth_provider, password_hash, oidc_subject, deactivated_at). Proper CHECK constraints on role and auth_provider enums. Foreign key from sessions.user_id to users.id with ON DELETE CASCADE for automatic session cleanup. TEXT primary keys with UUID values -- appropriate for SQLite.
• Indexes: Composite unique index idx_users_oidc_lookup on (auth_provider, oidc_subject) WHERE oidc_subject IS NOT NULL is well-designed for OIDC subject lookups. Session indexes on user_id and expires_at support the two main query patterns (user session lookup, expiry cleanup).
• Drizzle schema (schema.ts): Correctly mirrors the SQL migration. Enum types for role and auth_provider provide type safety. The isNotNull partial index filter is properly translated.

API Design -- PASS

All endpoints follow established REST conventions under /api/ prefix:

Endpoint	Method	Purpose	Status
/api/auth/me	GET	Auth state check (public)	Correct -- never returns 401
/api/auth/setup	POST	Initial admin creation	Correct -- 403 after setup complete
/api/auth/login	POST	Local authentication	Correct -- timing-safe
/api/auth/logout	POST	Session destruction	Correct -- 204 No Content
/api/auth/oidc/login	GET	OIDC flow initiation	Correct -- redirect-based
/api/auth/oidc/callback	GET	OIDC callback handler	Correct -- error handling via redirects
/api/users/me	GET	Current user profile	Correct
/api/users/me	PATCH	Update display name	Correct
/api/users/me/password	POST	Change password	Correct -- OIDC users blocked
/api/users	GET	List users (admin)	Correct -- search via ?q=
/api/users/:id	PATCH	Admin update user	Correct -- LAST_ADMIN check
/api/users/:id	DELETE	Deactivate user (admin)	Correct -- SELF_DEACTIVATION + LAST_ADMIN checks
/api/health	GET	Liveness probe	Correct
/api/health/ready	GET	Readiness probe	Correct -- verifies DB + crypto

Error Handling -- PASS

• Standard { error: { code, message, details? } } shape used consistently across all endpoints.
• ErrorCode type in @cornerstone/shared is comprehensive: 14 error codes covering all scenarios (NOT_FOUND, ROUTE_NOT_FOUND, VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, CONFLICT, INTERNAL_ERROR, SETUP_COMPLETE, INVALID_CREDENTIALS, ACCOUNT_DEACTIVATED, SELF_DEACTIVATION, LAST_ADMIN, OIDC_NOT_CONFIGURED, EMAIL_CONFLICT).
• AppError hierarchy is clean: NotFoundError, ValidationError, UnauthorizedError, ForbiddenError, ConflictError.
• Error handler plugin correctly sanitizes error messages in production mode.
• AJV validation errors mapped to structured VALIDATION_ERROR responses with field paths.

Authentication Architecture -- PASS

• Session management: 256-bit random hex tokens (crypto.randomBytes(32)), stored in SQLite sessions table. HttpOnly + SameSite=Strict + Secure (configurable) cookies. Hourly expired session cleanup via setInterval with proper shutdown cleanup.
• Password hashing: scrypt with proper parameters (N=16384, r=8, p=1, keylen=64). PHC-format storage. Timing-safe comparison via crypto.timingSafeEqual. The dummy hash in login for non-existent users prevents timing attacks -- good practice.
• OIDC: Uses openid-client v6 with server-side state storage (in-memory Map with 10-minute TTL). State cleanup on access prevents unbounded growth. Open redirect prevention via isSafeRedirect() validation. Discovery caching. Email conflict detection with proper ConflictError.
• Route protection: Global preValidation hook with public route exemption Set. Static file serving correctly excluded from auth. Not-found handler passthrough allows 404s instead of 401s for unknown routes.
• RBAC: requireRole() decorator pattern for admin-only routes. Clean separation between auth (preValidation) and authorization (preHandler).

Plugin Registration Order -- PASS

config -> errorHandler -> compress -> cookie -> db -> auth -> routes -> static -- correct dependency chain. Each plugin declares its dependencies via fastify-plugin's dependencies option.

Shared Types -- PASS

• @cornerstone/shared exports: ApiError, ApiErrorResponse, ErrorCode, User, UserResponse, UserRole, AuthProvider.
• UserResponse correctly omits passwordHash and oidcSubject -- sensitive fields never leak to the client.
• User interface (full entity) vs UserResponse (API-safe) separation is a good pattern.
• Client correctly imports types from shared package.

Client Architecture -- PASS

• AuthContext + AuthProvider pattern for global auth state management.
• AuthGuard component performs independent /api/auth/me check on mount -- correct for route-level protection. Redirects to /setup or /login as appropriate.
• Lazy-loaded pages with React.lazy() + Suspense.
• apiClient.ts provides clean abstraction with proper ApiClientError and NetworkError classes. Handles 204 No Content correctly.
• Admin-only UI elements (User Management nav link) conditionally rendered based on user.role === 'admin'.

Deployment Architecture -- PASS

• Dockerfile: Multi-stage build (DHI Alpine dev -> DHI Alpine production). Native addons built from source for musl compatibility. SQL migrations correctly copied to production image. Health check uses exec form (no shell in DHI production image). Data volume at /app/data.
• docker-compose.yml: Uses published image, env_file, persistent volume, health check.
• .env.example: Documents all environment variables with sensible defaults.
• TRUST_PROXY: Properly configurable for reverse proxy deployments, applied at both Fastify constructor level and cookie configuration.

Configuration Management -- PASS

• loadConfig() is a pure function with comprehensive validation and error aggregation.
• All env vars follow UPPER_SNAKE_CASE convention.
• OIDC is opt-in (enabled only when issuer + clientId + clientSecret are all set).
• Sensitive values (oidcClientSecret) excluded from config logging.

Test Coverage -- PASS

• 614 unit/integration tests across 34 suites -- all passing.
• 402 E2E tests (19 viewport-specific skips) -- all passing in CI.
• All quality gates green: lint, typecheck, format:check, build.
• Docker build and Docker Scout pass.

Known Items for Future Refinement

These are non-blocking observations documented in agent memory for tracking:

1. OIDC discovery cache has no TTL -- cached indefinitely. Consider adding a 24h expiry for key rotation scenarios in future OIDC hardening work.
2. readiness health check performs a full scrypt hash+verify cycle on every probe. This is CPU-intensive (by design for scrypt). The 30s interval and 10s timeout are adequate, but worth monitoring if the probe ever becomes a performance concern.

Verdict

Architecture compliance: APPROVED for stable release. The EPIC-01 implementation faithfully follows all established architectural conventions: naming, API patterns, error handling, plugin structure, type sharing, deployment configuration, and test coverage. The authentication and session management design is sound and production-ready for the target scale (<5 users, single container, SQLite).

[github-actions]

🎉 This PR is included in version 1.7.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀