@agentuity/auth 0.0.100 → 0.0.102

package/docs/adding-providers.md

@@ -0,0 +1,260 @@
+# Adding New Auth Providers
+
+Guide for implementing new authentication providers in `@agentuity/auth`.
+
+## Provider Structure
+
+Each provider follows a consistent structure:
+
+```
+src/<provider>/
+├── index.ts       # Re-exports client and server
+├── client.tsx     # React component for client-side auth
+└── server.ts      # Hono middleware for server-side validation
+```
+
+## Step 1: Create Provider Directory
+
+```bash
+mkdir -p src/workos
+```
+
+## Step 2: Implement Client Component
+
+```typescript
+// src/workos/client.tsx
+import React, { useEffect } from 'react';
+import { useAuth } from '@agentuity/react';
+import type { useAuth as WorkOSUseAuth } from '@workos/react';
+
+export interface AgentuityWorkOSProps {
+	children: React.ReactNode;
+	useAuth: typeof WorkOSUseAuth;
+}
+
+export function AgentuityWorkOS({ children, useAuth: workosUseAuth }: AgentuityWorkOSProps) {
+	const { getToken, isLoaded } = workosUseAuth();
+	const { setAuthHeader, setAuthLoading } = useAuth();
+
+	useEffect(() => {
+		if (!isLoaded || !setAuthHeader || !setAuthLoading) {
+			setAuthLoading?.(true);
+			return;
+		}
+
+		const fetchToken = async () => {
+			try {
+				setAuthLoading(true);
+				const token = await getToken();
+				setAuthHeader(token ? `Bearer ${token}` : null);
+			} catch (error) {
+				console.error('Failed to get WorkOS token:', error);
+				setAuthHeader(null);
+			} finally {
+				setAuthLoading(false);
+			}
+		};
+
+		fetchToken();
+	}, [getToken, isLoaded, setAuthHeader, setAuthLoading]);
+
+	return <>{children}</>;
+}
+```
+
+## Step 3: Implement Server Middleware
+
+```typescript
+// src/workos/server.ts
+import type { MiddlewareHandler } from 'hono';
+import { WorkOS } from '@workos-inc/node';
+import type { AgentuityAuth, AgentuityAuthUser } from '../types';
+
+export interface WorkOSMiddlewareOptions {
+	apiKey?: string;
+	clientId?: string;
+}
+
+export function createMiddleware(options: WorkOSMiddlewareOptions = {}): MiddlewareHandler {
+	const apiKey = options.apiKey || process.env.WORKOS_API_KEY;
+	const clientId = options.clientId || process.env.WORKOS_CLIENT_ID;
+
+	if (!apiKey) {
+		console.error('[WorkOS Auth] WORKOS_API_KEY is not set');
+		throw new Error('WorkOS API key is required');
+	}
+
+	const workos = new WorkOS(apiKey);
+
+	return async (c, next) => {
+		const authHeader = c.req.header('Authorization');
+
+		if (!authHeader) {
+			return c.json({ error: 'Unauthorized' }, 401);
+		}
+
+		try {
+			const token = authHeader.replace(/^Bearer\s+/i, '');
+			const { user } = await workos.userManagement.authenticateWithSessionCookie(token);
+
+			const auth: AgentuityAuth<typeof user, unknown> = {
+				async requireUser() {
+					return {
+						id: user.id,
+						email: user.email,
+						name: `${user.firstName} ${user.lastName}`.trim(),
+						raw: user,
+					};
+				},
+				async getToken() {
+					return token;
+				},
+				raw: {},
+			};
+
+			c.set('auth', auth);
+			await next();
+		} catch (error) {
+			console.error('WorkOS auth error:', error);
+			return c.json({ error: 'Unauthorized' }, 401);
+		}
+	};
+}
+
+declare module 'hono' {
+	interface ContextVariableMap {
+		auth: AgentuityAuth<any, unknown>;
+	}
+}
+```
+
+## Step 4: Create Index File
+
+```typescript
+// src/workos/index.ts
+export { AgentuityWorkOS } from './client';
+export type { AgentuityWorkOSProps } from './client';
+export { createMiddleware } from './server';
+export type { WorkOSMiddlewareOptions } from './server';
+```
+
+## Step 5: Update Package Exports
+
+```json
+// package.json
+{
+	"exports": {
+		".": "./src/index.ts",
+		"./clerk": "./src/clerk/index.ts",
+		"./workos": "./src/workos/index.ts"
+	},
+	"peerDependencies": {
+		"@workos-inc/node": "^7.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@workos-inc/node": { "optional": true }
+	}
+}
+```
+
+## Step 6: Write Tests
+
+```typescript
+// test/workos-server.test.ts
+import { describe, test, expect } from 'bun:test';
+import { createMiddleware } from '../src/workos/server';
+
+describe('WorkOS server middleware', () => {
+	test('throws error when WORKOS_API_KEY is missing', () => {
+		delete process.env.WORKOS_API_KEY;
+		expect(() => createMiddleware()).toThrow('WorkOS API key is required');
+	});
+});
+```
+
+## Type Safety Requirements
+
+### Generic Types
+
+Providers must use generic types for full type safety:
+
+```typescript
+export interface AgentuityAuthUser<T = unknown> {
+	id: string;
+	name?: string;
+	email?: string;
+	raw: T; // Provider-specific user object
+}
+
+export interface AgentuityAuth<TUser = unknown, TRaw = unknown> {
+	requireUser(): Promise<AgentuityAuthUser<TUser>>;
+	getToken(): Promise<string | null>;
+	raw: TRaw; // Provider-specific auth object
+}
+```
+
+### Hono Module Augmentation
+
+Each provider must augment Hono's types:
+
+```typescript
+declare module 'hono' {
+	interface ContextVariableMap {
+		auth: AgentuityAuth<User, ClerkJWTPayload>;
+	}
+}
+```
+
+## Environment Variables
+
+Support these patterns:
+- **Public keys**: `AGENTUITY_PUBLIC_<PROVIDER>_<KEY>`
+- **Secret keys**: `<PROVIDER>_SECRET_KEY`
+- **Fallback**: Standard provider env var names
+
+## Common Patterns
+
+### Conditional Rendering
+
+```tsx
+function ProtectedComponent() {
+	const { isAuthenticated, authLoading } = useAuth();
+
+	if (authLoading) return <div>Loading...</div>;
+	if (!isAuthenticated) return <SignInButton />;
+	return <div>Protected content</div>;
+}
+```
+
+### Optional Auth Routes
+
+```typescript
+router.get('/public-or-personalized', async (c) => {
+	const authHeader = c.req.header('Authorization');
+	if (authHeader) {
+		try {
+			const user = await c.var.auth?.requireUser();
+			return c.json({ personalized: true, userId: user?.id });
+		} catch {
+			// Auth failed, treat as public
+		}
+	}
+	return c.json({ personalized: false });
+});
+```
+
+## Security Rules
+
+- **Never log secrets**: `console.log('Auth present:', !!authHeader)` not the actual token
+- **Validate on every request**: Don't cache validation results
+- **Use provider SDKs**: Never manually verify JWTs
+
+## Checklist
+
+1. Research provider's auth flow (JWT, session, OAuth)
+2. Implement client component (token fetching)
+3. Implement server middleware (token validation)
+4. Add Hono type augmentation
+5. Write tests
+6. Update package.json exports
+7. Create template if commonly used

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/auth",
-	"version": "0.0.100",
+	"version": "0.0.102",
 	"type": "module",
 	"description": "Authentication helpers for popular identity providers",
 	"repository": {
@@ -11,7 +11,10 @@
 	"license": "Apache-2.0",
 	"exports": {
 		".": "./src/index.ts",
-		"./clerk": "./src/clerk/index.ts"
+		"./clerk": "./src/clerk/index.ts",
+		"./auth0": "./src/auth0/index.ts",
+		"./auth0/client": "./src/auth0/client.tsx",
+		"./auth0/server": "./src/auth0/server.ts"
 	},
 	"scripts": {
 		"build": "tsc --build",
@@ -22,8 +25,11 @@
 		"react": "^18.0.0 || ^19.0.0",
 		"@clerk/clerk-react": "^5.0.0",
 		"@clerk/backend": "^1.0.0",
-		"@agentuity/react": "0.0.100",
-		"@agentuity/runtime": "0.0.100",
+		"@auth0/auth0-react": "^2.11.0",
+		"jwks-rsa": "^3.2.0",
+		"jsonwebtoken": "^9.0.3",
+		"@agentuity/react": "0.0.102",
+		"@agentuity/runtime": "0.0.102",
 		"hono": "^4.0.0"
 	},
 	"peerDependenciesMeta": {
@@ -32,16 +38,29 @@
 		},
 		"@clerk/backend": {
 			"optional": true
+		},
+		"@auth0/auth0-react": {
+			"optional": true
+		},
+		"jwks-rsa": {
+			"optional": true
+		},
+		"jsonwebtoken": {
+			"optional": true
 		}
 	},
 	"devDependencies": {
-		"@agentuity/react": "0.0.100",
-		"@agentuity/runtime": "0.0.100",
-		"@agentuity/test-utils": "0.0.100",
-		"@clerk/clerk-react": "^5.46.1",
+		"@agentuity/react": "0.0.102",
+		"@agentuity/runtime": "0.0.102",
+		"@agentuity/test-utils": "0.0.102",
+		"@auth0/auth0-react": "^2.2.4",
 		"@clerk/backend": "^2.27.1",
+		"@clerk/clerk-react": "^5.46.1",
+		"@types/jsonwebtoken": "^9.0.10",
 		"@types/react": "^18.3.18",
 		"hono": "^4.6.14",
+		"jsonwebtoken": "^9.0.3",
+		"jwks-rsa": "^3.2.0",
 		"react": "^18.3.1",
 		"typescript": "^5.8.3"
 	}

package/src/auth0/client.tsx

@@ -0,0 +1,109 @@
+/**
+ * Auth0 client-side authentication provider for React.
+ *
+ * @module auth0/client
+ */
+
+import React, { useEffect, useRef } from 'react';
+import type { useAuth0 as Auth0UseAuth } from '@auth0/auth0-react';
+import { useAuth } from '@agentuity/react';
+
+type UseAuth0 = typeof Auth0UseAuth;
+
+export interface AgentuityAuth0Props {
+	/** React children to render */
+	children: React.ReactNode;
+
+	/** Auth0's useAuth0 hook from @auth0/auth0-react */
+	useAuth0: UseAuth0;
+
+	/** Token refresh interval in milliseconds (default: 60000 = 1 minute) */
+	refreshInterval?: number;
+
+	/** Options to pass to getAccessTokenSilently */
+	tokenOptions?: Parameters<ReturnType<UseAuth0>['getAccessTokenSilently']>[0];
+}
+
+/**
+ * Agentuity authentication provider for Auth0.
+ *
+ * This component integrates Auth0 authentication with Agentuity's context,
+ * automatically injecting auth tokens into API calls via useAPI and useWebsocket.
+ *
+ * Must be a child of both Auth0Provider and AgentuityProvider.
+ *
+ * @example
+ * ```tsx
+ * import { Auth0Provider, useAuth0 } from '@auth0/auth0-react';
+ * import { AgentuityProvider } from '@agentuity/react';
+ * import { AgentuityAuth0 } from '@agentuity/auth/auth0';
+ *
+ * <Auth0Provider domain={domain} clientId={clientId} authorizationParams={{ redirect_uri: window.location.origin }}>
+ *   <AgentuityProvider>
+ *     <AgentuityAuth0 useAuth0={useAuth0}>
+ *       <App />
+ *     </AgentuityAuth0>
+ *   </AgentuityProvider>
+ * </Auth0Provider>
+ * ```
+ */
+export function AgentuityAuth0({
+	children,
+	useAuth0,
+	refreshInterval = 60000,
+	tokenOptions,
+}: AgentuityAuth0Props) {
+	const { getAccessTokenSilently, isLoading, isAuthenticated } = useAuth0();
+	const { setAuthHeader, setAuthLoading } = useAuth();
+
+	// Use ref for tokenOptions to avoid infinite re-renders when parent passes inline object
+	const tokenOptionsRef = useRef(tokenOptions);
+	tokenOptionsRef.current = tokenOptions;
+
+	useEffect(() => {
+		if (isLoading || !setAuthHeader || !setAuthLoading) {
+			if (setAuthLoading) {
+				setAuthLoading(true);
+			}
+			return;
+		}
+
+		// Not authenticated - clear auth header
+		if (!isAuthenticated) {
+			setAuthHeader(null);
+			setAuthLoading(false);
+			return;
+		}
+
+		const fetchToken = async () => {
+			try {
+				setAuthLoading(true);
+				const token = await getAccessTokenSilently(tokenOptionsRef.current);
+				setAuthHeader(token ? `Bearer ${token}` : null);
+			} catch (error) {
+				console.error(
+					'Failed to get Auth0 token:',
+					error instanceof Error ? error.message : 'Unknown error'
+				);
+				setAuthHeader(null);
+			} finally {
+				setAuthLoading(false);
+			}
+		};
+
+		fetchToken();
+
+		// Refresh token periodically
+		const interval = setInterval(fetchToken, refreshInterval);
+		return () => clearInterval(interval);
+	}, [
+		getAccessTokenSilently,
+		isLoading,
+		isAuthenticated,
+		setAuthHeader,
+		setAuthLoading,
+		refreshInterval,
+	]);
+
+	return <>{children}</>;
+}

package/src/auth0/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Auth0 authentication provider for Agentuity.
+ *
+ * Provides client-side (React) and server-side (Hono) authentication.
+ *
+ * @example Client-side
+ * ```tsx
+ * import { Auth0Provider, useAuth0 } from '@auth0/auth0-react';
+ * import { AgentuityProvider } from '@agentuity/react';
+ * import { AgentuityAuth0 } from '@agentuity/auth/auth0';
+ *
+ * <Auth0Provider domain={domain} clientId={clientId} authorizationParams={{ redirect_uri: window.location.origin }}>
+ *   <AgentuityProvider>
+ *     <AgentuityAuth0 useAuth0={useAuth0}>
+ *       <App />
+ *     </AgentuityAuth0>
+ *   </AgentuityProvider>
+ * </Auth0Provider>
+ * ```
+ *
+ * @example Server-side
+ * ```typescript
+ * import { createMiddleware } from '@agentuity/auth/auth0/server';
+ *
+ * router.get('/api/profile', createMiddleware(), async (c) => {
+ *   const user = await c.var.auth.getUser();
+ *   return c.json({ email: user.email });
+ * });
+ * ```
+ *
+ * @module auth0
+ */
+
+// Client-side exports (safe for browser)
+export { AgentuityAuth0 } from './client';
+export type { AgentuityAuth0Props } from './client';
+
+// Server-side exports are NOT exported from the main index to prevent bundling server deps in frontend
+// Import server code directly from '@agentuity/auth/auth0/server' instead
+// This ensures jsonwebtoken/jwks-rsa are never bundled into browser code