Password-based auth flow for self-hosted distribution

[hebo-agent]

Context

Prerequisite for #298 (self-hosted Docker distribution). The self-hosted setup must be fully self-contained — no SMTP, OAuth, or any external dependency required to get started. Email OTP and social OAuth remain available as optional enhancements.

Background

The auth service (apps/auth) currently supports:

• Email OTP via better-auth's emailOTP plugin (requires SMTP)
• Social OAuth via Google, GitHub, Microsoft (requires client ID/secret)

Both methods require external service configuration, which is a barrier for quick self-hosted onboarding.

Scope

Add email + password sign-up/sign-in to apps/auth as a first-class method using better-auth's built-in credential-based auth.

Auth service (apps/auth)

• Enable better-auth's emailAndPassword option in apps/auth/src/better-auth.ts (see better-auth docs)
• Password hashing is handled by better-auth out of the box
• Ensure account linking works correctly between password accounts and social/OTP accounts (the accountLinking config with trustedProviders already exists)

Console UI (apps/console)

• Add email + password sign-up form (email, password, name fields)
• Add email + password sign-in form (email, password fields)
• Keep existing social OAuth buttons and email OTP as alternative methods
• Handle sign-up/sign-in errors (invalid credentials, email already exists, etc.)

Existing behavior

• Social OAuth (Google, GitHub, Microsoft) continues to work when configured
• Email OTP continues to work when SMTP is configured
• Password auth is always available regardless of external service configuration

Files likely affected

• apps/auth/src/better-auth.ts — enable emailAndPassword in the betterAuth() config
• apps/console/app/routes/ — sign-in and sign-up route components (add password form fields)
• Auth Prisma schema may need migration if better-auth requires additional columns for password storage

Acceptance criteria

• User can register with email + password (no SMTP or OAuth configured)
• User can sign in with email + password
• Password is securely hashed (handled by better-auth)
• Account linking works: a user who signed up with password can later link a social account, and vice versa
• Console UI shows password form alongside existing auth methods
• Existing email OTP and social OAuth flows are unaffected

Related

• Parent issue: Small Teams: Docker self-hosted distribution #298
• Ticket 2: Gateway provider expansion (Bedrock static creds, Vertex service account, Azure OpenAI)

[heiwen]

@claude small refinement: password auth is a fallback only available when SMTP is not configured. with that, we can get rid of the console based logger flow.

[hebo-agent]

Claude finished @heiwen's task in 6m 19s —— View job • claude-issue-299-20260320-0913 • Create PR ➔

---

Password auth as SMTP fallback

Implemented the refinement: password auth is now only available when SMTP is not configured, and the console-based OTP logger flow has been removed.

• Explore current auth setup
• Enable emailAndPassword in better-auth config (conditional on no SMTP)
• Add /auth-mode endpoint to auth service
• Add signInWithPassword / signUpWithPassword to console AuthService
• Create password sign-in component and sign-up route
• Update signin route to auto-detect auth mode (password vs OTP)
• Remove console-based OTP logger dev workaround

Summary of changes

Auth service (apps/auth)

• better-auth.ts — conditionally enables emailAndPassword when hasSmtpConfig() returns false; adds "credential" to trustedProviders for account linking
• index.ts — new GET /auth-mode endpoint returns { passwordAuth: boolean }
• lib/email.ts — exports hasSmtpConfig; removed console.info(">>> OTP:", ...) logger and the non-production early return (replaced by a top-level !hasSmtpConfig() guard)

Console (apps/console)

• lib/auth/types.ts — added signInWithPassword and signUpWithPassword methods
• lib/auth/better-auth.ts — implemented via authClient.signIn.email / authClient.signUp.email
• lib/auth/dummy-auth.ts — added stubs
• routes/_auth.signin/route.tsx — fetches /auth-mode on mount; shows PasswordSignIn when password auth is enabled, MagicLinkSignIn otherwise
• routes/_auth.signin/password.tsx — new password sign-in form with link to sign-up
• routes/_auth.signup/route.tsx — new sign-up page (name, email, password)

|

[heiwen]

@claude can we avoid the /auth-mode endpoint and work with existing SMTP env variables instead?

[hebo-agent]

Claude finished @heiwen's task in 4m 43s —— View job • claude-issue-299-20260320-0922 • Create PR ➔

---

Password auth via VITE_PASSWORD_AUTH env variable (no /auth-mode endpoint)

• Explore current implementation
• Enable emailAndPassword in auth service (conditional on no SMTP)
• Export hasSmtpConfig from email module and remove console OTP logger
• Add VITE_PASSWORD_AUTH env variable to console
• Add password auth methods to console auth service
• Create password sign-in component
• Create sign-up route for password auth
• Update signin route to switch based on env variable
• Commit and push changes

Summary

Replaced the /auth-mode endpoint approach with a build-time VITE_PASSWORD_AUTH env variable. The console reads this to decide whether to show password or magic-link sign-in — no runtime endpoint needed.

Auth service (apps/auth)

• better-auth.ts — conditionally enables emailAndPassword when hasSmtpConfig() returns false; adds "credential" to trustedProviders
• lib/email.ts — exports hasSmtpConfig; removed console.info(">>> OTP:", ...) logger and the !isProduction early-return guard (replaced by a top-level !hasSmtpConfig() guard)

Console (apps/console)

• lib/env.ts — new passwordAuth flag from VITE_PASSWORD_AUTH env variable
• lib/auth/types.ts — added signInWithPassword and signUpWithPassword
• lib/auth/better-auth.ts — implemented via authClient.signIn.email / authClient.signUp.email
• lib/auth/dummy-auth.ts — added stubs
• routes/_auth.signin/route.tsx — shows PasswordSignIn when passwordAuth is true, MagicLinkSignIn otherwise
• routes/_auth.signin/password.tsx — password sign-in form with link to sign-up
• routes/_auth.signup/route.tsx — sign-up page (name, email, password)

For self-hosted Docker: set VITE_PASSWORD_AUTH=true when building/running the console (and omit SMTP secrets). The auth service auto-detects the same condition server-side via hasSmtpConfig().

| claude-issue-299-20260320-0922

[heiwen]

@claude by default the VITE_PASSWORD_AUTH should be 'true' (so I guess, the opposite VITE_MAGICLINK_AUTH would be a better way to detect it). When deployed with SST, it switches over based on the SMTP_CONFIG (please add appropriate sst changes as well).

[hebo-agent]

Claude finished @heiwen's task in 3m 54s —— View job • claude-issue-299-20260320-0932

---

Password auth default with VITE_MAGICLINK_AUTH

• Explore current auth setup and SST config
• Enable emailAndPassword in auth service (conditional on no SMTP)
• Export hasSmtpConfig and remove console OTP logger
• Add VITE_MAGICLINK_AUTH env variable to console (inverted: default=password)
• Add password auth methods to console auth service
• Create password sign-in component + sign-up route
• Update signin route to switch based on env variable
• Add SST changes to set VITE_MAGICLINK_AUTH from SMTP secrets
• Commit and push

Summary

Flipped the env variable from VITE_PASSWORD_AUTH to VITE_MAGICLINK_AUTH — password auth is now the default (no env var needed). Set VITE_MAGICLINK_AUTH=true to enable email OTP magic link flow instead.

Auth service (apps/auth)

• better-auth.ts — emailAndPassword enabled when hasSmtpConfig() is false; "credential" added to trustedProviders
• lib/email.ts — exports hasSmtpConfig; removed console.info(">>> OTP:", ...) logger and the !isProduction early-return guard (replaced by top-level !hasSmtpConfig() guard)

Console (apps/console)

• lib/env.ts — magicLinkAuth flag from VITE_MAGICLINK_AUTH
• lib/auth/types.ts — added signInWithPassword and signUpWithPassword
• lib/auth/better-auth.ts — implemented via authClient.signIn.email / authClient.signUp.email
• lib/auth/dummy-auth.ts — added stubs
• routes/_auth.signin/route.tsx — shows PasswordSignIn by default, MagicLinkSignIn when magicLinkAuth is true
• routes/_auth.signin/password.tsx — password sign-in form with link to sign-up
• routes/_auth.signup/route.tsx — sign-up page (name, email, password)

SST (infra/stacks/console.ts)

• VITE_MAGICLINK_AUTH derived from smtpHost.value — automatically "true" when SMTP is configured, empty otherwise

Create PR

View job | claude-issue-299-20260320-0932