Streaming chat with the FOIA Expert Agent (SSE)

**Auth0 JWT Bearer Token Authentication** All protected endpoints require a valid JWT token issued by Auth0. ## Auth0 Configuration - **Tenant**: `dev-4fszoklachwdh46m.us.auth0.com` - **Issuer**: `https://dev-4fszoklachwdh46m.us.auth0.com/` - **Audience**: `https://api.theholefoundation.org` - **Algorithm**: RS256 (RSA Signature with SHA-256) - **JWKS URI**: `https://dev-4fszoklachwdh46m.us.auth0.com/.well-known/jwks.json` ## Getting a Token **For End Users (Web Application)**: - Login: https://theholetruth.org/api/auth - Uses Auth0 Universal Login - Returns JWT in response after successful authentication **For M2M (Service-to-Service)**: ```bash curl --request POST \ --url https://dev-4fszoklachwdh46m.us.auth0.com/oauth/token \ --header 'content-type: application/json' \ --data '{ "client_id": "YOUR_M2M_CLIENT_ID", "client_secret": "YOUR_M2M_CLIENT_SECRET", "audience": "https://api.theholefoundation.org", "grant_type": "client_credentials" }' ``` ## Using the Token Include the JWT in the `Authorization` header of all API requests: ``` Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... ``` ## Implementation Guide (Backend) **Step 1: Fetch JWKS from Auth0** ```javascript const jwksClient = require('jwks-rsa'); const client = jwksClient({ jwksUri: 'https://dev-4fszoklachwdh46m.us.auth0.com/.well-known/jwks.json' }); ``` **Step 2: Validate JWT** ```javascript const jwt = require('jsonwebtoken'); function validateAuth0Token(token) { return jwt.verify(token, getKey, { audience: 'https://api.theholefoundation.org', issuer: 'https://dev-4fszoklachwdh46m.us.auth0.com/', algorithms: ['RS256'] }); } ``` **Step 3: Extract User ID** ```javascript const decoded = validateAuth0Token(token); const userId = decoded.sub; // e.g., "auth0|507f1f77bcf86cd799439011" ``` **Step 4: Check Permissions** ```javascript const scopes = decoded.scope.split(' '); if (!scopes.includes('read:transparency')) { throw new Error('Insufficient permissions'); } ``` ## Token Claims Every Auth0 JWT contains these claims: ```json { "sub": "auth0|507f1f77bcf86cd799439011", // User ID (use this as primary key) "email": "user@example.com", "email_verified": true, "name": "John Doe", "iss": "https://dev-4fszoklachwdh46m.us.auth0.com/", "aud": "https://api.theholefoundation.org", "iat": 1516239022, // Issued at (Unix timestamp) "exp": 1516242622, // Expires at (Unix timestamp) "azp": "YOUR_CLIENT_ID", // Authorized party "scope": "read:transparency write:foia" // Permissions } ``` ## Required Scopes by Endpoint Category - **Vector Search**: `read:transparency` - **Transparency**: `read:transparency` - **FOIA Dashboard**: `read:foia`, `write:foia` - **Chat**: `chat:assistant` - **LaTeX Compilation**: `compile:documents` - **Neon Database**: `read:database` (admin: `admin:database`) - **Integration Workflows**: `execute:workflows` - **S3 Storage**: `read:storage`, `write:storage` - **Vector Store**: `read:vectors`, `write:vectors` (admin: `admin:vectors`) - **Project API**: `read:projects`, `write:projects` ## Error Responses **401 Unauthorized** - Missing or invalid token: ```json { "error": { "code": "AUTH_MISSING_TOKEN", "message": "Authentication token is required", "status": 401 } } ``` **401 Unauthorized** - Expired token: ```json { "error": { "code": "AUTH_TOKEN_EXPIRED", "message": "Token has expired", "status": 401 } } ``` **403 Forbidden** - Insufficient permissions: ```json { "error": { "code": "AUTH_INSUFFICIENT_SCOPE", "message": "Token does not have required scope", "status": 403, "metadata": { "required_scope": "write:foia", "provided_scopes": ["read:foia"] } } } ``` ## Security Best Practices 1. **Always validate the JWT signature** using Auth0's JWKS 2. **Verify the `iss` claim** matches Auth0 tenant 3. **Verify the `aud` claim** matches your API identifier 4. **Check the `exp` claim** to reject expired tokens 5. **Extract user ID from `sub` claim** for resource scoping 6. **Validate scopes** before granting access to protected resources 7. **Use HTTPS only** for all API communication 8. **Never log or expose** JWT tokens in plaintext 9. **Implement rate limiting** per `sub` claim to prevent abuse 10. **Audit all access** with Auth0 user ID for compliance ## Neon + BetterAuth Integration BetterAuth (Neon's authentication layer) uses Auth0 as the JWT provider: - Auth0 issues all JWT tokens - BetterAuth validates tokens against Auth0's JWKS - User sessions stored in Neon PostgreSQL - Row-Level Security (RLS) uses `auth.user_id()` function - RLS policies extract user ID from Auth0 `sub` claim **Example RLS Policy**: ```sql CREATE POLICY foia_requests_user_isolation ON foia_requests USING (user_id = auth.user_id()); ``` ## SDK Integration All generated SDKs include Auth0 authentication helpers: **TypeScript SDK**: ```typescript import { HoleFoundationClient } from '@hole-foundation/api'; const client = new HoleFoundationClient({ token: 'YOUR_AUTH0_JWT_TOKEN' }); ``` **Python SDK**: ```python from theholetruth import HoleFoundationClient client = HoleFoundationClient( token="YOUR_AUTH0_JWT_TOKEN" ) ``` ## Need Help? - **Auth0 Documentation**: Contact api@theholefoundation.org - **M2M Credentials**: Contact api@theholefoundation.org - **Permission Issues**: Check your Auth0 user roles and scopes - **Token Expiration**: Implement token refresh flow in your application