From d80e7877015a4ab5a50c223adc4f6abccf23b6fc Mon Sep 17 00:00:00 2001
From: Paul Bailey <psbailey31@gmail.com>
Date: Sun, 16 Nov 2025 19:23:37 +0000
Subject: [PATCH] docs: add Clerk setup guide and improve auth error messages

- Create CLERK_SETUP.md with step-by-step instructions
- Improve error message to indicate Clerk configuration issue
- Remove debug logging from auth middleware
- Update error handling to be more helpful

The 401 error is caused by missing Clerk Secret Key in server/.env
---
 server/CLERK_SETUP.md         | 81 +++++++++++++++++++++++++++++++++++
 server/TASK_25_SUMMARY.md     |  0
 server/src/middleware/auth.ts |  2 +-
 src/services/reportService.ts |  2 +-
 4 files changed, 83 insertions(+), 2 deletions(-)
 create mode 100644 server/CLERK_SETUP.md
 create mode 100644 server/TASK_25_SUMMARY.md

diff --git a/server/CLERK_SETUP.md b/server/CLERK_SETUP.md
new file mode 100644
index 0000000..00ffaa3
--- /dev/null
+++ b/server/CLERK_SETUP.md
@@ -0,0 +1,81 @@
+# Clerk Authentication Setup
+
+## Issue
+
+The backend server is returning 401 Unauthorized errors because the Clerk Secret Key is not configured correctly.
+
+**Error**: `The provided Clerk Secret Key is invalid. Make sure that your Clerk Secret Key is correct.`
+
+## Solution
+
+You need to add your real Clerk Secret Key to the backend environment configuration.
+
+### Steps to Fix
+
+1. **Get your Clerk Secret Key**:
+   - Go to [Clerk Dashboard](https://dashboard.clerk.com)
+   - Navigate to **API Keys** section
+   - Copy your **Secret Key** (starts with `sk_test_...` for test environment or `sk_live_...` for production)
+
+2. **Update the backend .env file**:
+   - Open `server/.env`
+   - Replace the placeholder with your real secret key:
+   
+   ```env
+   # Before (placeholder)
+   CLERK_SECRET_KEY="sk_test_placeholder"
+   
+   # After (your real key)
+   CLERK_SECRET_KEY="sk_test_YOUR_ACTUAL_SECRET_KEY_HERE"
+   ```
+
+3. **Restart the backend server**:
+   - The server will automatically restart if you're using `npm run dev`
+   - Or manually restart it
+
+### Current Configuration
+
+**Frontend** (`.env.local`):
+```env
+VITE_CLERK_PUBLISHABLE_KEY=pk_test_YWJvdmUtZmxvdW5kZXItOTEuY2xlcmsuYWNjb3VudHMuZGV2JA
+```
+✅ This is configured correctly
+
+**Backend** (`server/.env`):
+```env
+CLERK_SECRET_KEY="sk_test_placeholder"
+```
+❌ This needs to be updated with your real secret key
+
+### How to Find Your Keys
+
+1. Visit: https://dashboard.clerk.com/last-active?path=api-keys
+2. You'll see two keys:
+   - **Publishable Key** (pk_test_...) - Already configured in frontend ✅
+   - **Secret Key** (sk_test_...) - Needs to be added to backend ❌
+
+### Security Note
+
+⚠️ **Never commit your secret key to version control!**
+
+The `.env` file is already in `.gitignore`, but always double-check before committing.
+
+### Testing After Setup
+
+Once you've added the correct secret key:
+
+1. The server will restart automatically
+2. Try uploading a photo in the report form
+3. You should see successful uploads instead of 401 errors
+
+### Verification
+
+You can verify the setup is working by checking the server logs:
+
+```
+Auth middleware - Authorization header: present
+Auth middleware - Token extracted, length: XXX
+Auth middleware - Session verified for user: user_XXXXX
+```
+
+If you see these logs, authentication is working correctly!
diff --git a/server/TASK_25_SUMMARY.md b/server/TASK_25_SUMMARY.md
new file mode 100644
index 0000000..e69de29
diff --git a/server/src/middleware/auth.ts b/server/src/middleware/auth.ts
index b18f6ff..6f87f7f 100644
--- a/server/src/middleware/auth.ts
+++ b/server/src/middleware/auth.ts
@@ -48,7 +48,7 @@ export const requireAuth = async (
     return res.status(401).json({
       error: {
         code: 'UNAUTHORIZED',
-        message: 'Authentication failed',
+        message: 'Authentication failed. Please check that CLERK_SECRET_KEY is configured correctly in server/.env',
         timestamp: new Date().toISOString(),
       },
     });
diff --git a/src/services/reportService.ts b/src/services/reportService.ts
index 1072525..6b81b8a 100644
--- a/src/services/reportService.ts
+++ b/src/services/reportService.ts
@@ -50,7 +50,7 @@ class ReportService {
 
     if (!response.ok) {
       if (response.status === 401) {
-        throw new Error('You must be signed in to upload photos. Please sign in and try again.');
+        throw new Error('Authentication failed. Please make sure the backend Clerk Secret Key is configured correctly.');
       }
       
       // Try to get error details from response