Supershyft OS

Appearance

Google OAuth Setup Guide ​

This guide walks you through setting up Google OAuth authentication for Supershyft OS.

Implementation Status ​

✅ Backend OAuth routes implemented ✅ JWT session management implemented ✅ Auth middleware updated for session cookies ✅ Frontend login page updated with Google button ✅ Logout functionality added ✅ Dev mode compatibility maintained

Prerequisites ​

  • Google Cloud Console account
  • Access to Supershyft OS codebase
  • Wrangler CLI installed for production secrets

Step 1: Google Cloud Console Setup ​

1.1 Create/Select Project ​

  1. Go to Google Cloud Console
  2. Create a new project or select existing project
  3. Name it something like "Supershyft OS" or "Supershyft Authentication"

1.2 Enable Google Identity API ​

  1. Navigate to APIs & Services → Library
  2. Search for "Google+ API" or "Google Identity Services API"
  3. Click Enable

1.3 Configure OAuth Consent Screen ​

  1. Navigate to APIs & Services → OAuth consent screen
  2. Select Internal (if using Google Workspace) or External
  3. Fill in application details:
    • App name: Supershyft OS
    • User support email: Your email
    • Developer contact email: Your email
  4. Click Save and Continue
  5. Skip scopes (default scopes are sufficient)
  6. Add test users if using External consent:
    • Add all @capcoib.com users who need access
    • Add louis.decuypere@gmail.com
  7. Click Save and Continue

1.4 Create OAuth 2.0 Credentials ​

  1. Navigate to APIs & Services → Credentials
  2. Click + CREATE CREDENTIALS → OAuth client ID
  3. Select Web application
  4. Configure:
    • Name: Supershyft OS Web Client
    • Authorized JavaScript origins:
      • http://localhost:5173 (development)
      • http://localhost:8787 (API dev)
      • https://os.supershyft.capital (production)
      • https://api.supershyft.capital (production API)
    • Authorized redirect URIs:
      • http://localhost:8787/api/auth/google (development)
      • https://api.supershyft.capital/api/auth/google (production)
  5. Click Create
  6. Copy the Client ID and Client Secret (you'll need these next)

Step 2: Configure Local Development ​

2.1 Update .dev.vars ​

The file apps/api-worker/.dev.vars has been created with placeholders. Update it with your credentials:

bash
# Google OAuth Configuration
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
FRONTEND_URL=http://localhost:5173

# JWT Secret (already generated)
JWT_SECRET=Fi1UACq0Y22w1KcjOpovhwKJnlwJH9uGIGHLnTz74ok=

Replace:

  • GOOGLE_CLIENT_ID with the Client ID from Google Console
  • GOOGLE_CLIENT_SECRET with the Client Secret from Google Console

2.2 Test Locally ​

  1. Start the API worker:

    bash
    pnpm dev:api

  2. Start the frontend:

    bash
    pnpm dev:web

  3. Visit http://localhost:5173

  4. Click "Sign in with Google"

  5. You should be redirected to Google's OAuth consent screen

  6. After authorizing, you'll be redirected back to /home

  7. Check that your email is displayed in the sidebar

2.3 Verify Session ​

  • Check browser dev tools → Application → Cookies
  • You should see a session cookie (HttpOnly, SameSite=Lax)
  • The cookie contains your JWT session token

2.4 Test Logout ​

  1. Click your profile in the sidebar
  2. Click Sign out
  3. You should be redirected to the login page
  4. Session cookie should be cleared

Step 3: Configure Production ​

3.1 Set Production Secrets ​

Use Wrangler CLI to set secrets for the production API worker:

bash
cd apps/api-worker

# Set Google OAuth credentials
wrangler secret put GOOGLE_CLIENT_ID
# Paste your Client ID

wrangler secret put GOOGLE_CLIENT_SECRET
# Paste your Client Secret

# Set JWT secret (use a new one for production!)
wrangler secret put JWT_SECRET
# Generate new: openssl rand -base64 32

# Set frontend URL
wrangler secret put FRONTEND_URL
# Enter: https://os.supershyft.capital

3.2 Deploy API Worker ​

bash
pnpm deploy:api

3.3 Deploy Frontend ​

Frontend auto-deploys via Cloudflare Pages on git push:

bash
git add .
git commit -m "feat: Add Google OAuth authentication"
git push origin main

3.4 Test Production ​

  1. Visit https://os.supershyft.capital
  2. Click Sign in with Google
  3. Authorize with your @capcoib.com or louis.decuypere@gmail.com account
  4. Verify you're redirected to /home
  5. Test logout functionality

Step 4: Security Checklist ​

  • [ ] Google OAuth consent screen configured correctly
  • [ ] Only authorized domains can access (capcoib.com, louis.decuypere@gmail.com)
  • [ ] Redirect URIs match exactly (no trailing slashes)
  • [ ] Production uses HTTPS for all OAuth flows
  • [ ] JWT secret is different in production vs development
  • [ ] Session cookies are HttpOnly and Secure (in production)
  • [ ] Dev mode still works with X-User-Email header

Architecture Overview ​

Authentication Flow ​

1. User clicks "Sign in with Google"
   → Redirects to /api/auth/google

2. API redirects to Google OAuth consent screen
   → Google handles authentication

3. Google redirects back to /api/auth/google with auth code
   → API validates email domain
   → Creates JWT session token
   → Sets session cookie (HttpOnly, 7-day expiry)
   → Redirects to /home

4. Subsequent requests include session cookie
   → Auth middleware extracts email from JWT
   → User is authenticated for all API calls

5. User clicks "Sign out"
   → POST /api/auth/logout
   → Clears session cookie
   → Redirects to login page

Email Authorization ​

Only the following emails can log in:

  • louis.decuypere@gmail.com (exact match)
  • Any @capcoib.com email (domain match)

Unauthorized emails see an error message after Google OAuth.

Session Management ​

  • Token Type: JWT (JSON Web Token)
  • Storage: HttpOnly cookie named session
  • Expiry: 7 days
  • Refresh: Not implemented (user must re-login after 7 days)
  • Security: HttpOnly, SameSite=Lax, Secure (production only)

Dev Mode Compatibility ​

Dev mode continues to work as before:

  • X-User-Email header takes precedence
  • No OAuth required in development
  • LocalStorage-based user switching still functional

API Endpoints ​

Public Endpoints (No Auth Required) ​

  • GET /api/auth/google - Initiates OAuth flow
  • GET /api/auth/status - Health check for auth system

Protected Endpoints (Auth Required) ​

  • GET /api/auth/me - Returns current user info
  • POST /api/auth/logout - Clears session
  • All other /api/* routes require authentication

Troubleshooting ​

Issue: "redirect_uri_mismatch" error ​

Solution: Ensure the redirect URI in Google Console matches EXACTLY:

  • Dev: http://localhost:8787/api/auth/google
  • Prod: https://api.supershyft.capital/api/auth/google

No trailing slashes, exact protocol (http vs https).

Issue: "unauthorized_email" error ​

Solution:

  • Check that your email is @capcoib.com or louis.decuypere@gmail.com
  • Update apps/api-worker/src/routes/auth.ts to add more emails/domains

Solution:

  • Check browser dev tools → Network → Response headers
  • Look for Set-Cookie header
  • Ensure CORS is allowing credentials (credentials: true)
  • Verify domain matches (.supershyft.capital for production)

Issue: "JWT_SECRET environment variable is required" ​

Solution:

  • Check .dev.vars file exists and has JWT_SECRET
  • For production, run wrangler secret put JWT_SECRET
  • Restart API worker after adding secret

Issue: Dev mode stops working ​

Solution:

  • Dev mode should still work with X-User-Email header
  • Check that shared API client is sending the header
  • Verify auth middleware checks dev header FIRST (before OAuth)

Files Modified ​

Backend ​

  • apps/api-worker/src/routes/auth.ts (new) - OAuth routes
  • apps/api-worker/src/lib/jwt.ts (new) - JWT utilities
  • apps/api-worker/src/middleware/auth.ts - Session cookie support
  • apps/api-worker/src/index.ts - Register auth routes
  • apps/api-worker/.dev.vars - OAuth environment variables

Frontend ​

  • apps/web/src/views/Login.vue - Google sign-in button
  • apps/web/src/composables/useUser.ts - OAuth flow + logout
  • apps/web/src/ui/AppShell.vue - Logout button

Documentation ​

  • docs/development/GOOGLE_OAUTH_SETUP.md (this file)

Next Steps ​

  1. ✅ Complete Google Cloud Console setup
  2. ✅ Update .dev.vars with your credentials
  3. ✅ Test locally (dev environment)
  4. ⬜ Set production secrets via Wrangler
  5. ⬜ Deploy to production
  6. ⬜ Test production OAuth flow
  7. ⬜ Update CLAUDE.md with OAuth documentation

Support ​

If you encounter issues:

  1. Check browser console for errors
  2. Check API worker logs: wrangler tail
  3. Verify Google Cloud Console configuration
  4. Check CORS settings in apps/api-worker/src/index.ts

Last Updated: 2025-10-20 Status: Implementation complete, ready for Google Cloud setup

Built for Supershyft Capital

Copyright © 2025