Authentication & Cookie Debugging Guide

This guide will help you debug authentication and cookie issues with your Hyperclay-compatible self-updating page.

Set the DEBUG environment variable to true in your Val.town settings:

DEBUG=true

This will enable detailed server-side logging for all authentication flows.

Verify these are set correctly:

ADMIN_EMAIL=your-actual-email@domain.com
DEBUG=true
APP_NAMESPACE=default (optional)

1. Check that ADMIN_EMAIL is set to your exact email address
2. Enable DEBUG=true
3. Save your val to apply the changes

1. Visit /auth/edit
2. Enter your email (must match ADMIN_EMAIL exactly)
3. Check Val.town logs for debug messages:
   • Look for "Auth email submission" log
   • Verify email matches admin email
   • Check for "Generated magic link token" log

1. Check your email inbox (including spam folder)
2. Look for email with subject "Sign in to your Hyperclay app"
3. If no email received, check Val.town logs for email sending errors

1. Click the magic link in your email
2. Check Val.town logs for:
   • "Magic link verification attempt"
   • "Magic link token verification result"
   • "Creating session and redirecting"
3. You should be redirected to the main page

After clicking the magic link, check:

1. Browser cookies: Open DevTools → Application → Cookies
   • Look for session cookie (HttpOnly, so won't be visible in JS)
   • Look for isAdminOfCurrentResource=true cookie
   • Look for currentResource=app cookie

1. Visit the main page (/)
2. Check Val.town logs for:
   • "Checking admin status"
   • "Session ID from cookie"
   • "Admin check result"
   • "Setting Hyperclay admin cookies" (if admin)

1. Try to edit content on the page
2. Save changes (Ctrl+S)
3. Check Val.town logs for:
   • "Save endpoint accessed"
   • "Admin status for save endpoint"
   • "Save request details"
   • "HTML saved successfully"

Possible Causes:

1. Session not created: Magic link didn't work properly
2. Session expired: Check session expiry in logs
3. Email mismatch: Your email doesn't match ADMIN_EMAIL
4. Cookie header issues: Browser not sending session cookie

Debug Steps:

1. Check logs for "User admin status for main page" - should show isUserAdmin: true
2. Verify session cookie exists in browser
3. Check "Admin check result" log for email comparison
4. Try clearing all cookies and re-authenticating

Possible Causes:

1. Token expired: Links expire after 15 minutes
2. Token already used: Magic links are one-time use
3. Email mismatch: Token was generated for different email

Debug Steps:

1. Check "Magic link token verification result" log
2. Look for "Auth token expired" or "Auth token invalid" messages
3. Generate a new magic link if token expired

Possible Causes:

1. Not authenticated: Session invalid or expired
2. Wrong cookies: Hyperclay cookies not set properly
3. Network issues: Save requests not reaching server

Debug Steps:

1. Check "Admin status for save endpoint" log
2. Verify both session and Hyperclay cookies are present
3. Check browser Network tab for failed requests to /save/app

Possible Causes:

1. Hyperclay cookies missing: isAdminOfCurrentResource not set
2. Hyperclay.js not loading: Check browser console for errors
3. Cookie domain/path issues: Cookies not accessible to Hyperclay

Debug Steps:

1. Check browser cookies for isAdminOfCurrentResource=true
2. Open browser console and check for JavaScript errors
3. Verify Hyperclay.js is loading from CDN

1. Open DevTools (F12)
2. Go to Application → Cookies → [your-domain]
3. Look for:
   • session (HttpOnly - won't show value)
   • isAdminOfCurrentResource=true
   • currentResource=app

1. Open DevTools → Network tab
2. Try to save content (Ctrl+S)
3. Look for POST request to /save/app
4. Check request headers include cookies
5. Verify response is 200 OK with {"msg":"Saved"}

1. Open DevTools → Console
2. Look for JavaScript errors
3. Check if Hyperclay.js loaded successfully

Visit these URLs to test different states:

• /auth/edit - Should show email form
• /auth/view - Should clear session and redirect
• /versions - Should show version history (admin only)
• /save/app - Should return 401 if not authenticated

Use browser DevTools to:

1. Delete all cookies
2. Re-authenticate
3. Verify cookies are set correctly
4. Test edit functionality

[DEBUG] Auth email submission {"userEmail":"admin@example.com","adminEmail":"admin@example.com"}
[DEBUG] Generated magic link token {"token":"12345678...","userEmail":"admin@example.com"}
[DEBUG] Magic link sent {"userEmail":"admin@example.com","origin":"https://yourval.web.val.run"}
[DEBUG] Magic link verification attempt {"token":"12345678..."}
[DEBUG] Magic link token verification result {"email":"admin@example.com","adminEmail":"admin@example.com"}
[DEBUG] Creating session and redirecting {"sessionId":"87654321...","email":"admin@example.com","expires":"2024-02-15T10:30:00.000Z"}

[DEBUG] Incoming request {"method":"GET","path":"/","hasAuth":true,"userAgent":"Mozilla/5.0..."}
[DEBUG] Serving main HTML document
[DEBUG] Checking admin status {"hasCookieHeader":true,"cookieHeader":"session=87654321..."}
[DEBUG] Session ID from cookie {"sessionId":"87654321..."}
[DEBUG] Verifying session {"sessionId":"87654321..."}
[DEBUG] Session data retrieved {"hasData":true,"email":"admin@example.com","expiry":"2024-02-15T10:30:00.000Z"}
[DEBUG] Admin check result {"email":"admin@example.com","adminEmail":"admin@example.com","isAdmin":true}
[DEBUG] User admin status for main page {"isUserAdmin":true}
[DEBUG] Setting Hyperclay admin cookies {"cookies":["currentResource=app; Path=/; Expires=...","isAdminOfCurrentResource=true; Path=/; Expires=..."],"expires":"2024-02-15T10:30:00.000Z"}

[DEBUG] Auth email submission {"userEmail":"wrong@example.com","adminEmail":"admin@example.com"}
[DEBUG] Invalid email for auth {"userEmail":"wrong@example.com","adminEmail":"admin@example.com"}

If you suspect storage issues, you can manually check what's stored:

1. Look for keys like default_session_* and default_auth_token_*
2. Check expiry timestamps in stored data
3. Verify session data contains correct email

Try authentication in:

1. Incognito/private mode
2. Different browsers
3. Different devices

This helps identify browser-specific cookie issues.

If you're still having issues after following this guide:

1. Share debug logs: Copy relevant debug log entries
2. Describe the exact steps: What you did and what happened
3. Check environment: Verify all environment variables are set correctly
4. Browser details: Include browser type and version
5. Network info: Any proxy, VPN, or network restrictions

The debug logs will show exactly where the authentication flow is failing, making it much easier to identify and fix the issue.