Migrate authentication to Better Auth

Replace the hand-rolled JWT auth with Better Auth 1.6.25 httpOnly cookie
sessions, validated against the database on every request so revocation,
bans and role changes take effect immediately.

Backend:
- betterAuth.ts wires the Drizzle adapter, magic links, Google sign-in and
  the admin plugin; auth-schema.ts maps Better Auth's models onto the
  existing `users` table so user IDs and their foreign keys survive intact.
- routes/auth.ts is gone; Better Auth serves the standard endpoints and
  authExt.ts carries the flows it doesn't cover.
- auth.ts shrinks to session resolution and helpers; sessions/revocation in
  dashboard.ts now read and delete `auth_sessions` rows directly.
- Schema adds the Better Auth core + admin columns (email_verified, image,
  banned, ban_reason, ban_expires), with migrations and tests.
- rateLimit.ts resolves client IPs spoof-resistantly: proxy headers are only
  honoured from loopback/RFC1918 peers plus TRUSTED_PROXIES.
- passwordPolicy.ts centralises password validation.
- Bump drizzle-orm, drizzle-kit and better-sqlite3 to versions compatible
  with Better Auth.

Frontend:
- auth-client.ts plus a reworked AuthContext and api/client.ts move to
  cookie-based sessions; no more bearer tokens in requests or middleware.

photo-api:
- Validate Better Auth session cookies against the shared auth_sessions
  table instead of verifying JWTs; JWT_SECRET is no longer needed for user
  auth, and PHOTO_VIEW_SECRET now signs gallery view tokens.

BETTER_AUTH_SECRET and BETTER_AUTH_URL are required in production; the
deprecated JWT_SECRET stays only as the photo-api view-token fallback.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

frontend/src/lib/api/auth.ts

@@ -1,63 +1,97 @@
+import { authClient } from '../auth-client';
 import { fetchApi } from './client';
 import type { User } from './types';
 
+// Thin wrappers over the Better Auth client, preserving the legacy authApi
+// call surface used by the auth pages.
+
+type ClientError = { message?: string; code?: string; status: number } | null;
+
+function throwIfError(error: ClientError, fallback: string): void {
+  if (error) {
+    const err = new Error(error.message || fallback);
+    (err as any).code = error.code;
+    (err as any).status = error.status;
+    throw err;
+  }
+}
+
 export const authApi = {
-  // Magic link
-  requestMagicLink: (email: string) =>
-    fetchApi<{ message: string }>('/api/auth/magic-link/request', {
-      method: 'POST',
-      body: JSON.stringify({ email }),
-    }),
+  // Magic link login. Enumeration-safe UX parity: unknown emails resolve with
+  // the same generic message (magic links never create accounts server-side);
+  // only rate limiting surfaces as an error.
+  requestMagicLink: async (email: string, callbackURL: string = '/dashboard') => {
+    const { error } = await authClient.signIn.magicLink({ email, callbackURL });
+    if (error && error.status === 429) {
+      throwIfError(error, 'Too many requests. Please try again later.');
+    }
+    return { message: 'If an account exists with this email, a login link has been sent.' };
+  },
 
-  verifyMagicLink: (token: string) =>
-    fetchApi<{ user: User; token: string; refreshToken: string }>('/api/auth/magic-link/verify', {
-      method: 'POST',
-      body: JSON.stringify({ token }),
-    }),
+  verifyMagicLink: async (token: string) => {
+    const { data, error } = await authClient.magicLink.verify({ query: { token } });
+    throwIfError(error, 'Invalid or expired token');
+    return data;
+  },
 
-  // Password reset
-  requestPasswordReset: (email: string) =>
-    fetchApi<{ message: string }>('/api/auth/password-reset/request', {
-      method: 'POST',
-      body: JSON.stringify({ email }),
-    }),
+  // Password reset (Better Auth is enumeration-safe here by default)
+  requestPasswordReset: async (email: string) => {
+    const { error } = await authClient.requestPasswordReset({
+      email,
+      redirectTo: '/auth/reset-password',
+    });
+    throwIfError(error, 'Failed to request password reset');
+    return { message: 'If an account exists with this email, a password reset link has been sent.' };
+  },
 
-  confirmPasswordReset: (token: string, password: string) =>
-    fetchApi<{ message: string }>('/api/auth/password-reset/confirm', {
-      method: 'POST',
-      body: JSON.stringify({ token, password }),
-    }),
+  confirmPasswordReset: async (token: string, password: string) => {
+    const { error } = await authClient.resetPassword({ newPassword: password, token });
+    throwIfError(error, 'Invalid or expired token');
+    return { message: 'Password reset successfully. Please log in with your new password.' };
+  },
 
-  // Account claiming
+  // Account claiming: a magic link that lands on the claim page, where the
+  // session-holding user sets a password via /api/auth-ext/claim-account.
   requestClaimAccount: (email: string) =>
-    fetchApi<{ message: string }>('/api/auth/claim-account/request', {
+    authApi.requestMagicLink(email, '/auth/claim-account'),
+
+  confirmClaimAccount: (password: string) =>
+    fetchApi<{ user: User; message: string }>('/api/auth-ext/claim-account', {
       method: 'POST',
-      body: JSON.stringify({ email }),
+      body: JSON.stringify({ password }),
     }),
 
-  confirmClaimAccount: (token: string, data: { password?: string; googleId?: string }) =>
-    fetchApi<{ user: User; token: string; refreshToken: string; message: string }>(
-      '/api/auth/claim-account/confirm',
-      {
-        method: 'POST',
-        body: JSON.stringify({ token, ...data }),
-      }
+  claimEligibility: (email: string) =>
+    fetchApi<{ canClaim: boolean }>(
+      `/api/auth-ext/claim-eligibility?email=${encodeURIComponent(email)}`
     ),
 
-  // Google OAuth
-  googleAuth: (credential: string) =>
-    fetchApi<{ user: User; token: string; refreshToken: string }>('/api/auth/google', {
-      method: 'POST',
-      body: JSON.stringify({ credential }),
-    }),
+  // Google Identity Services credential (ID token) sign-in
+  googleAuth: async (credential: string) => {
+    const { data, error } = await authClient.signIn.social({
+      provider: 'google',
+      idToken: { token: credential },
+    });
+    throwIfError(error, 'Google login failed');
+    return data;
+  },
 
-  // Change password
-  changePassword: (currentPassword: string, newPassword: string) =>
-    fetchApi<{ message: string }>('/api/auth/change-password', {
-      method: 'POST',
-      body: JSON.stringify({ currentPassword, newPassword }),
-    }),
+  // Change password; other sessions are revoked so a stolen session can't
+  // outlive the change (this device stays signed in).
+  changePassword: async (currentPassword: string, newPassword: string) => {
+    const { error } = await authClient.changePassword({
+      currentPassword,
+      newPassword,
+      revokeOtherSessions: true,
+    });
+    throwIfError(error, 'Failed to change password');
+    return { message: 'Password changed successfully' };
+  },
 
   // Get current user
-  me: () => fetchApi<{ user: User }>('/api/auth/me'),
+  me: async (): Promise<{ user: User | null }> => {
+    const { data, error } = await authClient.getSession();
+    throwIfError(error, 'Failed to load session');
+    return { user: (data?.user as unknown as User) ?? null };
+  },
 };

frontend/src/lib/api/client.ts

@@ -1,30 +1,25 @@
 export const API_BASE = process.env.NEXT_PUBLIC_API_URL || '';
 
+// Auth rides on the Better Auth httpOnly session cookie. With API_BASE unset
+// (same-origin via Next rewrites) 'same-origin' sends it; a cross-origin
+// API_BASE needs 'include' plus CORS credentials on the backend.
+const CREDENTIALS: RequestCredentials = API_BASE ? 'include' : 'same-origin';
+
 export interface ApiError {
   error: string;
 }
 
-/** Read the stored auth token (browser only). */
-export function getToken(): string | null {
-  return typeof window !== 'undefined' ? localStorage.getItem('spanglish-token') : null;
-}
-
 export async function fetchApi<T>(
   endpoint: string,
   options: RequestInit = {}
 ): Promise<T> {
-  const token = getToken();
-
   const headers: HeadersInit = {
     'Content-Type': 'application/json',
     ...options.headers,
   };
 
-  if (token) {
-    (headers as Record<string, string>)['Authorization'] = `Bearer ${token}`;
-  }
-
   const res = await fetch(`${API_BASE}${endpoint}`, {
+    credentials: CREDENTIALS,
     ...options,
     headers,
   });
@@ -53,11 +48,7 @@ export async function fetchBlob(
   endpoint: string,
   fallbackFilename: string
 ): Promise<{ blob: Blob; filename: string }> {
-  const token = getToken();
-  const headers: Record<string, string> = {};
-  if (token) headers['Authorization'] = `Bearer ${token}`;
-
-  const res = await fetch(`${API_BASE}${endpoint}`, { headers });
+  const res = await fetch(`${API_BASE}${endpoint}`, { credentials: CREDENTIALS });
   if (!res.ok) {
     const errorData = await res.json().catch(() => ({ error: 'Export failed' }));
     throw new Error(errorData.error || 'Export failed');

frontend/src/lib/api/media.ts

@@ -1,4 +1,4 @@
-import { fetchApi, API_BASE, getToken } from './client';
+import { fetchApi, API_BASE } from './client';
 import type { Media } from './types';
 
 export const mediaApi = {
@@ -11,16 +11,15 @@ export const mediaApi = {
   },
 
   upload: async (file: File, relatedId?: string, relatedType?: string) => {
-    const token = getToken();
-
     const formData = new FormData();
     formData.append('file', file);
     if (relatedId) formData.append('relatedId', relatedId);
     if (relatedType) formData.append('relatedType', relatedType);
 
+    // Auth rides on the session cookie
     const res = await fetch(`${API_BASE}/api/media/upload`, {
       method: 'POST',
-      headers: token ? { 'Authorization': `Bearer ${token}` } : {},
+      credentials: API_BASE ? 'include' : 'same-origin',
       body: formData,
     });
 

frontend/src/lib/api/photos.ts

@@ -1,4 +1,4 @@
-import { fetchApi, API_BASE, getToken } from './client';
+import { fetchApi, API_BASE } from './client';
 
 // Client for the standalone photo-api Go service (photo-api/), reachable
 // under /api/photos via the Next rewrite (dev) or nginx (prod).
@@ -94,13 +94,13 @@ export const photosApi = {
     }),
 
   uploadPhoto: async (galleryId: string, file: File) => {
-    const token = getToken();
     const formData = new FormData();
     formData.append('files', file);
 
+    // Auth rides on the session cookie (sent same-origin automatically)
     const res = await fetch(`${API_BASE}/api/photos/galleries/${galleryId}/photos`, {
       method: 'POST',
-      headers: token ? { Authorization: `Bearer ${token}` } : {},
+      credentials: API_BASE ? 'include' : 'same-origin',
       body: formData,
     });
     if (!res.ok) {
@@ -122,8 +122,9 @@ export const photosApi = {
     new Promise<{ photos: Photo[] }>((resolve, reject) => {
       const xhr = new XMLHttpRequest();
       xhr.open('POST', `${API_BASE}/api/photos/galleries/${galleryId}/photos`);
-      const token = getToken();
-      if (token) xhr.setRequestHeader('Authorization', `Bearer ${token}`);
+      // Auth rides on the session cookie; XHR sends same-origin cookies by
+      // default, withCredentials is only needed for a cross-origin API_BASE.
+      if (API_BASE) xhr.withCredentials = true;
       xhr.upload.onprogress = (e) => {
         if (e.lengthComputable && e.total > 0) onProgress(e.loaded / e.total);
       };

frontend/src/lib/api/types.ts

@@ -439,6 +439,9 @@ export interface UserSession {
   ipAddress?: string;
   lastActiveAt: string;
   createdAt: string;
+  expiresAt?: string;
+  /** True for the session backing the current request. */
+  current?: boolean;
 }
 
 export interface DashboardSummary {

frontend/src/lib/auth-client.ts

@@ -0,0 +1,22 @@
+import { createAuthClient } from 'better-auth/react';
+import { magicLinkClient, adminClient, inferAdditionalFields } from 'better-auth/client/plugins';
+
+// Better Auth client. Sessions are httpOnly cookies set by the backend; with
+// NEXT_PUBLIC_API_URL unset everything is same-origin through the Next.js
+// rewrites (see next.config.js), so cookies flow automatically.
+export const authClient = createAuthClient({
+  baseURL: process.env.NEXT_PUBLIC_API_URL || '',
+  plugins: [
+    magicLinkClient(),
+    adminClient(),
+    inferAdditionalFields({
+      user: {
+        phone: { type: 'string', required: false },
+        languagePreference: { type: 'string', required: false },
+        rucNumber: { type: 'string', required: false },
+        isClaimed: { type: 'boolean', required: false },
+        accountStatus: { type: 'string', required: false },
+      },
+    }),
+  ],
+});