🔐 CNC Lab Documentation Security & Deployment Guide

CRITICAL: This documentation site (docs.cnclab.io) uses client-side authentication to restrict access to lab members only.

Security Implementation¶

How It Works¶

1. Client-side authentication gate (_static/auth-gate.js) runs on every page load

2. Google OAuth integration uses same system as main site (cnclab.io)

3. Lab member verification against existing team whitelist API

4. Secure token storage in browser localStorage with expiration

Authentication Flow¶

1. User visits docs.cnclab.io
2. auth-gate.js loads and checks for stored token
3. If no token: redirect to Google OAuth
4. OAuth callback processes authorization code
5. Main site API exchanges code for access token
6. Email verified against lab member whitelist
7. Token stored locally, user sees documentation

Deployment Requirements¶

Vercel Environment Variables (Main Site: cnclab.io)¶

These must be configured in the Vercel dashboard for the main site project:

GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

Google OAuth Configuration¶

In your Google Cloud Console OAuth client, add these authorized redirect URIs:

https://docs.cnclab.io/auth/callback

File Structure¶

docs-book/
├── _static/
│   └── auth-gate.js          # Client-side authentication script
├── auth/
│   └── callback.html         # OAuth callback handler  
├── _config.yml              # Injects auth-gate.js into all pages
├── vercel.json              # Deployment configuration
└── DEPLOYMENT_SECURITY.md   # This guide

API Endpoints (Main Site)¶

/api/docs/config¶

• Purpose: Provides auth configuration for docs site

• Response: { success: true, config: { enableAuth: true, googleClientId: "..." } }

• CORS: Enabled for docs.cnclab.io

/api/auth/exchange-token¶

• Purpose: Securely exchanges OAuth code for access token

• Method: POST

• Body: { code: "oauth_authorization_code" }

• Response: { success: true, access_token: "...", email: "...", name: "..." }

/api/auth/whitelist¶

• Purpose: Returns list of authorized lab member emails

• Response: { success: true, emails: ["email1@domain.com", ...] }

Testing Authentication¶

✅ With Authentication Enabled (Production)¶

1. Visit docs.cnclab.io

2. Should show Google login page

3. After login with lab email → documentation visible

4. Login with non-lab email → access denied

⚠️ Troubleshooting¶

Site shows login but fails after Google auth:

• Check Google OAuth redirect URIs include: https://docs.cnclab.io/auth/callback

• Verify GOOGLE_CLIENT_SECRET is set in main site Vercel env vars

“Could not load auth config” in browser console:

• Check main site /api/docs/config endpoint is accessible

• Verify CORS headers allow docs.cnclab.io

User gets “Access denied” after successful Google auth:

• Verify user’s email is in the team Google Sheet

• Check /api/auth/whitelist endpoint returns their email

Security Features¶

• ✅ No credentials in static files - all auth handled via API calls

• ✅ Token expiration - 5 minute automatic re-verification

• ✅ State verification - prevents CSRF attacks in OAuth flow

• ✅ Email whitelist - only authorized lab members can access

• ✅ Secure token exchange - authorization codes exchanged server-side

• ✅ CORS protection - API endpoints only allow docs.cnclab.io origin

Emergency Access¶

If authentication breaks and you need to disable it temporarily:

1. Go to main site Vercel dashboard

2. Remove GOOGLE_CLIENT_ID environment variable

3. Redeploy main site

4. Docs site will fall back to public access

The auth-gate.js script automatically detects missing configuration and allows public access as fallback.

Last Updated: September 6, 2025
Next Review: After any changes to OAuth setup or team member management