@agentuity/auth 0.0.96

package/dist/clerk/server.js

@@ -0,0 +1,110 @@
+/**
+ * Clerk server-side authentication middleware for Hono.
+ *
+ * @module clerk/server
+ */
+import { createClerkClient, verifyToken } from '@clerk/backend';
+/**
+ * Create Hono middleware for Clerk authentication.
+ *
+ * This middleware:
+ * - Extracts and validates JWT tokens from Authorization header
+ * - Returns 401 if token is missing or invalid
+ * - Exposes authenticated user via c.var.auth
+ *
+ * @example
+ * ```typescript
+ * import { createMiddleware } from '@agentuity/auth/clerk';
+ *
+ * router.get('/api/profile', createMiddleware(), async (c) => {
+ *   const user = await c.var.auth.requireUser();
+ *   return c.json({ email: user.email });
+ * });
+ * ```
+ */
+export function createMiddleware(options = {}) {
+    const secretKey = options.secretKey || process.env.CLERK_SECRET_KEY;
+    const publishableKey = options.publishableKey ||
+        process.env.AGENTUITY_PUBLIC_CLERK_PUBLISHABLE_KEY ||
+        process.env.CLERK_PUBLISHABLE_KEY;
+    if (!secretKey) {
+        console.error('[Clerk Auth] CLERK_SECRET_KEY is not set. Add it to your .env file or pass secretKey option to createMiddleware()');
+        throw new Error('Clerk secret key is required (set CLERK_SECRET_KEY or pass secretKey option)');
+    }
+    if (!publishableKey) {
+        console.warn('[Clerk Auth] AGENTUITY_PUBLIC_CLERK_PUBLISHABLE_KEY is not set. Token validation may fail. Add it to your .env file.');
+    }
+    // Create Clerk client instance
+    const clerkClient = createClerkClient({ secretKey });
+    return async (c, next) => {
+        const authHeader = c.req.header('Authorization');
+        if (!authHeader) {
+            return c.json({ error: 'Unauthorized' }, 401);
+        }
+        try {
+            // Extract token from Bearer header
+            let token;
+            if (options.getToken) {
+                token = options.getToken(authHeader);
+            }
+            else {
+                // Validate Authorization scheme is Bearer
+                if (!authHeader.match(/^Bearer\s+/i)) {
+                    return c.json({ error: 'Unauthorized' }, 401);
+                }
+                token = authHeader.replace(/^Bearer\s+/i, '');
+            }
+            // Ensure token is not empty
+            if (!token || token.trim().length === 0) {
+                return c.json({ error: 'Unauthorized' }, 401);
+            }
+            // Verify token with Clerk (delegates validation to provider)
+            const payload = (await verifyToken(token, {
+                secretKey,
+            }));
+            // Validate payload has required subject claim
+            if (!payload.sub || typeof payload.sub !== 'string') {
+                throw new Error('Invalid token: missing or invalid subject claim');
+            }
+            // Memoize user fetch to avoid multiple API calls
+            let cachedUser = null;
+            // Create auth object with Clerk user and payload types
+            const auth = {
+                async requireUser() {
+                    if (cachedUser) {
+                        return cachedUser;
+                    }
+                    const user = await clerkClient.users.getUser(payload.sub);
+                    cachedUser = mapClerkUserToAgentuityUser(user);
+                    return cachedUser;
+                },
+                async getToken() {
+                    return token;
+                },
+                raw: payload,
+            };
+            c.set('auth', auth);
+            await next();
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            const errorCode = error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
+                ? error.code
+                : 'CLERK_AUTH_ERROR';
+            console.error(`[Clerk Auth] Authentication failed: ${errorCode} - ${errorMessage}`);
+            return c.json({ error: 'Unauthorized' }, 401);
+        }
+    };
+}
+/**
+ * Map Clerk User to AgentuityAuthUser.
+ */
+function mapClerkUserToAgentuityUser(clerkUser) {
+    return {
+        id: clerkUser.id,
+        name: `${clerkUser.firstName || ''} ${clerkUser.lastName || ''}`.trim() || undefined,
+        email: clerkUser.emailAddresses[0]?.emailAddress,
+        raw: clerkUser,
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/clerk/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/clerk/server.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @agentuity/auth - Authentication helpers for identity providers
+ *
+ * Currently supports Clerk, with more providers coming soon.
+ *
+ * @example Clerk Integration
+ * ```typescript
+ * // Client-side (React)
+ * import { AgentuityClerk } from '@agentuity/auth/clerk';
+ *
+ * // Server-side (Hono)
+ * import { createMiddleware } from '@agentuity/auth/clerk';
+ * ```
+ *
+ * @module @agentuity/auth
+ */
+export type { AgentuityAuthUser, AgentuityAuth } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,YAAY,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @agentuity/auth - Authentication helpers for identity providers
+ *
+ * Currently supports Clerk, with more providers coming soon.
+ *
+ * @example Clerk Integration
+ * ```typescript
+ * // Client-side (React)
+ * import { AgentuityClerk } from '@agentuity/auth/clerk';
+ *
+ * // Server-side (Hono)
+ * import { createMiddleware } from '@agentuity/auth/clerk';
+ * ```
+ *
+ * @module @agentuity/auth
+ */
+export {};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Core authentication types shared across all providers.
+ *
+ * @module types
+ */
+/**
+ * Generic authenticated user interface.
+ * All auth providers return this structure with provider-specific data in `raw`.
+ */
+export interface AgentuityAuthUser<T = unknown> {
+    /** Unique user identifier from the auth provider */
+    id: string;
+    /** User's full name */
+    name?: string;
+    /** Primary email address */
+    email?: string;
+    /** Raw provider-specific user object for advanced use cases */
+    raw: T;
+}
+/**
+ * Generic authentication interface exposed on Hono context.
+ * All auth middleware implementations provide this interface.
+ */
+export interface AgentuityAuth<TUser = unknown, TRaw = unknown> {
+    /** Get the authenticated user, throws if not authenticated */
+    requireUser(): Promise<AgentuityAuthUser<TUser>>;
+    /** Get the raw JWT token */
+    getToken(): Promise<string | null>;
+    /** Raw provider-specific auth object (e.g., JWT payload, session) */
+    raw: TRaw;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,OAAO;IAC7C,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IAEX,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,+DAA+D;IAC/D,GAAG,EAAE,CAAC,CAAC;CACP;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO;IAC7D,8DAA8D;IAC9D,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC;IAEjD,4BAA4B;IAC5B,QAAQ,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEnC,qEAAqE;IACrE,GAAG,EAAE,IAAI,CAAC;CACV"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Core authentication types shared across all providers.
+ *
+ * @module types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@agentuity/auth",
+	"version": "0.0.96",
+	"type": "module",
+	"description": "Authentication helpers for popular identity providers",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/agentuity/sdk.git",
+		"directory": "packages/auth"
+	},
+	"license": "Apache-2.0",
+	"exports": {
+		".": "./src/index.ts",
+		"./clerk": "./src/clerk/index.ts"
+	},
+	"scripts": {
+		"build": "tsc --build",
+		"clean": "rm -rf dist .tsbuildinfo",
+		"typecheck": "tsc --noEmit"
+	},
+	"peerDependencies": {
+		"react": "^18.0.0 || ^19.0.0",
+		"@clerk/clerk-react": "^5.0.0",
+		"@clerk/backend": "^1.0.0",
+		"@agentuity/react": "0.0.96",
+		"@agentuity/runtime": "0.0.96",
+		"hono": "^4.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@clerk/clerk-react": {
+			"optional": true
+		},
+		"@clerk/backend": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"@agentuity/react": "0.0.96",
+		"@agentuity/runtime": "0.0.96",
+		"@agentuity/test-utils": "0.0.96",
+		"@clerk/clerk-react": "^5.46.1",
+		"@clerk/backend": "^2.27.1",
+		"@types/react": "^18.3.18",
+		"hono": "^4.6.14",
+		"react": "^18.3.1",
+		"typescript": "^5.8.3"
+	}
+}

package/src/clerk/client.tsx

@@ -0,0 +1,86 @@
+/**
+ * Clerk client-side authentication provider for React.
+ *
+ * @module clerk/client
+ */
+
+import React, { useEffect } from 'react';
+import type { useAuth as ClerkUseAuth } from '@clerk/clerk-react';
+import { useAgentuity } from '@agentuity/react';
+
+type UseAuth = typeof ClerkUseAuth;
+
+export interface AgentuityClerkProps {
+	/** React children to render */
+	children: React.ReactNode;
+
+	/** Clerk's useAuth hook from @clerk/clerk-react */
+	useAuth: UseAuth;
+
+	/** Token refresh interval in milliseconds (default: 60000 = 1 minute) */
+	refreshInterval?: number;
+}
+
+/**
+ * Agentuity authentication provider for Clerk.
+ *
+ * This component integrates Clerk authentication with Agentuity's context,
+ * automatically injecting auth tokens into API calls via useAPI and useWebsocket.
+ *
+ * Must be a child of both ClerkProvider and AgentuityProvider.
+ *
+ * @example
+ * ```tsx
+ * import { ClerkProvider, useAuth } from '@clerk/clerk-react';
+ * import { AgentuityProvider } from '@agentuity/react';
+ * import { AgentuityClerk } from '@agentuity/auth/clerk';
+ *
+ * <ClerkProvider publishableKey={key}>
+ *   <AgentuityProvider>
+ *     <AgentuityClerk useAuth={useAuth}>
+ *       <App />
+ *     </AgentuityClerk>
+ *   </AgentuityProvider>
+ * </ClerkProvider>
+ * ```
+ */
+export function AgentuityClerk({
+	children,
+	useAuth,
+	refreshInterval = 60000,
+}: AgentuityClerkProps) {
+	const { getToken, isLoaded } = useAuth();
+	const { setAuthHeader, setAuthLoading } = useAgentuity();
+
+	// Fetch and update token in AgentuityContext
+	useEffect(() => {
+		if (!isLoaded || !setAuthHeader || !setAuthLoading) {
+			if (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 Clerk token:', error);
+				setAuthHeader(null);
+			} finally {
+				setAuthLoading(false);
+			}
+		};
+
+		fetchToken();
+
+		// Clerk handles token expiry internally, we refresh periodically
+		const interval = setInterval(fetchToken, refreshInterval);
+		return () => clearInterval(interval);
+	}, [getToken, isLoaded, setAuthHeader, setAuthLoading, refreshInterval]);
+
+	// Render children directly - auth header is now in AgentuityContext
+	return <>{children}</>;
+}

package/src/clerk/index.ts

@@ -0,0 +1,37 @@
+/**
+ * Clerk authentication provider for Agentuity.
+ *
+ * Provides both client-side (React) and server-side (Hono) authentication.
+ *
+ * @example Client-side
+ * ```tsx
+ * import { ClerkProvider, useAuth } from '@clerk/clerk-react';
+ * import { AgentuityProvider } from '@agentuity/react';
+ * import { AgentuityClerk } from '@agentuity/auth/clerk';
+ *
+ * <ClerkProvider publishableKey={key}>
+ *   <AgentuityProvider>
+ *     <AgentuityClerk useAuth={useAuth}>
+ *       <App />
+ *     </AgentuityClerk>
+ *   </AgentuityProvider>
+ * </ClerkProvider>
+ * ```
+ *
+ * @example Server-side
+ * ```typescript
+ * import { createMiddleware } from '@agentuity/auth/clerk';
+ *
+ * router.get('/api/profile', createMiddleware(), async (c) => {
+ *   const user = await c.var.auth.requireUser();
+ *   return c.json({ email: user.email });
+ * });
+ * ```
+ *
+ * @module clerk
+ */
+
+export { AgentuityClerk } from './client';
+export type { AgentuityClerkProps } from './client';
+export { createMiddleware } from './server';
+export type { ClerkMiddlewareOptions, ClerkJWTPayload } from './server';

package/src/clerk/server.ts

@@ -0,0 +1,168 @@
+/**
+ * Clerk server-side authentication middleware for Hono.
+ *
+ * @module clerk/server
+ */
+
+import type { MiddlewareHandler } from 'hono';
+import { createClerkClient, verifyToken } from '@clerk/backend';
+import type { User } from '@clerk/backend';
+import type { AgentuityAuth, AgentuityAuthUser } from '../types';
+
+/**
+ * Clerk JWT payload structure.
+ */
+export interface ClerkJWTPayload {
+	/** Subject (user ID) */
+	sub: string;
+	/** Additional claims */
+	[key: string]: unknown;
+}
+
+/**
+ * Options for Clerk middleware.
+ */
+export interface ClerkMiddlewareOptions {
+	/** Clerk secret key (defaults to process.env.CLERK_SECRET_KEY) */
+	secretKey?: string;
+
+	/** Custom token extractor function */
+	getToken?: (authHeader: string) => string;
+
+	/** Clerk publishable key for token verification */
+	publishableKey?: string;
+}
+
+/**
+ * Create Hono middleware for Clerk authentication.
+ *
+ * This middleware:
+ * - Extracts and validates JWT tokens from Authorization header
+ * - Returns 401 if token is missing or invalid
+ * - Exposes authenticated user via c.var.auth
+ *
+ * @example
+ * ```typescript
+ * import { createMiddleware } from '@agentuity/auth/clerk';
+ *
+ * router.get('/api/profile', createMiddleware(), async (c) => {
+ *   const user = await c.var.auth.requireUser();
+ *   return c.json({ email: user.email });
+ * });
+ * ```
+ */
+export function createMiddleware(options: ClerkMiddlewareOptions = {}): MiddlewareHandler {
+	const secretKey = options.secretKey || process.env.CLERK_SECRET_KEY;
+	const publishableKey =
+		options.publishableKey ||
+		process.env.AGENTUITY_PUBLIC_CLERK_PUBLISHABLE_KEY ||
+		process.env.CLERK_PUBLISHABLE_KEY;
+
+	if (!secretKey) {
+		console.error(
+			'[Clerk Auth] CLERK_SECRET_KEY is not set. Add it to your .env file or pass secretKey option to createMiddleware()'
+		);
+		throw new Error(
+			'Clerk secret key is required (set CLERK_SECRET_KEY or pass secretKey option)'
+		);
+	}
+
+	if (!publishableKey) {
+		console.warn(
+			'[Clerk Auth] AGENTUITY_PUBLIC_CLERK_PUBLISHABLE_KEY is not set. Token validation may fail. Add it to your .env file.'
+		);
+	}
+
+	// Create Clerk client instance
+	const clerkClient = createClerkClient({ secretKey });
+
+	return async (c, next) => {
+		const authHeader = c.req.header('Authorization');
+
+		if (!authHeader) {
+			return c.json({ error: 'Unauthorized' }, 401);
+		}
+
+		try {
+			// Extract token from Bearer header
+			let token: string;
+			if (options.getToken) {
+				token = options.getToken(authHeader);
+			} else {
+				// Validate Authorization scheme is Bearer
+				if (!authHeader.match(/^Bearer\s+/i)) {
+					return c.json({ error: 'Unauthorized' }, 401);
+				}
+				token = authHeader.replace(/^Bearer\s+/i, '');
+			}
+
+			// Ensure token is not empty
+			if (!token || token.trim().length === 0) {
+				return c.json({ error: 'Unauthorized' }, 401);
+			}
+
+			// Verify token with Clerk (delegates validation to provider)
+			const payload = (await verifyToken(token, {
+				secretKey,
+			})) as ClerkJWTPayload;
+
+			// Validate payload has required subject claim
+			if (!payload.sub || typeof payload.sub !== 'string') {
+				throw new Error('Invalid token: missing or invalid subject claim');
+			}
+
+			// Memoize user fetch to avoid multiple API calls
+			let cachedUser: AgentuityAuthUser<User> | null = null;
+
+			// Create auth object with Clerk user and payload types
+			const auth: AgentuityAuth<User, ClerkJWTPayload> = {
+				async requireUser() {
+					if (cachedUser) {
+						return cachedUser;
+					}
+					const user = await clerkClient.users.getUser(payload.sub);
+					cachedUser = mapClerkUserToAgentuityUser(user);
+					return cachedUser;
+				},
+
+				async getToken() {
+					return token;
+				},
+
+				raw: payload,
+			};
+
+			c.set('auth', auth);
+			await next();
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+			const errorCode =
+				error && typeof error === 'object' && 'code' in error && typeof error.code === 'string'
+					? error.code
+					: 'CLERK_AUTH_ERROR';
+			console.error(`[Clerk Auth] Authentication failed: ${errorCode} - ${errorMessage}`);
+			return c.json({ error: 'Unauthorized' }, 401);
+		}
+	};
+}
+
+/**
+ * Map Clerk User to AgentuityAuthUser.
+ */
+function mapClerkUserToAgentuityUser(clerkUser: User): AgentuityAuthUser<User> {
+	return {
+		id: clerkUser.id,
+		name: `${clerkUser.firstName || ''} ${clerkUser.lastName || ''}`.trim() || undefined,
+		email: clerkUser.emailAddresses[0]?.emailAddress,
+		raw: clerkUser,
+	};
+}
+
+/**
+ * Augment Hono's context types to include auth.
+ */
+declare module 'hono' {
+	interface ContextVariableMap {
+		auth: AgentuityAuth<User, ClerkJWTPayload>;
+	}
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+/**
+ * @agentuity/auth - Authentication helpers for identity providers
+ *
+ * Currently supports Clerk, with more providers coming soon.
+ *
+ * @example Clerk Integration
+ * ```typescript
+ * // Client-side (React)
+ * import { AgentuityClerk } from '@agentuity/auth/clerk';
+ *
+ * // Server-side (Hono)
+ * import { createMiddleware } from '@agentuity/auth/clerk';
+ * ```
+ *
+ * @module @agentuity/auth
+ */
+
+export type { AgentuityAuthUser, AgentuityAuth } from './types';

package/src/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Core authentication types shared across all providers.
+ *
+ * @module types
+ */
+
+/**
+ * Generic authenticated user interface.
+ * All auth providers return this structure with provider-specific data in `raw`.
+ */
+export interface AgentuityAuthUser<T = unknown> {
+	/** Unique user identifier from the auth provider */
+	id: string;
+
+	/** User's full name */
+	name?: string;
+
+	/** Primary email address */
+	email?: string;
+
+	/** Raw provider-specific user object for advanced use cases */
+	raw: T;
+}
+
+/**
+ * Generic authentication interface exposed on Hono context.
+ * All auth middleware implementations provide this interface.
+ */
+export interface AgentuityAuth<TUser = unknown, TRaw = unknown> {
+	/** Get the authenticated user, throws if not authenticated */
+	requireUser(): Promise<AgentuityAuthUser<TUser>>;
+
+	/** Get the raw JWT token */
+	getToken(): Promise<string | null>;
+
+	/** Raw provider-specific auth object (e.g., JWT payload, session) */
+	raw: TRaw;
+}

package/test/clerk-client.test.tsx

@@ -0,0 +1,21 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { describe, test, expect } from 'bun:test';
+import { AgentuityClerk } from '../src/clerk/client';
+
+describe('AgentuityClerk', () => {
+	test('exports AgentuityClerk component', () => {
+		expect(AgentuityClerk).toBeDefined();
+		expect(typeof AgentuityClerk).toBe('function');
+	});
+
+	test('component props interface is correct', () => {
+		// Type test - will fail at compile time if interface changes
+		const validProps = {
+			children: null,
+			useAuth: (() => ({ getToken: async () => null, isLoaded: true })) as any,
+			refreshInterval: 60000,
+		};
+
+		expect(validProps).toBeDefined();
+	});
+});

package/test/clerk-server.test.ts

@@ -0,0 +1,34 @@
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { Hono } from 'hono';
+import { createMiddleware } from '../src/clerk/server';
+
+describe('Clerk server middleware', () => {
+	beforeEach(() => {
+		process.env.CLERK_SECRET_KEY = 'sk_test_secret';
+	});
+
+	test('returns 401 when Authorization header is missing', async () => {
+		const app = new Hono();
+		app.use('/protected', createMiddleware());
+		app.get('/protected', (c) => c.json({ success: true }));
+
+		const res = await app.request('/protected', {
+			method: 'GET',
+		});
+
+		expect(res.status).toBe(401);
+		const body = await res.json();
+		expect(body).toEqual({ error: 'Unauthorized' });
+	});
+
+	test('throws error when CLERK_SECRET_KEY is missing', () => {
+		delete process.env.CLERK_SECRET_KEY;
+
+		expect(() => createMiddleware()).toThrow('Clerk secret key is required');
+	});
+
+	test('creates middleware function', () => {
+		const middleware = createMiddleware();
+		expect(typeof middleware).toBe('function');
+	});
+});

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"composite": true,
+		"outDir": "./dist",
+		"rootDir": "./src",
+		"jsx": "react-jsx"
+	},
+	"include": ["src/**/*"],
+	"exclude": ["test/**/*"],
+	"references": [{ "path": "../react" }, { "path": "../runtime" }]
+}