This MR fixes critical authentication issues that prevented login on localhost and improves the developer experience with consolidated rebuild scripts and a working help modal keyboard shortcut. (#5)

# Fix authentication issues and improve developer experience

## Summary

This MR fixes critical authentication issues that prevented login on localhost and improves the developer experience with consolidated rebuild scripts and a working help modal keyboard shortcut.

## Problems Fixed

### 1. Authentication Issues
- **UntrustedHost Error**: NextAuth v5 was rejecting localhost requests with "UntrustedHost: Host must be trusted" error
- **Cookie Prefix Errors**: Cookies were being set with `__Host-` and `__Secure-` prefixes on HTTP (localhost), causing browser rejection
- **MissingCSRF Error**: CSRF token cookies were not being set correctly due to cookie configuration issues

### 2. Help Modal Keyboard Shortcut
- **Shift+? not working**: The help modal keyboard shortcut was not detecting the question mark key correctly

### 3. Developer Experience
- **Multiple rebuild scripts**: Had several overlapping rebuild scripts that were confusing
- **Unused code**: Removed unused `useSecureCookies` variable and misleading comments

## Changes Made

### Authentication Fixes (`lib/auth.ts`)
- Set `trustHost: true` to fix UntrustedHost error (required for NextAuth v5)
- Added explicit cookie configuration for HTTP (localhost) to prevent prefix errors:
  - Cookies use `secure: false` for HTTP
  - Cookie names without prefixes for HTTP
  - Let Auth.js defaults handle HTTPS (with prefixes and Secure flag)
- Removed unused `useSecureCookies` variable
- Simplified debug logging

### Help Modal Fix (`components/HelpModal.tsx`)
- Fixed keyboard shortcut detection to properly handle Shift+? (Shift+/)
- Updated help text to show correct shortcut (Shift+? instead of Ctrl+?)

### Developer Scripts
- **Consolidated rebuild scripts**: Merged `CLEAN_REBUILD.sh`, `FIX_AND_RESTART.sh`, and `start-server.sh` into single `rebuild.sh`
- **Added REBUILD.md**: Documentation for rebuild process
- Removed redundant script files

### Code Cleanup
- Removed unused `useSecureCookies` variable from `lib/auth.ts`
- Removed misleading comment from `app/api/auth/[...nextauth]/route.ts`
- Cleaned up verbose debug logging

## Technical Details

### Cookie Configuration
The fix works by explicitly configuring cookies for HTTP environments:
- **HTTP (localhost)**: Cookies without prefixes, `secure: false`
- **HTTPS (production)**: Let Auth.js defaults handle (prefixes + Secure flag)

This prevents NextAuth v5 from auto-detecting HTTPS from proxy headers and incorrectly adding cookie prefixes.

### Keyboard Shortcut
The question mark key requires Shift+/ on most keyboards. The fix now properly detects:
- `event.shiftKey && event.key === "/"`
- `event.key === "?"` (fallback)
- `event.code === "Slash" && event.shiftKey` (additional fallback)

## Testing

- ✅ Login works on localhost (http://localhost:3000)
- ✅ No cookie prefix errors in browser console
- ✅ No UntrustedHost errors in server logs
- ✅ Help modal opens/closes with Shift+?
- ✅ Rebuild script works in both dev and prod modes

## Files Changed

### Modified
- `lib/auth.ts` - Authentication configuration fixes
- `components/HelpModal.tsx` - Keyboard shortcut fix
- `app/api/auth/[...nextauth]/route.ts` - Removed misleading comment

### Added
- `rebuild.sh` - Consolidated rebuild script
- `REBUILD.md` - Rebuild documentation

## Migration Notes

No database migrations or environment variable changes required. The fix works with existing configuration.

## Related Issues

Fixes authentication issues preventing local development and testing.

Reviewed-on: #5

lib/activity-log.ts

@@ -1,7 +1,10 @@
 /**
  * Activity logging utility for tracking user actions
+ * Uses structured logging with log levels for better production control
  */
 
+import { logger } from './logger'
+
 export interface ActivityLog {
   timestamp: string
   userId?: string
@@ -14,6 +17,18 @@ export interface ActivityLog {
   details?: Record<string, unknown>
 }
 
+/**
+ * Log user activity with structured data
+ * Uses INFO level logging - can be filtered via LOG_LEVEL environment variable
+ * 
+ * @param action - The action being performed (e.g., "PHOTO_UPLOAD", "GUESS_SUBMITTED")
+ * @param path - The request path
+ * @param method - The HTTP method
+ * @param user - Optional user object (id, email, role)
+ * @param details - Optional additional context data
+ * @param request - Optional Request object for extracting IP address
+ * @returns Structured activity log object
+ */
 export function logActivity(
   action: string,
   path: string,
@@ -21,7 +36,7 @@ export function logActivity(
   user?: { id: string; email: string; role: string } | null,
   details?: Record<string, unknown>,
   request?: Request
-) {
+): ActivityLog {
   const timestamp = new Date().toISOString()
   const ip = request?.headers.get("x-forwarded-for") || 
              request?.headers.get("x-real-ip") || 
@@ -39,14 +54,17 @@ export function logActivity(
     details
   }
   
-  // Format: [ACTION] timestamp | method path | User: email (role) | IP: ip | Details: {...}
-  const userInfo = user 
-    ? `${user.email} (${user.role})` 
-    : "UNAUTHENTICATED"
-  
-  const detailsStr = details ? ` | Details: ${JSON.stringify(details)}` : ""
-  
-  console.log(`[${action}] ${timestamp} | ${method} ${path} | User: ${userInfo} | IP: ${ip.split(",")[0].trim()}${detailsStr}`)
+  // Use structured logging with INFO level
+  // This allows filtering via LOG_LEVEL environment variable
+  logger.info(`Activity: ${action}`, {
+    method,
+    path,
+    userId: user?.id,
+    userEmail: user?.email,
+    userRole: user?.role,
+    ip: ip.split(",")[0].trim(),
+    ...(details && { details }),
+  })
   
   return log
 }

lib/auth.ts

@@ -2,15 +2,29 @@ import NextAuth from "next-auth"
 import Credentials from "next-auth/providers/credentials"
 import { prisma } from "./prisma"
 import bcrypt from "bcryptjs"
+import { logger } from "./logger"
 
-const nextAuthSecret = process.env.NEXTAUTH_SECRET
-if (!nextAuthSecret) {
-  throw new Error("NEXTAUTH_SECRET is not set. Define it to enable authentication.")
+// Lazy check for NEXTAUTH_SECRET - only validate when actually needed
+// This prevents build-time errors when the secret isn't available
+function getNextAuthSecret(): string {
+  const secret = process.env.NEXTAUTH_SECRET
+  if (!secret) {
+    // Always throw at runtime - this is a critical configuration error
+    throw new Error("NEXTAUTH_SECRET is not set. Define it to enable authentication.")
+  }
+  return secret
 }
 
+// Determine if we should use secure cookies based on AUTH_URL/NEXTAUTH_URL
+// Auth.js v5 derives this from the origin it detects, so we need to be explicit
+const authUrl = process.env.AUTH_URL || process.env.NEXTAUTH_URL || "http://localhost:3000"
+const isHttp = authUrl.startsWith("http://")
+
 export const { handlers, auth, signIn, signOut } = NextAuth({
+  // trustHost must be true for NextAuth v5 to work, even on localhost
   trustHost: true,
   debug: process.env.NODE_ENV !== "production",
+  basePath: "/api/auth",
   providers: [
     Credentials({
       name: "Credentials",
@@ -48,7 +62,7 @@ export const { handlers, auth, signIn, signOut } = NextAuth({
             role: user.role,
           }
         } catch (err) {
-          console.error("Auth authorize error:", err)
+          logger.error("Auth authorize error", err instanceof Error ? err : new Error(String(err)))
           return null
         }
       }
@@ -61,27 +75,22 @@ export const { handlers, auth, signIn, signOut } = NextAuth({
         token.role = (user as { role: string }).role
         token.email = user.email
         token.name = user.name
-        console.log("JWT callback: user added to token", { userId: user.id, email: user.email })
+        // DEBUG level: only logs in development or when LOG_LEVEL=DEBUG
+        logger.debug("JWT callback: user added to token", { 
+          userId: user.id, 
+          email: user.email 
+        })
       } else {
-        console.log("JWT callback: no user, token exists", { 
+        // DEBUG level: token refresh (normal operation, only log in debug mode)
+        logger.debug("JWT callback: token refresh", { 
           hasToken: !!token,
-          tokenKeys: token ? Object.keys(token) : [],
           tokenId: token?.id,
           tokenEmail: token?.email,
-          tokenName: token?.name,
-          tokenRole: token?.role
         })
       }
       return token
     },
     async session({ session, token }) {
-      console.log("Session callback: called", {
-        hasToken: !!token,
-        hasSession: !!session,
-        tokenId: token?.id,
-        tokenEmail: token?.email,
-        stackTrace: new Error().stack?.split('\n').slice(1, 4).join('\n')
-      })
       // Always ensure session.user exists when token exists
       if (token && (token.id || token.email)) {
         session.user = {
@@ -91,23 +100,17 @@ export const { handlers, auth, signIn, signOut } = NextAuth({
           name: (token.name as string) || session.user?.name || "",
           role: token.role as string,
         }
-        console.log("Session callback: session created", { 
+        // DEBUG level: session creation is normal operation, only log in debug mode
+        logger.debug("Session callback: session created", { 
           userId: token.id, 
           email: token.email,
-          hasUser: !!session.user,
-          userKeys: session.user ? Object.keys(session.user) : [],
           userRole: token.role,
-          sessionUser: session.user,
-          sessionExpires: session.expires,
-          fullSession: JSON.stringify(session, null, 2)
         })
       } else {
-        console.warn("Session callback: token missing or invalid", { 
+        // WARN level: token missing/invalid is a warning condition
+        logger.warn("Session callback: token missing or invalid", { 
           hasToken: !!token,
-          tokenKeys: token ? Object.keys(token) : [],
           hasSession: !!session,
-          sessionKeys: session ? Object.keys(session) : [],
-          sessionUser: session?.user,
           tokenId: token?.id,
           tokenEmail: token?.email
         })
@@ -124,16 +127,39 @@ export const { handlers, auth, signIn, signOut } = NextAuth({
     strategy: "jwt",
     maxAge: 30 * 24 * 60 * 60, // 30 days
   },
-  cookies: {
-    sessionToken: {
-      name: `__Secure-authjs.session-token`,
-      options: {
-        httpOnly: true,
-        sameSite: "lax",
-        path: "/",
-        secure: true, // Always secure in production (HTTPS required)
-      },
-    },
-  },
-  secret: nextAuthSecret,
+  // Explicitly configure cookies for HTTP (localhost)
+  // For HTTPS, let Auth.js defaults handle it (prefixes + Secure)
+  cookies: isHttp
+    ? {
+        // localhost / pure HTTP: no prefixes, no Secure
+        sessionToken: {
+          name: "authjs.session-token",
+          options: {
+            httpOnly: true,
+            sameSite: "lax",
+            path: "/",
+            secure: false,
+          },
+        },
+        csrfToken: {
+          name: "authjs.csrf-token",
+          options: {
+            httpOnly: true,
+            sameSite: "lax",
+            path: "/",
+            secure: false,
+          },
+        },
+        callbackUrl: {
+          name: "authjs.callback-url",
+          options: {
+            httpOnly: true,
+            sameSite: "lax",
+            path: "/",
+            secure: false,
+          },
+        },
+      }
+    : undefined, // Let Auth.js defaults handle HTTPS envs (prefixes + Secure)
+  secret: getNextAuthSecret(),
 })

lib/constants.ts

@@ -0,0 +1,10 @@
+/**
+ * Application-wide constants
+ */
+
+/**
+ * NextAuth session cookie name
+ * Must match the cookie name defined in lib/auth.ts
+ * For HTTP (localhost), no prefix. For HTTPS, Auth.js will add __Secure- prefix automatically.
+ */
+export const SESSION_COOKIE_NAME = "authjs.session-token"

lib/logger.ts

@@ -0,0 +1,156 @@
+/**
+ * Structured logging utility with log levels and environment-based filtering
+ * 
+ * Log levels (in order of severity):
+ * - DEBUG: Detailed information for debugging (only in development)
+ * - INFO: General informational messages
+ * - WARN: Warning messages for potentially harmful situations
+ * - ERROR: Error messages for error events
+ * 
+ * Usage:
+ *   import { logger } from '@/lib/logger'
+ *   logger.debug('Debug message', { data })
+ *   logger.info('Info message', { data })
+ *   logger.warn('Warning message', { data })
+ *   logger.error('Error message', { error })
+ */
+
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+  NONE = 4, // Disable all logging
+}
+
+export interface LogContext {
+  [key: string]: unknown;
+}
+
+export interface Logger {
+  debug(message: string, context?: LogContext): void;
+  info(message: string, context?: LogContext): void;
+  warn(message: string, context?: LogContext): void;
+  error(message: string, context?: LogContext | Error): void;
+  isLevelEnabled(level: LogLevel): boolean;
+}
+
+/**
+ * Parse log level from environment variable or default based on NODE_ENV
+ */
+function getLogLevel(): LogLevel {
+  const envLogLevel = process.env.LOG_LEVEL?.toUpperCase();
+  
+  // If explicitly set, use that
+  if (envLogLevel) {
+    switch (envLogLevel) {
+      case 'DEBUG':
+        return LogLevel.DEBUG;
+      case 'INFO':
+        return LogLevel.INFO;
+      case 'WARN':
+        return LogLevel.WARN;
+      case 'ERROR':
+        return LogLevel.ERROR;
+      case 'NONE':
+        return LogLevel.NONE;
+      default:
+        // Invalid value, fall through to default behavior
+        break;
+    }
+  }
+  
+  // Default behavior: DEBUG in development, INFO in production
+  return process.env.NODE_ENV === 'production' ? LogLevel.INFO : LogLevel.DEBUG;
+}
+
+/**
+ * Format log entry as structured JSON or human-readable string
+ */
+function formatLog(
+  level: LogLevel,
+  message: string,
+  context?: LogContext | Error
+): string {
+  const timestamp = new Date().toISOString();
+  const levelName = LogLevel[level];
+  
+  // If structured logging is enabled, output JSON
+  if (process.env.LOG_FORMAT === 'json') {
+    const logEntry: Record<string, unknown> = {
+      timestamp,
+      level: levelName,
+      message,
+    };
+    
+    if (context) {
+      if (context instanceof Error) {
+        logEntry.error = {
+          name: context.name,
+          message: context.message,
+          stack: context.stack,
+        };
+      } else {
+        Object.assign(logEntry, context);
+      }
+    }
+    
+    return JSON.stringify(logEntry);
+  }
+  
+  // Human-readable format
+  const contextStr = context
+    ? context instanceof Error
+      ? ` | Error: ${context.name}: ${context.message}`
+      : ` | ${JSON.stringify(context)}`
+    : '';
+  
+  return `[${levelName}] ${timestamp} | ${message}${contextStr}`;
+}
+
+/**
+ * Create a logger instance with the configured log level
+ */
+function createLogger(): Logger {
+  const currentLevel = getLogLevel();
+  
+  const shouldLog = (level: LogLevel): boolean => {
+    return level >= currentLevel;
+  };
+  
+  return {
+    debug(message: string, context?: LogContext): void {
+      if (shouldLog(LogLevel.DEBUG)) {
+        console.log(formatLog(LogLevel.DEBUG, message, context));
+      }
+    },
+    
+    info(message: string, context?: LogContext): void {
+      if (shouldLog(LogLevel.INFO)) {
+        console.log(formatLog(LogLevel.INFO, message, context));
+      }
+    },
+    
+    warn(message: string, context?: LogContext): void {
+      if (shouldLog(LogLevel.WARN)) {
+        console.warn(formatLog(LogLevel.WARN, message, context));
+      }
+    },
+    
+    error(message: string, context?: LogContext | Error): void {
+      if (shouldLog(LogLevel.ERROR)) {
+        console.error(formatLog(LogLevel.ERROR, message, context));
+      }
+    },
+    
+    isLevelEnabled(level: LogLevel): boolean {
+      return shouldLog(level);
+    },
+  };
+}
+
+// Export singleton logger instance
+export const logger = createLogger();
+
+// Export for testing
+export { getLogLevel, formatLog, createLogger };