feat: password reset flow with welcome emails

- POST /auth/forgot-password with welcome/reset email templates
- POST /auth/reset-password with Zod validation, 4-hour tokens
- Per-email rate limiting (3/hr) via Valkey, no user enumeration
- Login page "Forgot password?" toggle with inline form
- /reset-password page for setting new password from email link
- Initial user seed sends welcome email instead of requiring password
- CLI script for force-resetting passwords via kubectl exec
- APP_URL env var in chart, removed INITIAL_USER_PASSWORD

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chart/templates/backend-deployment.yaml

@@ -93,18 +93,14 @@ spec:
                 secretKeyRef:
                   name: lunarfront-secrets
                   key: business-name
+            - name: APP_URL
+              value: "https://{{ .Values.ingress.host }}"
             - name: INITIAL_USER_EMAIL
               valueFrom:
                 secretKeyRef:
                   name: lunarfront-secrets
                   key: initial-user-email
                   optional: true
-            - name: INITIAL_USER_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: lunarfront-secrets
-                  key: initial-user-password
-                  optional: true
             - name: INITIAL_USER_FIRST_NAME
               valueFrom:
                 secretKeyRef:

packages/admin/src/api/auth.ts

@@ -14,3 +14,11 @@ interface LoginResponse {
 export async function login(email: string, password: string): Promise<LoginResponse> {
   return api.post<LoginResponse>('/v1/auth/login', { email, password })
 }
+
+export async function forgotPassword(email: string): Promise<{ message: string }> {
+  return api.post<{ message: string }>('/v1/auth/forgot-password', { email })
+}
+
+export async function resetPassword(token: string, newPassword: string): Promise<{ message: string }> {
+  return api.post<{ message: string }>('/v1/auth/reset-password', { token, newPassword })
+}

packages/admin/src/routeTree.gen.ts

@@ -9,6 +9,7 @@
 // Additionally, you should also exclude this file from your linter and/or formatter to prevent it from being checked or modified.
 
 import { Route as rootRouteImport } from './routes/__root'
+import { Route as ResetPasswordRouteImport } from './routes/reset-password'
 import { Route as PosRouteImport } from './routes/pos'
 import { Route as LoginRouteImport } from './routes/login'
 import { Route as AuthenticatedRouteImport } from './routes/_authenticated'
@@ -58,6 +59,11 @@ import { Route as AuthenticatedAccountsAccountIdMembersRouteImport } from './rou
 import { Route as AuthenticatedAccountsAccountIdEnrollmentsRouteImport } from './routes/_authenticated/accounts/$accountId/enrollments'
 import { Route as AuthenticatedLessonsScheduleInstructorsInstructorIdRouteImport } from './routes/_authenticated/lessons/schedule/instructors/$instructorId'
 
+const ResetPasswordRoute = ResetPasswordRouteImport.update({
+  id: '/reset-password',
+  path: '/reset-password',
+  getParentRoute: () => rootRouteImport,
+} as any)
 const PosRoute = PosRouteImport.update({
   id: '/pos',
   path: '/pos',
@@ -337,6 +343,7 @@ export interface FileRoutesByFullPath {
   '/': typeof AuthenticatedIndexRoute
   '/login': typeof LoginRoute
   '/pos': typeof PosRoute
+  '/reset-password': typeof ResetPasswordRoute
   '/help': typeof AuthenticatedHelpRoute
   '/profile': typeof AuthenticatedProfileRoute
   '/settings': typeof AuthenticatedSettingsRoute
@@ -385,6 +392,7 @@ export interface FileRoutesByFullPath {
 export interface FileRoutesByTo {
   '/login': typeof LoginRoute
   '/pos': typeof PosRoute
+  '/reset-password': typeof ResetPasswordRoute
   '/help': typeof AuthenticatedHelpRoute
   '/profile': typeof AuthenticatedProfileRoute
   '/settings': typeof AuthenticatedSettingsRoute
@@ -435,6 +443,7 @@ export interface FileRoutesById {
   '/_authenticated': typeof AuthenticatedRouteWithChildren
   '/login': typeof LoginRoute
   '/pos': typeof PosRoute
+  '/reset-password': typeof ResetPasswordRoute
   '/_authenticated/help': typeof AuthenticatedHelpRoute
   '/_authenticated/profile': typeof AuthenticatedProfileRoute
   '/_authenticated/settings': typeof AuthenticatedSettingsRoute
@@ -487,6 +496,7 @@ export interface FileRouteTypes {
     | '/'
     | '/login'
     | '/pos'
+    | '/reset-password'
     | '/help'
     | '/profile'
     | '/settings'
@@ -535,6 +545,7 @@ export interface FileRouteTypes {
   to:
     | '/login'
     | '/pos'
+    | '/reset-password'
     | '/help'
     | '/profile'
     | '/settings'
@@ -584,6 +595,7 @@ export interface FileRouteTypes {
     | '/_authenticated'
     | '/login'
     | '/pos'
+    | '/reset-password'
     | '/_authenticated/help'
     | '/_authenticated/profile'
     | '/_authenticated/settings'
@@ -635,10 +647,18 @@ export interface RootRouteChildren {
   AuthenticatedRoute: typeof AuthenticatedRouteWithChildren
   LoginRoute: typeof LoginRoute
   PosRoute: typeof PosRoute
+  ResetPasswordRoute: typeof ResetPasswordRoute
 }
 
 declare module '@tanstack/react-router' {
   interface FileRoutesByPath {
+    '/reset-password': {
+      id: '/reset-password'
+      path: '/reset-password'
+      fullPath: '/reset-password'
+      preLoaderRoute: typeof ResetPasswordRouteImport
+      parentRoute: typeof rootRouteImport
+    }
     '/pos': {
       id: '/pos'
       path: '/pos'
@@ -1112,6 +1132,7 @@ const rootRouteChildren: RootRouteChildren = {
   AuthenticatedRoute: AuthenticatedRouteWithChildren,
   LoginRoute: LoginRoute,
   PosRoute: PosRoute,
+  ResetPasswordRoute: ResetPasswordRoute,
 }
 export const routeTree = rootRouteImport
   ._addFileChildren(rootRouteChildren)

packages/admin/src/routes/login.tsx

@@ -1,7 +1,7 @@
 import { useState, useEffect } from 'react'
 import { createFileRoute, useRouter, redirect } from '@tanstack/react-router'
 import { useAuthStore } from '@/stores/auth.store'
-import { login } from '@/api/auth'
+import { login, forgotPassword } from '@/api/auth'
 
 interface Branding {
   name: string | null
@@ -26,6 +26,8 @@ function LoginPage() {
   const [error, setError] = useState('')
   const [loading, setLoading] = useState(false)
   const [branding, setBranding] = useState<Branding | null>(null)
+  const [forgotMode, setForgotMode] = useState(false)
+  const [forgotSent, setForgotSent] = useState(false)
 
   useEffect(() => {
     fetch('/v1/store/branding')
@@ -72,42 +74,117 @@ function LoginPage() {
             <p className="text-sm mt-1" style={{ color: '#6b7a8d' }}>Small Business Management</p>
           )}
         </div>
-        <form onSubmit={handleSubmit} className="space-y-4">
+        {forgotMode ? (
-          <div className="space-y-2">
+          forgotSent ? (
-            <label className="text-sm font-medium" style={{ color: '#b0bec5' }}>Email</label>
+            <div className="text-center space-y-4">
-            <input
+              <p className="text-sm" style={{ color: '#b0bec5' }}>If an account exists with that email, you will receive a password reset link.</p>
-              type="email"
+              <button
-              placeholder="you@example.com"
+                onClick={() => { setForgotMode(false); setForgotSent(false); setError('') }}
-              value={email}
+                className="text-xs"
-              onChange={(e) => setEmail(e.target.value)}
+                style={{ color: '#6b7a8d' }}
-              required
+              >
-              className="h-9 w-full rounded-md border px-3 py-1 text-sm outline-none login-input"
+                Back to sign in
-            />
+              </button>
-          </div>
+            </div>
-          <div className="space-y-2">
+          ) : (
-            <label className="text-sm font-medium" style={{ color: '#b0bec5' }}>Password</label>
+            <form onSubmit={async (e) => {
-            <input
+              e.preventDefault()
-              type="password"
+              setError('')
-              value={password}
+              setLoading(true)
-              onChange={(e) => setPassword(e.target.value)}
+              try {
-              required
+                await forgotPassword(email)
-              className="h-9 w-full rounded-md border px-3 py-1 text-sm outline-none login-input"
+                setForgotSent(true)
-            />
+              } catch (err) {
-          </div>
+                setError(err instanceof Error ? err.message : 'Something went wrong')
-          {error && (
+              } finally {
-            <p className="text-sm" style={{ color: '#e57373' }}>{error}</p>
+                setLoading(false)
-          )}
+              }
-          <button
+            }} className="space-y-4">
-            type="submit"
+              <p className="text-sm" style={{ color: '#b0bec5' }}>Enter your email and we'll send you a reset link.</p>
-            disabled={loading}
+              <div className="space-y-2">
-            className="h-9 w-full rounded-md border text-sm font-medium transition-colors disabled:opacity-50"
+                <label className="text-sm font-medium" style={{ color: '#b0bec5' }}>Email</label>
-            style={{ backgroundColor: 'transparent', color: '#d0d8e0', borderColor: '#3a4a62' }}
+                <input
-            onMouseEnter={(e) => { (e.target as HTMLElement).style.backgroundColor = '#1e2d45' }}
+                  type="email"
-            onMouseLeave={(e) => { (e.target as HTMLElement).style.backgroundColor = 'transparent' }}
+                  placeholder="you@example.com"
-          >
+                  value={email}
-            {loading ? 'Signing in...' : 'Sign in'}
+                  onChange={(e) => setEmail(e.target.value)}
-          </button>
+                  required
-        </form>
+                  className="h-9 w-full rounded-md border px-3 py-1 text-sm outline-none login-input"
+                />
+              </div>
+              {error && (
+                <p className="text-sm" style={{ color: '#e57373' }}>{error}</p>
+              )}
+              <button
+                type="submit"
+                disabled={loading}
+                className="h-9 w-full rounded-md border text-sm font-medium transition-colors disabled:opacity-50"
+                style={{ backgroundColor: 'transparent', color: '#d0d8e0', borderColor: '#3a4a62' }}
+                onMouseEnter={(e) => { (e.target as HTMLElement).style.backgroundColor = '#1e2d45' }}
+                onMouseLeave={(e) => { (e.target as HTMLElement).style.backgroundColor = 'transparent' }}
+              >
+                {loading ? 'Sending...' : 'Send reset link'}
+              </button>
+              <div className="text-center">
+                <button
+                  type="button"
+                  onClick={() => { setForgotMode(false); setError('') }}
+                  className="text-xs"
+                  style={{ color: '#6b7a8d' }}
+                >
+                  Back to sign in
+                </button>
+              </div>
+            </form>
+          )
+        ) : (
+          <form onSubmit={handleSubmit} className="space-y-4">
+            <div className="space-y-2">
+              <label className="text-sm font-medium" style={{ color: '#b0bec5' }}>Email</label>
+              <input
+                type="email"
+                placeholder="you@example.com"
+                value={email}
+                onChange={(e) => setEmail(e.target.value)}
+                required
+                className="h-9 w-full rounded-md border px-3 py-1 text-sm outline-none login-input"
+              />
+            </div>
+            <div className="space-y-2">
+              <label className="text-sm font-medium" style={{ color: '#b0bec5' }}>Password</label>
+              <input
+                type="password"
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+                required
+                className="h-9 w-full rounded-md border px-3 py-1 text-sm outline-none login-input"
+              />
+            </div>
+            {error && (
+              <p className="text-sm" style={{ color: '#e57373' }}>{error}</p>
+            )}
+            <button
+              type="submit"
+              disabled={loading}
+              className="h-9 w-full rounded-md border text-sm font-medium transition-colors disabled:opacity-50"
+              style={{ backgroundColor: 'transparent', color: '#d0d8e0', borderColor: '#3a4a62' }}
+              onMouseEnter={(e) => { (e.target as HTMLElement).style.backgroundColor = '#1e2d45' }}
+              onMouseLeave={(e) => { (e.target as HTMLElement).style.backgroundColor = 'transparent' }}
+            >
+              {loading ? 'Signing in...' : 'Sign in'}
+            </button>
+            <div className="text-center">
+              <button
+                type="button"
+                onClick={() => { setForgotMode(true); setError('') }}
+                className="text-xs"
+                style={{ color: '#6b7a8d' }}
+              >
+                Forgot password?
+              </button>
+            </div>
+          </form>
+        )}
       </div>
     </div>
   )

packages/admin/src/routes/reset-password.tsx

@@ -0,0 +1,154 @@
+import { useState, useEffect } from 'react'
+import { createFileRoute, Link } from '@tanstack/react-router'
+import { resetPassword } from '@/api/auth'
+
+interface Branding {
+  name: string | null
+  hasLogo: boolean
+}
+
+export const Route = createFileRoute('/reset-password')({
+  component: ResetPasswordPage,
+})
+
+function ResetPasswordPage() {
+  const { token } = Route.useSearch() as { token?: string }
+  const [password, setPassword] = useState('')
+  const [confirmPassword, setConfirmPassword] = useState('')
+  const [error, setError] = useState('')
+  const [loading, setLoading] = useState(false)
+  const [success, setSuccess] = useState(false)
+  const [branding, setBranding] = useState<Branding | null>(null)
+
+  useEffect(() => {
+    fetch('/v1/store/branding')
+      .then((r) => r.ok ? r.json() : null)
+      .then((data) => { if (data) setBranding(data) })
+      .catch(() => {})
+  }, [])
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    setError('')
+
+    if (!token) {
+      setError('Missing reset token. Please use the link from your email.')
+      return
+    }
+
+    if (password !== confirmPassword) {
+      setError('Passwords do not match')
+      return
+    }
+
+    if (password.length < 12) {
+      setError('Password must be at least 12 characters')
+      return
+    }
+
+    setLoading(true)
+    try {
+      await resetPassword(token, password)
+      setSuccess(true)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Reset failed. The link may have expired.')
+    } finally {
+      setLoading(false)
+    }
+  }
+
+  return (
+    <div
+      className="flex min-h-screen items-center justify-center"
+      style={{ background: 'linear-gradient(135deg, #0f1724 0%, #142038 100%)' }}
+    >
+      <div
+        className="w-full max-w-sm rounded-xl border p-8 shadow-2xl"
+        style={{ backgroundColor: '#131c2e', borderColor: '#1e2d45' }}
+      >
+        <div className="text-center mb-8">
+          {branding?.hasLogo ? (
+            <img src="/v1/store/logo" alt={branding.name ?? 'Store'} className="max-h-14 max-w-[220px] object-contain mx-auto" />
+          ) : (
+            <h1 className="text-3xl font-bold" style={{ color: '#d8dfe9' }}>{branding?.name ?? 'LunarFront'}</h1>
+          )}
+          {branding?.name ? (
+            <p className="text-[10px] mt-2" style={{ color: '#4a5568' }}>Powered by <span style={{ color: '#6b7a8d' }}>LunarFront</span></p>
+          ) : (
+            <p className="text-sm mt-1" style={{ color: '#6b7a8d' }}>Small Business Management</p>
+          )}
+        </div>
+
+        {success ? (
+          <div className="text-center space-y-4">
+            <p style={{ color: '#81c784' }}>Password reset successfully.</p>
+            <Link
+              to="/login"
+              className="inline-block h-9 rounded-md border px-4 py-2 text-sm font-medium transition-colors"
+              style={{ color: '#d0d8e0', borderColor: '#3a4a62' }}
+            >
+              Sign in
+            </Link>
+          </div>
+        ) : !token ? (
+          <div className="text-center space-y-4">
+            <p style={{ color: '#e57373' }}>Invalid reset link. Please request a new one.</p>
+            <Link
+              to="/login"
+              className="inline-block h-9 rounded-md border px-4 py-2 text-sm font-medium transition-colors"
+              style={{ color: '#d0d8e0', borderColor: '#3a4a62' }}
+            >
+              Back to sign in
+            </Link>
+          </div>
+        ) : (
+          <>
+            <h2 className="text-lg font-semibold text-center mb-4" style={{ color: '#d8dfe9' }}>Set new password</h2>
+            <form onSubmit={handleSubmit} className="space-y-4">
+              <div className="space-y-2">
+                <label className="text-sm font-medium" style={{ color: '#b0bec5' }}>New password</label>
+                <input
+                  type="password"
+                  value={password}
+                  onChange={(e) => setPassword(e.target.value)}
+                  required
+                  minLength={12}
+                  placeholder="At least 12 characters"
+                  className="h-9 w-full rounded-md border px-3 py-1 text-sm outline-none login-input"
+                />
+              </div>
+              <div className="space-y-2">
+                <label className="text-sm font-medium" style={{ color: '#b0bec5' }}>Confirm password</label>
+                <input
+                  type="password"
+                  value={confirmPassword}
+                  onChange={(e) => setConfirmPassword(e.target.value)}
+                  required
+                  className="h-9 w-full rounded-md border px-3 py-1 text-sm outline-none login-input"
+                />
+              </div>
+              {error && (
+                <p className="text-sm" style={{ color: '#e57373' }}>{error}</p>
+              )}
+              <button
+                type="submit"
+                disabled={loading}
+                className="h-9 w-full rounded-md border text-sm font-medium transition-colors disabled:opacity-50"
+                style={{ backgroundColor: 'transparent', color: '#d0d8e0', borderColor: '#3a4a62' }}
+                onMouseEnter={(e) => { (e.target as HTMLElement).style.backgroundColor = '#1e2d45' }}
+                onMouseLeave={(e) => { (e.target as HTMLElement).style.backgroundColor = 'transparent' }}
+              >
+                {loading ? 'Resetting...' : 'Reset password'}
+              </button>
+              <div className="text-center">
+                <Link to="/login" className="text-xs" style={{ color: '#6b7a8d' }}>
+                  Back to sign in
+                </Link>
+              </div>
+            </form>
+          </>
+        )}
+      </div>
+    </div>
+  )
+}

packages/backend/src/main.ts

@@ -39,21 +39,55 @@ import { AppConfigService } from './services/config.service.js'
 import { SettingsService } from './services/settings.service.js'
 import { users } from './db/schema/users.js'
 import { companies } from './db/schema/stores.js'
+import { EmailService } from './services/email.service.js'
 import bcrypt from 'bcryptjs'
 
 async function seedInitialUser(app: Awaited<ReturnType<typeof buildApp>>) {
   const email = process.env.INITIAL_USER_EMAIL
-  const password = process.env.INITIAL_USER_PASSWORD
   const firstName = process.env.INITIAL_USER_FIRST_NAME
   const lastName = process.env.INITIAL_USER_LAST_NAME
-  if (!email || !password || !firstName || !lastName) return
+  if (!email || !firstName || !lastName) return
 
   const existing = await app.db.select({ id: users.id }).from(users).limit(1)
   if (existing.length > 0) return
 
-  const passwordHash = await bcrypt.hash(password, 10)
+  // Create user with a random password — they'll set their real one via the welcome email
-  await app.db.insert(users).values({ email, passwordHash, firstName, lastName, role: 'admin' })
+  const tempPassword = crypto.randomUUID()
+  const passwordHash = await bcrypt.hash(tempPassword, 10)
+  const [user] = await app.db.insert(users).values({ email, passwordHash, firstName, lastName, role: 'admin' }).returning({ id: users.id })
   app.log.info({ email }, 'Initial admin user created')
+
+  // Send welcome email with password setup link
+  try {
+    const resetToken = app.jwt.sign({ userId: user.id, purpose: 'password-reset' } as any, { expiresIn: '4h' })
+    const appUrl = process.env.APP_URL ?? `https://${process.env.HOSTNAME ?? 'localhost'}`
+    const resetLink = `${appUrl}/reset-password?token=${resetToken}`
+
+    const [store] = await app.db.select({ name: companies.name }).from(companies).limit(1)
+    const storeName = store?.name ?? process.env.BUSINESS_NAME ?? 'LunarFront'
+
+    await EmailService.send(app.db, {
+      to: email,
+      subject: `Welcome to ${storeName} — Set your password`,
+      html: `
+        <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 480px; margin: 0 auto; padding: 40px 20px;">
+          <h2 style="color: #1a1a2e; margin-bottom: 8px;">${storeName}</h2>
+          <p style="color: #555; margin-bottom: 24px;">Hi ${firstName},</p>
+          <p style="color: #555;">Your account has been created. Click the button below to set your password and get started:</p>
+          <div style="text-align: center; margin: 32px 0;">
+            <a href="${resetLink}" style="background-color: #1a1a2e; color: #fff; padding: 12px 32px; border-radius: 6px; text-decoration: none; font-weight: 500;">Set Your Password</a>
+          </div>
+          <p style="color: #888; font-size: 13px;">This link expires in 4 hours. If it expires, you can request a new one from the login page.</p>
+          <hr style="border: none; border-top: 1px solid #eee; margin: 32px 0;" />
+          <p style="color: #aaa; font-size: 11px;">Powered by LunarFront</p>
+        </div>
+      `,
+      text: `Hi ${firstName}, welcome to ${storeName}! Set your password here: ${resetLink} — This link expires in 4 hours.`,
+    })
+    app.log.info({ email }, 'Welcome email sent to initial user')
+  } catch (err) {
+    app.log.error({ email, error: (err as Error).message }, 'Failed to send welcome email — user can use forgot password')
+  }
 }
 
 async function seedEmailSettings(app: Awaited<ReturnType<typeof buildApp>>) {

packages/backend/src/routes/v1/auth.ts

@@ -1,8 +1,10 @@
 import type { FastifyPluginAsync } from 'fastify'
 import { eq } from 'drizzle-orm'
 import bcrypt from 'bcryptjs'
-import { RegisterSchema, LoginSchema, PinLoginSchema, SetPinSchema } from '@lunarfront/shared/schemas'
+import { RegisterSchema, LoginSchema, PinLoginSchema, SetPinSchema, ForgotPasswordSchema, ResetPasswordSchema } from '@lunarfront/shared/schemas'
 import { users } from '../../db/schema/users.js'
+import { companies } from '../../db/schema/stores.js'
+import { EmailService } from '../../services/email.service.js'
 
 const SALT_ROUNDS = 10
 
@@ -151,24 +153,22 @@ export const authRoutes: FastifyPluginAsync = async (app) => {
     const [user] = await app.db.select({ id: users.id, email: users.email }).from(users).where(eq(users.id, userId)).limit(1)
     if (!user) return reply.status(404).send({ error: { message: 'User not found', statusCode: 404 } })
 
-    // Generate a signed reset token that expires in 1 hour
+    const resetToken = app.jwt.sign({ userId: user.id, purpose: 'password-reset' } as any, { expiresIn: '4h' })
-    const resetToken = app.jwt.sign({ userId: user.id, purpose: 'password-reset' } as any, { expiresIn: '1h' })
     const resetLink = `${process.env.APP_URL ?? 'http://localhost:5173'}/reset-password?token=${resetToken}`
 
     request.log.info({ userId, generatedBy: request.user.id }, 'Password reset link generated')
-    return reply.send({ resetLink, expiresIn: '1 hour' })
+    return reply.send({ resetLink, expiresIn: '4 hours' })
   })
 
   // Reset password with token
   app.post('/auth/reset-password', async (request, reply) => {
-    const { token, newPassword } = request.body as { token?: string; newPassword?: string }
+    const parsed = ResetPasswordSchema.safeParse(request.body)
-    if (!token || !newPassword) {
+    if (!parsed.success) {
-      return reply.status(400).send({ error: { message: 'token and newPassword are required', statusCode: 400 } })
+      return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
-    }
-    if (newPassword.length < 12) {
-      return reply.status(400).send({ error: { message: 'Password must be at least 12 characters', statusCode: 400 } })
     }
 
+    const { token, newPassword } = parsed.data
+
     try {
       const payload = app.jwt.verify<{ userId: string; purpose: string }>(token)
       if (payload.purpose !== 'password-reset') {
@@ -185,6 +185,86 @@ export const authRoutes: FastifyPluginAsync = async (app) => {
     }
   })
 
+  // Forgot password / resend welcome — public, always returns success (no user enumeration)
+  // Pass ?type=welcome for welcome emails, defaults to reset
+  app.post('/auth/forgot-password', rateLimitConfig, async (request, reply) => {
+    const parsed = ForgotPasswordSchema.safeParse(request.body)
+    if (!parsed.success) {
+      return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
+    }
+
+    const { email } = parsed.data
+    const isWelcome = (request.query as { type?: string }).type === 'welcome'
+
+    // Rate limit per email — max 3 emails per hour
+    const emailKey = `pwd-reset:${email.toLowerCase()}`
+    const count = await app.redis.incr(emailKey)
+    if (count === 1) await app.redis.expire(emailKey, 3600)
+    if (count > 3) {
+      return reply.send({ message: 'If an account exists with that email, you will receive an email.' })
+    }
+
+    // Always return success — don't reveal whether the email exists
+    const [user] = await app.db.select({ id: users.id, firstName: users.firstName }).from(users).where(eq(users.email, email)).limit(1)
+
+    if (user) {
+      try {
+        const resetToken = app.jwt.sign({ userId: user.id, purpose: 'password-reset' } as any, { expiresIn: '4h' })
+        const appUrl = process.env.APP_URL ?? 'http://localhost:5173'
+        const resetLink = `${appUrl}/reset-password?token=${resetToken}`
+
+        const [store] = await app.db.select({ name: companies.name }).from(companies).limit(1)
+        const storeName = store?.name ?? 'LunarFront'
+
+        if (isWelcome) {
+          await EmailService.send(app.db, {
+            to: email,
+            subject: `Welcome to ${storeName} — Set your password`,
+            html: `
+              <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 480px; margin: 0 auto; padding: 40px 20px;">
+                <h2 style="color: #1a1a2e; margin-bottom: 8px;">${storeName}</h2>
+                <p style="color: #555; margin-bottom: 24px;">Hi ${user.firstName},</p>
+                <p style="color: #555;">Your account has been created. Click the button below to set your password and get started:</p>
+                <div style="text-align: center; margin: 32px 0;">
+                  <a href="${resetLink}" style="background-color: #1a1a2e; color: #fff; padding: 12px 32px; border-radius: 6px; text-decoration: none; font-weight: 500;">Set Your Password</a>
+                </div>
+                <p style="color: #888; font-size: 13px;">This link expires in 4 hours. If it expires, you can request a new one from the login page.</p>
+                <hr style="border: none; border-top: 1px solid #eee; margin: 32px 0;" />
+                <p style="color: #aaa; font-size: 11px;">Powered by LunarFront</p>
+              </div>
+            `,
+            text: `Hi ${user.firstName}, welcome to ${storeName}! Set your password here: ${resetLink} — This link expires in 4 hours.`,
+          })
+        } else {
+          await EmailService.send(app.db, {
+            to: email,
+            subject: `Reset your password — ${storeName}`,
+            html: `
+              <div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; max-width: 480px; margin: 0 auto; padding: 40px 20px;">
+                <h2 style="color: #1a1a2e; margin-bottom: 8px;">${storeName}</h2>
+                <p style="color: #555; margin-bottom: 24px;">Hi ${user.firstName},</p>
+                <p style="color: #555;">We received a request to reset your password. Click the button below to choose a new one:</p>
+                <div style="text-align: center; margin: 32px 0;">
+                  <a href="${resetLink}" style="background-color: #1a1a2e; color: #fff; padding: 12px 32px; border-radius: 6px; text-decoration: none; font-weight: 500;">Reset Password</a>
+                </div>
+                <p style="color: #888; font-size: 13px;">This link expires in 4 hours. If you didn't request this, you can safely ignore this email.</p>
+                <hr style="border: none; border-top: 1px solid #eee; margin: 32px 0;" />
+                <p style="color: #aaa; font-size: 11px;">Powered by LunarFront</p>
+              </div>
+            `,
+            text: `Hi ${user.firstName}, reset your password here: ${resetLink} — This link expires in 4 hours.`,
+          })
+        }
+
+        request.log.info({ userId: user.id, type: isWelcome ? 'welcome' : 'reset' }, 'Password email sent')
+      } catch (err) {
+        request.log.error({ email, error: (err as Error).message }, 'Failed to send password email')
+      }
+    }
+
+    return reply.send({ message: 'If an account exists with that email, you will receive a password reset link.' })
+  })
+
   // Get current user profile
   app.get('/auth/me', { preHandler: [app.authenticate] }, async (request, reply) => {
     const [user] = await app.db

packages/backend/src/scripts/reset-password.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env bun
+/**
+ * Force-reset a user's password from the command line.
+ *
+ * Usage:
+ *   bun run packages/backend/src/scripts/reset-password.ts <email> <new-password>
+ *
+ * From a customer pod:
+ *   kubectl exec -n customer-tvs deploy/customer-tvs-backend -- \
+ *     bun run src/scripts/reset-password.ts user@example.com NewPassword123!
+ */
+import postgres from 'postgres'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { eq } from 'drizzle-orm'
+import bcrypt from 'bcryptjs'
+import { users } from '../db/schema/users.js'
+
+const [email, newPassword] = process.argv.slice(2)
+
+if (!email || !newPassword) {
+  console.error('Usage: bun run reset-password.ts <email> <new-password>')
+  process.exit(1)
+}
+
+if (newPassword.length < 12) {
+  console.error('Error: Password must be at least 12 characters')
+  process.exit(1)
+}
+
+const databaseUrl = process.env.DATABASE_URL
+if (!databaseUrl) {
+  console.error('Error: DATABASE_URL is not set')
+  process.exit(1)
+}
+
+const sql = postgres(databaseUrl)
+const db = drizzle(sql)
+
+const [user] = await db.select({ id: users.id, email: users.email }).from(users).where(eq(users.email, email)).limit(1)
+
+if (!user) {
+  console.error(`Error: No user found with email "${email}"`)
+  await sql.end()
+  process.exit(1)
+}
+
+const hash = await bcrypt.hash(newPassword, 10)
+await db.update(users).set({ passwordHash: hash, updatedAt: new Date() }).where(eq(users.id, user.id))
+
+console.log(`Password reset for ${email} (user ${user.id})`)
+await sql.end()

packages/shared/src/schemas/auth.schema.ts

@@ -27,3 +27,14 @@ export const SetPinSchema = z.object({
   pin: z.string().min(4).max(6).regex(/^\d+$/, 'PIN must be digits only'),
 })
 export type SetPinInput = z.infer<typeof SetPinSchema>
+
+export const ForgotPasswordSchema = z.object({
+  email: z.string().email(),
+})
+export type ForgotPasswordInput = z.infer<typeof ForgotPasswordSchema>
+
+export const ResetPasswordSchema = z.object({
+  token: z.string().min(1),
+  newPassword: z.string().min(12, 'Password must be at least 12 characters').max(128),
+})
+export type ResetPasswordInput = z.infer<typeof ResetPasswordSchema>

packages/shared/src/schemas/index.ts

@@ -1,8 +1,8 @@
 export { PaginationSchema } from './pagination.schema.js'
 export type { PaginationInput, PaginatedResponse } from './pagination.schema.js'
 
-export { UserRole, RegisterSchema, LoginSchema, PinLoginSchema, SetPinSchema } from './auth.schema.js'
+export { UserRole, RegisterSchema, LoginSchema, PinLoginSchema, SetPinSchema, ForgotPasswordSchema, ResetPasswordSchema } from './auth.schema.js'
-export type { RegisterInput, LoginInput, PinLoginInput, SetPinInput } from './auth.schema.js'
+export type { RegisterInput, LoginInput, PinLoginInput, SetPinInput, ForgotPasswordInput, ResetPasswordInput } from './auth.schema.js'
 
 export {
   BillingMode,