Better Auth — Central Authentication

Summary

Deploy Better Auth v1.5 as a shared authentication service on the Coolify server (159.195.68.41), replacing the custom magic-access server on the old server. All admin services on *.magicomniverse.online will be protected via Traefik forwardAuth with cross-subdomain SSO cookies.

Framework

Better Auth v1.5 + Express + TypeScript

Frontend

Vite + React + Tailwind (login/2FA pages)

Database

PostgreSQL (magic_auth on magic-postgres)

Repo

midego1/Magic-Auth (to be created)

Item	Value
URL	https://auth.magicomniverse.online
Coolify Project	tools / production
Status	Planned (reviewed by Codex, 9 critical fixes incorporated)
Replaces	magic-access (old server, port 3334)
Users	19 existing users (4 admin, 2 dev, 13 client)

Why Better Auth?

Criteria	Better Auth	magic-access (current)	Keycloak	Authentik
Language	TypeScript	Node.js (custom)	Java	Python
Weight	~5MB npm	~Custom 1300 LOC	~500MB Docker	~800MB Docker
2FA	TOTP + Email OTP (plugin)	WhatsApp + Email OTP (custom)	Built-in	Built-in
Device Trust	Built-in (2FA plugin)	Custom 64-char tokens	Built-in	Built-in
Multi-tenant	Organization plugin	Project-based (custom)	Realms	Tenants
Sessions	PostgreSQL-backed	In-memory (lost on restart)	Database	Database
Cross-service	Shared subdomain cookies	IP whitelist + nginx	OIDC/SAML	OIDC/SAML
Maintenance	Active (27.5k stars, v1.5.6)	Hand-rolled, single developer	Enterprise team	Community

Architecture

Browser visits any *.magicomniverse.online
        |
   Traefik Proxy (v3.6.11)
        |
   forwardAuth middleware --> auth.magicomniverse.online/api/verify
        |                           |
        |                    Valid session cookie?
        |                     /           \
        |                   YES            NO
        |                    |              |
        |               200 + headers   302 --> /login?redirect=...
        |                    |
        v                    |
   Target Service      (user logs in, cookie set
   (portal, monitor,    on .magicomniverse.online,
    price-import, etc.)  redirect back)

Cross-Service SSO Cookie

Cookie: better-auth.session_token
Domain: .magicomniverse.online     <-- shared across ALL subdomains
HttpOnly: true | Secure: true | SameSite: Lax

One login covers all protected services. No per-app auth code needed.

What Gets Protected

Protected (forwardAuth)

Service	Current Auth	After
portal.magicomniverse.online	None (public)	forwardAuth
monitor.magicomniverse.online	None (public)	forwardAuth
price-import.magicomniverse.online	Basic Auth	forwardAuth
admin-*.magicomniverse.online	Medusa login	forwardAuth + Medusa login
terminal.magicomniverse.online	None	forwardAuth (+ WS handshake validation)
flowbuilder.magicomniverse.online	None	forwardAuth
n8n*.magicomniverse.online	n8n built-in	forwardAuth (webhooks excluded)
pim.magicomniverse.online	None	forwardAuth

NOT Protected

Service	Why
auth.magicomniverse.online	The auth service itself (would loop)
Storefronts (brinxx, default, etc.)	Public customer-facing shops
Webhook paths (n8n /webhook/*)	External integrations need access
Internal services (*.internal)	Not publicly routable

Key Design Decisions

1. forwardAuth 302 Redirect (not 401)

Codex identified that Traefik forwardAuth doesn’t auto-redirect on 401. The /api/verify endpoint returns a 302 redirect to the login page for browser requests, and 401 JSON for API/XHR requests (detected via Accept header).

2. Break-Glass Admin Access

Static API key (BREAK_GLASS_KEY env var) that bypasses auth entirely. If the auth service crashes, admins can still access services by passing X-Break-Glass header.

3. Per-Path Exceptions

Services with public endpoints (n8n webhooks, health checks) use split Traefik routers: one public (no auth), one protected (with auth), differentiated by path prefix.

4. Password Hash Migration

Existing bcryptjs hashes ($2a$ prefix, 10 rounds) must be verified compatible with Better Auth’s bcrypt implementation before building the migration script. This is a Day 0 pre-build checkpoint.

5. Network Isolation

The auth service container is only reachable via the Coolify Docker network (Traefik proxy). No direct port mapping to the host.

Implementation Phases

1. Day 0: Pre-Build Verification

   • Verify bcrypt hash compatibility
   • Test Traefik forwardAuth 302 behavior
   • Test cross-subdomain cookies in browser
   • Confirm PostgreSQL + SMTP connectivity from Coolify

2. Phase 1: Core Auth Service

   • Create midego1/Magic-Auth repo
   • Build Express + Better Auth backend
   • Build Vite React login/2FA frontend
   • Deploy on Coolify as auth.magicomniverse.online
   • Run Better Auth DB migrations

3. Phase 2: User Migration

   • Run migration script (19 users from magic_access.users)
   • Verify admin login + 2FA enrollment
   • Set up audit logging

4. Phase 3: Service Protection (one at a time)

   • Pilot on a disposable test service first
   • Then: price-import (remove Basic Auth)
   • Then: portal, monitor, terminal, flowbuilder, pim
   • Then: admin backends, n8n instances
   • Each with per-path exceptions as needed

5. Phase 4: Cleanup

   • Remove Basic Auth from price-import code
   • Update devdocs
   • Update CLAUDE.md

Security Model

Layer	Protection
Session cookies	HttpOnly, Secure, SameSite=Lax, domain-scoped
CSRF	SameSite + Better Auth built-in CSRF tokens
Brute force	Rate limiting (5 attempts / 15 min)
2FA	TOTP (authenticator app) + Email OTP fallback
Trusted devices	30-day device trust via 2FA plugin
Header spoofing	Traefik strips client X-Auth-* headers
Open redirect	Redirect URLs validated against trustedOrigins
Audit trail	All login/2FA/admin events logged
Break-glass	Emergency API key bypass for admin lockout

Not in Scope (v1)

• WhatsApp OTP — using TOTP instead (no Meta API dependency)
• IP whitelisting — replaced by session-based auth
• Password expiry/history — can add via Better Auth hooks in v2
• RBAC/authorization — v1 is auth-only, v2 adds role-based access
• HA/multi-instance — overkill for 19 users
• OIDC provider — services use forwardAuth, not OIDC

Review Status

Review	Status	Findings
Codex Review	DONE	30+ findings, 9 critical fixes incorporated
Eng Review	Pending	Recommended before implementation
CEO Review	—	—
Design Review	—	—

Critical Fixes from Codex Review

1. forwardAuth 401 doesn’t redirect — added 302 redirect with Accept header detection
2. No break-glass admin path — added emergency API key bypass
3. Password hash compatibility unproven — added Day 0 verification step
4. Webhooks break with blanket auth — added per-path Traefik routing
5. WebSocket auth for terminal — validate on WS handshake, not forwardAuth
6. Logout across subdomains missing — clear domain-scoped cookie
7. XHR calls can’t follow 302 — return 401 JSON for API requests
8. Audit logging missing — added login/2FA/admin event logging
9. Auth service network isolation — verify container only reachable via Docker network

Caution

Pre-build checkpoint: Before any code is written, the bcrypt hash compatibility, Traefik forwardAuth redirect behavior, and cross-subdomain cookie behavior must be verified. See “Day 0” in Implementation Phases.

Rollback Plan

1. Remove magic-auth middleware from Traefik labels on affected service (per-service)
2. Re-add previous auth (Basic Auth for price-import, etc.)
3. Use break-glass key during incidents
4. Auth service can be stopped without affecting other services

ForwardAuth is per-service. Removing it from one service’s labels instantly removes auth for that service only. No global config to break.