Feature: Create and integrate auth wrapper for docs (#210)

## Description 📝

This PR implements comprehensive OAuth2 authentication for docs by
creating an OAuth provider. The authentication system protects all
documentation routes while maintaining a seamless user experience with
environment-aware configuration that adapts between development and
production contexts.

### Authentication Strategy

The implementation uses a three-tier approach:

1. **OAuth2 Flow**: Standard authorization code flow with an OAuth2
server
2. **Route Protection**: React context-based authentication state with
protected route wrappers
3. **Environment-Aware Access Control**: Mock authentication for
development, real GraphQL queries for production

## Code Architecture

### Authentication Context
The core authentication logic is centralized in `AuthContext.tsx`:

```typescript
export const AuthProvider: React.FC<AuthProviderProps> = ({ children }) => {
  const [user, setUser] = useState<User | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  const login = () => {
    initiateLogin();
  };

  const handleAuthCallbackWrapper = async (code: string, state: string) => {
    const accessToken = await handleAuthCallback(code, state);
    storeSession(accessToken);
    setUser({ id: 'authenticated', email: 'authenticated' });
  };
};
```

### Route Protection
Protected routes are wrapped with authentication checks:

```typescript
const ProtectedRoute: React.FC<ProtectedRouteProps> = ({ children }) => {
  const { isAuthenticated, isLoading, login } = useAuth();

  if (!isAuthenticated) {
    return (
      <div className="auth-required">
        <button onClick={login} className="auth-button">
          Sign In with Hasura Cloud
        </button>
      </div>
    );
  }

  return <>{children}</>;
};
```

### Environment-Aware Configuration
The system automatically detects environment context and adapts
behavior:

```typescript
export const getAuthConfig = (): AuthConfig => {
  const env = getEnvironmentContext();

  if (env.isDevelopment || env.isLocalBuild) {
    return {
      useMockUserAccess: true,
      enableUserAccessCheck: true
    };
  }

  return {
    useMockUserAccess: false,
    graphqlEndpoint: 'https://data.pro.hasura.io/v1/graphql',
    enableUserAccessCheck: true
  };
};
```

## Production User Access Control

In production environments, user entitlements are determined through
GraphQL queries against the `ddn_promptql_enabled_users` table,
leveraging Hasura's authentication webhook system. The browser
automatically includes the `hasura-lux` cookie with GraphQL requests,
and Hasura's configured auth webhook decrypts and validates this cookie
to authorize the query.

### Access Verification Flow

When a user completes the OAuth flow, their access token is stored in a
browser cookie. Subsequent GraphQL requests automatically include this
cookie, which Hasura's auth webhook validates:

```typescript
export const checkUserAccess = async (token: string): Promise<boolean> => {
  // Store token in cookie for automatic inclusion in requests
  Cookies.set('hasura-lux', token, { expires: 1 });

  const response = await fetch(authConfig.graphqlEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Hasura-Client-Name': 'promptql-docs',
    },
    // Cookie automatically sent by browser
    body: JSON.stringify({
      query: USER_ACCESS_QUERY,
      variables: {}
    })
  });

  const data = await response.json();
  const enabledUsers = data.data?.ddn_promptql_enabled_users || [];
  return enabledUsers.length > 0;
};
```

### User Entitlement Query

The system uses a simple GraphQL query that relies on Hasura's
webhook-based authentication to identify the user:

```graphql
query CheckUserAccess {
  ddn_promptql_enabled_users {
    id
    email
  }
}
```

The Hasura auth webhook automatically processes the `hasura-lux` cookie
sent by the browser, decrypts the user's session data, and determines
their identity and permissions before executing the query.

## Developer Changes

### New Scripts
- `yarn start` - Starts development environment with authentication
services
- `yarn dev:stop` - Stops development services
- `yarn build:local` - Builds and serves production locally with
authentication
- Manual service management via `docker compose -f auth/compose.yml`

### Authentication Services
The development environment now includes:
- **Hydra OAuth2 Server**
- **Mock Login/Consent App**
- **Docusaurus**

### Environment Setup
Docker is now required for development. The setup is automated:

```bash
# Start development environment
yarn start

# Services will be automatically configured:
# - Hydra OAuth2 server
# - Mock login interface
# - OAuth2 client registration
```

### Testing Authentication
Access control can be tested by:
1. Checking out this branch
2. Starting the dev environment (`yarn start`) 
3. Visiting any protected documentation page
4. Being redirected to login interface
5. Completing OAuth flow through mock Hasura Cloud login
6. Being redirected back to original destination

Author: robertjdominguez

.gitignore

@@ -46,4 +46,4 @@ yarn-error.log*
 /pdf_output
 
 /static/docs-schema.json
-/docs-schema.json
+/docs-schema.json

Dockerfile

@@ -3,8 +3,9 @@
 #Modifying this will trigger deployment without a code change
 FROM --platform=linux/amd64 node:18.14.2
 
+ARG RELEASE_MODE=production
 ENV PORT=8080
-ENV release_mode="production"
+ENV release_mode=${RELEASE_MODE}
 ENV BUILD_VERSION="3.0"
 
 # Create app directory

README.md

@@ -27,11 +27,11 @@ git clone https://github.com/hasura/promptql-docs.git
 cd promptql-docs
 yarn
 
-# Start the dev server
+# Start the development environment
 yarn start
 ```
 
-The docs will open at `http://localhost:3001` with hot reloading - edit away and see changes instantly.
+The docs will open at `http://localhost:3001` with hot reloading and full authentication - edit away and see changes instantly.
 
 ### Making Changes
 
@@ -45,11 +45,11 @@ The docs will open at `http://localhost:3001` with hot reloading - edit away and
 # Build for production
 yarn build
 
-# Test the build locally
-yarn serve
+# Test the production build locally (with authentication)
+yarn build:local
 ```
 
-The build generates static files in the `build` directory, ready for any static hosting service.
+The `build` command generates static files in the `build` directory, ready for any static hosting service. The `build:local` command builds the site and serves it locally with the full authentication system for testing.
 
 
 ## Need Help?

auth/README.md

@@ -0,0 +1,179 @@
+# PromptQL Docs Authentication Setup
+
+This directory contains the mock authentication setup for the PromptQL documentation site using Hydra OAuth2 server.
+
+## Quick Start
+
+1. **Start the development environment:**
+   ```bash
+   yarn start
+   ```
+
+2. **Test the authentication flow:**
+   - Visit http://localhost:3001
+   - Try to access any documentation page (e.g., http://localhost:3001/docs/quickstart/)
+   - You should be redirected to the login page
+   - Click "Sign In with Hasura Cloud" to start the OAuth flow
+
+3. **Test production build locally:**
+   ```bash
+   yarn build:local
+   ```
+
+## Architecture Overview
+
+### Components
+
+1. **Hydra OAuth2 Server** (Port 4444/4445)
+   - Handles OAuth2 authorization flow
+   - Admin API on port 4445, Public API on port 4444
+
+2. **Login/Consent App** (Port 3000)
+   - Mock login interface that simulates Hasura Cloud login
+   - Handles user consent for OAuth2 flow
+
+3. **Docusaurus App** (Port 3001)
+   - Main documentation site with integrated authentication
+
+### Authentication Flow
+
+1. User visits protected documentation page
+2. `Root.tsx` provides AuthContext to entire app
+3. `Layout.tsx` component checks authentication status
+4. If not authenticated, `ProtectedRoute.tsx` shows login prompt
+5. User clicks login → redirected to Hydra OAuth2 endpoint
+6. Hydra redirects to mock login app (port 3000)
+7. User "logs in" → redirected back to Hydra
+8. Hydra redirects to `/docs/callback` with authorization code
+9. `AuthContext.tsx` exchanges code for access token (with duplicate call protection)
+10. User info is fetched and stored in cookies
+11. User is redirected to original destination
+
+### Key Files
+
+- `src/contexts/AuthContext.tsx` - Main authentication logic with OAuth2 flow
+- `src/theme/Root.tsx` - Provides AuthContext to entire app
+- `src/theme/Layout/index.tsx` - Route protection logic and loading states
+- `src/components/ProtectedRoute.tsx` - Protected route wrapper with delayed loading
+- `src/pages/login.tsx` - Login page with brand styling
+- `src/pages/callback.tsx` - OAuth callback handler with duplicate call protection
+- `src/theme/Navbar/Content/index.tsx` - Navbar with conditional auth elements
+- `src/css/custom.css` - Authentication styles with brand colors and animations
+
+## Configuration
+
+### OAuth2 Settings
+- **Client ID:** `docusaurus-client`
+- **Redirect URI:** `http://localhost:3001/docs/callback`
+- **Scopes:** `openid email`
+
+### Public Routes
+The following routes are accessible without authentication:
+- `/` (landing page)
+- `/docs/` (docs landing page)
+- `/login` (login page)
+- `/docs/callback` (OAuth callback)
+
+All other routes require authentication.
+
+## Key Features
+
+### UI/UX Enhancements
+- **Brand Colors**: Uses PromptQL brand colors that adapt to light/dark themes
+- **Delayed Loading**: Loading animations only appear after 5 seconds to avoid visual noise
+- **Animated Dots**: Professional 3-dot loading animation using CSS keyframes
+- **Conditional Navbar**: Search and navigation elements hidden when unauthenticated
+- **Responsive Design**: Works across all device sizes
+
+### Technical Features
+- **Duplicate Call Protection**: Prevents React Strict Mode from causing "code already used" errors
+- **CORS Support**: Proper CORS configuration for browser-to-Hydra communication
+- **Session Persistence**: Authentication state persists across browser refreshes
+- **Error Handling**: Comprehensive error states with user-friendly messages
+- **Clean Architecture**: Centralized auth logic with proper separation of concerns
+
+## Development vs Production
+
+### Development (Current Setup)
+- Mock Hydra server with in-memory storage and CORS enabled
+- Mock login/consent interface configured as public client (no client secret)
+- User access check always returns `true`
+- Access tokens stored in browser cookies (`pql-docs-access`) with 1-day expiration; refresh tokens in (`pql-docs-refresh`)
+- Tokens are retrieved from cookies and sent as Authorization Bearer headers to GraphQL API
+- Delayed loading animations (5-second threshold)
+- Brand-consistent styling across light/dark themes
+
+### Production (Future)
+- Real Hydra endpoints: `https://oauth.pro.hasura.io/*`
+- Real Hasura Cloud login interface configured as public client
+- GraphQL API check against `ddn_promptql_enabled_users` table
+- Secure httpOnly cookies for token storage
+- Tokens sent as Authorization Bearer headers to GraphQL API
+- Proper error handling and security headers
+
+## Troubleshooting
+
+### Services won't start
+```bash
+# Check if ports are in use
+lsof -i :3000 -i :4444 -i :4445
+
+# Stop existing containers
+docker compose -f auth/compose.yml down
+
+# Restart services
+./auth/start-auth-dev.sh
+```
+
+### Authentication fails
+```bash
+# Check service logs
+docker compose -f auth/compose.yml logs -f
+
+# Verify client registration
+curl http://localhost:4445/admin/clients/docusaurus-client
+```
+
+### Clear authentication state
+```bash
+# In browser console:
+document.cookie.split(";").forEach(function(c) { 
+  document.cookie = c.replace(/^ +/, "").replace(/=.*/, "=;expires=" + new Date().toUTCString() + ";path=/"); 
+});
+```
+
+## Testing Checklist
+
+- [ ] Unauthenticated users can access landing pages (`/` and `/docs/`)
+- [ ] Unauthenticated users redirected to login for protected pages
+- [ ] Login flow redirects to Hydra auth endpoint
+- [ ] Mock login interface appears and works correctly
+- [ ] Successful auth redirects to `/docs/callback` then to original destination
+- [ ] User email appears in navbar after authentication
+- [ ] Logout clears session and redirects to `/docs/index/`
+- [ ] Auth state persists across browser refresh
+- [ ] Loading animations only appear after 5-second delay
+- [ ] Search bar and navigation hidden when unauthenticated
+- [ ] Error handling works for failed auth attempts
+- [ ] No "authorization code already used" errors (duplicate call protection)
+
+## Commands
+
+```bash
+# Start development environment
+yarn start
+
+# Stop development services
+yarn dev:stop
+
+# Test production build locally
+yarn build:local
+
+# Manual service management (if needed)
+docker compose -f auth/compose.yml logs -f    # View logs
+docker compose -f auth/compose.yml down       # Stop services
+docker compose -f auth/compose.yml restart hydra  # Restart Hydra
+
+# Check client configuration
+curl http://localhost:4445/admin/clients/docusaurus-client
+```

auth/compose.yml

@@ -0,0 +1,39 @@
+services:
+  hydra-migrate:
+    image: oryd/hydra:v2.2.0
+    environment:
+      - DSN=memory
+    command: migrate -c /etc/config/hydra/hydra.yml sql -e --yes
+    volumes:
+      - type: bind
+        source: ./hydra
+        target: /etc/config/hydra
+    restart: on-failure
+
+  hydra:
+    image: oryd/hydra:v2.2.0
+    ports:
+      - "4444:4444" # Public port
+      - "4445:4445" # Admin port
+    command: serve -c /etc/config/hydra/hydra.yml all --dev
+    volumes:
+      - type: bind
+        source: ./hydra
+        target: /etc/config/hydra
+    environment:
+      - DSN=memory
+    restart: unless-stopped
+    depends_on:
+      - hydra-migrate
+
+  # Mock consent/login app
+  hydra-login-consent:
+    image: oryd/hydra-login-consent-node:v2.2.0
+    ports:
+      - "3000:3000"
+    environment:
+      - HYDRA_ADMIN_URL=http://hydra:4445
+      - NODE_TLS_REJECT_UNAUTHORIZED=0
+    restart: unless-stopped
+    depends_on:
+      - hydra

auth/hydra/hydra.yml

@@ -0,0 +1,37 @@
+serve:
+  public:
+    port: 4444
+    host: 0.0.0.0
+    cors:
+      enabled: true
+      allowed_origins:
+        - http://localhost:3001
+      allowed_methods:
+        - POST
+        - GET
+        - PUT
+        - PATCH
+        - DELETE
+      allowed_headers:
+        - Authorization
+        - Content-Type
+      allow_credentials: true
+  admin:
+    port: 4445
+    host: 0.0.0.0
+
+urls:
+  self:
+    issuer: http://localhost:4444
+  consent: http://localhost:3000/consent
+  login: http://localhost:3000/login
+
+secrets:
+  system:
+    - youReallyNeedToChangeThis
+
+oauth2:
+  expose_internal_errors: true
+
+log:
+  level: debug

auth/setup-client.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+echo "Waiting for Hydra to start..."
+sleep 10
+
+# Create OAuth2 client for Docusaurus
+curl -X POST \
+  http://localhost:4445/admin/clients \
+  -H "Content-Type: application/json" \
+  -d '{
+    "client_id": "docusaurus-client",
+    "client_name": "Docusaurus Documentation",
+    "redirect_uris": ["http://localhost:3001/docs/callback"],
+    "grant_types": ["authorization_code"],
+    "response_types": ["code"],
+    "scope": "openid email",
+    "token_endpoint_auth_method": "none"
+  }'
+
+echo "Client created successfully!"
+echo "Client ID: docusaurus-client"
+echo "Client Type: Public (no client secret)"
+echo "Redirect URI: http://localhost:3001/docs/callback"

auth/start-auth-dev.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+
+echo "🚀 Starting PromptQL Docs Authentication Development Environment"
+echo "=============================================================="
+
+# Check if Docker is running
+if ! docker info > /dev/null 2>&1; then
+    echo "❌ Docker is not running. Please start Docker and try again."
+    exit 1
+fi
+
+echo "📦 Starting Hydra and Login/Consent services..."
+
+# Start the services in the background
+cd "$(dirname "$0")"
+docker compose -f compose.yml up -d
+
+echo "⏳ Waiting for services to start..."
+sleep 15
+
+echo "🔧 Setting up OAuth2 client..."
+./setup-client.sh
+
+echo ""
+echo "✅ Authentication services are ready!"
+echo ""
+echo "🌐 Service URLs:"
+echo "   - Hydra Admin API: http://localhost:4445"
+echo "   - Hydra Public API: http://localhost:4444"
+echo "   - Login/Consent UI: http://localhost:3000"
+echo ""
+echo "📝 Next steps:"
+echo "   1. Start your Docusaurus dev server: npm start"
+echo "   2. Visit http://localhost:3001"
+echo "   3. Try accessing any documentation page to test authentication"
+echo ""
+echo "🔍 To view logs:"
+echo "   docker compose -f auth/compose.yml logs -f"
+echo ""
+echo "🛑 To stop services:"
+echo "   docker compose -f auth/compose.yml down"

custom-build-script.cjs

@@ -70,7 +70,7 @@ function generateLlmBundle() {
 
 // First run the Docusaurus build
 console.log('\n\x1b[36mRunning Docusaurus build...\x1b[0m');
-execSync('docusaurus build', { cwd: rootDir, stdio: 'inherit' });
+execSync('docusaurus build', { cwd: rootDir, stdio: 'inherit', env: process.env });
 
 // Then try to generate LLM bundle
 try {